feat(diagnostic_report): register SpilloverDiDResults routing (#599)

Route DiagnosticReport(spillover_result) to parallel_trends (event-study on
the per-event-time direct-effect dynamics), design_effect (survey fits), and
heterogeneity by adding SpilloverDiDResults to _APPLICABILITY / _PT_METHOD.
Add the coupled describe_target_parameter branch (aggregation="spillover",
headline att). Goodman-Bacon is deliberately excluded: SpilloverDiD identifies
the direct effect off far-away control units (Butts Assumption 5), not off the
TWFE 2x2 comparisons a Bacon decomposition enumerates. Aggregate-only fits skip
parallel_trends with an estimator-accurate remediation (event_study=True
constructor kwarg, not aggregate='event_study').

Docs (REGISTRY/REPORTING/spillover.rst/llms-full/CHANGELOG) and TODO updated;
12 new tests (DR routing across event-study/survey/aggregate-only paths, BR
smoke, target-parameter branch).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: igerber

CHANGELOG.md

@@ -34,6 +34,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   still defers cluster with a warning).
 
 ### Changed
+- **`DiagnosticReport` now routes `SpilloverDiDResults`.** Previously a fitted
+  `SpilloverDiD` (Butts 2021) result matched no `_APPLICABILITY` / `_PT_METHOD` entry, so
+  `DiagnosticReport(spillover_result)` reported every check as `not_applicable`. It now routes
+  to parallel-trends (event-study joint test on the per-event-time direct-effect dynamics,
+  populated when `event_study=True`), design-effect (survey-weighted fits), and heterogeneity;
+  Goodman-Bacon is intentionally excluded because SpilloverDiD identifies off far-away control
+  units rather than TWFE 2×2 comparisons. Aggregate-only fits now skip parallel-trends with an
+  estimator-accurate remediation (`SpilloverDiD(..., event_study=True)`). `BusinessReport` and the
+  `describe_target_parameter` block pick up the routing automatically.
 - **`SyntheticControl` in-space / leave-one-out placebo diagnostics now distinguish structural `cv`
   infeasibility from solver non-convergence.** Under `v_method="cv"`, an excluded `in_space_placebo()`
   / `leave_one_out()` refit whose pseudo-treated (in-space) or reduced (leave-one-out) donor pool is

TODO.md

@@ -37,7 +37,6 @@ The `Origin` column (Actionable tables) and the `PR` column (Deferred tables) bo
 | TWFE's HC2/HC2-BM inline full-dummy build (`twfe.py:280-315`) duplicates the dummy-construction logic in `DifferenceInDifferences(fixed_effects=...)` (`estimators.py:478-486`). Extract a shared helper, or delegate TWFE's HC2/HC2-BM path to DiD's `fixed_effects=` branch (with TWFE-specific cluster-default threading), to reduce drift risk on FE naming / survey behavior / result-surface conventions. Substantive refactor — touches both estimators. | `twfe.py::fit`, `estimators.py::DifferenceInDifferences.fit` | follow-up | Heavy | Low |
 | Decide whether to formally deprecate `CallawaySantAnna.cluster=X` in favor of `survey_design=SurveyDesign(psu=X)` (the bare-cluster path already synthesizes a minimal SurveyDesign). Two equivalent paths = redundant surface. Mirrors the question for ImputationDiD / EfficientDiD / TwoStageDiD. | `staggered.py` | follow-up | Mid | Low |
 | `HeterogeneousAdoptionDiD` **event-study (Phase 2b)** continuous cluster= threading: Phase 2a static path now threads `cluster=` into `bias_corrected_local_linear` (cluster-robust CCT SE, unweighted + weighted). The per-horizon event-study path still ignores `cluster=` with a `UserWarning` because the `cband` sup-t bootstrap normalizes HC-scale perturbations by the analytical SE and would mix variance families under clustering (mirrors the mass-point `weights= + cluster= + cband=True` `NotImplementedError`). Needs a per-horizon clustered-bootstrap variance-family reconciliation. | `had.py::_fit_event_study` | Phase 2b | Mid | Low |
