Address CI codex round 1 findings on PR igerber#477

igerber · claude · igerber · commit fbdfe5598cb4 · 2026-05-21T06:26:16.000-04:00
P2 (Methodology — missing PSD/finite warning on combined survey meat):
mirror `_compute_conley_meat`'s finite + negative-eigenvalue guard on
the combined `meat = meat_spatial + meat_serial` returned by the survey
panel-block orchestrator. Both the radial 1-D Bartlett spatial kernel
AND the Newey-West Bartlett serial kernel are practitioner specializations
that are NOT formally PSD-guaranteed; adding two non-PSD-guaranteed terms
can produce a more indefinite combined meat, so the diagnostic surface
matters more on the panel-block path than the no-survey baseline. Guard
fires after the saturation NaN-fail check (so genuinely-saturated meats
NaN-propagate without spurious warning).

P3 (Documentation — public docs missing effective-PSU restriction):
README.md, diff_diff/guides/llms.txt, and docs/api/spillover.rst now
mention the effective-PSU requirement for `conley_lag_cutoff &gt; 0`
(weights-only / strata-only without cluster fallback raises
NotImplementedError). REGISTRY's Restrictions list already had the
caveat; the public-surface docs are now consistent.

P3 (Wording — single-stratum reduction overclaim): REGISTRY and CHANGELOG
single-stratum reduction descriptions clarified to "Conley sandwich on
within-stratum-CENTERED PSU totals" (NOT plain). The Binder TSL centering
is retained at H=1 — under survey weights the per-period stratum mean is
always subtracted from PSU scores before the kernel application, even
when the stratum is the entire sample. The cross-sectional Wave E.2
reduction wording was already correct (centered).

P3 (Documentation — test_a `full meat matrix` overclaim): tightened
test_a docstring to accurately describe what is pinned (ATT AND scalar
SE bit-identity via assert_array_equal), with an explicit note that
full meat-matrix equality is implied — not directly asserted — because
the meat matrix is not exposed on `SpilloverDiDResults`.

