fix(staggered): rank-0 centered reg bread collapses to zero correction, not NaN

CI review P1: with a constant as the ONLY reg covariate the centered
estimation-effect Gram is rank-0, and _safe_inv's all-NaN sentinel
NaN-poisoned per-cell/aggregated SEs for cells whose intercept-only
projection is fully identified (pre-fix raw-Gram column-drop and the
no-covariate fit both give finite SEs). New _centered_or_bread helper
(shared by all three reg sites) maps the rank-0 sentinel to a zero
correction - proj collapses to 1/sum(W_c), equal to the no-covariate
fit - while partial deficiency and the aggregate rank-guard warning
are unchanged. ipw/dr breads are over [1, X] and keep NaN propagation
(true pathology); the rank-0 monkeypatch test is re-scoped to ipw/dr
with constant-only reg equivalence tests (unweighted + survey) added.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X4AzrFUMqJxcUumSH31mSr

Author: igerber

diff_diff/staggered.py

@@ -1437,10 +1437,7 @@ def _compute_all_att_gt_covariate_reg(
                 if is_balanced and self.control_group == "never_treated":
                     group_xbar_c = X_ctrl_raw.mean(axis=0)
                     group_Xc_centered = X_ctrl_raw - group_xbar_c
-                    group_bread = _safe_inv(
-                        group_Xc_centered.T @ group_Xc_centered,
-                        tracker=self._safe_inv_tracker,
-                    )
+                    group_bread = self._centered_or_bread(group_Xc_centered.T @ group_Xc_centered)
 
             # Process each (g, t) pair in this group
             for g, t, bp_val, base_col, post_col in tasks:
@@ -1604,10 +1601,7 @@ def _compute_all_att_gt_covariate_reg(
                         else:
                             xbar_c = X_control_pair.mean(axis=0)
                             Xc_centered = X_control_pair - xbar_c
-                            bread = _safe_inv(
-                                Xc_centered.T @ Xc_centered,
-                                tracker=self._safe_inv_tracker,
-                            )
+                            bread = self._centered_or_bread(Xc_centered.T @ Xc_centered)
                         d_tc = X_treated_pair.mean(axis=0) - xbar_c
                         with np.errstate(all="ignore"):
                             proj_c = 1.0 / pair_n_c + Xc_centered @ (bread @ d_tc)
@@ -2616,6 +2610,28 @@ def fit(
         self.is_fitted_ = True
         return self.results_
 
+    def _centered_or_bread(self, gram: np.ndarray) -> np.ndarray:
+        """Rank-guarded inverse of the CENTERED control covariate Gram.
+
+        Unlike the ``[1, X]`` breads elsewhere, the intercept direction is
+        handled analytically here (the ``1/sum(W_c)`` leading term of the
+        reg estimation-effect projection), so a rank-0 centered Gram — zero
+        within-control covariate variation, e.g. a constant covariate as
+        the only regressor — is benign: the correction on the identified
+        (intercept-only) subset is exactly zero, and the projection
+        collapses to ``1/sum(W_c)``. Map ``_safe_inv``'s all-NaN rank-0
+        sentinel to a zero matrix so the cell keeps the finite SE on the
+        identified subset (rank-guard REGISTRY contract; equals both the
+        no-covariate fit and the pre-centered raw-Gram column-drop) instead
+        of NaN-poisoning the IF. Partial deficiency is untouched —
+        ``_safe_inv`` already returns a zero-filled column-dropped inverse,
+        and the aggregate rank-guard warning still fires via the tracker.
+        """
+        bread = _safe_inv(gram, tracker=self._safe_inv_tracker)
+        if bread.size and not np.any(np.isfinite(bread)):
+            return np.zeros_like(bread)
+        return bread
+
     def _outcome_regression(
         self,
         treated_change: np.ndarray,
@@ -2704,10 +2720,7 @@ def _outcome_regression(
             with np.errstate(all="ignore"):
                 xbar_c = np.sum(W_c[:, None] * X_control, axis=0) / w_c_sum
                 Xc_centered = X_control - xbar_c
-                bread = _safe_inv(
-                    Xc_centered.T @ (W_c[:, None] * Xc_centered),
-                    tracker=self._safe_inv_tracker,
-                )
+                bread = self._centered_or_bread(Xc_centered.T @ (W_c[:, None] * Xc_centered))
                 proj_c = 1.0 / w_c_sum + Xc_centered @ (bread @ (xbar_t - xbar_c))
                 inf_control = -(W_c * resid_c) * proj_c
             inf_func = np.concatenate([inf_treated, inf_control])

docs/methodology/REGISTRY.md

@@ -523,6 +523,15 @@ Aggregations:
   DR's no-covariate per-cell SE keeps its ddof=1 plug-in (O(1/n) from R; TODO row).
   Side effect: reg/ipw fits with collinear covariates now route their IF breads
   through the rank-guarded inverse and fire the same aggregate warning as dr.
+  Rank-0 semantics of the reg CENTERED Gram: because the intercept direction is
+  handled analytically by the `1/sum(W_c)` leading term, a rank-0 centered Gram
+  (zero within-control covariate variation, e.g. a constant as the only
+  covariate) is the benign identified-subset case — the estimation-effect
+  correction is exactly zero and the fit collapses to the no-covariate reg fit
+  with finite SEs (`_centered_or_bread` maps `_safe_inv`'s all-NaN rank-0
+  sentinel to a zero correction; the aggregate rank-guard warning still fires).
+  This differs from the `[1, X]` breads (ipw PS Hessian, dr), where all-NaN is
+  a true pathology that NaN-propagates.
 - All aggregation SEs (simple, event study) include the weight influence function (WIF)
   adjustment, matching R's `did::aggte()`. The WIF accounts for uncertainty in estimating
   group-size aggregation weights. Group aggregation uses equal time weights (deterministic),

tests/test_staggered.py

@@ -1655,16 +1655,20 @@ def test_clustered_constant_covariate_finite_se(self):
         assert np.isfinite(res.overall_se)
         assert res.overall_se < 1.0
 
-    @pytest.mark.parametrize("method", ["reg", "ipw", "dr"])
+    @pytest.mark.parametrize("method", ["ipw", "dr"])
     def test_rank0_bread_propagates_nan_not_zero(self, monkeypatch, method):
         # rank-0 is unreachable through covariates alone (the always-present
         # intercept guarantees rank >= 1), so simulate an all-NaN bread to
         # exercise the NaN-masking fix: var_psi becomes NaN and must yield a NaN
-        # SE, NOT 0.0 via the old ``var_psi > 0 else 0.0`` guard. reg/ipw now
-        # derive their per-cell SE from _safe_inv-based IF terms too (OLS
-        # estimation-effect bread / PS Hessian), so all three methods share
-        # the contract. The point estimate does NOT depend on the bread, so
-        # it stays finite (NaN inference on an estimable cell, not _nan_gt_entry).
+        # SE, NOT 0.0 via the old ``var_psi > 0 else 0.0`` guard. ipw's PS
+        # Hessian and dr's breads are over [1, X], so all-NaN there is a true
+        # pathology that must propagate. reg is deliberately EXCLUDED: its
+        # estimation-effect bread is over the CENTERED covariate Gram (the
+        # intercept is handled analytically), where rank-0 is the benign
+        # constant-covariate case mapped to a zero correction — see
+        # test_reg_constant_only_covariate_matches_no_covariate below.
+        # The point estimate does NOT depend on the bread, so it stays
+        # finite (NaN inference on an estimable cell, not _nan_gt_entry).
         from tests.conftest import assert_nan_inference
         import diff_diff.staggered as staggered_mod
 
@@ -2020,6 +2024,73 @@ def test_universal_base_period_anticipation_reg_smoke(self):
                 assert np.isfinite(cell["se"]), f"cell ({g},{t})"
         assert np.isfinite(res.overall_se)
 
+    def test_reg_constant_only_covariate_matches_no_covariate(self):
+        """A constant as the ONLY reg covariate makes the CENTERED
+        estimation-effect Gram rank-0 (all-zero). The correction on the
+        identified (intercept-only) subset is exactly zero, so effects AND
+        SEs must equal the no-covariate fit - finite, never NaN (the rank-0
+        centered bread maps to a zero correction, not an all-NaN inverse)."""
+        data = generate_staggered_data_with_covariates(seed=789)
+        data["xc"] = 5.0
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            no_cov = CallawaySantAnna(estimation_method="reg").fit(
+                data, "outcome", "unit", "time", "first_treat"
+            )
+            const_only = CallawaySantAnna(estimation_method="reg").fit(
+                data, "outcome", "unit", "time", "first_treat", covariates=["xc"]
+            )
+        assert np.isfinite(const_only.overall_se)
+        np.testing.assert_allclose(
+            const_only.overall_att, no_cov.overall_att, rtol=1e-12
+        )
+        np.testing.assert_allclose(
+            const_only.overall_se, no_cov.overall_se, rtol=1e-9
+        )
+        for key, cell in const_only.group_time_effects.items():
+            ref = no_cov.group_time_effects[key]
+            np.testing.assert_allclose(cell["effect"], ref["effect"], rtol=1e-12)
+            np.testing.assert_allclose(cell["se"], ref["se"], rtol=1e-9)
+
+    def test_reg_constant_only_covariate_matches_no_covariate_survey(self):
+        """Survey-weighted twin of the constant-only-covariate case: the
+        weighted centered Gram is also rank-0, and the general
+        (survey-branch) producer must likewise collapse to the
+        no-covariate survey fit with finite SEs."""
+        from diff_diff.survey import SurveyDesign
+
+        rng = np.random.default_rng(17)
+        data = generate_staggered_data_with_covariates(seed=789)
+        data["xc"] = 5.0
+        weights = pd.DataFrame(
+            {
+                "unit": data["unit"].unique(),
+                "weight": rng.uniform(0.5, 2.0, size=data["unit"].nunique()),
+            }
+        )
+        data = data.merge(weights, on="unit")
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            no_cov = CallawaySantAnna(estimation_method="reg").fit(
+                data, "outcome", "unit", "time", "first_treat",
+                survey_design=SurveyDesign(weights="weight"),
+            )
+            const_only = CallawaySantAnna(estimation_method="reg").fit(
+                data, "outcome", "unit", "time", "first_treat",
+                covariates=["xc"],
+                survey_design=SurveyDesign(weights="weight"),
+            )
+        assert np.isfinite(const_only.overall_se)
+        np.testing.assert_allclose(
+            const_only.overall_att, no_cov.overall_att, rtol=1e-12
+        )
+        np.testing.assert_allclose(
+            const_only.overall_se, no_cov.overall_se, rtol=1e-9
+        )
+        for key, cell in const_only.group_time_effects.items():
+            ref = no_cov.group_time_effects[key]
+            np.testing.assert_allclose(cell["se"], ref["se"], rtol=1e-9)
+
     def test_uniform_survey_weights_match_unweighted_per_cell_se(self):
         """Uniform survey weights route reg+cov through the general
         (survey-branch) producer while the unweighted fit takes the