From 64cc8a2ce04c43a26194b2ed933d97491dab8a26 Mon Sep 17 00:00:00 2001
From: igerber <isaac.gerber@gmail.com>
Date: Tue, 26 May 2026 10:18:15 -0400
Subject: [PATCH 1/3] efficient-did: thread vcov_type as narrow {hc1} contract
 per Chen-Sant'Anna-Xie 2025 (Phase 1b interstitial #4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirrors the IF-based narrow-contract template from CallawaySantAnna #487,
TripleDifference #488, and ImputationDiD #492. EfficientDiD uses
influence-function-based variance per Chen-Sant'Anna-Xie (2025) achieving
the semiparametric efficiency bound; the per-unit EIF aggregation has no
equivalent single design matrix, so analytical-sandwich families cannot
be defined and vcov_type is permanently narrow to {"hc1"}.

Input contract:
- vcov_type kwarg threaded through __init__ / get_params / set_params
- _validate_vcov_type rejects {classical, hc2, hc2_bm} with methodology-rooted
  message citing Chen-Sant'Anna-Xie (2025) and the missing design matrix
- conley rejected as deferred (TODO.md follow-up row)
- set_params(vcov_type=bad) raises immediately via _validate_params chain
  (intentional eager-validation; diverges from sibling IF-based estimators
  which defer to fit-time per sklearn mutate-then-validate-at-use)

EfficientDiDResults harmonization (BC):
- cluster field renamed to cluster_name (matches IF-based estimator naming)
- New n_clusters field for the G=<n> suffix on the variance summary line
- New vcov_type field
- New to_dict() method (mirrors TripleDifferenceResults / ImputationDiDResults)
- summary() now renders "Variance estimator: <label>" after the survey block,
  suppressed under bootstrap (renders "Inference method: bootstrap" instead)
- Default cluster=None renders "HC1 heteroskedasticity-robust" — methodologically
  correct (per-unit EIF SE is HC1-style, no Liang-Zeger G/(G-1) correction);
  diverges from ImputationDiD which auto-clusters at unit per BJS Theorem 3
- DiagnosticReport._pt_hausman updated to read renamed cluster_name field

Bootstrap defensive fix:
- Survey-PSU multiplier bootstrap with G<2 PSUs collapses to constant draws
  → BLAS roundoff produces ≈0 SE (not NaN). Single-site guard at the
  survey-PSU branch returns NaN dicts keyed to the same (g,t)/event-time/
  group reductions the downstream override loop expects (cluster path
  already guards n_clusters≥2 at fit-time; unit path guarded upstream by
  balanced-panel validator).
- New _build_nan_bootstrap_results helper constructs the all-NaN object.

Tests (40 new in TestEfficientDiDVcovType across 7 surfaces):
- Default / cluster / TSL-survey / replicate-survey bit-equal parametrized
  over aggregate ∈ {None, event_study, group, all}
- Bootstrap × cluster + bootstrap × survey bit-equal (per-horizon + per-group
  SE override branches asserted)
- set_params eager revalidation
- Bootstrap n_psu<2 NaN propagation (regression on defensive fix)
- DR (covariates=) path bit-equal under explicit vcov_type="hc1"
- 5 input-rejection pins (classical/hc2/hc2_bm/conley/unknown)
- cluster + replicate_weights rejection (validates blanket guard at L357)
- 7 introspection tests (default attr, get_params, Results carries,
  to_dict default vs cluster, summary HC1 default vs CR1 cluster vs
  bootstrap-suppressed, cluster_name suppression under both analytical and
  replicate survey, fit-clone idempotence)

Documentation:
- REGISTRY.md: IF-based taxonomy "Enforced today" expanded to four-way
  (CS+TD+ImputationDiD+EfficientDiD); 3 EfficientDiD Notes added
- llms-full.txt: vcov_type added to EfficientDiD signature; shared
  staggered-results variance metadata section updated
- CHANGELOG [Unreleased] entry surfaces both vcov_type threading AND the
  Results-field BC break
- TODO.md Phase 1b row collapses to TwoStageDiD only (last remaining);
  new EfficientDiD Conley follow-up row added
- EfficientDiD class + module + Results docstrings updated

210 tests pass across test_efficient_did.py + test_efficient_did_validation.py
+ test_diagnostics.py. black + ruff clean.
---
 CHANGELOG.md                         |   5 +
 TODO.md                              |   5 +-
 diff_diff/diagnostic_report.py       |   2 +-
 diff_diff/efficient_did.py           |  86 +++-
 diff_diff/efficient_did_bootstrap.py |  94 ++++-
 diff_diff/efficient_did_results.py   |  94 ++++-
 diff_diff/guides/llms-full.txt       |   9 +-
 docs/methodology/REGISTRY.md         |  17 +-
 tests/test_efficient_did.py          | 608 +++++++++++++++++++++++++++
 9 files changed, 897 insertions(+), 23 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c0931e3f..4c34e2d8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added / Changed
+- **EfficientDiD `vcov_type` threading + Results metadata harmonization (Phase 1b interstitial #4, permanently narrow).** `EfficientDiD(vcov_type=...)` now accepts `{"hc1"}` only (default). Analytical-sandwich families `{classical, hc2, hc2_bm}` and `conley` are REJECTED at `__init__` / `set_params` with methodology-rooted messages — EfficientDiD uses influence-function-based variance per Chen-Sant'Anna-Xie (2025) achieving the semiparametric efficiency bound; the per-unit EIF aggregation has no single design matrix on which hat-matrix leverage or Bell-McCaffrey Satterthwaite DOF can be defined. `cluster=` (Liang-Zeger CR1 on cluster-aggregated EIF) and `survey_design=` (TSL on combined IF) paths are unchanged. **BC break on `EfficientDiDResults`:** the `cluster` field renamed to `cluster_name`; new `n_clusters` + `vcov_type` fields added; `to_dict()` method added (mirrors TripleDifferenceResults). `DiagnosticReport._pt_hausman` updated to read the renamed `cluster_name` field for the Hausman pretest replay (`diff_diff/diagnostic_report.py:2444`). `EfficientDiD.set_params(vcov_type=bad)` raises immediately rather than deferring to `fit()` — intentional eager-validation pattern matching EfficientDiD's existing handling of `pt_assumption`/`control_group` etc, diverging from `ImputationDiD`/`TripleDifference`/`CallawaySantAnna` (which use sklearn mutate-then-validate-at-use). Survey-PSU bootstrap path returns NaN SE when fewer than 2 independent PSUs are available (was ≈0 SE from BLAS roundoff). New summary block: `Variance estimator: <label>` line rendered after the survey block when not under bootstrap; suppressed under bootstrap (replaced with `Inference method: bootstrap` + `Bootstrap replications: <n>`). Default `cluster=None` (no survey) renders "HC1 heteroskedasticity-robust" — methodologically correct because the per-unit EIF SE `sqrt(mean(EIF²)/n)` is HC1-style (no Liang-Zeger G/(G-1) finite-sample correction); diverges from `ImputationDiD` which auto-clusters at unit per BJS Theorem 3.
+
 ## [3.4.2] - 2026-05-25
 
 ### Fixed
diff --git a/TODO.md b/TODO.md
index a4f15185..95a5a24e 100644
--- a/TODO.md
+++ b/TODO.md
@@ -104,7 +104,7 @@ Deferred items from PR reviews that were not addressed before merge.
 | PreTrendsPower: CS/SA `anticipation=1` R-parity fixture. The PR-C R-parity goldens cover NIS power + γ_p MDV at `atol=1e-4` on four shifted-grid / regular / irregular / K=1 fixtures, but R `pretrends` has no anticipation parameter so the Python-side `_extract_pre_period_params` anticipation filter (`if t < _pre_cutoff` in `pretrends.py` lines 1138-1150 for CS; mirror in SA branch) is not R-parity-locked. Build a synthetic `CallawaySantAnnaResults` (or `SunAbrahamResults`) with `anticipation=1` and a t=-1 event-study entry that should be filtered before reaching `_compute_power_nis`, then assert the resulting γ_p matches R's `slope_for_power()` on the K=4 shifted-grid fixture. Existing PR-B MC-based tests (`TestPretrendsPropositions`) and full-VCV tests (`TestPretrendsCovarianceSource`) already cover the filter mechanically; this would close the loop against R. | `tests/test_methodology_pretrends.py::TestPretrendsParityR`, `benchmarks/R/generate_pretrends_golden.R` | PR-C follow-up | Low |
 
 
-| Thread `vcov_type` (classical / hc1 / hc2 / hc2_bm) through the standalone estimators that expose `cluster=` but not yet `vcov_type=`: `TwoStageDiD`, `EfficientDiD`. Phase 1a added the chain to DiD/MPD/TWFE; Phase 1b PR 1/8 added `SunAbraham`; PR 2/8 added `StackedDiD`; PR 3/8 added `WooldridgeDiD` OLS path. **Three interstitial PRs (post-PR-3/8) addressed the IF-based estimators separately, each permanently narrow to `{"hc1"}`**: (a) `CallawaySantAnna` per Callaway & Sant'Anna (2021) Theorem 2 (also fixed CS's bare-`cluster=` silent no-op); (b) `TripleDifference` per Ortiz-Villavicencio & Sant'Anna (2025) on the 3-pairwise-DiD decomposition; (c) `ImputationDiD` per Borusyak-Jaravel-Spiess (2024) Theorem 3 on per-unit IF aggregation (also added defensive `n_clusters<2`/`n_psu<2` NaN guard on the bootstrap path + `cluster=` + replicate-weights `NotImplementedError`). Analytical-sandwich families don't compose with IF-based variance for any of the three. This row tracks the remaining 2 (`EfficientDiD` is also IF-based and will likely adopt the same narrow contract; `TwoStageDiD` is sandwich-class). | multiple | Phase 1b | Medium |
+| Thread `vcov_type` (classical / hc1 / hc2 / hc2_bm) through the standalone estimators that expose `cluster=` but not yet `vcov_type=`: `TwoStageDiD`. Phase 1a added the chain to DiD/MPD/TWFE; Phase 1b PR 1/8 added `SunAbraham`; PR 2/8 added `StackedDiD`; PR 3/8 added `WooldridgeDiD` OLS path. **Four interstitial PRs (post-PR-3/8) addressed the IF-based estimators separately, each permanently narrow to `{"hc1"}`**: (a) `CallawaySantAnna` per Callaway & Sant'Anna (2021) Theorem 2 (also fixed CS's bare-`cluster=` silent no-op); (b) `TripleDifference` per Ortiz-Villavicencio & Sant'Anna (2025) on the 3-pairwise-DiD decomposition; (c) `ImputationDiD` per Borusyak-Jaravel-Spiess (2024) Theorem 3 on per-unit IF aggregation (also added defensive `n_clusters<2`/`n_psu<2` NaN guard on the bootstrap path + `cluster=` + replicate-weights `NotImplementedError`); (d) `EfficientDiD` per Chen-Sant'Anna-Xie (2025) EIF aggregation achieving the semiparametric efficiency bound (also renamed `EfficientDiDResults.cluster` → `cluster_name`, added `n_clusters`/`vcov_type` fields + `to_dict()`, added defensive survey-PSU n<2 NaN guard, eager set_params validation diverging from sibling IF-based estimators). Analytical-sandwich families don't compose with IF-based variance for any of the four. This row tracks the remaining 1 (`TwoStageDiD` is sandwich-class with GMM-corrected meat). | `diff_diff/two_stage.py` | Phase 1b | Medium |
 | Extend `SunAbraham` with `vcov_type="conley"` (Conley spatial-HAC) as a first-class feature: thread `conley_coords` / `conley_cutoff_km` / `conley_metric` / `conley_kernel` / `conley_time` / `conley_unit` / `conley_lag_cutoff` through `_fit_saturated_regression`. Phase 1b PR 1/8 deferred this; SA currently rejects `vcov_type="conley"` at `__init__` with a deferral message. | `diff_diff/sun_abraham.py` | follow-up | Medium |
 | Extend `StackedDiD` with `vcov_type="conley"` (Conley spatial-HAC) — thread the six `conley_*` params through `solve_ols` at `stacked_did.py:419` (and the `_refit_stacked` closure at `:444`). Phase 1b PR 2/8 deferred this; StackedDiD currently rejects `vcov_type="conley"` at `__init__` with a deferral message. Same shape as the SunAbraham conley follow-up. | `diff_diff/stacked_did.py` | follow-up | Medium |
 | Extend `WooldridgeDiD` with `vcov_type="conley"` — thread the six `conley_*` params through `solve_ols` in `_fit_ols`. Phase 1b PR 3/8 deferred this; WooldridgeDiD currently rejects `vcov_type="conley"` at `__init__` with a deferral message. Same shape as the SunAbraham / StackedDiD conley follow-ups. | `diff_diff/wooldridge.py` | follow-up | Medium |
