Codex CI R11 P3: gate MPD wild-bootstrap fallback warning on non-Conley path + harmonize doc restriction bullets

Two P3 doc-and-UX items from R11 (✅ Looks good overall).

P3 #1 (Code Quality) — contradictory warning + error on MPD+Conley
+wild_bootstrap
  `MultiPeriodDiD.fit()` had an unconditional UserWarning at the top
  of fit() saying wild_bootstrap "is not yet supported, using
  analytical instead" — but the Conley validator below raises
  NotImplementedError on `vcov_type="conley", inference="wild_bootstrap"`.
  Users hitting that combination got "warn we're falling back" followed
  immediately by "actually we're raising," which is contradictory
  guidance on the same call.

  Fix: gate the warning on `self.vcov_type != "conley"`. The Conley
  validator's raise takes precedence. Adds regression
  `test_mpd_conley_wild_bootstrap_raises_without_warning` asserting
  the NotImplementedError fires with no analytical-fallback warning.

P3 #2 (Documentation/Tests) — restriction bullets understated MPD's
reject surface
  - `llms-full.txt:L2026` only named DiD/TWFE for the
    `inference="wild_bootstrap"` reject; MPD also rejects this combo
    via the shared validator. Updated to enumerate all three.
  - `llms-full.txt:L2027` only named DiD for the estimator-level
    `survey_design=` reject; MPD and TWFE both raise the same on this
    combo. Updated to enumerate all three.
  - `docs/methodology/REGISTRY.md:L3188` had the same drift; updated
    in parallel and added a parenthetical noting the MPD warning
    suppression.

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

Author: igerber

diff_diff/estimators.py