-| `SpilloverDiDResults` not registered in `DiagnosticReport`'s `_APPLICABILITY` / `_PT_METHOD` tables, so `DiagnosticReport(spillover_result)` doesn't route to event-study diagnostics. Decide which diagnostics apply (PT, pre-trends power, heterogeneity, design-effect) and add an end-to-end test. | `diagnostic_report.py` | Wave C | Mid | Low |
 
 ### Performance
 

diff_diff/_reporting_helpers.py

@@ -635,6 +635,26 @@ def describe_target_parameter(results: Any) -> Dict[str, Any]:
             "reference": "REGISTRY.md Sec. SyntheticControl",
         }
 
+    if name == "SpilloverDiDResults":
+        return {
+            "name": "total effect on the treated (Butts spillover-aware ATT)",
+            "definition": (
+                "The total effect on the treated ``tau_total`` from Butts (2021) "
+                "ring-indicator spillover DiD, identified off FAR-AWAY control "
+                "observations (``d_it > d_bar``, Assumption 5) rather than any "
+                "not-yet-/never-treated pool. The estimator decomposes into the "
+                "DIRECT effect on treated units plus per-ring spillover-on-control "
+                "effects that relax SUTVA within the treated units' spatial "
+                "neighborhood; ``att`` is the headline total effect, while the "
+                "per-ring ``spillover_effects`` and (when ``event_study=True``) the "
+                "per-event-time direct dynamics are available on the result object "
+                "for disaggregated inference."
+            ),
+            "aggregation": "spillover",
+            "headline_attribute": "att",
+            "reference": "Butts (2021); REGISTRY.md Sec. SpilloverDiD",
+        }
+
     # Default: unrecognized result class. Fall through with a neutral
     # block — agents / downstream consumers can still dispatch on
     # ``aggregation="unknown"`` and fall back to generic ATT narration.

diff_diff/diagnostic_report.py

@@ -65,16 +65,16 @@
     "placebo",
 )
 
-# Type-level applicability: which checks are *ever* applicable for each of the
-# 16 result types. Instance-level applicability further filters by whether
+# Type-level applicability: which checks are *ever* applicable for each
+# registered result type. Instance-level applicability further filters by whether
 # required attributes are present (e.g. ``survey_metadata`` for DEFF) and by
 # whether the user disabled a check via ``run_*=False``.
 # See ``docs/methodology/REPORTING.md`` for the full matrix and rationale.
 #
 # Implementation note: The keys are result-class names looked up via
 # ``type(results).__name__``. This string-based dispatch mirrors the
 # ``_HANDLERS`` pattern in ``diff_diff/practitioner.py`` and avoids circular
-# imports across the 16 result modules. Renaming or aliasing any result class
+# imports across the result modules. Renaming or aliasing any result class
 # requires updating both this table and ``_PT_METHOD`` below; the
 # applicability-matrix test parametrized over all result types serves as the
 # regression guard.
@@ -131,6 +131,27 @@
             "heterogeneity",
         }
     ),