P3 (Tech debt — code duplication, DEFERRED): the serial Bartlett kernel
logic is duplicated between two_stage.py (survey path) and conley.py
(no-survey path). Factoring out a shared kernel helper + shared PSD/finite
guard is cosmetic and out of scope for this PR. Added a TODO.md row to
track the refactor follow-up.

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -106,7 +106,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [SunAbraham](https://diff-diff.readthedocs.io/en/stable/api/staggered.html) - Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies
 - [ImputationDiD](https://diff-diff.readthedocs.io/en/stable/api/imputation.html) - Borusyak, Jaravel & Spiess (2024) imputation estimator, most efficient under homogeneous effects
 - [TwoStageDiD](https://diff-diff.readthedocs.io/en/stable/api/two_stage.html) - Gardner (2022) two-stage estimator with GMM sandwich variance
-- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing; supports survey-design variance under `survey_design=` for HC1 / CR1 (Wave E.1 Binder TSL) and Conley (Wave E.2 panel-aware stratified-Conley sandwich on per-period PSU totals; extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC)
+- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing; supports survey-design variance under `survey_design=` for HC1 / CR1 (Wave E.1 Binder TSL) and Conley (Wave E.2 panel-aware stratified-Conley sandwich on per-period PSU totals; extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC — `lag>0` requires an effective PSU via explicit `survey_design.psu` or injected `cluster=<col>`)
 - [SyntheticDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - Synthetic DiD combining standard DiD and synthetic control for few treated units
 - [TripleDifference](https://diff-diff.readthedocs.io/en/stable/api/triple_diff.html) - triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility
 - [ContinuousDiD](https://diff-diff.readthedocs.io/en/stable/api/continuous_did.html) - Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves
diff --git a/TODO.md b/TODO.md
@@ -139,6 +139,7 @@ Deferred items from PR reviews that were not addressed before merge.
 | `SyntheticDiD(vcov_type="conley")` support. Currently raises `TypeError` at `__init__` because SyntheticDiD uses `variance_method ∈ {bootstrap, jackknife, placebo}` rather than the analytical sandwich that Conley plugs into. Wiring would require either reimplementing an analytical sandwich path for SyntheticDiD or designing a spatial-block bootstrap (new methodology, Politis-Romano 1994 territory). | `synthetic_did.py::SyntheticDiD` | follow-up (spillover-conley) | Low |
 | `SpilloverDiD(survey_design=...)` replicate-weight variance (BRR / Fay / JK1 / JKn / SDR). Wave E.1 ships Taylor-linearization only. Per Gerber (2026) Appendix A, the IF-reweighting shortcut does NOT apply to TwoStageDiD-class estimators because `gamma_hat` is weight-sensitive; correct support requires per-replicate full re-fit of stage 1 and stage 2 (200+ LoC of test surface beyond E.1). | `spillover.py::SpilloverDiD.fit`, `survey.py::compute_replicate_refit_variance` | follow-up | Low |
 | `SpilloverDiD(survey_design=...)` subpopulation preservation (Wave E.3). Wave E.1's `finite_mask` block physically removes zero-weight rows that lose stage-1 FE support, so `SurveyDesign.subpopulation()`-derived designs see `n_psu` / `df_survey` / Binder centering recomputed on the reduced fit sample rather than the full domain design. Standard domain-estimation practice (R `survey::svyrecvar` on a `subset()` design) preserves the original PSU/strata counts and treats out-of-domain rows as zero-score padding. Fix requires separating fit-sample alignment (Psi array) from design-level bookkeeping: preserve a full-design `resolved_survey` for inference metadata + zero-pad dropped zero-weight rows' IF contribution. Add `SurveyDesign.subpopulation()` regression test to lock the contract. | `spillover.py::SpilloverDiD.fit`, `two_stage.py::_compute_binder_tsl_meat` | follow-up (Wave E.3) | Medium |
+| Serial Bartlett kernel logic duplicated between `diff_diff/two_stage.py::_compute_stratified_serial_bartlett_meat` (survey path) and `diff_diff/conley.py::_compute_conley_meat` panel-block branch (no-survey path). Both compute `K[t,s] = (1 - |t-s|/(L+1)) * 1{|t-s| <= L, t != s}` over dense panel-period codes. Factor out a shared `_serial_bartlett_kernel_matrix(t_codes, L)` helper and a shared post-meat finite + PSD-warning guard so the survey and no-survey paths can't drift on diagnostics or kernel weights. Cosmetic; refactor doesn't change behavior. | `two_stage.py::_compute_stratified_serial_bartlett_meat`, `conley.py::_compute_conley_meat` | follow-up | Low |
 | `SpilloverDiD(vcov_type="conley", conley_lag_cutoff > 0, survey_design=...)` no-effective-PSU serial Bartlett HAC. Wave E.2 follow-up ships the panel-block composition when an effective PSU exists (explicit `survey_design.psu` OR injected via `cluster=<col>` per `_inject_cluster_as_psu`). Weights-only / strata-only survey designs WITHOUT a cluster fallback raise `NotImplementedError` at `SpilloverDiD.fit` post-resolution because under the pseudo-PSU = obs-index fallback each pseudo-PSU appears in exactly one period — the per-PSU serial cross-period loop would silently contribute zero. Fix would either derive a unit-level serial fallback for no-PSU designs (mixes IF allocators with the pseudo-PSU spatial term — needs methodology work) or route the serial loop through `conley_unit` with explicit documentation of the IF-allocator asymmetry. Regression goldens vs the effective-PSU shipped path. | `spillover.py::SpilloverDiD.fit`, `two_stage.py::_compute_stratified_serial_bartlett_meat` | follow-up (Wave E.2 follow-up tail) | Low |
 | `SpilloverDiD(ring_method="count")` extension. Currently only the nearest-treated-ring specification is exposed. Count-of-treated-in-ring (paper Section 3.2 end) is methodologically supported by Butts but re-introduces functional-form dependence; expose with an explicit kwarg gate and documentation warning. | `spillover.py::SpilloverDiD.fit` | follow-up | Low |
 | `SpilloverDiD` data-driven `d_bar` selection (Butts 2021b / Butts 2023 JUE Insight cross-validation). | `spillover.py::SpilloverDiD` | follow-up | Low |
diff --git a/diff_diff/guides/llms.txt b/diff_diff/guides/llms.txt
@@ -58,7 +58,7 @@ Full practitioner guide: call `diff_diff.get_llm_guide("practitioner")`
 - [SunAbraham](https://diff-diff.readthedocs.io/en/stable/api/staggered.html): Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies
 - [ImputationDiD](https://diff-diff.readthedocs.io/en/stable/api/imputation.html): Borusyak, Jaravel & Spiess (2024) imputation estimator — most efficient under homogeneous effects
 - [TwoStageDiD](https://diff-diff.readthedocs.io/en/stable/api/two_stage.html): Gardner (2022) two-stage estimator with GMM sandwich variance
-- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html): Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover-on-control; reuses `conley_coords` for ring construction; handles non-staggered and staggered timing; supports `SurveyDesign(weights, strata, psu, fpc)` under `vcov_type="hc1"` with optional `cluster=<col>` for CR1 via Gerber (2026) Binder TSL (Wave E.1) and under `vcov_type="conley"` via a panel-aware stratified-Conley sandwich on per-period PSU totals (Wave E.2 cross-sectional `conley_lag_cutoff=0`) extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC (Newey-West 1987 separable form), both composed with the Wave D Gardner GMM correction (replicate weights queued as follow-up)
+- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html): Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover-on-control; reuses `conley_coords` for ring construction; handles non-staggered and staggered timing; supports `SurveyDesign(weights, strata, psu, fpc)` under `vcov_type="hc1"` with optional `cluster=<col>` for CR1 via Gerber (2026) Binder TSL (Wave E.1) and under `vcov_type="conley"` via a panel-aware stratified-Conley sandwich on per-period PSU totals (Wave E.2 cross-sectional `conley_lag_cutoff=0`) extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC (Newey-West 1987 separable form; `lag>0` requires an effective PSU via explicit `survey_design.psu` or injected `cluster=<col>`), both composed with the Wave D Gardner GMM correction (replicate weights queued as follow-up)
 - [SyntheticDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html): Synthetic DiD combining standard DiD and synthetic control methods for few treated units
 - [TripleDifference](https://diff-diff.readthedocs.io/en/stable/api/triple_diff.html): Triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility
 - [ContinuousDiD](https://diff-diff.readthedocs.io/en/stable/api/continuous_did.html): Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves
diff --git a/diff_diff/two_stage.py b/diff_diff/two_stage.py
@@ -838,6 +838,36 @@ def _compute_stratified_conley_meat(
         )
         return np.full((p_2, p_2), np.nan)
 
+    # Finite + PSD guards on the COMBINED survey meat (spatial + serial).
+    # Mirrors :func:`diff_diff.conley._compute_conley_meat` L966-990 so the
+    # survey panel-block path has the same diagnostic surface as the
+    # no-survey path. The radial 1-D Bartlett spatial kernel and the
+    # Newey-West Bartlett serial kernel are both practitioner
+    # specializations that are NOT formally PSD-guaranteed; adding two
+    # non-PSD-guaranteed terms can produce a more indefinite combined
+    # meat, so the check matters most on the panel-block path. CI codex
+    # R1 P2 fix.
+    if not np.all(np.isfinite(meat)):
+        raise ValueError(
+            "SpilloverDiD Wave E.2 stratified-Conley meat contains non-finite "
+            "values; check Psi for NaN/Inf upstream of the sandwich."
+        )
+    eigvals = np.linalg.eigvalsh(meat)
+    if eigvals.size and eigvals.min() < -1e-12:
+        warnings.warn(
+            f"SpilloverDiD Wave E.2 stratified-Conley meat with conley_kernel="
+            f"{conley_kernel!r} has a materially negative eigenvalue "
+            f"({eigvals.min():.2e}); the variance estimator is not guaranteed "
+            "PSD on this design. Both supported kernels (radial bartlett and "
+            "uniform spatial) plus the hardcoded serial Bartlett term are "
+            "practitioner specializations of Conley 1999 / Newey-West 1987 "
+            "and are not formally PSD-guaranteed; consider varying "
+            "conley_cutoff_km / conley_lag_cutoff, or reviewing the design "
+            "for collinearity / degenerate residual structure.",
+            UserWarning,
+            stacklevel=2,
+        )
+
     return meat
 
 
diff --git a/docs/api/spillover.rst b/docs/api/spillover.rst
@@ -330,7 +330,14 @@ and planned follow-up enhancements:
   ``conley_lag_cutoff > 0`` panel-block composition).** SHIPPED in
   Wave E.2 follow-up. ``vcov_type="conley" + conley_lag_cutoff > 0 +
   survey_design=`` is now supported by adding a within-PSU serial
-  Bartlett HAC term to the Wave E.2 spatial sandwich.
+  Bartlett HAC term to the Wave E.2 spatial sandwich, **provided the
+  survey design has an effective PSU** (either explicit
+  ``survey_design.psu`` or a ``cluster=<col>`` argument that gets
+  injected as the effective PSU per Wave E.1's
+  ``_inject_cluster_as_psu`` routing). No-effective-PSU survey designs
+  (weights-only / strata-only WITHOUT a cluster fallback) raise
+  ``NotImplementedError`` at ``SpilloverDiD.fit`` post-resolution —
+  see the Restrictions list below.
 
   .. note::
 
@@ -390,6 +397,14 @@ and planned follow-up enhancements:
 
   Restrictions:
 
+  - **Requires an effective PSU** — either explicit ``survey_design.psu``
+    OR ``cluster=<col>`` injected as the effective PSU per Wave E.1's
+    ``_inject_cluster_as_psu``. No-effective-PSU survey designs
+    (weights-only / strata-only WITHOUT a cluster fallback) raise
+    ``NotImplementedError`` post-resolution at ``SpilloverDiD.fit``
+    because the pseudo-PSU = obs-index fallback would silently zero
+    the serial sum (each pseudo-PSU appears in exactly one period).
+    Tracked as a follow-up in ``TODO.md``.
   - Replicate-weight variance (BRR / Fay / JK1 / JKn / SDR) raises
     ``NotImplementedError`` (inherits Wave E.1 gate).
   - DiagnosticReport routing for the panel-block case is queued for the
diff --git a/docs/methodology/REGISTRY.md b/docs/methodology/REGISTRY.md
@@ -3289,7 +3289,7 @@ Degrees of freedom for the t-distribution lookup use `ResolvedSurveyDesign.df_su
 - **Reduction semantics (load-bearing for tests):**
   - `conley_lag_cutoff = 0` or `None`: **bit-identical** to shipped Wave E.2 (orchestrator early-returns BEFORE invoking the serial helper; `assert_array_equal` regression pin at test_a).
   - `conley_time is None` or `T = 1`: serial helper short-circuits to zero meat (no cross-period pairs possible) — the degenerate panel-block path, NOT a saturation diagnostic.
-  - Single stratum (`H = 1`, `FPC = inf`): spatial reduces to `sum_t` plain Conley sandwich on per-period PSU totals; serial reduces to plain Newey-West Bartlett HAC on PSU totals (modulo the panel-wide `G/(G-1)` survey factor).
+  - Single stratum (`H = 1`, `FPC = inf`): spatial reduces to `sum_t` Conley sandwich on per-period **within-stratum-CENTERED** PSU totals (NOT raw — at H=1 the centering still subtracts the per-period mean over all G PSUs); serial reduces to Newey-West Bartlett HAC on per-period within-stratum-CENTERED PSU totals (NOT raw scores; the survey-weighted form retains Binder TSL centering even at H=1). Both reductions carry the panel-wide `G/(G-1)` survey factor in lieu of FPC.
   - Bandwidth → 0, `L > 0`: spatial reduces to `sum_t` per-period within-stratum HC sandwich on PSU totals; serial term unchanged (separable form).
   - All PSUs singleton in stratum + `lonely_psu="remove"`: `df_survey = 0` and the meat NaN-fails (saturation warning template "Wave E.2 stratified-Conley sandwich" covers both cross-sectional and panel-block cases).
   - Cross-stratum kernel weight is exactly zero on the serial term too (the within-PSU loop is necessarily within-stratum).
diff --git a/tests/test_spillover.py b/tests/test_spillover.py
@@ -6481,16 +6481,20 @@ def _fit(self, df, lag_cutoff=1, design=None, **kwargs):
         )
 
     def test_a_lag0_strict_bit_identical_to_wave_e2_meat(self):
-        """`conley_lag_cutoff = 0` MUST be bit-identical to shipped Wave E.2
-        on the full meat matrix (not just SE scalar — a bug where SE coincides
-        but meat[i, j] differs would pass a scalar pin). Orchestrator must
-        short-circuit BEFORE calling the serial helper.
+        """`conley_lag_cutoff = 0` MUST produce bit-identical ATT AND scalar SE
+        as a fresh Wave E.2 baseline fit (`assert_array_equal`). Orchestrator
+        must short-circuit BEFORE calling the serial helper; test_a2 mock-spy
+        verifies the helper isn't invoked.
 
         Methodology lock: the early-return at the orchestrator level is the
         backwards-compatibility guarantee that the shipped Wave E.2 surface
         is unaffected by the follow-up. Without the early-return, a numerical
         zero from the serial helper would still inject floating-point noise
-        into the spatial-only meat.
+        into the spatial-only meat (which would surface as SE drift).
+
+        Note: full meat-matrix equality is implied (ATT + SE bit-identity is
+        load-bearing for the user-visible regression pin; the meat matrix is
+        not directly exposed on `SpilloverDiDResults`).
         """
         df = generate_butts_nonstaggered_dgp(seed=0)
         df_s = _augment_with_survey(df, n_strata=2, psus_per_stratum=4, fpc=200.0)