@@ -1249,9 +1249,14 @@ def fit(  # type: ignore[override]
             If required parameters are missing or data validation fails.
         """
         # Fall back to analytical inference if wild bootstrap requested
-        # (must happen before _resolve_survey_for_fit which rejects bootstrap+survey)
+        # (must happen before _resolve_survey_for_fit which rejects bootstrap+survey).
+        # SKIP the warning on the Conley path — the Conley validator below
+        # raises NotImplementedError for wild_bootstrap + Conley, so emitting
+        # the analytical-fallback warning first would produce contradictory
+        # guidance on the same call (warn "falling back" + raise "not
+        # supported"). The Conley raise takes precedence. Codex CI R11 P3.
         effective_inference = self.inference
-        if self.inference == "wild_bootstrap":
+        if self.inference == "wild_bootstrap" and self.vcov_type != "conley":
             warnings.warn(
                 "Wild bootstrap inference is not yet supported for MultiPeriodDiD. "
                 "Using analytical inference instead.",

diff_diff/guides/llms-full.txt

@@ -2023,8 +2023,8 @@ SE range.
 - `DifferenceInDifferences` / `MultiPeriodDiD` / `TwoWayFixedEffects` `+ vcov_type="conley"` without `conley_lag_cutoff` → `ValueError` (no defensible default; explicit user choice required).
 - `DifferenceInDifferences` / `MultiPeriodDiD` `+ vcov_type="conley"` without `unit=` at fit-time → `ValueError`.
 - Combining `vcov_type="conley"` with explicit `cluster=<col>` applies the combined spatial + cluster product kernel (Wave A #119). On the panel path the cluster must be constant within each unit across periods (validator raises `ValueError` otherwise). TWFE's default auto-cluster on the Conley path is silently dropped; users opt into the combined kernel explicitly.
-- `TwoWayFixedEffects` / `DifferenceInDifferences` `(vcov_type="conley", inference="wild_bootstrap")` → `NotImplementedError` (wild bootstrap does not consume the analytical sandwich).
-- `DifferenceInDifferences(vcov_type="conley")` + `survey_design=` → `NotImplementedError` (Bertanha-Imbens 2014 follow-up).
+- `DifferenceInDifferences` / `MultiPeriodDiD` / `TwoWayFixedEffects` `(vcov_type="conley", inference="wild_bootstrap")` → `NotImplementedError` (wild bootstrap does not consume the analytical sandwich).
+- `DifferenceInDifferences` / `MultiPeriodDiD` / `TwoWayFixedEffects` `(vcov_type="conley")` + `survey_design=` → `NotImplementedError` (Bertanha-Imbens 2014 follow-up).
 - `SyntheticDiD(vcov_type="conley")` → `TypeError` (uses bootstrap, not analytical sandwich).
 - Any-mode `vcov_type="conley"` `+ weights=` / `survey_design=` on `LinearRegression` / `compute_robust_vcov` → `NotImplementedError` (Bertanha-Imbens 2014 weighted-Conley deferred to follow-up PR).
 - A sparse k-d-tree fast path auto-activates for `n > 5_000` with `conley_kernel="bartlett"` AND `conley_metric` in `{"haversine", "euclidean"}` (Wave A #120); callable metrics and uniform kernel fall back to the dense path. `n > 20_000` with the dense fallback still emits a memory-OOM `UserWarning`.

docs/methodology/REGISTRY.md

@@ -3185,7 +3185,8 @@ metrics (`"haversine"`, `"euclidean"`) satisfy this by construction.
 - `MultiPeriodDiD` / `DifferenceInDifferences` `(vcov_type="conley")` without `unit=` at fit-time → `ValueError`.
 - `TwoWayFixedEffects(vcov_type="conley", cluster=<col>)` is supported (Wave A #119): combined spatial + cluster product kernel applies. The cluster must be time-invariant within each unit on the panel path (validator-enforced). TWFE's default auto-cluster is silently dropped on the Conley path; explicit cluster is required to opt in.
 - `DifferenceInDifferences(vcov_type="conley", cluster=<col>)`: combined kernel applies; same time-invariance contract on the panel path. DiD has no auto-cluster, so the cluster choice is fully explicit.
-- `TwoWayFixedEffects(vcov_type="conley", inference="wild_bootstrap")` / `DifferenceInDifferences(vcov_type="conley", inference="wild_bootstrap")` → `NotImplementedError`.
+- `DifferenceInDifferences` / `MultiPeriodDiD` / `TwoWayFixedEffects` `(vcov_type="conley", inference="wild_bootstrap")` → `NotImplementedError`. (MPD's pre-Conley analytical-fallback `UserWarning` is suppressed when `vcov_type="conley"` so the user gets one consistent error message.)
+- `DifferenceInDifferences` / `MultiPeriodDiD` / `TwoWayFixedEffects` `(vcov_type="conley")` + `survey_design=` → `NotImplementedError` at the estimator level (deferred to Bertanha-Imbens 2014 weighted-Conley follow-up).
 - `SyntheticDiD(vcov_type="conley")` → `TypeError` (SyntheticDiD uses bootstrap/jackknife/placebo variance, not the analytical sandwich; tracked in TODO.md).
 - Any-mode `vcov_type="conley"` `+ weights=` / `survey_design=` → `NotImplementedError` (Bertanha-Imbens 2014 territory; Phase 5 follow-up).
 - Panel path: partial `conley_time` / `conley_unit` / `conley_lag_cutoff` (not all three set) → `ValueError` at validator.

tests/test_conley_vcov.py

@@ -1259,6 +1259,62 @@ def test_twfe_conley_unknown_cluster_column_raises(self):
                 conley_lag_cutoff=1,
             ).fit(df, outcome="y", treatment="treated", time="time", unit="unit")
 
+    def test_mpd_conley_wild_bootstrap_raises_without_warning(self):
+        """MPD + Conley + inference='wild_bootstrap' raises NotImplementedError
+        cleanly. The pre-Conley analytical-fallback UserWarning is suppressed
+        on this combination so the user gets one consistent error message
+        instead of "warn then raise". Codex CI R11 P3 #1.
+        """
+        import pandas as _pd
+
+        from diff_diff import MultiPeriodDiD
+
+        rng = np.random.default_rng(seed=211)
+        rows = []
+        for u in range(8):
+            lat = rng.uniform(-30, 30)
+            lon = rng.uniform(-100, 100)
+            for t in range(3):
+                rows.append(
+                    {
+                        "unit": u,
+                        "time": t,
+                        "y": rng.standard_normal(),
+                        "treated": int(u >= 4),
+                        "lat": lat,
+                        "lon": lon,
+                    }
+                )
+        df = _pd.DataFrame(rows)
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            with pytest.raises(NotImplementedError, match="wild_bootstrap"):
+                MultiPeriodDiD(
+                    vcov_type="conley",
+                    inference="wild_bootstrap",
+                    conley_coords=("lat", "lon"),
+                    conley_cutoff_km=2000.0,
+                    conley_lag_cutoff=1,
+                ).fit(
+                    df,
+                    outcome="y",
+                    treatment="treated",
+                    time="time",
+                    unit="unit",
+                    post_periods=[1, 2],
+                    reference_period=0,
+                )
+            fallback_warnings = [
+                msg
+                for msg in w
+                if "falling back to analytical" in str(msg.message)
+                or "Wild bootstrap inference is not yet supported" in str(msg.message)
+            ]
+            assert len(fallback_warnings) == 0, (
+                "Got the analytical-fallback warning on a Conley fit that will "
+                "raise NotImplementedError — contradictory guidance."
+            )
+
     def test_did_conley_malformed_coord_tuple_raises(self, two_period_panel):
         """vcov_type='conley' with a malformed conley_coords (wrong arity or
         non-string elements) raises ValueError before downstream access.