PR #458 R2: move auto-route ahead of multi-absorb-survey guard

R2 review flagged that REGISTRY/CHANGELOG documented
`DiD(absorb=..., vcov_type in {hc2,hc2_bm})` as SUPPORTED, but the
legacy `len(absorb) > 1 + survey_weights` guard at estimators.py:347
fired BEFORE the auto-route, so weighted multi-absorb fits still raised.

The guard's rationale ("single-pass demeaning isn't the correct weighted
FWL projection for N>1 absorbed dimensions") doesn't apply when we're
auto-routing to fixed_effects= — the fixed_effects= path builds the
full-dummy design and solves WLS directly with no within-transform.

Reorder: move the auto-route block above the multi-absorb-survey guard.
The guard now only fires when absorb was NOT consumed by the auto-route
(i.e., hc1/classical/conley/etc. — paths that still demean).

Adds `test_absorb_hc2_bm_survey_multi_absorb_auto_routes` to pin the
new placement against silent regression. The existing `test_survey.py`
multi-absorb-survey rejection tests continue to pass (they use the
default vcov_type=hc1 path which still hits the guard).

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

Author: igerber

diff_diff/estimators.py

@@ -344,25 +344,6 @@ def fit(
         n_treated_raw = int(np.sum(data[treatment].values.astype(float)))
         n_control_raw = len(data) - n_treated_raw
 
-        # Reject multi-absorb with survey weights (single-pass demeaning is
-        # not the correct weighted FWL projection for N > 1 dimensions)
-        if absorb and len(absorb) > 1 and survey_weights is not None:
-            raise ValueError(
-                f"Multiple absorbed fixed effects (absorb={absorb}) with survey "
-                "weights is not supported. Single-pass sequential demeaning is not "
-                "the correct weighted FWL projection for multiple absorbed dimensions. "
-                "Use absorb with a single variable, or use fixed_effects= instead."
-            )
-
-        if absorb and fixed_effects:
-            raise ValueError(
-                "Cannot use both absorb and fixed_effects. "
-                "The absorb within-transformation does not residualize "
-                "fixed_effects dummies, violating the FWL theorem. "
-                "Use absorb alone (for high-dimensional FE) "
-                "or fixed_effects alone (for low-dimensional FE)."
-            )
-
         # Auto-route absorb → fixed_effects when vcov_type needs the FULL FE
         # hat matrix. HC2 leverage and CR2 Bell-McCaffrey DOF both depend on
         # the full-design hat; FWL preserves coefficients and residuals but
@@ -379,12 +360,42 @@ def fit(
         # Note: the user-facing `result.coefficients` under this auto-route
         # will include the FE-dummy entries (matching the fixed_effects= path),
         # not the slope-only view that a plain `absorb=` returns.
+        #
+        # Placement: this auto-route runs BEFORE the legacy multi-absorb +
+        # survey-weights guard because that guard's rationale ("single-pass
+        # demeaning is not the correct weighted FWL projection for N > 1
+        # dimensions") doesn't apply when we're about to swap absorb for
+        # fixed_effects: the fixed_effects= path builds the full-dummy design
+        # and solves WLS directly, with no within-transform step. R2 review
+        # surfaced the scope mismatch (REGISTRY/CHANGELOG said "SUPPORTED" but
+        # the survey guard fired first on weighted multi-absorb fits).
         if absorb and self.vcov_type in ("hc2", "hc2_bm"):
             fixed_effects = list(fixed_effects or []) + list(absorb)
             absorb = None
             absorbed_vars = []
             n_absorbed_effects = 0
 
+        # Reject multi-absorb with survey weights (single-pass demeaning is
+        # not the correct weighted FWL projection for N > 1 dimensions). Only
+        # fires when absorb is still set — i.e., the auto-route above didn't
+        # consume it.
+        if absorb and len(absorb) > 1 and survey_weights is not None:
+            raise ValueError(
+                f"Multiple absorbed fixed effects (absorb={absorb}) with survey "
+                "weights is not supported. Single-pass sequential demeaning is not "
+                "the correct weighted FWL projection for multiple absorbed dimensions. "
+                "Use absorb with a single variable, or use fixed_effects= instead."
+            )
+
+        if absorb and fixed_effects:
+            raise ValueError(
+                "Cannot use both absorb and fixed_effects. "
+                "The absorb within-transformation does not residualize "
+                "fixed_effects dummies, violating the FWL theorem. "
+                "Use absorb alone (for high-dimensional FE) "
+                "or fixed_effects alone (for low-dimensional FE)."
+            )
+
         # Validate vcov_type="conley" wire-up. DiD.fit() accepts `unit`
         # as a fit-time arg (NOT on __init__) because cluster/unit
         # semantics on DiD are opt-in rather than auto-derived (unlike

tests/test_estimators_vcov_type.py

@@ -1095,6 +1095,48 @@ def test_absorb_hc2_bm_clustered_matches_clubsandwich(self):
         np.testing.assert_allclose(res.se, expected_se_slope, atol=1e-10)
         np.testing.assert_allclose(res.att, float(d["coef"][treat_post_idx]), atol=1e-10)
 
+    def test_absorb_hc2_bm_survey_multi_absorb_auto_routes(self):
+        """Survey-weighted multi-absorb + HC2-BM should auto-route, not reject.
+
+        The legacy guard at `estimators.py` rejects `survey_design` paired with
+        `len(absorb) > 1` because single-pass demeaning is not the correct
+        weighted FWL projection for multiple absorbed dimensions. But when the
+        auto-route fires (hc2/hc2_bm), absorb is swapped for fixed_effects=
+        BEFORE the survey guard sees it, so the demeaning rationale doesn't
+        apply. R2 review caught the scope mismatch: REGISTRY said "SUPPORTED"
+        but the survey guard fired first on weighted multi-absorb. This test
+        pins the new placement.
+        """
+        from diff_diff import SurveyDesign
+
+        d = self._load_golden()
+        rng = np.random.default_rng(20260420)
+        n = len(d["y"])
+        data = pd.DataFrame(
+            {
+                "unit": d["unit"],
+                "period": d["period"],
+                "treated": d["treated"],
+                "post": d["post"],
+                "y": d["y"],
+                "weight": rng.uniform(0.5, 2.0, size=n),
+            }
+        )
+        sd = SurveyDesign(weights="weight", weight_type="aweight")
+        # Multi-absorb (`unit` + `period`) + survey-weighted + hc2_bm: should
+        # auto-route to fixed_effects= and succeed.
+        res = DifferenceInDifferences(vcov_type="hc2_bm").fit(
+            data,
+            outcome="y",
+            treatment="treated",
+            time="post",
+            absorb=["unit", "period"],
+            unit="unit",
+            survey_design=sd,
+        )
+        assert np.isfinite(res.att)
+        assert np.isfinite(res.se)
+
     def test_absorb_hc2_bm_df_sensitive_inference(self):
         """Bell-McCaffrey Satterthwaite DOF must propagate to `p_value` / `conf_int`.