@@ -112,6 +112,7 @@ Deferred items from PR reviews that were not addressed before merge.
 | Extend `CallawaySantAnna` with `vcov_type="conley"` — would require deriving a spatial-HAC composition for per-unit influence functions (Conley 1999 spatial kernel × per-(g,t) IF aggregation); no reference implementation exists today. Phase 1b interstitial PR rejected this at `__init__` with a deferral pointer here. | `diff_diff/staggered.py` | follow-up | Low |
 | Extend `TripleDifference` with `vcov_type="conley"` — would require deriving a spatial-HAC composition for the 3-pairwise-DiD influence-function decomposition (Conley 1999 spatial kernel × `inf = w3·IF_3 + w2·IF_2 - w1·IF_1` aggregation); no reference implementation exists today. Phase 1b interstitial #2 PR rejected this at `__init__` with a deferral pointer here. | `diff_diff/triple_diff.py` | follow-up | Low |
 | Extend `ImputationDiD` with `vcov_type="conley"` — would require deriving a spatial-HAC composition with the Theorem 3 per-unit IF aggregation (Conley 1999 spatial kernel × `sigma_sq = (cluster_psi_sums**2).sum()` reduction); no reference implementation exists today. Phase 1b interstitial #3 PR rejected this at `__init__` with a deferral pointer here. | `diff_diff/imputation.py` | follow-up | Low |
+| Extend `EfficientDiD` with `vcov_type="conley"` — would require deriving a spatial-HAC composition with the per-unit EIF aggregation (Conley 1999 spatial kernel × `_compute_se_from_eif` reduction); no reference implementation exists today. Phase 1b interstitial #4 PR rejected this at `__init__` with a deferral pointer here. | `diff_diff/efficient_did.py` | follow-up | Low |
 | Decide whether to formally deprecate `CallawaySantAnna.cluster=X` in favor of `survey_design=SurveyDesign(psu=X)`. Both APIs are first-class today (the bare-cluster path synthesizes a minimal SurveyDesign internally), but having two equivalent paths to express the same intent creates redundant surface. Mirrors a similar question for ImputationDiD / EfficientDiD / TwoStageDiD if those estimators ever face the same review. | `diff_diff/staggered.py` | follow-up | Low |
 | Harmonize SunAbraham's HC1 within-transform finite-sample correction with `fixest::sunab()`. SA's `solve_ols` applies `n / (n - k_dm)` (within-transform columns only); fixest applies `n / (n - k_total)` (counts absorbed FE). SE values differ by ~1-2% on typical panel sizes (documented in REGISTRY.md "Deviation from R"; pinned at `atol=5e-3` in `tests/test_methodology_sun_abraham.py`). Either thread `df_adjustment` into the vcov scaling or document as an intentional difference. | `diff_diff/sun_abraham.py`, `diff_diff/linalg.py::compute_robust_vcov` | follow-up | Low |
 <!-- Rows 104-105 LIFTED 2026-05-20 via the clubSandwich WLS-CR2 port. The diff-diff
@@ -203,7 +204,7 @@ Ordered paydown view across the tables above. Tier A → D is by effort × risk,
 
 #### Tier B — Mid-size methodology (5-10 CI rounds expected, per memory cascade priors)
 
