Fix CI review Round 3: validation guards for het/design2 interactions

P1: heterogeneity without L_max now raises ValueError (was silent no-op).
P1: heterogeneity rejects trends_linear and trends_nonparam (would produce
    coefficients for wrong estimand since het test uses raw level changes).
P1: design2=True with drop_larger_lower=True now raises ValueError (the
    2-switch groups Design-2 needs are dropped by the default filter).
P3: NaN overall row under trends_linear+L_max>=2 now labeled as
    "DID^{fd}_l (see linear_trends_effects)" instead of "Cost-Benefit Delta".

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

Author: igerber

diff_diff/chaisemartin_dhaultfoeuille.py

@@ -601,6 +601,16 @@ def fit(
                 "CallawaySantAnna which supports survey_design."
             )
 
+        # Design-2 precondition: requires drop_larger_lower=False
+        if design2 and self.drop_larger_lower:
+            raise ValueError(
+                "design2=True requires drop_larger_lower=False because "
+                "Design-2 groups have exactly 2 treatment changes (join "
+                "then leave), which are dropped by the default "
+                "drop_larger_lower=True filter. Construct the estimator "
+                "with ChaisemartinDHaultfoeuille(drop_larger_lower=False)."
+            )
+
         # ------------------------------------------------------------------
         # Step 4-5: Validate input + aggregate to (g, t) cells via the
         # shared helper used by both fit() and twowayfeweights(). The
@@ -2132,7 +2142,12 @@ def fit(
         # Heterogeneity testing (Web Appendix Section 1.5, Lemma 7)
         # ------------------------------------------------------------------
         heterogeneity_effects: Optional[Dict[int, Dict[str, Any]]] = None
-        if heterogeneity is not None and L_max is not None and L_max >= 1:
+        if heterogeneity is not None:
+            if L_max is None:
+                raise ValueError(
+                    "heterogeneity testing requires L_max >= 1. Set L_max "
+                    "to use the per-group DID_{g,l} path."
+                )
             het_col = str(heterogeneity)
             if het_col not in data.columns:
                 raise ValueError(
@@ -2146,6 +2161,20 @@ def fit(
                     "R's did_multiplegt_dyn disallows predict_het with "
                     "controls; remove one of the two options."
                 )
+            if _is_trends_linear:
+                raise ValueError(
+                    "heterogeneity cannot be combined with trends_linear. "
+                    "The heterogeneity test operates on level outcome "
+                    "changes but trends_linear uses second-differenced "
+                    "outcomes; the results would be inconsistent."
+                )
+            if trends_nonparam is not None:
+                raise ValueError(
+                    "heterogeneity cannot be combined with trends_nonparam. "
+                    "The heterogeneity test does not thread state-set "
+                    "control-pool restrictions; the results would be "
+                    "inconsistent with the fitted estimator."
+                )
             # Extract per-group covariate (must be time-invariant)
             het_per_group = data.groupby(group)[het_col].nunique()
             het_varying = het_per_group[het_per_group > 1]

diff_diff/chaisemartin_dhaultfoeuille_results.py

@@ -423,6 +423,11 @@ def _estimand_label(self) -> str:
         has_controls = self.covariate_residuals is not None
         has_trends = self.linear_trends_effects is not None
 
+        # When trends_linear + L_max>=2, overall is NaN (no aggregate).
+        # Label reflects that per-horizon effects are in linear_trends_effects.
+        if has_trends and self.L_max is not None and self.L_max >= 2:
+            return "DID^{fd}_l (see linear_trends_effects)"
+
         if self.L_max is not None and self.L_max >= 2:
             base = "delta"
         elif self.L_max is not None and self.L_max == 1:

tests/test_chaisemartin_dhaultfoeuille.py

@@ -2772,6 +2772,34 @@ def test_heterogeneity_rejects_controls(self):
                 L_max=1, heterogeneity="het_x", controls=["X1"],
             )
 
+    def test_heterogeneity_requires_lmax(self):
+        """heterogeneity without L_max raises ValueError."""
+        df = self._make_panel_with_het()
+        with pytest.raises(ValueError, match="requires L_max >= 1"):
+            ChaisemartinDHaultfoeuille(seed=1).fit(
+                df, "outcome", "group", "period", "treatment",
+                heterogeneity="het_x",
+            )
+
+    def test_heterogeneity_rejects_trends_linear(self):
+        """heterogeneity + trends_linear raises ValueError."""
+        df = self._make_panel_with_het()
+        with pytest.raises(ValueError, match="cannot be combined with trends_linear"):
+            ChaisemartinDHaultfoeuille(seed=1).fit(
+                df, "outcome", "group", "period", "treatment",
+                L_max=2, heterogeneity="het_x", trends_linear=True,
+            )
+
+    def test_heterogeneity_rejects_trends_nonparam(self):
+        """heterogeneity + trends_nonparam raises ValueError."""
+        df = self._make_panel_with_het()
+        df["state"] = df["group"] % 3
+        with pytest.raises(ValueError, match="cannot be combined with trends_nonparam"):
+            ChaisemartinDHaultfoeuille(seed=1).fit(
+                df, "outcome", "group", "period", "treatment",
+                L_max=1, heterogeneity="het_x", trends_nonparam="state",
+            )
+
 
 class TestDesign2:
     """Design-2 switch-in/switch-out separation (ROADMAP item 3e)."""
@@ -2822,7 +2850,8 @@ def test_design2_no_eligible(self):
                 y = 10 + 2 * t + 5 * d + rng.normal(0, 0.5)
                 rows.append({"group": g, "period": t, "treatment": d, "outcome": y})
         df = pd.DataFrame(rows)
-        r = ChaisemartinDHaultfoeuille(seed=1).fit(
+        # drop_larger_lower=False required for design2=True
+        r = ChaisemartinDHaultfoeuille(seed=1, drop_larger_lower=False).fit(
             df, "outcome", "group", "period", "treatment",
             L_max=1, design2=True,
         )
@@ -2836,6 +2865,15 @@ def test_design2_disabled_by_default(self):
         )
         assert r.design2_effects is None
 
+    def test_design2_rejects_drop_larger_lower(self):
+        """design2=True with default drop_larger_lower=True raises ValueError."""
+        df = self._make_join_then_leave_panel()
+        with pytest.raises(ValueError, match="drop_larger_lower=False"):
+            ChaisemartinDHaultfoeuille(seed=1).fit(
+                df, "outcome", "group", "period", "treatment",
+                L_max=1, design2=True,
+            )
+
 
 class TestNonBinaryTreatment:
     """Non-binary treatment support (ROADMAP item 3f)."""