Address PR #355 R8 P1: front-door FPC validation for implicit-PSU SDID bootstrap

When ``SurveyDesign(fpc=...)`` is declared without an explicit
``psu=``, ``bootstrap_utils.generate_rao_wu_weights`` (L654-L655)
treats each unit as its own PSU. The helper rejects
``FPC < n_PSU`` mid-draw (L684-L688), so if FPC is set lower than the
unit count (per stratum if stratified), every bootstrap draw raises
ValueError; ``_bootstrap_se`` swallows the error in its retry loop and
the user eventually sees a generic bootstrap-exhaustion message
instead of a targeted FPC/design error.

Add a front-door validation on ``resolved_survey_unit`` after
``collapse_survey_to_unit_level``:
  - unstratified: fpc >= total unit count;
  - stratified: fpc_h >= per-stratum unit count.

Error messages point at the two actionable fixes (declare an
explicit psu= column, or raise FPC).

Two regression tests added:
``test_fit_raises_on_implicit_psu_fpc_below_unit_count_unstratified``
and ``test_fit_raises_on_implicit_psu_fpc_below_stratum_unit_count``.

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

Author: igerber

diff_diff/synthetic_did.py

@@ -439,6 +439,47 @@ def fit(  # type: ignore[override]
             resolved_survey_unit = collapse_survey_to_unit_level(
                 resolved_survey, data, unit, all_units_for_bootstrap,
             )
+            # Front-door FPC validation for implicit-PSU Rao-Wu (PR #355
+            # R8 P1). When psu is None but fpc is set,
+            # ``generate_rao_wu_weights`` (bootstrap_utils.py L654-L655)
+            # treats each unit as its own PSU and rejects
+            # ``FPC < n_units`` per stratum mid-draw. ``_bootstrap_se``
+            # catches that ``ValueError`` and keeps retrying, so the user
+            # sees a generic bootstrap-exhaustion message instead of a
+            # targeted FPC/design error. Validate upstream so the user
+            # gets a clean error before the bootstrap loop even starts.
+            if (
+                resolved_survey_unit.psu is None
+                and resolved_survey_unit.fpc is not None
+            ):
+                if resolved_survey_unit.strata is None:
+                    n_units_total = len(resolved_survey_unit.weights)
+                    fpc_val = float(resolved_survey_unit.fpc[0])
+                    if fpc_val < n_units_total:
+                        raise ValueError(
+                            f"FPC ({fpc_val}) is less than the number of "
+                            f"units ({n_units_total}). With no explicit "
+                            "psu= column, SDID Rao-Wu treats each unit as "
+                            "its own PSU; FPC must be >= the number of "
+                            "units. Declare an explicit psu= column or "
+                            "increase FPC."
+                        )
+                else:
+                    unique_strata = np.unique(resolved_survey_unit.strata)
+                    for h in unique_strata:
+                        mask_h = resolved_survey_unit.strata == h
+                        n_h_units = int(mask_h.sum())
+                        fpc_h = float(resolved_survey_unit.fpc[mask_h][0])
+                        if fpc_h < n_h_units:
+                            raise ValueError(
+                                f"FPC ({fpc_h}) in stratum {h} is less than "
+                                f"the number of units in that stratum "
+                                f"({n_h_units}). With no explicit psu= "
+                                "column, SDID Rao-Wu treats each unit as "
+                                "its own PSU within strata; FPC must be "
+                                ">= the per-stratum unit count. Declare an "
+                                "explicit psu= column or increase FPC."
+                            )
             # Source w_control / w_treated from resolved_survey_unit.weights
             # rather than re-extracting raw panel columns. resolved_survey.weights
             # is normalized to mean=1 by SurveyDesign.resolve() (survey.py L189-

tests/test_methodology_sdid.py

@@ -909,6 +909,57 @@ def test_fit_raises_on_zero_treated_mass_under_full_design(self):
                 survey_design=SurveyDesign(weights="wt", strata="stratum", psu="psu"),
             )
 
+    def test_fit_raises_on_implicit_psu_fpc_below_unit_count_unstratified(self):
+        """Fit-time FPC validation fires when psu=None and FPC < n_units.
+
+        When ``SurveyDesign(fpc=...)`` is declared without an explicit
+        ``psu=``, SDID Rao-Wu (via ``bootstrap_utils.generate_rao_wu_weights``
+        L654-L655) treats each unit as its own PSU. The helper rejects
+        ``FPC < n_PSU`` mid-draw (``bootstrap_utils.py`` L684-L688); without
+        a front-door guard, every bootstrap draw raises, ``_bootstrap_se``
+        swallows the ``ValueError`` in its retry loop, and the user sees a
+        generic bootstrap-exhaustion error. Regression against PR #355 R8
+        P1: ``fit()`` must validate FPC vs unit count before dispatching
+        the bootstrap.
+        """
+        from diff_diff.survey import SurveyDesign
+
+        df = _make_panel(n_control=10, n_treated=3, seed=42)
+        df["wt"] = 1.0
+        # 13 units total; FPC says population size is 5 — infeasible for
+        # 13 implicit PSUs.
+        df["fpc_pop"] = 5.0
+        with pytest.raises(ValueError, match=r"FPC.*less than the number of units"):
+            SyntheticDiD(variance_method="bootstrap", n_bootstrap=20, seed=1).fit(
+                df, outcome="outcome", treatment="treated",
+                unit="unit", time="period",
+                post_periods=[5, 6, 7],
+                survey_design=SurveyDesign(weights="wt", fpc="fpc_pop"),
+            )
+
+    def test_fit_raises_on_implicit_psu_fpc_below_stratum_unit_count(self):
+        """Fit-time FPC validation fires per stratum under implicit PSU.
+
+        Mirror of the unstratified case but with strata present. Each
+        stratum's FPC must be >= its unit count (PR #355 R8 P1).
+        """
+        from diff_diff.survey import SurveyDesign
+
+        df = _make_panel(n_control=12, n_treated=4, seed=42)
+        df["wt"] = 1.0
+        df["stratum"] = df["unit"] % 2  # 2 strata, ~8 units each
+        # FPC says 3 per stratum — infeasible for 8 implicit PSUs/stratum.
+        df["fpc_pop"] = 3.0
+        with pytest.raises(ValueError, match=r"FPC.*less than the number of units in that stratum"):
+            SyntheticDiD(variance_method="bootstrap", n_bootstrap=20, seed=1).fit(
+                df, outcome="outcome", treatment="treated",
+                unit="unit", time="period",
+                post_periods=[5, 6, 7],
+                survey_design=SurveyDesign(
+                    weights="wt", strata="stratum", fpc="fpc_pop",
+                ),
+            )
+
     def test_bootstrap_scale_invariance_under_pweight_rescaling(self):
         """Survey-bootstrap SE / p / CI are invariant to a global pweight rescaling.