-- Thread `vcov_type` through the 2 remaining standalone estimators: `TwoStageDiD`, `EfficientDiD` (Phase 1b PR 1/8 added SunAbraham, PR 2/8 added StackedDiD, PR 3/8 added WooldridgeDiD-OLS; interstitial #1 narrowed CallawaySantAnna permanently to `{hc1}` per IF-based variance + fixed bare-`cluster=` silent no-op; interstitial #2 narrowed TripleDifference permanently to `{hc1}` per IF-based variance on the 3-pairwise-DiD decomposition; interstitial #3 narrowed ImputationDiD permanently to `{hc1}` per IF-based variance on Theorem 3 per-unit IF aggregation + defensive bootstrap n_psu<2/n_clusters<2 NaN guard)
+- Thread `vcov_type` through the 1 remaining standalone estimator: `TwoStageDiD` (Phase 1b PR 1/8 added SunAbraham, PR 2/8 added StackedDiD, PR 3/8 added WooldridgeDiD-OLS; interstitial #1 narrowed CallawaySantAnna permanently to `{hc1}` per IF-based variance + fixed bare-`cluster=` silent no-op; interstitial #2 narrowed TripleDifference permanently to `{hc1}` per IF-based variance on the 3-pairwise-DiD decomposition; interstitial #3 narrowed ImputationDiD permanently to `{hc1}` per IF-based variance on Theorem 3 per-unit IF aggregation + defensive bootstrap n_psu<2/n_clusters<2 NaN guard; interstitial #4 narrowed EfficientDiD permanently to `{hc1}` per IF-based variance on Chen-Sant'Anna-Xie 2025 EIF aggregation + renamed `EfficientDiDResults.cluster` to `cluster_name` + added `n_clusters`/`vcov_type` fields + `to_dict()` + defensive survey-PSU n<2 NaN guard + eager set_params validation)
 - SyntheticDiD: rename internal `placebo_effects` → `variance_effects` AND public `placebo_effects` field with deprecation alias retained for one release (`synthetic_did.py`, `results.py`)
 - StaggeredTripleDifference R parity: commit CSV fixtures + add covariate-adjusted scenarios + aggregation-SE assertions (`tests/test_methodology_staggered_triple_diff.py`, `benchmarks/R/benchmark_staggered_triplediff.R`)
 - StaggeredTripleDifference: per-cohort group-effect SE WIF override for exact R `triplediff` match (`staggered_triple_diff.py`)
diff --git a/diff_diff/diagnostic_report.py b/diff_diff/diagnostic_report.py
index 6645bb0d..cdfdf21a 100644
--- a/diff_diff/diagnostic_report.py
+++ b/diff_diff/diagnostic_report.py
@@ -2441,7 +2441,7 @@ def _pt_hausman(self) -> Dict[str, Any]:
         fit_anticipation = getattr(r, "anticipation", None)
         if isinstance(fit_anticipation, (int, float)) and np.isfinite(fit_anticipation):
             hausman_kwargs["anticipation"] = int(fit_anticipation)
-        fit_cluster = getattr(r, "cluster", None)
+        fit_cluster = getattr(r, "cluster_name", None)
         if isinstance(fit_cluster, str) and fit_cluster:
             hausman_kwargs["cluster"] = fit_cluster
 
diff --git a/diff_diff/efficient_did.py b/diff_diff/efficient_did.py
index 1f3e48ca..3a71a411 100644
--- a/diff_diff/efficient_did.py
+++ b/diff_diff/efficient_did.py
@@ -10,6 +10,16 @@
 Under PT-All the model is overidentified and EDiD exploits this for
 tighter inference; under PT-Post it reduces to the standard
 single-baseline estimator (Callaway-Sant'Anna).
+
+The variance machinery is purely influence-function-based: per-unit EIF
+values aggregate via ``sqrt(mean(EIF**2)/n)`` (unclustered, HC1-style),
+Liang-Zeger CR1 on cluster-aggregated EIF (under ``cluster=``), or
+Taylor Series Linearization on the combined IF (under ``survey_design=``).
+Because the per-unit EIF aggregation has no equivalent single design
+matrix, analytical-sandwich families ``{classical, hc2, hc2_bm}`` cannot
+be defined and the ``vcov_type`` input contract is permanently narrow to
+``{"hc1"}`` — see ``docs/methodology/REGISTRY.md`` "IF-based variance
+estimators vs analytical-sandwich estimators" for the structural rationale.
 """
 
 import warnings
@@ -158,6 +168,16 @@ class EfficientDiD(EfficientDiDBootstrapMixin):
         use the Liang-Zeger clustered sandwich estimator on EIF values.
         With ``n_bootstrap > 0``, bootstrap weights are generated at the
         cluster level (all units in a cluster share the same weight).
+    vcov_type : str, default ``"hc1"``
+        Variance-estimator family. Permanently narrow to ``{"hc1"}`` per
+        the Chen-Sant'Anna-Xie (2025) IF-based variance — analytical-sandwich
+        families ``{classical, hc2, hc2_bm}`` and ``conley`` are rejected
+        at ``__init__`` / ``set_params``. See REGISTRY.md for the
+        methodology rationale (no single design matrix on which hat-matrix
+        leverage or Bell-McCaffrey Satterthwaite DOF can be defined).
+        Use ``cluster=<col>`` for Liang-Zeger CR1 on cluster-aggregated EIF;
+        use ``survey_design=`` for Taylor Series Linearization on the
+        combined IF.
     control_group : str, default ``"never_treated"``
         Which units serve as the comparison group:
         ``"never_treated"`` requires a never-treated cohort (raises if
@@ -203,6 +223,7 @@ def __init__(
         pt_assumption: str = "all",
         alpha: float = 0.05,
         cluster: Optional[str] = None,
+        vcov_type: str = "hc1",
         control_group: str = "never_treated",
         n_bootstrap: int = 0,
         bootstrap_weights: str = "rademacher",
@@ -216,6 +237,7 @@ def __init__(
         self.pt_assumption = pt_assumption
         self.alpha = alpha
         self.cluster = cluster
+        self.vcov_type = vcov_type
         self.control_group = control_group
         self.n_bootstrap = n_bootstrap
         self.bootstrap_weights = bootstrap_weights
@@ -263,6 +285,50 @@ def _validate_params(self) -> None:
                     f"sieve_k_max must be a positive integer (or None for auto), "
                     f"got {self.sieve_k_max}"
                 )
+        self._validate_vcov_type(self.vcov_type)
+
+    @staticmethod
+    def _validate_vcov_type(vcov_type: str) -> None:
+        """Validate ``vcov_type`` against EfficientDiD's narrow IF-based contract.
+
+        Permanently accepts ``{"hc1"}`` only — EfficientDiD uses
+        influence-function-based variance per Chen-Sant'Anna-Xie (2025) achieving
+        the semiparametric efficiency bound. The per-unit EIF aggregation has no
+        equivalent single design matrix, so analytical-sandwich families
+        (``classical``, ``hc2``, ``hc2_bm``) cannot be defined; ``conley`` is
+        deferred (see TODO.md). Mirrors the narrow-contract pattern in
+        :class:`ImputationDiD`, :class:`CallawaySantAnna`, and
+        :class:`TripleDifference`.
+        """
+        _accepted_vcov = {"hc1"}
+        _if_incompatible_vcov = {"classical", "hc2", "hc2_bm"}
+        _deferred_vcov = {"conley"}
+
+        if vcov_type in _if_incompatible_vcov:
+            raise ValueError(
+                f"EfficientDiD(vcov_type={vcov_type!r}) is rejected: "
+                f"EfficientDiD uses influence-function-based variance per Chen, "
+                f"Sant'Anna, and Xie (2025) achieving the semiparametric efficiency "
+                f"bound for ATT(g,t). The per-unit EIF aggregation has no equivalent "
+                f"single design matrix on which hat matrix leverage or Bell-McCaffrey "
+                f"Satterthwaite DOF can be defined, so analytical-sandwich families "
+                f"{{classical, hc2, hc2_bm}} are not paper-prescribed. Use "
+                f"vcov_type='hc1' (the default) with cluster=<col> for the "
+                f"Liang-Zeger clustered EIF sandwich estimator."
+            )
+        if vcov_type in _deferred_vcov:
+            raise ValueError(
+                f"EfficientDiD(vcov_type={vcov_type!r}) is not yet supported: "
+                f"spatial-HAC composition with EIF aggregation has no reference "
+                f"implementation today. See TODO.md for the deferred follow-up row. "
+                f"Use vcov_type='hc1' (the default) with cluster=<col> for "
+                f"cluster-robust inference."
+            )
+        if vcov_type not in _accepted_vcov:
+            raise ValueError(
+                f"EfficientDiD(vcov_type={vcov_type!r}) is invalid. "
+                f"Accepted: {sorted(_accepted_vcov)}."
+            )
 
     # -- sklearn compatibility ------------------------------------------------
 
@@ -273,6 +339,7 @@ def get_params(self) -> Dict[str, Any]:
             "anticipation": self.anticipation,
             "alpha": self.alpha,
             "cluster": self.cluster,
+            "vcov_type": self.vcov_type,
             "control_group": self.control_group,
             "n_bootstrap": self.n_bootstrap,
             "bootstrap_weights": self.bootstrap_weights,
@@ -505,8 +572,6 @@ def fit(
         # construction in _compute_survey_eif_se and ensures consistent
         # unit-level df for safe_inference t-distribution).
         if resolved_survey is not None:
-            from diff_diff.survey import ResolvedSurveyDesign
-
             row_idx = self._unit_first_panel_row
             unit_weights_s = resolved_survey.weights[row_idx]
             unit_strata = (
@@ -1096,7 +1161,22 @@ def fit(
             efficient_weights=stored_weights if stored_weights else None,
             omega_condition_numbers=stored_cond if stored_cond else None,
             control_group=self.control_group,
-            cluster=self.cluster,
+            # 2-branch cluster_name/n_clusters resolution: suppress under any
+            # survey design (analytical TSL or replicate); populate under bare
+            # ``cluster=``; default to None under unclustered, non-survey fits.
+            # The default per-unit EIF SE ``sqrt(mean(EIF^2)/n)`` is HC1-style
+            # (not auto-cluster-at-unit), so no third unit-default branch.
+            cluster_name=(
+                None
+                if resolved_survey is not None
+                else (self.cluster if self.cluster is not None else None)
+            ),
+            n_clusters=(
+                None
+                if resolved_survey is not None
+                else (n_clusters if self.cluster is not None else None)
+            ),
+            vcov_type=self.vcov_type,
             influence_functions=eif_by_gt if store_eif else None,
             bootstrap_results=bootstrap_results,
             estimation_path="dr" if use_covariates else "nocov",
diff --git a/diff_diff/efficient_did_bootstrap.py b/diff_diff/efficient_did_bootstrap.py
index 26ad55ed..08ad7007 100644
--- a/diff_diff/efficient_did_bootstrap.py
+++ b/diff_diff/efficient_did_bootstrap.py
@@ -113,6 +113,28 @@ def _run_multiplier_bootstrap(
             psu_weights, psu_ids = _gen_survey_weights(
                 self.n_bootstrap, resolved_survey, self.bootstrap_weights, rng
             )
+            # Single-cluster (G<2) survey-PSU multiplier bootstrap collapses
+            # to constant multiplier draws → BLAS roundoff produces ≈0
+            # variance (NOT NaN). Downstream zero-SE guards check exact 0 and
+            # miss this. EfficientDiD's cluster path is already protected by
+            # ``_validate_and_build_cluster_mapping`` (n_clusters≥2 at fit-time)
+            # and the unit path is protected by the balanced-panel validator;
+            # only the survey-PSU branch reaches the bootstrap with <2 PSUs.
+            if len(psu_ids) < 2:
+                warnings.warn(
+                    f"Survey-PSU bootstrap with n_psu={len(psu_ids)} (<2 "
+                    "independent PSUs) produces degenerate variance from BLAS "
+                    "roundoff; returning NaN SE.",
+                    UserWarning,
+                    stacklevel=3,
+                )
+                return self._build_nan_bootstrap_results(
+                    group_time_effects,
+                    aggregate,
+                    balance_e,
+                    treatment_groups,
+                    cohort_fractions,
+                )
             # Build unit -> PSU column map
             if resolved_survey.psu is not None:
                 psu_id_to_col = {int(p): c for c, p in enumerate(psu_ids)}
@@ -239,7 +261,7 @@ def _run_multiplier_bootstrap(
                     bootstrap_event_study[e],
                     alpha=self.alpha,
                     context=f"event study (e={e})",
-                    )
+                )
                 es_ses[e] = se
                 es_cis[e] = ci
                 es_pvs[e] = pv
@@ -253,7 +275,7 @@ def _run_multiplier_bootstrap(
                     bootstrap_group[g],
                     alpha=self.alpha,
                     context=f"group effect (g={g})",
-                    )
+                )
                 g_ses[g] = se
                 g_cis[g] = ci
                 g_pvs[g] = pv
@@ -357,3 +379,71 @@ def _prepare_group_agg_boot(
                 "effect": float(np.sum(w * effs)),
             }
         return result
+
+    def _build_nan_bootstrap_results(
+        self,
+        group_time_effects: Dict[Tuple[Any, Any], Dict[str, Any]],
+        aggregate: Optional[str],
+        balance_e: Optional[int],
+        treatment_groups: List[Any],
+        cohort_fractions: Dict[float, float],
+    ) -> EDiDBootstrapResults:
+        """Return an all-NaN ``EDiDBootstrapResults`` for degenerate bootstrap.
+
+        Used when survey-PSU bootstrap collapses to G<2 PSUs and would
+        otherwise produce ≈0 SE from BLAS roundoff. Each NaN dict is keyed
+        to the same (g,t)/event-time/group reductions the downstream
+        override loop at ``efficient_did.py:1078-1115`` expects, so the
+        override finds each key and overwrites analytical SE with NaN.
+        Setting these dicts to ``None`` instead would let the analytical
+        SE leak through, defeating the NaN-propagation contract; keying
+        an empty dict would silently no-op the override for every key.
+        ``event_study_ses``/``group_effect_ses`` are ``None`` (not empty)
+        when ``aggregate`` does not request them, matching the
+        ``is not None`` gates at ``efficient_did.py:1090, 1109``.
+        """
+        gt_pairs = list(group_time_effects.keys())
+        gt_ses: Dict[Tuple[Any, Any], float] = {gt: np.nan for gt in gt_pairs}
+        gt_cis: Dict[Tuple[Any, Any], Tuple[float, float]] = {
+            gt: (np.nan, np.nan) for gt in gt_pairs
+        }
+        gt_pvs: Dict[Tuple[Any, Any], float] = {gt: np.nan for gt in gt_pairs}
+
+        original_atts = np.array([group_time_effects[gt]["effect"] for gt in gt_pairs])
+
+        es_ses = es_cis = es_pvs = None
+        if aggregate in ("event_study", "all"):
+            es_info = self._prepare_es_agg_boot(
+                gt_pairs, original_atts, cohort_fractions, balance_e
+            )
+            if es_info:
+                es_ses = {e: np.nan for e in es_info.keys()}
+                es_cis = {e: (np.nan, np.nan) for e in es_info.keys()}
+                es_pvs = {e: np.nan for e in es_info.keys()}
+
+        g_ses = g_cis = g_pvs = None
+        if aggregate in ("group", "all"):
+            g_info = self._prepare_group_agg_boot(gt_pairs, original_atts, treatment_groups)
+            if g_info:
+                g_ses = {g: np.nan for g in g_info.keys()}
+                g_cis = {g: (np.nan, np.nan) for g in g_info.keys()}
+                g_pvs = {g: np.nan for g in g_info.keys()}
+
+        return EDiDBootstrapResults(
+            n_bootstrap=self.n_bootstrap,
+            weight_type=self.bootstrap_weights,
+            alpha=self.alpha,
+            overall_att_se=np.nan,
+            overall_att_ci=(np.nan, np.nan),
+            overall_att_p_value=np.nan,
+            group_time_ses=gt_ses,
+            group_time_cis=gt_cis,
+            group_time_p_values=gt_pvs,
+            event_study_ses=es_ses,
+            event_study_cis=es_cis,
+            event_study_p_values=es_pvs,
+            group_effect_ses=g_ses,
+            group_effect_cis=g_cis,
+            group_effect_p_values=g_pvs,
+            bootstrap_distribution=None,
+        )
diff --git a/diff_diff/efficient_did_results.py b/diff_diff/efficient_did_results.py
index 6ca90c17..85312c53 100644
--- a/diff_diff/efficient_did_results.py
+++ b/diff_diff/efficient_did_results.py
@@ -105,6 +105,16 @@ class EfficientDiDResults:
         ``{(g, t): ndarray}`` — diagnostic: weight vector per target.
     omega_condition_numbers : dict, optional
         ``{(g, t): float}`` — diagnostic: Omega* condition numbers.
+    cluster_name : str or None
+        Cluster column used at fit time (None for unclustered fits;
+        suppressed under any survey design). Populated when ``cluster=``
+        is passed to :meth:`~EfficientDiD.fit`.
+    n_clusters : int or None
+        Number of clusters at fit time (None for unclustered or survey
+        fits). Renders as ``G=<n>`` in the variance-estimator summary line.
+    vcov_type : str
+        Variance-estimator family. Permanently ``"hc1"`` per the
+        Chen-Sant'Anna-Xie (2025) IF-based variance; see REGISTRY.md.
     influence_functions : dict, optional
         ``{(g, t): ndarray(n_units,)}`` — per-unit EIF values for each
         group-time cell.  Only populated when ``store_eif=True`` in
@@ -149,12 +159,19 @@ class EfficientDiDResults:
         default=None, repr=False
     )
     control_group: str = "never_treated"
-    # Cluster column used at fit time (None for unclustered fits). Persisted
-    # so downstream diagnostics — notably ``DiagnosticReport._pt_hausman`` —
-    # can replay the Hausman PT-All vs PT-Post pretest under the same
-    # clustering as the original estimate rather than silently producing
-    # unclustered p-values for a clustered fit.
-    cluster: Optional[str] = None
+    # Cluster column used at fit time (None for unclustered fits, suppressed
+    # under survey designs). Persisted so downstream diagnostics — notably
+    # ``DiagnosticReport._pt_hausman`` — can replay the Hausman PT-All vs
+    # PT-Post pretest under the same clustering as the original estimate
+    # rather than silently producing unclustered p-values for a clustered fit.
+    cluster_name: Optional[str] = None
+    # Number of clusters at fit time (None for unclustered fits, suppressed
+    # under survey designs). Used by the shared ``_format_vcov_label`` helper
+    # to render the ``G=<n>`` suffix on the variance-estimator summary line.
+    n_clusters: Optional[int] = None
+    # Variance-estimator family. Permanently narrow to ``{"hc1"}`` per the
+    # Chen-Sant'Anna-Xie (2025) EIF-based variance — see REGISTRY.md.
+    vcov_type: str = "hc1"
     influence_functions: Optional[Dict[Tuple[Any, Any], "np.ndarray"]] = field(
         default=None, repr=False
     )
@@ -239,6 +256,30 @@ def summary(self, alpha: Optional[float] = None) -> str:
             sm = self.survey_metadata
             lines.extend(_format_survey_block(sm, 85))
 
+        # Variance-estimator / inference-method line. Bootstrap takes precedence
+        # over analytical because ``bootstrap_results`` overwrites SE/CI/p-value
+        # downstream; the analytical HC1/CR1 label would mislabel the reported
+        # numbers. Survey-fit summary block already covers TSL/replicate metadata
+        # so the variance line is suppressed under ``survey_metadata is not None``.
+        if self.bootstrap_results is not None:
+            lines.append(f"{'Inference method:':<30} {'bootstrap':>15}")
+            lines.append(
+                f"{'Bootstrap replications:':<30} {self.bootstrap_results.n_bootstrap:>15}"
+            )
+        elif self.survey_metadata is None:
+            from diff_diff.results import _format_vcov_label
+
+            vcov_label = _format_vcov_label(
+                self.vcov_type,
+                cluster_name=self.cluster_name,
+                n_clusters=self.n_clusters,
+                n_obs=self.n_obs,
+            )
+            if vcov_label:
+                lines.append(f"{'Variance estimator:':<30} {vcov_label:>15}")
+        if self.n_clusters is not None and self.bootstrap_results is None:
+            lines.append(f"{'Number of clusters:':<30} {self.n_clusters:>15}")
+
         # Overall ATT
         lines.extend(
             [
@@ -384,6 +425,47 @@ def to_dataframe(self, level: str = "group_time") -> pd.DataFrame:
                 f"Unknown level: {level}. " "Use 'group_time', 'event_study', or 'group'."
             )
 
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert headline results to a flat dictionary.
+
+        Mirrors :meth:`TripleDifferenceResults.to_dict` and
+        :meth:`ImputationDiDResults.to_dict` — surfaces variance metadata
+        (``vcov_type``, ``cluster_name``, ``n_clusters``, ``n_bootstrap``,
+        ``inference_method``) for external adapters that don't render
+        the full summary.
+        """
+        result: Dict[str, Any] = {
+            "att": self.overall_att,
+            "se": self.overall_se,
+            "t_stat": self.overall_t_stat,
+            "p_value": self.overall_p_value,
+            "conf_int_lower": self.overall_conf_int[0],
+            "conf_int_upper": self.overall_conf_int[1],
+            "n_obs": self.n_obs,
+            "n_treated_units": self.n_treated_units,
+            "n_control_units": self.n_control_units,
+            "alpha": self.alpha,
+            "pt_assumption": self.pt_assumption,
+            "estimation_path": self.estimation_path,
+            "vcov_type": self.vcov_type,
+        }
+        if self.cluster_name is not None:
+            result["cluster_name"] = self.cluster_name
+        if self.n_clusters is not None:
+            result["n_clusters"] = self.n_clusters
+        if self.bootstrap_results is not None:
+            # Mirror summary() gate exactly — bootstrap_results can be None
+            # even when n_bootstrap > 0 (e.g. empty eif_by_gt skips the path).
+            result["n_bootstrap"] = self.bootstrap_results.n_bootstrap
+            result["inference_method"] = "bootstrap"
+        elif self.survey_metadata is not None:
+            result["inference_method"] = "survey"
+        elif self.cluster_name is not None:
+            result["inference_method"] = "cluster_robust"
+        else:
+            result["inference_method"] = "heteroskedasticity_robust"
+        return result
+
     @property
     def is_significant(self) -> bool:
         """Check if overall ATT is significant."""
diff --git a/diff_diff/guides/llms-full.txt b/diff_diff/guides/llms-full.txt
index 4950c2ac..8307f280 100644
--- a/diff_diff/guides/llms-full.txt
+++ b/diff_diff/guides/llms-full.txt
@@ -790,6 +790,7 @@ EfficientDiD(
     pt_assumption: str = "all",              # "all" (overidentified) or "post" (just-identified)
     alpha: float = 0.05,
     cluster: str | None = None,              # Column name for cluster-robust SEs (Liang-Zeger on EIF values); cluster-level multiplier bootstrap when n_bootstrap > 0
+    vcov_type: str = "hc1",                  # {"hc1"} only — IF-based variance per Chen-Sant'Anna-Xie (2025); analytical-sandwich families {classical, hc2, hc2_bm} and conley rejected at __init__/set_params
     n_bootstrap: int = 0,                    # Multiplier bootstrap iterations
     bootstrap_weights: str = "rademacher",   # "rademacher", "mammen", or "webb"
     seed: int | None = None,
@@ -1281,13 +1282,13 @@ ImputationDiDResults, TwoStageDiDResults, StackedDiDResults, and EfficientDiDRes
 
 Each event study effect dict contains: `effect`, `se`, `t_stat`, `p_value`, `conf_int`, `n_obs` (or `n_groups`).
 
-**Variance metadata** (`ImputationDiDResults` carries these; other staggered Results may surface a subset):
+**Variance metadata** (`ImputationDiDResults` and `EfficientDiDResults` carry these; other staggered Results may surface a subset):
 
 | Attribute | Type | Description |
 |-----------|------|-------------|
-| `vcov_type` | `str` | Variance estimator family (`"hc1"` for IF-based estimators; permanently narrow on `ImputationDiD` / `CallawaySantAnna` / `TripleDifference` per IF-vs-sandwich taxonomy) |
-| `cluster_name` | `str | None` | Effective cluster column name (e.g. `"unit"` for default `cluster=None`); `None` under survey designs (the survey block already names PSU/strata) |
-| `n_clusters` | `int | None` | Number of effective clusters; `None` under survey designs |
+| `vcov_type` | `str` | Variance estimator family (`"hc1"` for IF-based estimators; permanently narrow on `ImputationDiD` / `CallawaySantAnna` / `TripleDifference` / `EfficientDiD` per IF-vs-sandwich taxonomy) |
+| `cluster_name` | `str | None` | Effective cluster column name (e.g. `"unit"` for default `cluster=None` on `ImputationDiD`; `None` for default on `EfficientDiD` since its per-unit EIF SE is HC1-style not CR1-at-unit); `None` under survey designs (the survey block already names PSU/strata) |
+| `n_clusters` | `int | None` | Number of effective clusters; `None` under survey designs and `None` under EfficientDiD's default unclustered fit |
 
 **Methods:** `summary()`, `print_summary()`, `to_dataframe()`, `to_dict()` (flat dict of headline aliases + `vcov_type` + conditional `cluster_name`/`n_clusters`/`n_bootstrap`/`inference_method`)
 
diff --git a/docs/methodology/REGISTRY.md b/docs/methodology/REGISTRY.md
index 2bc33482..001d7ffb 100644
--- a/docs/methodology/REGISTRY.md
+++ b/docs/methodology/REGISTRY.md
@@ -348,8 +348,9 @@ Sant'Anna 2021 for `CallawaySantAnna`; Borusyak-Jaravel-Spiess 2024 for
 This split is a structural property of the estimator's variance derivation,
 not a missing feature. The `vcov_type` input contract for IF-based estimators
 is **permanently narrow** at `{"hc1"}`. Enforced today on
-`CallawaySantAnna`, `TripleDifference`, and `ImputationDiD`; the same narrow
-contract is expected when `EfficientDiD` reaches `vcov_type` threading.
+`CallawaySantAnna`, `TripleDifference`, `ImputationDiD`, and `EfficientDiD`;
+the same narrow contract is expected when `TwoStageDiD` reaches `vcov_type`
+threading (sandwich + GMM-corrected meat; non-IF, so threading model differs).
 
 **Note:** This routing is a documented synthesis. The clustered-`hc1`
 activation path is estimator-specific: `CallawaySantAnna` synthesizes
@@ -358,9 +359,12 @@ PSU-meat machinery (`_compute_stratified_psu_meat`); `TripleDifference`
 computes the algebraically equivalent CR1 directly from cluster-summed
 IFs inline; `ImputationDiD` computes the Theorem 3 conservative variance
 (`sigma_sq = (cluster_psi_sums**2).sum()`) directly from per-cluster
-influence-function sums. The CR1 Liang-Zeger algebra on the IF is
-Williams (2000) / Hansen (2007) in all three cases — no new methodology
-is introduced.
+influence-function sums; `EfficientDiD` aggregates per-unit EIF within
+clusters, centers, and applies the standard `G/(G-1)` correction
+(`_cluster_aggregate` + `_compute_se_from_eif` at
+`diff_diff/efficient_did.py:79-127`). The CR1 Liang-Zeger algebra on the
+IF is Williams (2000) / Hansen (2007) in all four cases — no new
+methodology is introduced.
 
 ---
 
@@ -1050,6 +1054,9 @@ where `q_{g,e} = pi_g / sum_{g' in G_{trt,e}} pi_{g'}`.
 - **Note:** Cluster-robust SEs use the standard Liang-Zeger clustered sandwich estimator applied to EIF values: aggregate EIF within clusters, center, and compute variance with G/(G-1) small-sample correction. Cluster bootstrap generates multiplier weights at the cluster level (all units in a cluster share the same weight). Analytical clustered SEs are the default when `cluster` is set; cluster bootstrap is opt-in via `n_bootstrap > 0`.
 - **Note:** Hausman pretest operates on the post-treatment event-study vector ES(e) per Theorem A.1. Both PT-All and PT-Post fits are aggregated to ES(e) using cohort-size weights before computing the test statistic H = delta' V^{-1} delta where delta = ES_post - ES_all and V = Cov(ES_post) - Cov(ES_all). Covariance is computed from aggregated ES(e)-level EIF values. The variance-difference matrix V is inverted via Moore-Penrose pseudoinverse to handle finite-sample non-positive-definiteness. Effective rank of V (number of positive eigenvalues) is used as degrees of freedom.
 - **Note:** Last-cohort-as-control (`control_group="last_cohort"`) reclassifies the latest treatment cohort as pseudo-never-treated and drops time periods at `t >= last_g - anticipation`, excluding anticipation-contaminated periods from the pseudo-control's pre-treatment window. This is distinct from CallawaySantAnna's `not_yet_treated` option which dynamically selects not-yet-treated units per (g,t) pair.
+- **Note:** `vcov_type` is permanently narrow to `{"hc1"}` per the Chen-Sant'Anna-Xie (2025) EIF-based variance achieving the semiparametric efficiency bound. Analytical-sandwich families `{classical, hc2, hc2_bm}` are rejected at `__init__` — the per-unit EIF aggregation has no equivalent single design matrix on which hat-matrix leverage or Bell-McCaffrey Satterthwaite DOF can be defined. `cluster=` invokes Liang-Zeger CR1 on cluster-aggregated EIF (`_compute_se_from_eif` with `cluster_indices` at `diff_diff/efficient_did.py:124-127`); `survey_design=` invokes TSL on the combined IF (`_compute_survey_eif_se` at `diff_diff/efficient_did.py:1151-1176`). `vcov_type='conley'` deferred to the EfficientDiD Conley follow-up row in TODO.md.
+- **Note:** Default `cluster=None` (no survey design) renders summary label "HC1 heteroskedasticity-robust" because the per-unit EIF SE `sqrt(mean(EIF²)/n)` is methodologically HC1-style (no Liang-Zeger G/(G-1) finite-sample correction). `EfficientDiDResults.cluster_name` and `n_clusters` stay None under unclustered fits. This diverges from `ImputationDiD` which auto-clusters at unit per Borusyak-Jaravel-Spiess (2024) Theorem 3 — there the default summary renders the CR1 unit-clustered label.
+- **Note (deviation from sibling estimators):** `EfficientDiD.set_params(vcov_type=bad)` raises immediately rather than deferring to `fit()`. EfficientDiD's `set_params` calls `_validate_params()` which invokes `_validate_vcov_type`, matching the existing eager-validation pattern for `pt_assumption`, `control_group`, `bootstrap_weights`, etc. This is intentional — `ImputationDiD`/`TripleDifference`/`CallawaySantAnna` use sklearn mutate-then-validate-at-use, so the same set_params + bad vcov_type sequence is silently accepted there until `fit()` is called.
 
 ---
 
diff --git a/tests/test_efficient_did.py b/tests/test_efficient_did.py
index 3bd192fb..e3edbad4 100644
--- a/tests/test_efficient_did.py
+++ b/tests/test_efficient_did.py
@@ -20,6 +20,7 @@
 from diff_diff.efficient_did_weights import (
     enumerate_valid_triples,
 )
+from diff_diff.survey import SurveyDesign
 
 # =============================================================================
 # Helpers
@@ -2161,3 +2162,610 @@ def test_ratio_sieve_no_warning_when_no_skips(self):
         assert (
             partial_skip_msgs == []
         ), f"Unexpected partial-skip warning on clean data: {partial_skip_msgs}"
+
+
+# =============================================================================
+# Phase 1b interstitial #4: vcov_type input contract on EfficientDiD
+# =============================================================================
+
+
+def _efficient_clustered_panel(
+    seed: int = 71,
+    n_units: int = 60,
+    n_periods: int = 6,
+    n_states: int = 8,
+) -> pd.DataFrame:
+    """Staggered-adoption panel with a ``state`` cluster column.
+
+    States carry random effects so ``cluster=state`` shifts the analytical
+    SE relative to the default ``cluster=None`` per-unit EIF SE.
+    """
+    rng = np.random.default_rng(seed)
+    units = np.repeat(np.arange(n_units), n_periods)
+    times = np.tile(np.arange(n_periods), n_units)
+
+    unit_to_state = rng.integers(0, n_states, size=n_units)
+    state = np.repeat(unit_to_state, n_periods)
+    state_re = rng.standard_normal(n_states) * 1.2
+
+    cohorts = np.array([2, 3, 4])
+    n_never = n_units // 2
+    n_treated = n_units - n_never
+    first_treat = np.zeros(n_units, dtype=int)
+    first_treat[n_never:] = cohorts[rng.integers(0, len(cohorts), size=n_treated)]
+    first_treat_expanded = np.repeat(first_treat, n_periods)
+
+    unit_fe = rng.standard_normal(n_units) * 1.2
+    time_fe = np.linspace(0, 0.5, n_periods)
+    unit_fe_expanded = np.repeat(unit_fe, n_periods)
+    time_fe_expanded = np.tile(time_fe, n_units)
+    state_fe_expanded = state_re[state]
+
+    post = (times >= first_treat_expanded) & (first_treat_expanded > 0)
+    outcome = (
+        unit_fe_expanded
+        + time_fe_expanded
+        + state_fe_expanded
+        + 1.5 * post
+        + rng.standard_normal(len(units)) * 0.4
+    )
+
+    return pd.DataFrame(
+        {
+            "unit": units,
+            "time": times,
+            "y": outcome,
+            "first_treat": first_treat_expanded,
+            "state": state,
+        }
+    )
+
+
+def _efficient_survey_panel(
+    seed: int = 71,
+    n_units: int = 80,
+    n_periods: int = 5,
+    n_psu: int = 16,
+    n_strata: int = 4,
+) -> pd.DataFrame:
+    """Staggered-adoption panel with analytical survey columns (pweight +
+    panel-constant PSU + stratum). Used for TSL-survey bit-equality tests."""
+    rng = np.random.default_rng(seed)
+    units = np.repeat(np.arange(n_units), n_periods)
+    times = np.tile(np.arange(n_periods), n_units)
+
+    unit_psu = rng.integers(0, n_psu, size=n_units)
+    psu = np.repeat(unit_psu, n_periods)
+    psu_to_stratum = rng.integers(0, n_strata, size=n_psu)
+    stratum = psu_to_stratum[psu]
+
+    cohorts = np.array([2, 3])
+    n_never = n_units // 2
+    n_treated = n_units - n_never
+    first_treat = np.zeros(n_units, dtype=int)
+    first_treat[n_never:] = cohorts[rng.integers(0, len(cohorts), size=n_treated)]
+    first_treat_expanded = np.repeat(first_treat, n_periods)
+
+    unit_fe = rng.standard_normal(n_units) * 1.0
+    time_fe = np.linspace(0, 0.4, n_periods)
+    unit_fe_expanded = np.repeat(unit_fe, n_periods)
+    time_fe_expanded = np.tile(time_fe, n_units)
+
+    post = (times >= first_treat_expanded) & (first_treat_expanded > 0)
+    outcome = (
+        unit_fe_expanded + time_fe_expanded + 1.2 * post + rng.standard_normal(len(units)) * 0.35
+    )
+
+    unit_weight = 1.0 + rng.exponential(0.3, n_units)
+    weight = np.repeat(unit_weight, n_periods)
+
+    return pd.DataFrame(
+        {
+            "unit": units,
+            "time": times,
+            "y": outcome,
+            "first_treat": first_treat_expanded,
+            "psu": psu,
+            "stratum": stratum,
+            "weight": weight,
+        }
+    )
+
+
+def _efficient_replicate_panel(
+    seed: int = 89, n_units: int = 40, n_periods: int = 5, n_rep: int = 8
+):
+    """Staggered-adoption panel with JK1 replicate-weight columns."""
+    rng = np.random.default_rng(seed)
+    units = np.repeat(np.arange(n_units), n_periods)
+    times = np.tile(np.arange(n_periods), n_units)
+
+    cohorts = np.array([2, 3])
+    n_never = n_units // 2
+    n_treated = n_units - n_never
+    first_treat = np.zeros(n_units, dtype=int)
+    first_treat[n_never:] = cohorts[rng.integers(0, len(cohorts), size=n_treated)]
+    first_treat_expanded = np.repeat(first_treat, n_periods)
+
+    unit_fe = rng.standard_normal(n_units) * 1.0
+    time_fe = np.linspace(0, 0.4, n_periods)
+    unit_fe_expanded = np.repeat(unit_fe, n_periods)
+    time_fe_expanded = np.tile(time_fe, n_units)
+
+    post = (times >= first_treat_expanded) & (first_treat_expanded > 0)
+    outcome = (
+        unit_fe_expanded + time_fe_expanded + 1.0 * post + rng.standard_normal(len(units)) * 0.4
+    )
+
+    unit_weight = 1.0 + rng.exponential(0.2, n_units)
+    weight = np.repeat(unit_weight, n_periods)
+
+    data = pd.DataFrame(
+        {
+            "unit": units,
+            "time": times,
+            "y": outcome,
+            "first_treat": first_treat_expanded,
+            "weight": weight,
+        }
+    )
+
+    units_per_rep = max(n_units // n_rep, 1)
+    rep_cols = []
+    for r in range(n_rep):
+        w_r = unit_weight.copy()
+        start = r * units_per_rep
+        end = min((r + 1) * units_per_rep, n_units)
+        w_r[start:end] = 0.0
+        nonzero = w_r > 0
+        w_r[nonzero] = w_r[nonzero] * n_rep / (n_rep - 1)
+        col = f"rep_{r}"
+        data[col] = np.repeat(w_r, n_periods)
+        rep_cols.append(col)
+    return data, rep_cols
+
+
+class TestEfficientDiDVcovType:
+    """Phase 1b interstitial #4: vcov_type input contract on EfficientDiD.
+
+    EfficientDiD uses IF-based variance per Chen-Sant'Anna-Xie (2025) achieving
+    the semiparametric efficiency bound; ``vcov_type`` is permanently narrow
+    to ``{"hc1"}``. Analytical-sandwich families ``{classical, hc2, hc2_bm}``
+    and ``conley`` are rejected at ``__init__`` / ``set_params`` with
+    methodology-rooted messages. Mirrors ImputationDiD PR #492 template.
+
+    Key divergence from ImputationDiD: default ``cluster=None`` SE is the
+    per-unit EIF SE ``sqrt(mean(EIF²)/n)`` — methodologically HC1-style
+    (NOT auto-cluster-at-unit). The summary label "HC1 heteroskedasticity-
+    robust" is methodologically correct here, and ``cluster_name``/``n_clusters``
+    stay None under unclustered fits.
+
+    7-surface matrix:
+      1. Default preserved bit-equally across all 4 aggregate modes
+      2. Cluster path preserved bit-equally across the same aggregate grid
+      3. TSL-survey path preserved bit-equally across the same aggregate grid
+      4. Replicate-survey path preserved bit-equally across the same aggregate grid
+      5. Bootstrap × cluster + bootstrap × survey bit-equal
+      6. set_params(vcov_type=bad) eager revalidation
+      7. Bootstrap n_psu<2 NaN propagation (defensive fix regression)
+
+    Plus 7 introspection tests, 5 input-rejection pins, the
+    ``cluster + replicate_weights`` rejection, and a DR-path bit-equality test.
+    """
+
+    # ---- Surface 1: default bit-equal across aggregation modes ------------
+
+    @pytest.mark.parametrize("aggregate", [None, "event_study", "group", "all"])
+    def test_default_hc1_bit_equal_baseline(self, aggregate):
+        data = _efficient_clustered_panel()
+        common = dict(
+            data=data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            aggregate=aggregate,
+        )
+        r_default = EfficientDiD().fit(**common)
+        r_explicit = EfficientDiD(vcov_type="hc1").fit(**common)
+        assert r_default.overall_att == r_explicit.overall_att
+        assert r_default.overall_se == r_explicit.overall_se
+
+    # ---- Surface 2: cluster path bit-equal --------------------------------
+
+    @pytest.mark.parametrize("aggregate", [None, "event_study", "group", "all"])
+    def test_cluster_hc1_bit_equal_baseline(self, aggregate):
+        data = _efficient_clustered_panel()
+        common = dict(
+            data=data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            aggregate=aggregate,
+        )
+        r_default = EfficientDiD(cluster="state").fit(**common)
+        r_explicit = EfficientDiD(cluster="state", vcov_type="hc1").fit(**common)
+        assert r_default.overall_att == r_explicit.overall_att
+        assert r_default.overall_se == r_explicit.overall_se
+
+    # ---- Surface 3: TSL-survey path bit-equal -----------------------------
+
+    @pytest.mark.parametrize("aggregate", [None, "event_study", "group", "all"])
+    def test_survey_tsl_hc1_bit_equal_baseline(self, aggregate):
+        data = _efficient_survey_panel()
+        design = SurveyDesign(weights="weight", psu="psu", strata="stratum", weight_type="pweight")
+        common = dict(
+            data=data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            aggregate=aggregate,
+            survey_design=design,
+        )
+        r_default = EfficientDiD().fit(**common)
+        r_explicit = EfficientDiD(vcov_type="hc1").fit(**common)
+        assert r_default.overall_att == r_explicit.overall_att
+        assert r_default.overall_se == r_explicit.overall_se
+
+    # ---- Surface 4: replicate-survey path bit-equal -----------------------
+
+    @pytest.mark.parametrize("aggregate", [None, "event_study", "group", "all"])
+    def test_survey_replicate_hc1_bit_equal_baseline(self, aggregate):
+        data, rep_cols = _efficient_replicate_panel()
+        design = SurveyDesign(
+            weights="weight",
+            replicate_weights=rep_cols,
+            replicate_method="JK1",
+            weight_type="pweight",
+        )
+        common = dict(
+            data=data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            survey_design=design,
+            aggregate=aggregate,
+        )
+        r_default = EfficientDiD().fit(**common)
+        r_explicit = EfficientDiD(vcov_type="hc1").fit(**common)
+        assert r_default.overall_att == r_explicit.overall_att
+        assert r_default.overall_se == r_explicit.overall_se
+        # Per-horizon / per-group SE override branches must also agree under
+        # the replicate-weight variance path.
+        if aggregate in ("event_study", "all"):
+            assert r_default.event_study_effects is not None
+            assert r_explicit.event_study_effects is not None
+            for h in r_default.event_study_effects:
+                assert (
+                    r_default.event_study_effects[h]["se"]
+                    == r_explicit.event_study_effects[h]["se"]
+                )
+        if aggregate in ("group", "all"):
+            assert r_default.group_effects is not None
+            assert r_explicit.group_effects is not None
+            for g in r_default.group_effects:
+                assert r_default.group_effects[g]["se"] == r_explicit.group_effects[g]["se"]
+
+    # ---- Surface 5: bootstrap × cluster / × survey bit-equal --------------
+
+    def test_bootstrap_cluster_hc1_bit_equal(self, ci_params):
+        data = _efficient_clustered_panel()
+        n_boot = ci_params.bootstrap(199)
+        common = dict(
+            data=data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            aggregate="all",
+        )
+        r_default = EfficientDiD(cluster="state", n_bootstrap=n_boot, seed=11).fit(**common)
+        r_explicit = EfficientDiD(
+            cluster="state", n_bootstrap=n_boot, seed=11, vcov_type="hc1"
+        ).fit(**common)
+        assert r_default.bootstrap_results is not None
+        assert r_explicit.bootstrap_results is not None
+        assert (
+            r_default.bootstrap_results.overall_att_se
+            == r_explicit.bootstrap_results.overall_att_se
+        )
+        # Per-horizon / per-group bootstrap SE override branches at
+        # efficient_did.py:1090-1115 must also agree.
+        assert r_default.bootstrap_results.event_study_ses is not None
+        assert r_explicit.bootstrap_results.event_study_ses is not None
+        for h, se in r_default.bootstrap_results.event_study_ses.items():
+            assert se == r_explicit.bootstrap_results.event_study_ses[h]
+        assert r_default.bootstrap_results.group_effect_ses is not None
+        assert r_explicit.bootstrap_results.group_effect_ses is not None
+        for g, se in r_default.bootstrap_results.group_effect_ses.items():
+            assert se == r_explicit.bootstrap_results.group_effect_ses[g]
+
+    def test_bootstrap_survey_hc1_bit_equal(self, ci_params):
+        data = _efficient_survey_panel()
+        design = SurveyDesign(weights="weight", psu="psu", strata="stratum", weight_type="pweight")
+        n_boot = ci_params.bootstrap(199)
+        common = dict(
+            data=data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            survey_design=design,
+            aggregate="all",
+        )
+        r_default = EfficientDiD(n_bootstrap=n_boot, seed=23).fit(**common)
+        r_explicit = EfficientDiD(n_bootstrap=n_boot, seed=23, vcov_type="hc1").fit(**common)
+        assert r_default.bootstrap_results is not None
+        assert r_explicit.bootstrap_results is not None
+        assert (
+            r_default.bootstrap_results.overall_att_se
+            == r_explicit.bootstrap_results.overall_att_se
+        )
+
+    # ---- Surface 6: set_params eager revalidation -------------------------
+
+    def test_set_params_bad_vcov_caught_immediately(self):
+        # EfficientDiD's set_params calls _validate_params (which now invokes
+        # _validate_vcov_type), so the check fires NOW (not at fit-time).
+        # This intentionally diverges from ImputationDiD/TripleDifference
+        # (which defer to fit-time per sklearn mutate-then-validate-at-use).
+        ed = EfficientDiD()
+        with pytest.raises(ValueError, match="influence-function"):
+            ed.set_params(vcov_type="classical")
+
+    def test_set_params_unknown_vcov_caught_immediately(self):
+        ed = EfficientDiD()
+        with pytest.raises(ValueError, match="hc4"):
+            ed.set_params(vcov_type="hc4")
+
+    # ---- Surface 7: bootstrap n_psu<2 NaN propagation ---------------------
+
+    def test_bootstrap_n_psu_less_than_2_returns_nan(self):
+        # Single-PSU survey design forces the survey-PSU bootstrap path to
+        # hit the n_psu<2 BLAS-roundoff guard. Survey weight_type must be
+        # pweight per EfficientDiD's survey contract.
+        data = _efficient_survey_panel(seed=42)
+        data["single_psu"] = 0
+        data["single_stratum"] = 0
+        design = SurveyDesign(
+            weights="weight",
+            psu="single_psu",
+            strata="single_stratum",
+            weight_type="pweight",
+        )
+        with pytest.warns(UserWarning, match="n_psu=1"):
+            results = EfficientDiD(n_bootstrap=199, seed=5).fit(
+                data,
+                outcome="y",
+                unit="unit",
+                time="time",
+                first_treat="first_treat",
+                survey_design=design,
+            )
+        assert results.bootstrap_results is not None
+        assert np.isnan(results.bootstrap_results.overall_att_se)
+        assert np.isnan(results.bootstrap_results.overall_att_p_value)
+        assert all(np.isnan(x) for x in results.bootstrap_results.overall_att_ci)
+        # Derived coef_var propagates NaN through the alias property.
+        assert np.isnan(results.coef_var)
+
+    # ---- DR (covariates) path bit-equal -----------------------------------
+
+    def test_dr_path_hc1_bit_equal(self):
+        # Doubly-robust (covariates=) path uses the same _eif_se / _aggregate_*
+        # variance funnel as the no-cov path — only EIF *construction* differs.
+        # Validates the variance machinery passes through the sieve/OLS DR path
+        # unchanged under explicit vcov_type="hc1".
+        data = make_compustat_dgp(seed=23, n_units=80, n_periods=5)
+        # Use one panel-constant synthetic covariate so DR path engages.
+        rng = np.random.default_rng(23)
+        n_units = data["unit"].nunique()
+        x1_per_unit = rng.standard_normal(n_units)
+        unit_to_x1 = dict(zip(sorted(data["unit"].unique()), x1_per_unit))
+        data = data.copy()
+        data["x1"] = data["unit"].map(unit_to_x1)
+        common = dict(
+            data=data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            covariates=["x1"],
+            aggregate="event_study",
+        )
+        r_default = EfficientDiD().fit(**common)
+        r_explicit = EfficientDiD(vcov_type="hc1").fit(**common)
+        assert r_default.estimation_path == "dr"
+        assert r_explicit.estimation_path == "dr"
+        assert r_default.overall_att == r_explicit.overall_att
+        assert r_default.overall_se == r_explicit.overall_se
+
+    # ---- Input rejection: methodology-rooted messages ---------------------
+
+    @pytest.mark.parametrize(
+        "bad_vcov,keyword",
+        [
+            ("classical", "influence-function"),
+            ("hc2", "Chen"),
+            ("hc2_bm", "Bell-McCaffrey"),
+            ("hc2_bm", "hat matrix"),
+        ],
+    )
+    def test_reject_invalid_vcov_at_init(self, bad_vcov, keyword):
+        with pytest.raises(ValueError, match=keyword):
+            EfficientDiD(vcov_type=bad_vcov)
+
+    def test_reject_conley_at_init(self):
+        with pytest.raises(ValueError, match="spatial-HAC"):
+            EfficientDiD(vcov_type="conley")
+
+    def test_reject_unknown_vcov_at_init(self):
+        with pytest.raises(ValueError, match="hc4"):
+            EfficientDiD(vcov_type="hc4")
+
+    # ---- cluster + survey blanket rejection (covers replicate subset) -----
+
+    def test_cluster_plus_replicate_weights_rejected(self):
+        # cluster + survey_design is blanket-rejected at efficient_did.py:357,
+        # which transitively covers cluster + replicate_weights. Asserting
+        # via NotImplementedError on a JK1 replicate design.
+        data, rep_cols = _efficient_replicate_panel()
+        data["state"] = (data["unit"] // 4).astype(int)
+        design = SurveyDesign(
+            weights="weight",
+            replicate_weights=rep_cols,
+            replicate_method="JK1",
+            weight_type="pweight",
+        )
+        with pytest.raises(NotImplementedError, match="cluster and survey_design"):
+            EfficientDiD(cluster="state").fit(
+                data,
+                outcome="y",
+                unit="unit",
+                time="time",
+                first_treat="first_treat",
+                survey_design=design,
+            )
+
+    # ---- Introspection / safety-gate tests --------------------------------
+
+    def test_default_vcov_type_is_hc1(self):
+        assert EfficientDiD().vcov_type == "hc1"
+
+    def test_get_params_includes_vcov_type(self):
+        params = EfficientDiD().get_params()
+        assert "vcov_type" in params
+        assert params["vcov_type"] == "hc1"
+
+    def test_results_carries_vcov_type(self):
+        data = _efficient_clustered_panel()
+        r = EfficientDiD().fit(
+            data, outcome="y", unit="unit", time="time", first_treat="first_treat"
+        )
+        assert r.vcov_type == "hc1"
+
+    def test_to_dict_includes_vcov_type(self):
+        data = _efficient_clustered_panel()
+        r = EfficientDiD().fit(
+            data, outcome="y", unit="unit", time="time", first_treat="first_treat"
+        )
+        d = r.to_dict()
+        assert d["vcov_type"] == "hc1"
+        # Headline alias keys are present per the TripleDifference precedent.
+        for k in ("att", "se", "t_stat", "p_value", "conf_int_lower", "conf_int_upper"):
+            assert k in d
+        # Default unclustered fit → no cluster_name / n_clusters in dict.
+        assert "cluster_name" not in d
+        assert "n_clusters" not in d
+        assert d["inference_method"] == "heteroskedasticity_robust"
+
+    def test_to_dict_under_cluster(self):
+        data = _efficient_clustered_panel()
+        r = EfficientDiD(cluster="state").fit(
+            data, outcome="y", unit="unit", time="time", first_treat="first_treat"
+        )
+        d = r.to_dict()
+        assert d["cluster_name"] == "state"
+        assert d["n_clusters"] is not None and d["n_clusters"] > 1
+        assert d["inference_method"] == "cluster_robust"
+
+    def test_summary_includes_vcov_type_label_default(self):
+        # Default cluster=None (no survey, no bootstrap) → HC1 label, NOT CR1.
+        # This is methodologically correct for EfficientDiD: the per-unit EIF
+        # SE `sqrt(mean(EIF²)/n)` is HC1-style (no Liang-Zeger G/(G-1)
+        # finite-sample correction). Diverges from ImputationDiD (BJS Theorem 3
+        # auto-clusters at unit by construction).
+        data = _efficient_clustered_panel()
+        r = EfficientDiD().fit(
+            data, outcome="y", unit="unit", time="time", first_treat="first_treat"
+        )
+        text = r.summary()
+        assert "Variance estimator:" in text
+        assert "HC1 heteroskedasticity-robust" in text
+        # No CR1 cluster label under default cluster=None.
+        assert "CR1 cluster-robust" not in text
+        # Results metadata stays None under default fits (no auto-cluster-at-unit).
+        assert r.cluster_name is None
+        assert r.n_clusters is None
+
+    def test_summary_renders_cluster_label_under_cluster(self):
+        data = _efficient_clustered_panel()
+        r = EfficientDiD(cluster="state").fit(
+            data, outcome="y", unit="unit", time="time", first_treat="first_treat"
+        )
+        text = r.summary()
+        assert "Variance estimator:" in text
+        assert "CR1 cluster-robust" in text
+        assert "state" in text
+        assert "Number of clusters:" in text
+        assert r.cluster_name == "state"
+        assert r.n_clusters is not None and r.n_clusters > 1
+
+    def test_summary_suppresses_variance_label_under_bootstrap(self, ci_params):
+        # Under bootstrap fits, bootstrap_results overwrites SE/CI/p-value, so
+        # the analytical variance-family label would misstate the inference
+        # source. Mirror the canonical DiDResults gate at results.py:213-226.
+        data = _efficient_clustered_panel()
+        n_boot = ci_params.bootstrap(199)
+        r = EfficientDiD(n_bootstrap=n_boot, seed=7).fit(
+            data, outcome="y", unit="unit", time="time", first_treat="first_treat"
+        )
+        text = r.summary()
+        assert "Inference method:" in text
+        assert "bootstrap" in text
+        # Analytical variance-family label must be suppressed.
+        assert "Variance estimator:" not in text
+        assert "HC1 heteroskedasticity-robust" not in text
+        assert "CR1 cluster-robust" not in text
+
+    def test_cluster_name_suppressed_under_survey(self):
+        data = _efficient_survey_panel()
+        design = SurveyDesign(weights="weight", psu="psu", strata="stratum", weight_type="pweight")
+        r = EfficientDiD().fit(
+            data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            survey_design=design,
+        )
+        assert r.cluster_name is None
+        assert r.n_clusters is None
+
+    def test_cluster_name_suppressed_under_replicate_survey(self):
+        # Replicate-weight survey designs have psu=None — gate must be on
+        # `resolved_survey is not None`, NOT `resolved_survey.psu is not None`.
+        # Mirror ImputationDiD R2 fix pattern.
+        data, rep_cols = _efficient_replicate_panel()
+        design = SurveyDesign(
+            weights="weight",
+            replicate_weights=rep_cols,
+            replicate_method="JK1",
+            weight_type="pweight",
+        )
+        r = EfficientDiD().fit(
+            data,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            survey_design=design,
+        )
+        assert r.cluster_name is None
+        assert r.n_clusters is None
+        text = r.summary()
+        assert "Number of clusters:" not in text
+        assert "CR1 cluster-robust" not in text
+
+    def test_fit_clone_idempotent_on_vcov_type(self):
+        data = _efficient_clustered_panel()
+        ed1 = EfficientDiD(vcov_type="hc1")
+        r1 = ed1.fit(data, outcome="y", unit="unit", time="time", first_treat="first_treat")
+        ed2 = EfficientDiD(**ed1.get_params())
+        r2 = ed2.fit(data, outcome="y", unit="unit", time="time", first_treat="first_treat")
+        assert r1.overall_att == r2.overall_att
+        assert r1.overall_se == r2.overall_se
+        assert r1.vcov_type == r2.vcov_type

From 79f428d7978686fb908bbcc119e03cfcf81745b7 Mon Sep 17 00:00:00 2001
From: igerber <isaac.gerber@gmail.com>
Date: Tue, 26 May 2026 10:27:11 -0400
Subject: [PATCH 2/3] efficient-did: complete cluster_name rename propagation +
 suppress duplicate Bootstrap summary line
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two follow-up fixes:

1. cluster → cluster_name propagation. The original PR renamed the
   EfficientDiDResults.cluster field to cluster_name but left two
   consumers still referencing the old name:
   - tests/test_business_report.py:1267 (TestHausmanPretestPropagatesCluster
     regression test asserting the field is persisted for the Hausman
     pretest replay) — updated assertion + class docstring.
   - docs/api/_autosummary/diff_diff.EfficientDiDResults.rst — the
     checked-in Sphinx autosummary still listed cluster and was missing
     cluster_name, n_clusters, vcov_type, and the new to_dict() method.

2. Suppress duplicate Bootstrap summary header. EfficientDiDResults.summary()
   previously emitted both the legacy "Bootstrap: <n> (<weights>)" header
   line (L250-L251 pre-PR) and the new "Inference method: bootstrap" +
   "Bootstrap replications: <n>" block. The legacy header is now gated on
   `bootstrap_results is None` so analytical-only fits keep the original
   render and bootstrap-overwritten fits use the canonical inference-method
   block alone (matches the sibling result-container convention).

211 tests pass across test_efficient_did.py, test_efficient_did_validation.py,
test_diagnostics.py, and test_business_report.py::TestHausmanPretestPropagatesCluster.
black + ruff clean on touched Python files.
---
 diff_diff/efficient_did_results.py                      | 6 +++++-
 docs/api/_autosummary/diff_diff.EfficientDiDResults.rst | 5 ++++-
 tests/test_business_report.py                           | 4 ++--
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/diff_diff/efficient_did_results.py b/diff_diff/efficient_did_results.py
index 85312c53..8e91b9fa 100644
--- a/diff_diff/efficient_did_results.py
+++ b/diff_diff/efficient_did_results.py
@@ -247,7 +247,11 @@ def summary(self, alpha: Optional[float] = None) -> str:
             lines.append(f"{'Control group:':<30} {self.control_group:>10}")
         if self.anticipation > 0:
             lines.append(f"{'Anticipation periods:':<30} {self.anticipation:>10}")
-        if self.n_bootstrap > 0:
+        # Suppress the legacy ``Bootstrap:`` header when ``bootstrap_results``
+        # is present — the new variance/inference-method block below renders
+        # the canonical ``Inference method: bootstrap`` + ``Bootstrap
+        # replications:`` lines, so the old header would duplicate metadata.
+        if self.n_bootstrap > 0 and self.bootstrap_results is None:
             lines.append(f"{'Bootstrap:':<30} {self.n_bootstrap:>10} ({self.bootstrap_weights})")
         lines.append("")
 
diff --git a/docs/api/_autosummary/diff_diff.EfficientDiDResults.rst b/docs/api/_autosummary/diff_diff.EfficientDiDResults.rst
index d19233eb..193419cd 100644
--- a/docs/api/_autosummary/diff_diff.EfficientDiDResults.rst
+++ b/docs/api/_autosummary/diff_diff.EfficientDiDResults.rst
@@ -15,6 +15,7 @@
       ~EfficientDiDResults.print_summary
       ~EfficientDiDResults.summary
       ~EfficientDiDResults.to_dataframe
+      ~EfficientDiDResults.to_dict
 
 
 
@@ -28,7 +29,7 @@
       ~EfficientDiDResults.att
       ~EfficientDiDResults.bootstrap_results
       ~EfficientDiDResults.bootstrap_weights
-      ~EfficientDiDResults.cluster
+      ~EfficientDiDResults.cluster_name
       ~EfficientDiDResults.coef_var
       ~EfficientDiDResults.conf_int
       ~EfficientDiDResults.control_group
@@ -40,6 +41,7 @@
       ~EfficientDiDResults.is_significant
       ~EfficientDiDResults.kernel_bandwidth
       ~EfficientDiDResults.n_bootstrap
+      ~EfficientDiDResults.n_clusters
       ~EfficientDiDResults.omega_condition_numbers
       ~EfficientDiDResults.p_value
       ~EfficientDiDResults.pt_assumption
@@ -51,6 +53,7 @@
       ~EfficientDiDResults.significance_stars
       ~EfficientDiDResults.survey_metadata
       ~EfficientDiDResults.t_stat
+      ~EfficientDiDResults.vcov_type
       ~EfficientDiDResults.group_time_effects
       ~EfficientDiDResults.overall_att
       ~EfficientDiDResults.overall_se
diff --git a/tests/test_business_report.py b/tests/test_business_report.py
index cf96bc22..940ca1ef 100644
--- a/tests/test_business_report.py
+++ b/tests/test_business_report.py
@@ -1242,7 +1242,7 @@ def test_survey_weighted_fit_skipped_with_reason(self):
 
 class TestHausmanPretestPropagatesCluster:
     """Round-11 regression: ``EfficientDiDResults`` now persists the
-    ``cluster`` column used at fit time, and ``_pt_hausman`` forwards
+    ``cluster_name`` column used at fit time, and ``_pt_hausman`` forwards
     it to ``EfficientDiD.hausman_pretest``. Without this, clustered
     fits would be replayed under unclustered inference, silently
     publishing an H statistic / p-value for the wrong design.
@@ -1266,7 +1266,7 @@ def test_hausman_pretest_receives_cluster_kwarg(self):
             first_treat="first_treat",
         )
         # Confirm persistence landed.
-        assert getattr(edid, "cluster", None) == "cluster_col"
+        assert getattr(edid, "cluster_name", None) == "cluster_col"
 
         captured: dict = {}
 

From f808ae69a18363104e65bf3bb92932e084a172c3 Mon Sep 17 00:00:00 2001
From: igerber <isaac.gerber@gmail.com>
Date: Tue, 26 May 2026 10:50:07 -0400
Subject: [PATCH 3/3] =?UTF-8?q?efficient-did:=20make=20set=5Fparams=20atom?=
 =?UTF-8?q?ic=20=E2=80=94=20rollback=20all=20attribute=20mutations=20on=20?=
 =?UTF-8?q?validation=20failure?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously, EfficientDiD.set_params iterated over the kwargs and called
setattr() before invoking _validate_params(). A rejected batched call
such as set_params(vcov_type="classical", alpha=0.1, anticipation=2)
raised on validation but left every kwarg in the partially-mutated
state — the rejected vcov_type plus the otherwise-valid alpha and
anticipation. Callers that catch ValueError and continue using the
estimator would then operate on a silently corrupted parameter
configuration, defeating the eager-validation contract introduced when
_validate_vcov_type was wired into _validate_params.

Fix: snapshot original attribute values for every kwarg before applying
mutations, run validation, and on exception restore the snapshot before
re-raising. The snapshot pass also moves the "Unknown parameter" check
ahead of any mutation so that even unknown-name rejections leave the
estimator untouched.

Regression test added: test_set_params_rollback_on_validation_failure
fires the 3-kwarg batched call and pins all three attribute values to
their pre-call snapshot after the raise.
---
 diff_diff/efficient_did.py  | 27 ++++++++++++++++++++++-----
 tests/test_efficient_did.py | 18 ++++++++++++++++++
 2 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/diff_diff/efficient_did.py b/diff_diff/efficient_did.py
index 3a71a411..8760c2e4 100644
--- a/diff_diff/efficient_did.py
+++ b/diff_diff/efficient_did.py
@@ -351,13 +351,30 @@ def get_params(self) -> Dict[str, Any]:
         }
 
     def set_params(self, **params: Any) -> "EfficientDiD":
-        """Set estimator parameters (sklearn-compatible)."""
+        """Set estimator parameters (sklearn-compatible).
+
+        Atomic: snapshots the original attribute values before applying
+        mutations, validates the new state via ``_validate_params``, and
+        rolls every attribute back to its pre-call value if validation
+        raises. Without this, ``set_params(vcov_type="classical",
+        alpha=0.1)`` would leave ``self.vcov_type`` partially mutated
+        even though the call raised, defeating the eager-validation
+        contract for callers that catch ``ValueError`` and keep using
+        the estimator.
+        """
+        snapshot: Dict[str, Any] = {}
+        for key in params:
+            if not hasattr(self, key):
+                raise ValueError(f"Unknown parameter: {key}")
+            snapshot[key] = getattr(self, key)
         for key, value in params.items():
-            if hasattr(self, key):
+            setattr(self, key, value)
+        try:
+            self._validate_params()
+        except Exception:
+            for key, value in snapshot.items():
                 setattr(self, key, value)
-            else:
-                raise ValueError(f"Unknown parameter: {key}")
-        self._validate_params()
+            raise
         return self
 
     # -- Main estimation ------------------------------------------------------
diff --git a/tests/test_efficient_did.py b/tests/test_efficient_did.py
index e3edbad4..e5140c0d 100644
--- a/tests/test_efficient_did.py
+++ b/tests/test_efficient_did.py
@@ -2521,6 +2521,24 @@ def test_set_params_unknown_vcov_caught_immediately(self):
         with pytest.raises(ValueError, match="hc4"):
             ed.set_params(vcov_type="hc4")
 
+    def test_set_params_rollback_on_validation_failure(self):
+        # set_params is atomic: when validation rejects a batched call, NO
+        # attribute mutation persists. Pre-fix, set_params assigned every
+        # kwarg before invoking _validate_params, so a rejected
+        # `set_params(vcov_type="classical", alpha=0.1, anticipation=2)`
+        # raised but left all three attributes mutated — weakening eager-
+        # validation for callers that catch ValueError and keep using the
+        # estimator.
+        ed = EfficientDiD()
+        original_vcov = ed.vcov_type
+        original_alpha = ed.alpha
+        original_anticipation = ed.anticipation
+        with pytest.raises(ValueError, match="influence-function"):
+            ed.set_params(vcov_type="classical", alpha=0.1, anticipation=2)
+        assert ed.vcov_type == original_vcov
+        assert ed.alpha == original_alpha
+        assert ed.anticipation == original_anticipation
+
     # ---- Surface 7: bootstrap n_psu<2 NaN propagation ---------------------
 
     def test_bootstrap_n_psu_less_than_2_returns_nan(self):