Fix CI review R3: thread _df_survey to delta + HonestDiD surfaces

- P0: delta overall surface now uses _df_survey instead of df=None at both
  safe_inference sites (primary delta path + placebo NaN-SE fallback).
  This makes overall_* under L_max>=2 use survey-t inference and respects
  safe_inference's df<=0 NaN guard.
- P1: HonestDiD dCDH extraction now propagates df_survey from
  survey_metadata (mirrors CS pattern). Survey-backed dCDH HonestDiD
  bounds now use survey-aware critical values.
- P2: Add 4 regressions (survey delta t-matches-reported, t-vs-z differs,
  survey+controls, survey+honest_did df propagation). Update stale comment
  in test_dcdh_extraction.

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

Author: igerber

diff_diff/chaisemartin_dhaultfoeuille.py

@@ -2146,7 +2146,7 @@ def fit(
                 if np.isfinite(delta_se):
                     effective_overall_se = delta_se
                     effective_overall_t, effective_overall_p, effective_overall_ci = safe_inference(
-                        delta_val, delta_se, alpha=self.alpha, df=None
+                        delta_val, delta_se, alpha=self.alpha, df=_df_survey
                     )
                 else:
                     effective_overall_se = float("nan")
@@ -2180,7 +2180,7 @@ def fit(
                         # Fallback: NaN SE (Phase 1 path or missing IF)
                         pl_se = float("nan")
                         pl_t, pl_p, pl_ci = safe_inference(
-                            pl_data["placebo_l"], pl_se, alpha=self.alpha, df=None
+                            pl_data["placebo_l"], pl_se, alpha=self.alpha, df=_df_survey
                         )
                         placebo_event_study_dict[-lag_l] = {
                             "effect": pl_data["placebo_l"],

diff_diff/honest_did.py

@@ -967,14 +967,24 @@ def _largest_consecutive_block(times, boundary_val):
                 beta_hat = np.array(effects)
                 sigma = np.diag(np.array(ses) ** 2)
 
+                # Extract survey df. For replicate designs with undefined df
+                # (rank <= 1), use sentinel df=0 so _get_critical_value returns
+                # NaN, matching the safe_inference contract.
+                df_survey = None
+                if hasattr(results, "survey_metadata") and results.survey_metadata is not None:
+                    sm = results.survey_metadata
+                    df_survey = getattr(sm, "df_survey", None)
+                    if df_survey is None and getattr(sm, "replicate_method", None) is not None:
+                        df_survey = 0  # undefined replicate df → NaN inference
+
                 return (
                     beta_hat,
                     sigma,
                     len(pre_times),
                     len(post_times),
                     pre_times,
                     post_times,
-                    None,  # df_survey: dCDH has no survey support
+                    df_survey,
                 )
         except ImportError:
             pass

tests/test_honest_did.py

@@ -1381,7 +1381,7 @@ def test_dcdh_extraction(self):
         assert sigma.shape == (n_pre + n_post, n_pre + n_post)
         assert all(t < 0 for t in pre_t)
         assert all(t > 0 for t in post_t)
-        assert df_s is None  # dCDH has no survey support
+        assert df_s is None  # non-survey fixture → df_survey is None
 
     def test_dcdh_no_placebos_raises(self):
         """dCDH results without placebos raise ValueError."""

tests/test_survey_dcdh.py

@@ -442,3 +442,134 @@ def test_zero_weight_cell_excluded(self, base_data):
             survey_design=sd,
         )
         assert np.isfinite(result.overall_att)
+
+
+# ── Test: Delta overall surface threads survey df ───────────────────
+
+
+class TestSurveyDeltaInference:
+    """Verify the L_max>=2 cost-benefit delta surface uses survey df."""
+
+    def test_survey_delta_uses_survey_df(self, data_with_survey):
+        """Under L_max=2 with a survey design, overall_p_value must match
+        t-distribution inference with df=df_survey (not z-inference)."""
+        from scipy import stats
+
+        sd = SurveyDesign(
+            weights="pw", strata="stratum", psu="cluster", nest=True
+        )
+        r = ChaisemartinDHaultfoeuille(seed=1).fit(
+            data_with_survey,
+            outcome="outcome", group="group",
+            time="period", treatment="treatment",
+            L_max=2, survey_design=sd,
+        )
+        if not (np.isfinite(r.overall_se) and r.overall_se > 0):
+            pytest.skip("delta not estimable on this fixture")
+
+        assert r.survey_metadata is not None
+        df_s = r.survey_metadata.df_survey
+        assert df_s is not None and df_s > 0, (
+            f"expected positive df_survey, got {df_s}"
+        )
+
+        t_stat = r.overall_att / r.overall_se
+        p_t = 2.0 * (1.0 - stats.t.cdf(abs(t_stat), df=df_s))
+        # Reported p-value must match t-based (proving _df_survey was threaded)
+        assert r.overall_p_value == pytest.approx(p_t, abs=1e-10)
+
+    def test_survey_delta_t_differs_from_z(self, base_data):
+        """With a small-df design (df~4), survey-t p-value must differ
+        measurably from z p-value at the delta surface."""
+        from scipy import stats
+
+        df_ = base_data.copy()
+        df_["pw"] = 1.0
+        # 2 strata × 3 clusters/stratum = 6 nested PSUs → df_survey = 4
+        groups = sorted(df_["group"].unique())
+        n_g = len(groups)
+        strata_map = {g: i // (n_g // 2) for i, g in enumerate(groups)}
+        psu_map = {g: i // (n_g // 6) for i, g in enumerate(groups)}
+        df_["stratum"] = df_["group"].map(strata_map)
+        df_["cluster"] = df_["group"].map(psu_map)
+        sd = SurveyDesign(
+            weights="pw", strata="stratum", psu="cluster", nest=True
+        )
+        r = ChaisemartinDHaultfoeuille(seed=1).fit(
+            df_,
+            outcome="outcome", group="group",
+            time="period", treatment="treatment",
+            L_max=2, survey_design=sd,
+        )
+        if not (np.isfinite(r.overall_se) and r.overall_se > 0):
+            pytest.skip("delta not estimable on this fixture")
+        assert r.survey_metadata is not None
+        df_s = r.survey_metadata.df_survey
+        assert df_s is not None and df_s < 30, (
+            f"expected small df_survey for t-vs-z gap, got {df_s}"
+        )
+
+        t_stat = r.overall_att / r.overall_se
+        p_t = 2.0 * (1.0 - stats.t.cdf(abs(t_stat), df=df_s))
+        p_z = 2.0 * (1.0 - stats.norm.cdf(abs(t_stat)))
+        # Threaded p-value must match t, not z
+        assert r.overall_p_value == pytest.approx(p_t, abs=1e-10)
+        assert abs(r.overall_p_value - p_z) > 1e-6, (
+            "overall_p_value must differ from z-inference when df_survey is small"
+        )
+
+
+# ── Test: Survey + controls (DID^X) ─────────────────────────────────
+
+
+class TestSurveyControls:
+    """Covariate-adjusted (DID^X) path must work with survey_design."""
+
+    def test_survey_plus_controls_runs(self, data_with_survey):
+        """Covariate-adjusted dCDH with survey_design produces finite ATT."""
+        rng = np.random.default_rng(7)
+        df_ = data_with_survey.copy()
+        df_["x"] = rng.normal(0, 1.0, size=len(df_))
+        sd = SurveyDesign(
+            weights="pw", strata="stratum", psu="cluster", nest=True
+        )
+        r = ChaisemartinDHaultfoeuille(seed=1).fit(
+            df_,
+            outcome="outcome", group="group",
+            time="period", treatment="treatment",
+            controls=["x"], L_max=1, survey_design=sd,
+        )
+        assert np.isfinite(r.overall_att)
+        assert r.survey_metadata is not None
+
+
+# ── Test: Survey + HonestDiD ────────────────────────────────────────
+
+
+class TestSurveyHonestDiD:
+    """HonestDiD bounds on survey-backed dCDH results must carry df_survey."""
+
+    def test_survey_honest_did_propagates_df(self, data_with_survey):
+        """results.honest_did_results.df_survey must match
+        results.survey_metadata.df_survey (non-None propagation)."""
+        import warnings
+
+        sd = SurveyDesign(
+            weights="pw", strata="stratum", psu="cluster", nest=True
+        )
+        with warnings.catch_warnings():
+            # dCDH HonestDiD emits a methodology-deviation warning
+            warnings.simplefilter("ignore")
+            r = ChaisemartinDHaultfoeuille(seed=1).fit(
+                data_with_survey,
+                outcome="outcome", group="group",
+                time="period", treatment="treatment",
+                L_max=2, honest_did=True, survey_design=sd,
+            )
+        if r.honest_did_results is None:
+            pytest.skip("HonestDiD computation returned None on this fixture")
+        assert r.survey_metadata is not None
+        df_meta = r.survey_metadata.df_survey
+        assert df_meta is not None
+        # df_survey must propagate from survey_metadata into HonestDiD result
+        assert r.honest_did_results.df_survey == df_meta