Extend PR #312 Y-normalization contract into SDID diagnostic methods

[igerber]

Summary

• Capture Y_shift and Y_scale on _SyntheticDiDFitSnapshot so that SyntheticDiDResults.in_time_placebo() and SyntheticDiDResults.sensitivity_to_zeta_omega() can reproduce the exact normalization the main fit path applies.
• Normalize the relevant Y arrays before running Frank-Wolfe inside each diagnostic, pass zeta / Y_scale and a min_decrease derived from the normalized noise level, then rescale att / pre_fit_rmse back to original-Y units. max_unit_weight and effective_n are scale-invariant and reported unchanged.
• Update the SyntheticDiD registry note to describe the new diagnostic contract (replaces the prior "diagnostics run on original-scale snapshot" caveat).

Methodology references (required if estimator / math changes)

• Method name(s): SyntheticDiDResults.in_time_placebo(), SyntheticDiDResults.sensitivity_to_zeta_omega().
• Paper / source link(s): Arkhangelsky et al. (2021); synth-inference/synthdid#71 (R-package version of the extreme-Y cancellation issue).
• Any intentional deviations from the source (and why): None. The diagnostic contract is a no-op on well-scaled Y (τ is location-invariant and scale-equivariant, FW is invariant under (Y, ζ) → (Y/s, ζ/s)); the change only prevents catastrophic cancellation at extreme Y that PR Fix SyntheticDiD catastrophic cancellation at extreme Y scale #312 already fixed on the main fit() path.

Validation

• Tests added/updated in tests/test_methodology_sdid.py:
  • TestDiagnosticScaleParity — asserts att / pre_fit_rmse scale by |a| across (Y -> a*Y + b) for both diagnostic methods; checks finite placebo output at Y ~ 1e9 on a no-effect DGP.
  • TestHeterogeneousAndRampingScale — cross-unit heterogeneous scale (units spanning 1e6-1e9) and cross-period ramping trend must leave fit + both diagnostics finite (D-4b regression coverage).
  • TestDiagnosticSnapshotBackwardCompat — asserts that a _SyntheticDiDFitSnapshot constructed without Y_shift / Y_scale (using the new defaults of 0.0 and 1.0) still drives both diagnostics with the same schema and row count — locks in the legacy-snapshot contract.
• Full tests/test_methodology_sdid.py suite green (135 tests).
• Backtest / simulation / notebook evidence: N/A — scale-parity regression coverage above is the substantive evidence.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Audit context: resolves findings D-4 and D-4b from the axis-A (numerical precision / scale fragility) slice of the in-flight silent-failures audit. Follows the SDID coordination protocol; no in-flight SDID work to coordinate with (main-path fix #312 already landed).

[github-actions]

Overall Assessment

✅ Looks good

Executive Summary

• No unmitigated P0/P1 findings in the changed SDID diagnostic paths.
• The affected methods are SyntheticDiDResults.in_time_placebo(), SyntheticDiDResults.sensitivity_to_zeta_omega(), fit-time snapshot capture in diff_diff/synthetic_did.py:L659-L671, and the internal snapshot schema in diff_diff/results.py:L653-L677.
• Methodology review looks clean: the PR extends the same fit-time normalization contract into the two diagnostic refits by normalizing snapshot arrays, passing zeta / Y_scale into Frank-Wolfe, and rescaling att / pre_fit_rmse back to original-Y units, matching diff_diff/synthetic_did.py:L419-L506, diff_diff/results.py:L1153-L1264, diff_diff/results.py:L1340-L1420, and docs/methodology/REGISTRY.md:L1522-L1534.
• I did not find a control-group, weighting, variance/SE, or assumption-check regression in the modified code. The shared SDID primitives and estimator contract remain unchanged in diff_diff/utils.py:L1500-L1713.
• Added coverage is aligned with the change: scale-parity regressions, extreme-scale finite diagnostics, and legacy-snapshot construction coverage were added in tests/test_methodology_sdid.py:L2301-L2563.
• Reviewer note: I could not execute the test suite in this environment because pytest and numpy are unavailable, so this is a source review plus test inspection.

Methodology

• No findings.

The PR changes library diagnostics rather than the paper-defined ATT or SE estimators. Within that scope, the implementation is consistent with the documented SDID contract: fit already normalizes Y, rescales user-visible outputs, and stores original-scale zeta_*/noise_level; the diagnostics now replay the same optimization problem on the normalized scale and report back on the original scale. That is a documented numerical-stability extension, not an undocumented methodology deviation. See diff_diff/synthetic_did.py:L419-L506, diff_diff/results.py:L1153-L1264, diff_diff/results.py:L1340-L1420, and docs/methodology/REGISTRY.md:L1522-L1534.

Code Quality

• No findings.

The snapshot plumbing is narrow and backward compatible: Y_shift and Y_scale were added as defaulted trailing fields, and the only production constructor updated is the fit path. See diff_diff/results.py:L653-L677 and diff_diff/synthetic_did.py:L659-L671.

Performance

• No findings.

The extra subtraction/division is confined to post-fit diagnostics and does not touch the main fit or variance hot paths.

Maintainability

• No findings.

The implementation, registry note, and new tests now describe the same diagnostic normalization contract, which reduces future drift risk.

Tech Debt

• No findings.

I did not see a new silent-correctness issue that would need TODO tracking, and there is no conflicting tracked limitation in TODO.md that changes the assessment.

Security

• No findings.

The retained fit snapshot is still excluded from pickling, so the new fields do not widen the serialization/privacy surface. See diff_diff/results.py:L808-L823.

Documentation/Tests

• No findings.

The registry update accurately describes the new behavior, and the added tests cover the right regression surfaces for this PR. See docs/methodology/REGISTRY.md:L1522-L1534 and tests/test_methodology_sdid.py:L2301-L2563.