Codex re-review round 3: TWFE contract narrowing + lag_cutoff propagation

P1 (Methodology): the prior commit's "arbitrary ordered labels" contract
was unreachable on TwoWayFixedEffects because TWFE's design step builds
`_treatment_post = treated * time` from raw column values, which fails
on datetime64 / pd.Period / string labels. Narrowing the docs to make
explicit that the non-numeric-label contract is MultiPeriodDiD-only (MPD
builds period dummies, not a `treated * time` product). TWFE inherits
its pre-existing numeric-time constraint.

- llms-full.txt: split the panel example into a TWFE block (binary post
  indicator only, `conley_lag_cutoff=1`) and an MPD block (multi-period
  time, arbitrary orderable encoding). New caveat paragraph spells out
  the TWFE numeric-time constraint.
- test_twfe_conley_non_numeric_time_fails: TWFE + string-encoded time
  raises a clean error (string * int multiplication fails inside the
  estimator) — regression for the narrowed contract.

P1 (Maintainability): `conley_lag_cutoff` is a new public parameter that
materially changes vcov semantics (0 = spatial only, >0 = adds within-
unit Bartlett serial HAC), but the result objects didn't expose it.

- DiDResults + MultiPeriodDiDResults: new `conley_lag_cutoff: Optional[int]`
  field threaded through the estimator-side construction.
- `_format_vcov_label` now includes `lag_cutoff=<int>` in the Conley
  label so summary() readers can tell which Conley variant produced
  the reported SEs (e.g. "Conley spatial HAC (1999), lag_cutoff=1").
- TestConleyTWFE summary test asserts both the label format and the
  programmatic `res.conley_lag_cutoff` accessor.

P3 (Doc/test): MPD docstring claimed `inference="wild_bootstrap"` + conley
raises but only TWFE had that guard. Added the explicit raise in MPD.fit()
to match the documented contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

diff_diff/estimators.py

@@ -601,6 +601,7 @@ def _refit_did_absorb(w_r):
             # stored `self.vcov_type`.
             vcov_type=_fit_vcov_type,
             cluster_name=self.cluster,
+            conley_lag_cutoff=(self.conley_lag_cutoff if _fit_vcov_type == "conley" else None),
         )
 
         self._coefficients = coefficients
@@ -1416,6 +1417,14 @@ def fit(  # type: ignore[override]
                     "cluster-robust without spatial HAC, or drop survey_design= "
                     "for panel Conley."
                 )
+            if self.inference == "wild_bootstrap":
+                raise NotImplementedError(
+                    "MultiPeriodDiD(vcov_type='conley', "
+                    "inference='wild_bootstrap') is not supported: wild "
+                    "bootstrap is a separate inference path that does not "
+                    "consume the analytical Conley sandwich. Use "
+                    "inference='analytical' for Conley SEs."
+                )
         # Pre-compute non_ref_periods (needed for absorb demeaning)
         non_ref_periods = [p for p in all_periods if p != reference_period]
 
@@ -1878,6 +1887,7 @@ def _refit_mp_absorb(w_r):
             n_clusters=(
                 len(np.unique(effective_cluster_ids)) if effective_cluster_ids is not None else None
             ),
+            conley_lag_cutoff=(self.conley_lag_cutoff if _fit_vcov_type == "conley" else None),
         )
 
         self._coefficients = coefficients

diff_diff/guides/llms-full.txt

@@ -1924,39 +1924,47 @@ reg = LinearRegression(
 ).fit(X, y)
 se = np.sqrt(np.diag(reg.vcov_))
 
-# Panel design: TWFE with within-unit Bartlett serial HAC (lag = 2 periods).
-# `time` must be a panel-period index column with one row per (unit, period).
-# diff-diff internally normalizes the time labels to dense panel-period codes
-# 0..T-1, so any orderable encoding works — int years (2020, 2021, ...),
-# YYYYMM (202012, 202101, ...), datetime64, pd.Period, strings.
+# Panel design: TWFE with within-unit Bartlett serial HAC.
+# TWFE's `time` column is intrinsically a binary post indicator
+# (treatment * time interaction); only numeric encodings are supported on
+# this surface. `conley_lag_cutoff=1` includes the cross-period pair under
+# the Bartlett taper. For multi-period panels, use MultiPeriodDiD.
 res = TwoWayFixedEffects(
     vcov_type="conley",
     conley_coords=("lat", "lon"),        # column names on `data`
     conley_cutoff_km=500.0,
-    conley_lag_cutoff=2,                 # within-unit Bartlett up to 2 panel periods
-).fit(data, outcome="y", treatment="treated", time="period", unit="unit_id")
+    conley_lag_cutoff=1,                 # within-unit Bartlett, lag 1 panel period
+).fit(data, outcome="y", treatment="treated", time="post", unit="unit_id")
 
