Merge pull request #570 from igerber/fix/or-nuisance-scale-equilibration

fix(staggered): scale-equilibrate CS / StaggeredTripleDiff covariate OR fits

Author: igerber

CHANGELOG.md

@@ -118,6 +118,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   numerical, or public-API change.
 
 ### Fixed
+- **`CallawaySantAnna` / `StaggeredTripleDifference` covariate outcome-regression is now
+  scale-robust.** The covariate OR nuisance fits — `_compute_all_att_gt_covariate_reg` and
+  `_doubly_robust` (CS) and `_compute_or` (StaggeredTripleDifference) — previously used an
+  estimator-local `cho_solve(X'X)` cache fast path (with bare `scipy.linalg.lstsq(cond=1e-7)`
+  fallbacks) that **bypassed the shared scale-equilibrated solver**. They now route through
+  `solve_ols` (column-equilibrated SVD/gelsd), matching `TripleDifference._fit_predict_mu` and
+  R's `lm()`/QR. A covariate **correlated with another regressor at a very large scale** (e.g. a
+  large constant offset, near-collinear with the intercept) could perturb the point-estimate ATT —
+  and the influence-function SE that follows it — because forming the normal equations squares the
+  condition number; the equilibrated SVD avoids this (offset-invariant to ~1e-11 where the prior
+  solve drifted, e.g. ~4e-6 at an offset of 1e6, growing with scale). Pure orthogonal ill-scaling
+  was already safe (diagonal `X'X`), so the practical impact is confined to ill-conditioned /
+  correlated covariate designs. **Not bit-identical** (cho/normal-equations → SVD) — well-scaled
+  designs move only ~1e-12, well under the R-parity tolerances; the existing CS covariate R-`did`
+  golden tests (`reg`/`ipw`) still pass, a new `with_covariates_dr` att+SE golden parity test is
+  added (R-parity at ~1e-3), and scale-invariance tests pin the fix. No change to estimands,
+  identifying assumptions, the no-covariate path, or the propensity-score fits.
 - **Corrected the Korn & Graubard (1990) citation venue** in `docs/methodology/REGISTRY.md`
   (Survey Degrees of Freedom) from *JASA* 85(409) to *The American Statistician* 44(4), 270-276
   — the survey-df / Bonferroni-t paper (DOI 10.1080/00031305.1990.10475737).

TODO.md

@@ -30,7 +30,6 @@ The `Origin` column (Actionable tables) and the `PR` column (Deferred tables) bo
 |-------|----------|--------|--------|----------|
 | `SyntheticControl` cv: thread an `"infeasible"` reason-code from `_outer_solve_V_cv()` / `_placebo_fit_unit()` so `in_space_placebo()` / `leave_one_out()` distinguish a structural cv-refit exclusion (donor-indistinguishable re-aggregated window) from a genuine inner-solver non-convergence — mirror the split `in_time_placebo()` already emits. Warnings already distinguish the two causes; only the machine-readable status/count is missing. | `synthetic_control.py`, `synthetic_control_results.py` | follow-up | Mid | Low |
 | `CallawaySantAnna`: materialize NaN entries for non-estimable `(g,t)` cells in `group_time_effects` (currently omitted with a consolidated warning); requires updating downstream consumers (event study, `balance_e`, aggregation). | `staggered.py` | #256 | Mid | Low |
-| `CallawaySantAnna` / `StaggeredTripleDifference` fit their covariate OR nuisance via estimator-local `cho_solve(X'X)` / `scipy.lstsq(cond=1e-7)` that bypass `solve_ols`, so they are NOT scale-equilibrated — a large-scale covariate can perturb the nuisance fit (`TripleDifference`'s OR fit already routes through `solve_ols`). Route the local OR fits through the shared scale-robust solver (or equilibrate locally). | `staggered.py`, `staggered_triple_diff.py` | covariate-review | Mid | Medium |
 | Adopt the shared `_rank_guarded_inv` for the *structural* (non-covariate) matrix inverses sharing the `LinAlgError`-only fallback that can go near-singular: `continuous_did.py:1056` (dose B-spline), `spillover.py:3371` (ring-solve, partially guarded), `two_stage.py:3154` (TSL Stage-2 variance), `imputation.py:2403`, `had.py:2413`, `conley.py:1109`. These invert internal bases users cannot perturb with `covariates=` (distinct from the already-fixed covariate-triggered SE bug); the helper is the seam. | `continuous_did.py`, `spillover.py`, `two_stage.py`, `imputation.py`, `had.py`, `conley.py` | dr-or-se-rank-guard | Mid | Low |
 | Survey-design resolution / collapse patterns are inconsistent across panel estimators — `ContinuousDiD` rebuilds unit-level design in SE code, `EfficientDiD` builds once in `fit()`, `StackedDiD` re-resolves on stacked data. Extract shared helpers for panel-to-unit collapse, post-filter re-resolution, and metadata recomputation. | `continuous_did.py`, `efficient_did.py`, `stacked_did.py` | #226 | Mid | Low |
 | `SyntheticControl` remaining ADH-2015 §4 items: the regression-weight `W^reg = X_0'(X_0 X_0')^{-1} X_1` extrapolation diagnostic (flag implied OLS weights outside `[0,1]`) and sparse-SC subset search (`l < J`, holding `V` fixed). LOO, in-time placebo, CV `V`-selection, and inverse-variance `V` have landed; these two are the deferred tail. | `synthetic_control.py`, `synthetic_control_results.py` | ADH-2015 | Mid | Low |