+    "SpilloverDiDResults": frozenset(
+        # Butts (2021) ring-indicator spillover DiD is a two-stage-GMM
+        # estimator, so it inherits TwoStage's diagnostic set MINUS
+        # ``bacon``. ``bacon`` is excluded because SpilloverDiD identifies
+        # the direct effect off FAR-AWAY units (Butts Assumption 5), not
+        # off the TWFE 2x2 comparisons a Goodman-Bacon decomposition
+        # enumerates: ``bacon_decompose`` on the raw binary treatment
+        # ignores the ring/distance structure and would pool spillover-
+        # contaminated in-ring units into the control group — the exact
+        # SUTVA violation the estimator exists to handle (same rationale
+        # that excludes bacon for SyntheticControl / TROP / Continuous).
+        # ``parallel_trends`` routes to ``event_study`` on the per-event-
+        # time DIRECT-effect dynamics (populated when ``event_study=True``);
+        # ``design_effect`` is instance-gated on ``survey_metadata`` (Wave
+        # E.1); ``heterogeneity`` reads ``event_study_effects``.
+        {
+            "parallel_trends",
+            "design_effect",
+            "heterogeneity",
+        }
+    ),
     "StackedDiDResults": frozenset(
         {
             "parallel_trends",
@@ -218,6 +239,7 @@
     "SunAbrahamResults": "event_study",
     "ImputationDiDResults": "event_study",
     "TwoStageDiDResults": "event_study",
+    "SpilloverDiDResults": "event_study",
     "StackedDiDResults": "event_study",
     "EfficientDiDResults": "hausman",
     "ContinuousDiDResults": "event_study",
@@ -263,7 +285,7 @@ class DiagnosticReport:
     ----------
     results : Any
         A fitted diff-diff results object (e.g. ``CallawaySantAnnaResults``,
-        ``DiDResults``, ``SyntheticDiDResults``). Any of the 16 result types
+        ``DiDResults``, ``SyntheticDiDResults``). Any registered result type
         in the library is accepted.
     data : pandas.DataFrame, optional
         The underlying panel. Required for checks that need raw data
@@ -703,6 +725,19 @@ def _instance_skip_reason(self, check: str) -> Optional[str]:
                 # summary emits the "inconclusive" identifying-
                 # assumption warning rather than silently dropping PT.
                 if not pre_coefs and n_dropped_undefined == 0:
+                    # SpilloverDiD's event-study switch is the
+                    # ``SpilloverDiD(..., event_study=True)`` constructor
+                    # kwarg, not the ``aggregate='event_study'`` argument
+                    # the generic staggered-estimator message points at
+                    # (SpilloverDiD has no ``aggregate`` kwarg). Emit an
+                    # estimator-accurate remediation for this family.
+                    if name == "SpilloverDiDResults":
+                        return (
+                            "No pre-period event-study coefficients are exposed "
+                            "on this fit. Re-fit with "
+                            "SpilloverDiD(..., event_study=True) to populate the "
+                            "per-event-time direct-effect output."
+                        )
                     return (
                         "No pre-period event-study coefficients are exposed on "
                         "this fit. For staggered estimators, re-fit with "

diff_diff/guides/llms-full.txt

@@ -514,7 +514,7 @@ sp.fit(
 - `covariates=` raises `NotImplementedError` (planned follow-up). Gardner two-stage requires covariate effects estimated on the untreated-and-unexposed Omega_0 subsample at stage 1; appending raw covariates only at stage 2 silently biases `tau_total` / `delta_j` on panels with time-varying covariates.
 - `survey_design=` is **supported** (Wave E): design-based variance via Binder (1983) Taylor-series linearization for `vcov_type="hc1"` (HC1) and `cluster=<col>` (CR1), and for `vcov_type="conley"` via a panel-aware stratified-Conley sandwich on per-period PSU totals (`conley_lag_cutoff > 0` adds a within-PSU serial Bartlett HAC and requires an effective PSU — supply `survey_design.psu` or inject one via `cluster=<col>`). Accepts `pweight` with strata / PSU / FPC. Replicate-weight variance (BRR / Fay / JK1 / JKn / SDR) is NOT yet supported (`NotImplementedError`): per Gerber (2026) Appendix A the IF-reweighting shortcut does not apply because `gamma_hat` is weight-sensitive, so correct support requires a per-replicate full re-fit.
 - `vcov_type="classical"` raises `NotImplementedError` (Wave D restriction). Wave D GMM first-stage correction has not been derived for the homoskedastic meat structure `sigma_hat^2 * (X_10' X_10)`. Use `vcov_type="hc1"`, `vcov_type="conley"`, or pair with `cluster=<col>` for CR1 — all three apply the Wave D GMM correction.
-- `event_study=True` SHIPPED (Wave C): emits per-event-time `tau_k` and per-(ring, event-time) `delta_jk` as `att_dynamic: pd.DataFrame` (indexed by event-time `k`) plus MultiIndex `spillover_effects: pd.DataFrame` (levels `(ring_label, event_time)`). TwoStageDiD-compatible `event_study_effects: Dict[int, Dict]` alias also emitted for `plot_event_study` consumption — `_extract_plot_data` prefers the new `reference_period` attribute over the legacy `n_obs==0` heuristic. (DiagnosticReport integration: NOT yet wired; queued as a follow-up.) (schema: `{k: {"effect", "se", "n_obs", "t_stat", "p_value", "conf_int": (low, high)}}` mirroring `two_stage.py:1355-1389`). Reference period `ref_period = -1 - anticipation` (TwoStageDiD `two_stage.py:486` convention); reference row uses `coef=0.0, se=0.0, n_obs=0, conf_int=(0.0, 0.0)`. Scalar `att` field becomes a sample-share-weighted average of post-treatment `tau_k` (`att = sum_{k>=0} w_k * tau_k` with `w_k = n_treated_at_k / total`) with SE from linear-combination inference `Var(att) = w' V_subset w` on the post-treatment vcov block — no separate fit. **Two-clock K_it:** direct-effect clock is `K_direct = t - effective_first_treat(i)` for ever-treated rows; spillover clock is `K_spill = t - earliest-in-range-cohort-onset(i)` (running min across activated cohorts, NaN pre-trigger). `K_spill >= 0` structurally; negative-k spillover cells are rectangularly emitted with `coef = NaN, n_obs = 0`. **`horizon_max` semantics:** bins event-times outside `[-H, +H]` into endpoint pools (no observations dropped — divergence from TwoStageDiD which filters; intentional, per `feedback_no_silent_failures`). With `horizon_max=None`, auto-detects bin set from observed K. **Validation:** `horizon_max < 0` raises `ValueError`; `ref_period < -horizon_max` (i.e., `anticipation > horizon_max - 1`) raises `ValueError` — silently floor-shifting the reference would change identification. **Reduce-to-aggregate:** under constant-tau DGP with `horizon_max=None`, the share-weighted scalar `att` reproduces Wave B's aggregate bit-identically. **Note:** `horizon_max=0` does NOT reduce to Wave B (binning collapses pre-treatment K values to `k=0`, making `D^0 = D_i` ever-treated indicator rather than `D_it`). Per-event-time SEs include the Wave D Gardner GMM first-stage correction (see next bullet).
+- `event_study=True` SHIPPED (Wave C): emits per-event-time `tau_k` and per-(ring, event-time) `delta_jk` as `att_dynamic: pd.DataFrame` (indexed by event-time `k`) plus MultiIndex `spillover_effects: pd.DataFrame` (levels `(ring_label, event_time)`). TwoStageDiD-compatible `event_study_effects: Dict[int, Dict]` alias also emitted for `plot_event_study` consumption — `_extract_plot_data` prefers the new `reference_period` attribute over the legacy `n_obs==0` heuristic. (DiagnosticReport integration: WIRED — `SpilloverDiDResults` routes to parallel_trends (event-study on these direct-effect dynamics), design_effect, and heterogeneity; bacon excluded since spillover identifies off far-away controls, not TWFE 2x2 comparisons.) (schema: `{k: {"effect", "se", "n_obs", "t_stat", "p_value", "conf_int": (low, high)}}` mirroring `two_stage.py:1355-1389`). Reference period `ref_period = -1 - anticipation` (TwoStageDiD `two_stage.py:486` convention); reference row uses `coef=0.0, se=0.0, n_obs=0, conf_int=(0.0, 0.0)`. Scalar `att` field becomes a sample-share-weighted average of post-treatment `tau_k` (`att = sum_{k>=0} w_k * tau_k` with `w_k = n_treated_at_k / total`) with SE from linear-combination inference `Var(att) = w' V_subset w` on the post-treatment vcov block — no separate fit. **Two-clock K_it:** direct-effect clock is `K_direct = t - effective_first_treat(i)` for ever-treated rows; spillover clock is `K_spill = t - earliest-in-range-cohort-onset(i)` (running min across activated cohorts, NaN pre-trigger). `K_spill >= 0` structurally; negative-k spillover cells are rectangularly emitted with `coef = NaN, n_obs = 0`. **`horizon_max` semantics:** bins event-times outside `[-H, +H]` into endpoint pools (no observations dropped — divergence from TwoStageDiD which filters; intentional, per `feedback_no_silent_failures`). With `horizon_max=None`, auto-detects bin set from observed K. **Validation:** `horizon_max < 0` raises `ValueError`; `ref_period < -horizon_max` (i.e., `anticipation > horizon_max - 1`) raises `ValueError` — silently floor-shifting the reference would change identification. **Reduce-to-aggregate:** under constant-tau DGP with `horizon_max=None`, the share-weighted scalar `att` reproduces Wave B's aggregate bit-identically. **Note:** `horizon_max=0` does NOT reduce to Wave B (binning collapses pre-treatment K values to `k=0`, making `D^0 = D_i` ever-treated indicator rather than `D_it`). Per-event-time SEs include the Wave D Gardner GMM first-stage correction (see next bullet).
 - Stage-2 variance applies the Gardner GMM first-stage uncertainty correction across HC1 / Conley / cluster (Wave D, SHIPPED). The IF outer-product formula `psi_i = gamma_hat' X_{10,i} eps_{10,i} - X_{2,i} eps_{2,i}` is used unconditionally; kernel `K` is path-dependent (identity for HC1, block-indicator for cluster, spatial kernel for Conley). Documented synthesis of Butts (2021) §3.1 + Gardner (2022) §4 + Conley (1999); no reference software combines all three. Point estimates unchanged from Wave B/C; SE values shift upward by 1-few percent.
 - Only nearest-treated rings supported; `ring_method="count"` (count of treated neighbors in ring) not yet exposed
 
@@ -2342,7 +2342,7 @@ DIFF_DIFF_BACKEND=rust pytest     # Force Rust (fail if unavailable)
 
 ## BusinessReport
 
-Plain-English stakeholder narrative from any of the 16 fitted result types.
+Plain-English stakeholder narrative from any fitted result type.
 Renders `summary()` (short paragraph), `full_report()` (multi-section
 markdown), and `to_dict()` (stable AI-legible schema — single source of
 truth; prose renders from the dict).

diff_diff/results.py

@@ -434,9 +434,11 @@ class SpilloverDiDResults(DiDResults):
     # TwoStageDiD-compatible alias for ``att_dynamic`` consumable by
     # ``plot_event_study`` (wired in Wave C via the ``reference_period``
     # attribute fallback in ``_extract_plot_data``). ``DiagnosticReport``
-    # routing is NOT yet wired — registering ``SpilloverDiDResults`` in
-    # ``DiagnosticReport``'s applicability/method tables is a planned
-    # follow-up (see TODO.md).
+    # routing is now wired: ``SpilloverDiDResults`` is registered in
+    # ``DiagnosticReport``'s ``_APPLICABILITY`` / ``_PT_METHOD`` tables with
+    # applicable checks {parallel_trends (event-study on these direct-effect
+    # dynamics), design_effect, heterogeneity}; bacon is excluded (spillover
+    # identifies off far-away units, not TWFE 2x2 comparisons).
     # Schema mirrors ``two_stage.py:1355-1389``:
     #   {k: {"effect", "se", "n_obs", "t_stat", "p_value", "conf_int": (low, high)}}
     # Reference row uses ``conf_int = (0.0, 0.0)`` (TwoStageDiD parity).

docs/api/spillover.rst

@@ -196,7 +196,10 @@ and planned follow-up enhancements:
   ``TwoStageDiD``'s schema for ``plot_event_study`` consumption (the
   plotter prefers the new ``reference_period`` attribute over the
   legacy ``n_obs==0`` heuristic). ``DiagnosticReport`` routing for
-  ``SpilloverDiDResults`` is queued as a follow-up. Reference
+  ``SpilloverDiDResults`` is wired: parallel-trends (event-study on
+  the direct-effect dynamics), design-effect, and heterogeneity apply;
+  Goodman-Bacon is excluded (spillover identifies off far-away
+  controls, not TWFE 2x2 comparisons). Reference
   period ``-1 - anticipation`` (TwoStageDiD parity). ``horizon_max``
   bins event-times into endpoint pools (no row drop — divergence
   from TwoStageDiD's filtering semantic, intentional per