-# Panel design: MultiPeriodDiD with cross-sectional within-period only (lag=0)
+# Panel design: MultiPeriodDiD with multi-period time.
+# MultiPeriodDiD builds period dummies (NOT a treated * time product), so
+# `time` can be any orderable encoding — int years (2020, 2021, ...),
+# YYYYMM (202012, 202101, ...), datetime64, pd.Period, strings.
+# `_compute_conley_vcov` normalizes time to dense codes 0..T-1 internally,
+# so `conley_lag_cutoff` always counts panel periods regardless of label.
 mp_res = MultiPeriodDiD(
     vcov_type="conley",
     conley_coords=("lat", "lon"),
     conley_cutoff_km=200.0,
-    conley_lag_cutoff=0,                 # spatial-within-period only
+    conley_lag_cutoff=2,                 # within-unit Bartlett up to 2 panel periods
 ).fit(data, outcome="y", treatment="treated", time="period",
       post_periods=[2, 3], unit="unit_id")
 ```
 
 **Note on `conley_lag_cutoff` semantics:** the lag is counted in **panel
 periods** (number of distinct sorted values in the `time` column), NOT in
 raw-label differences. Internally, time labels are normalized to dense codes
-`0..T-1` via `np.unique(return_inverse=True)`. For example, `time` values
-`(2020, 2021, 2022)` and `(202012, 202101, 202102)` both produce the same
-codes `(0, 1, 2)` and the same lag matrix. **Deviation from R `conleyreg`:**
-R uses raw `time` values directly in the lag computation, which silently
-mishandles non-dense encodings (`time = 202012, 202101` and `lag_cutoff=1`
-under R produces 0 weight because the raw difference is 89). diff-diff is
-the more robust default; for bit-exact R parity, pass `time` as a dense
-integer index.
+`0..T-1` via `np.unique(return_inverse=True)`. For example, MultiPeriodDiD
+with `time` values `(2020, 2021, 2022)` and `(202012, 202101, 202102)` both
+produce the same codes `(0, 1, 2)` and the same lag matrix. **TWFE caveat:**
+the time-label normalization runs inside `_compute_conley_vcov`, but TWFE's
+own design step `_treatment_post = treated * time` requires numeric `time`;
+non-numeric labels (datetime64, pd.Period, strings) are TWFE-incompatible
+end-to-end. Use MultiPeriodDiD if you need datetime/Period/string time
+labels. **Deviation from R `conleyreg`:** R uses raw `time` values directly
+in the lag computation, which silently mishandles non-dense encodings.
+diff-diff is the more robust default; for bit-exact R parity, pass `time`
+as a dense integer index.
 
 **Variance estimator — cross-sectional:**
 

diff_diff/results.py

@@ -52,6 +52,7 @@ def _format_vcov_label(
     cluster_name: Optional[str],
     n_clusters: Optional[int],
     n_obs: Optional[int],
+    conley_lag_cutoff: Optional[int] = None,
 ) -> Optional[str]:
     """Compose a human-readable variance-family label for summary output.
 
@@ -77,6 +78,8 @@ def _format_vcov_label(
         # Cross-sectional Conley on direct LinearRegression / compute_robust_vcov,
         # or panel block-decomposed Conley (within-period spatial + within-unit
         # Bartlett serial) on MultiPeriodDiD / TwoWayFixedEffects.
+        if conley_lag_cutoff is not None:
+            return f"Conley spatial HAC (1999), lag_cutoff={conley_lag_cutoff}"
         return "Conley spatial HAC (1999)"
     return None
 
@@ -130,15 +133,17 @@ class DiDResults:
     bootstrap_distribution: Optional[np.ndarray] = field(default=None, repr=False)
     # Survey design metadata (SurveyMetadata instance from diff_diff.survey)
     survey_metadata: Optional[Any] = field(default=None)
-    # Variance-covariance family: "classical" | "hc1" | "hc2" | "hc2_bm".
-    # Plus cluster_name when cluster-robust. Used by summary() to label the
-    # SE family in the output. vcov_type='conley' is rejected at fit-time
-    # for all panel estimators (DifferenceInDifferences/MultiPeriodDiD/TWFE)
-    # in Phase 1; the supported Conley path is direct LinearRegression /
-    # compute_robust_vcov on a cross-sectional design, which uses its own
-    # result class.
+    # Variance-covariance family: "classical" | "hc1" | "hc2" | "hc2_bm" |
+    # "conley". Plus cluster_name when cluster-robust. Used by summary() to
+    # label the SE family in the output. For vcov_type='conley' on
+    # MultiPeriodDiD / TwoWayFixedEffects, `conley_lag_cutoff` carries the
+    # within-unit Bartlett max lag (matches the constructor arg). On
+    # DifferenceInDifferences, vcov_type='conley' is rejected at fit-time
+    # (DiD.fit() has no unit column declaration); see MultiPeriodDiD /
+    # TwoWayFixedEffects for the panel block-decomposed path.
     vcov_type: Optional[str] = field(default=None)
     cluster_name: Optional[str] = field(default=None)
+    conley_lag_cutoff: Optional[int] = field(default=None)
 
     def __repr__(self) -> str:
         """Concise string representation."""
@@ -220,6 +225,7 @@ def summary(self, alpha: Optional[float] = None) -> str:
                 cluster_name=self.cluster_name,
                 n_clusters=self.n_clusters,
                 n_obs=self.n_obs,
+                conley_lag_cutoff=self.conley_lag_cutoff,
             )
             if label is not None:
                 lines.append(f"{'Variance:':<25} {label:>40}")
@@ -453,11 +459,12 @@ class MultiPeriodDiDResults:
     n_bootstrap: Optional[int] = field(default=None)
     n_clusters: Optional[int] = field(default=None)
     # Variance-covariance family and cluster column for summary() labeling.
-    # vcov_type='conley' is rejected at fit-time for MultiPeriodDiD (Phase 1
-    # supports cross-sectional Conley only via direct compute_robust_vcov);
-    # see _format_vcov_label.
+    # vcov_type='conley' on MultiPeriodDiD uses the panel block-decomposed
+    # form; `conley_lag_cutoff` carries the within-unit Bartlett max lag
+    # (matches the constructor arg). See _format_vcov_label.
     vcov_type: Optional[str] = field(default=None)
     cluster_name: Optional[str] = field(default=None)
+    conley_lag_cutoff: Optional[int] = field(default=None)
 
     # --- Inference-field aliases (balance/external-adapter compatibility) ---
     @property
@@ -560,6 +567,7 @@ def summary(self, alpha: Optional[float] = None) -> str:
                 cluster_name=self.cluster_name,
                 n_clusters=self.n_clusters,
                 n_obs=self.n_obs,
+                conley_lag_cutoff=self.conley_lag_cutoff,
             )
             if label is not None:
                 lines.append(f"{'Variance:':<25} {label:>50}")

diff_diff/twfe.py

@@ -593,6 +593,7 @@ def _refit_twfe(w_r):
             # remapped hc1 under the legacy alias path, not self.vcov_type.
             vcov_type=_fit_vcov_type,
             cluster_name=_twfe_cluster_label,
+            conley_lag_cutoff=(self.conley_lag_cutoff if _fit_vcov_type == "conley" else None),
         )
 
         self.is_fitted_ = True

tests/test_conley_vcov.py

@@ -1403,7 +1403,10 @@ def test_twfe_conley_binary_post_label_normalization(self, panel):
 
     def test_twfe_conley_summary_emits_conley_label(self, panel):
         """Panel result summary must label the variance family as Conley
-        spatial HAC when vcov_type='conley'. Closes Codex P3."""
+        spatial HAC and surface `lag_cutoff` so downstream consumers can tell
+        which Conley variant produced the SEs. Closes Codex P3 and the
+        re-review P1 (Maintainability).
+        """
         from diff_diff import TwoWayFixedEffects
 
         res = TwoWayFixedEffects(
@@ -1414,6 +1417,34 @@ def test_twfe_conley_summary_emits_conley_label(self, panel):
         ).fit(panel, outcome="y", treatment="treated", time="time", unit="unit")
         summary = res.summary()
         assert "Conley spatial HAC" in summary
+        assert "lag_cutoff=1" in summary
+        # The result dataclass also carries the lag for programmatic access.
+        assert res.conley_lag_cutoff == 1
+
+    def test_twfe_conley_non_numeric_time_fails(self, panel):
+        """TWFE's `_treatment_post = treated * time` design step requires
+        numeric `time`. Non-numeric labels (datetime64, pd.Period, strings)
+        are TWFE-incompatible end-to-end and surface as a clean error before
+        the Conley path runs. Use MultiPeriodDiD if you need non-numeric
+        time labels.
+        """
+        from diff_diff import TwoWayFixedEffects
+
+        df_str = panel.copy()
+        df_str["time_str"] = df_str["time"].map({0: "pre", 1: "post"})
+        with pytest.raises((TypeError, ValueError)):
+            TwoWayFixedEffects(
+                vcov_type="conley",
+                conley_coords=("lat", "lon"),
+                conley_cutoff_km=2000.0,
+                conley_lag_cutoff=1,
+            ).fit(
+                df_str,
+                outcome="y",
+                treatment="treated",
+                time="time_str",
+                unit="unit",
+            )
 
     def test_twfe_conley_within_vs_dummy_expansion_equivalence(self, panel):
         """FWL composability: TWFE (within-transform) + Conley should produce