Address PR #376 R1 (1 P1 + 1 P2)

R1 P1: deprecated `survey=SurveyDesign(...)` alias didn't trigger the
SurveyDesign type guard on stute_test, yatchew_hr_test, stute_joint_pretest
because the guard ran BEFORE the alias rebinding. Move the guard AFTER the
soft-deprecation block so it covers both `survey_design=SurveyDesign(...)`
(canonical) and `survey=SurveyDesign(...)` (deprecated alias) identically.
Adds 3 regression tests in TestArrayInTypeGuard covering the alias path on
all 3 array-in surfaces.

R1 P2: REGISTRY.md had two contradictory notes on HAD survey support — the
pre-Phase-4.5-C bullet said "pretests still do NOT accept survey/weights"
while the Phase 4.5 C bullet listed all 8 surfaces as supporting them.
Rewrote the older bullet to reflect the current Phase 4.5 B + C state.

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

Author: igerber

diff_diff/had_pretests.py

@@ -1558,19 +1558,9 @@ def stute_test(
     if n_set > 1:
         raise ValueError(HAD_DUAL_KNOB_MUTEX_MSG_ARRAY_IN)
 
-    # Type guard: array-in helpers reject SurveyDesign (cannot resolve column
-    # names without `data`).
-    if survey_design is not None and isinstance(survey_design, SurveyDesign):
-        raise TypeError(
-            "stute_test: `survey_design=` accepts a pre-resolved "
-            "ResolvedSurveyDesign only (array-in helpers have no `data` to "
-            "resolve column names against). For pweight-only, use "
-            "`survey_design=make_pweight_design(arr)`. For full PSU/strata/"
-            "FPC, pre-resolve via `SurveyDesign(...).resolve(data)` and pass "
-            "the result."
-        )
-
-    # Soft deprecation: route legacy survey=/weights= aliases to survey_design=.
+    # Soft deprecation: route legacy survey=/weights= aliases to survey_design=
+    # FIRST so the type guard below covers `survey=SurveyDesign(...)` too
+    # (PR #376 R1 P1: alias must behave identically to the canonical kwarg).
     # The bit-exact normalization-order invariant requires passing UNNORMALIZED
     # weights to make_pweight_design; the unified path's mean=1 step (~line
     # 1669) fires downstream EXACTLY ONCE.
@@ -1585,6 +1575,20 @@ def stute_test(
         )
         survey_design = make_pweight_design(np.asarray(weights, dtype=np.float64))
 
+    # Type guard: array-in helpers reject SurveyDesign (cannot resolve column
+    # names without `data`). Runs AFTER alias rebinding so it covers both
+    # `survey_design=SurveyDesign(...)` and the deprecated
+    # `survey=SurveyDesign(...)` form identically.
+    if survey_design is not None and isinstance(survey_design, SurveyDesign):
+        raise TypeError(
+            "stute_test: `survey_design=` accepts a pre-resolved "
+            "ResolvedSurveyDesign only (array-in helpers have no `data` to "
+            "resolve column names against). For pweight-only, use "
+            "`survey_design=make_pweight_design(arr)`. For full PSU/strata/"
+            "FPC, pre-resolve via `SurveyDesign(...).resolve(data)` and pass "
+            "the result."
+        )
+
     # Internal alias rebind: downstream code uses `survey` and `weights` as
     # internal variable names (Phase 4.5 C convention). After the deprecation
     # block, fold the canonical survey_design back into the legacy variable
@@ -2031,17 +2035,9 @@ def yatchew_hr_test(
     if n_set > 1:
         raise ValueError(HAD_DUAL_KNOB_MUTEX_MSG_ARRAY_IN)
 
-    # Type guard: array-in helpers reject SurveyDesign.
-    if survey_design is not None and isinstance(survey_design, SurveyDesign):
-        raise TypeError(
-            "yatchew_hr_test: `survey_design=` accepts a pre-resolved "
-            "ResolvedSurveyDesign only (array-in helpers have no `data` to "
-            "resolve column names against). For pweight-only, use "
-            "`survey_design=make_pweight_design(arr)`. For full PSU/strata/"
-            "FPC, pre-resolve via `SurveyDesign(...).resolve(data)`."
-        )
-
-    # Soft deprecation: route legacy survey=/weights= aliases to survey_design=.
+    # Soft deprecation: route legacy survey=/weights= aliases to survey_design=
+    # FIRST so the type guard below covers `survey=SurveyDesign(...)` too
+    # (PR #376 R1 P1: alias must behave identically to the canonical kwarg).
     if survey is not None:
         warnings.warn(HAD_DEPRECATION_MSG_SURVEY_KWARG, DeprecationWarning, stacklevel=2)
         survey_design = survey
@@ -2053,6 +2049,18 @@ def yatchew_hr_test(
         )
         survey_design = make_pweight_design(np.asarray(weights, dtype=np.float64))
 
+    # Type guard: array-in helpers reject SurveyDesign. Runs AFTER alias
+    # rebinding so it covers both `survey_design=SurveyDesign(...)` and the
+    # deprecated `survey=SurveyDesign(...)` form identically.
+    if survey_design is not None and isinstance(survey_design, SurveyDesign):
+        raise TypeError(
+            "yatchew_hr_test: `survey_design=` accepts a pre-resolved "
+            "ResolvedSurveyDesign only (array-in helpers have no `data` to "
+            "resolve column names against). For pweight-only, use "
+            "`survey_design=make_pweight_design(arr)`. For full PSU/strata/"
+            "FPC, pre-resolve via `SurveyDesign(...).resolve(data)`."
+        )
+
     # Internal alias rebind for back-compat with downstream code.
     survey = survey_design
     weights = None
@@ -2709,17 +2717,9 @@ def stute_joint_pretest(
     if n_set > 1:
         raise ValueError(HAD_DUAL_KNOB_MUTEX_MSG_ARRAY_IN)
 
-    # Type guard: array-in helpers reject SurveyDesign.
-    if survey_design is not None and isinstance(survey_design, SurveyDesign):
-        raise TypeError(
-            "stute_joint_pretest: `survey_design=` accepts a pre-resolved "
-            "ResolvedSurveyDesign only (array-in helpers have no `data` to "
-            "resolve column names against). For pweight-only, use "
-            "`survey_design=make_pweight_design(arr)`. For full PSU/strata/"
-            "FPC, pre-resolve via `SurveyDesign(...).resolve(data)`."
-        )
-
-    # Soft deprecation: route legacy survey=/weights= aliases to survey_design=.
+    # Soft deprecation: route legacy survey=/weights= aliases to survey_design=
+    # FIRST so the type guard below covers `survey=SurveyDesign(...)` too
+    # (PR #376 R1 P1: alias must behave identically to the canonical kwarg).
     if survey is not None:
         warnings.warn(HAD_DEPRECATION_MSG_SURVEY_KWARG, DeprecationWarning, stacklevel=2)
         survey_design = survey
@@ -2731,6 +2731,18 @@ def stute_joint_pretest(
         )
         survey_design = make_pweight_design(np.asarray(weights, dtype=np.float64))
 
+    # Type guard: array-in helpers reject SurveyDesign. Runs AFTER alias
+    # rebinding so it covers both `survey_design=SurveyDesign(...)` and the
+    # deprecated `survey=SurveyDesign(...)` form identically.
+    if survey_design is not None and isinstance(survey_design, SurveyDesign):
+        raise TypeError(
+            "stute_joint_pretest: `survey_design=` accepts a pre-resolved "
+            "ResolvedSurveyDesign only (array-in helpers have no `data` to "
+            "resolve column names against). For pweight-only, use "
+            "`survey_design=make_pweight_design(arr)`. For full PSU/strata/"
+            "FPC, pre-resolve via `SurveyDesign(...).resolve(data)`."
+        )
+
     # Internal alias rebind for back-compat with downstream code.
     survey = survey_design
     weights = None

docs/methodology/REGISTRY.md

@@ -2347,7 +2347,7 @@ Under `survey=SurveyDesign(weights, strata, psu, fpc)`, the variance composes vi
 - **Note:** Monte Carlo oracle consistency — `tests/test_had_mc.py` validates that the weighted estimator recovers the oracle τ under informative sampling, with coverage near nominal and visible bias reduction vs unweighted. Slow-gated; 4 tests.
 - **Note:** Auto-bandwidth selection (Phase 1b MSE-DPI via `lpbwselect_mse_dpi`) remains UNWEIGHTED in this phase; users who want a weight-aware bandwidth should pass `h`/`b` explicitly. The auto path with uniform weights reduces to the existing unweighted bandwidth selector, so the uniform-weights bit-parity chain is preserved.
 - **Note:** Replicate-weight SurveyDesigns (BRR / Fay / JK1 / JKn / SDR) on the HAD continuous path raise `NotImplementedError` in this PR; Rao-Wu-style rescaled bootstrap is deferred to Phase 4.5 C (survey-under-pretests).
-- **Note:** `HeterogeneousAdoptionDiD.fit()` dispatch matrix after Phase 4.5 B — survey / weights are supported on ALL design × aggregate combinations (continuous × {overall, event-study}, mass-point × {overall, event-study}). Pretests (`qug_test`, `stute_test`, `yatchew_hr_test`, joint Stute variants, `did_had_pretest_workflow`) still do NOT accept `survey=` / `weights=` — deferred to Phase 4.5 C / C0 per reciprocal-guard discipline.
+- **Note:** `HeterogeneousAdoptionDiD.fit()` dispatch matrix after Phase 4.5 B + 4.5 C — survey/weights are supported on ALL design × aggregate combinations (continuous × {overall, event-study}, mass-point × {overall, event-study}). The HAD pretests (`qug_test`, `stute_test`, `yatchew_hr_test`, joint Stute variants, `did_had_pretest_workflow`) ship survey support in Phase 4.5 C (PR #370) — `qug_test` permanently rejects (Phase 4.5 C0 deferral; see "QUG Null Test" §); the linearity family supports pweight + PSU + FPC via PSU-level Mammen multipliers (Stute) + closed-form weighted variance components (Yatchew); replicate-weight and stratified designs raise `NotImplementedError` (parallel follow-ups). The canonical kwarg on all 8 HAD surfaces is `survey_design=` (see "Note (HAD survey-design API consolidation)" below); `survey=` / `weights=` remain accepted as deprecated aliases for one minor cycle.
 - **Note (HAD survey-design API consolidation):** All 8 HAD surfaces — `HeterogeneousAdoptionDiD.fit`, `did_had_pretest_workflow`, `qug_test`, `stute_test`, `yatchew_hr_test`, `stute_joint_pretest`, `joint_pretrends_test`, `joint_homogeneity_test` — accept the canonical kwarg `survey_design=` (matching `ContinuousDiD`, `EfficientDiD`, `ChaisemartinDHaultfoeuille`). The pre-existing dual `survey=` and `weights=` kwargs become deprecated aliases (`DeprecationWarning`); both will be removed in the next minor release. Internal back-end behavior is UNCHANGED (the legacy paths for `weights=np.ndarray` and `survey=SurveyDesign(...)` still execute the same code; only the entry signature wraps them). Mutex semantics extend from 2-way (`survey + weights`) to 3-way (`survey_design + survey + weights`) — at most one may be non-None per call. Two distinct mutex error messages per surface group: data-in surfaces (HAD.fit + workflow + joint data-in wrappers) point users to `survey_design=SurveyDesign(weights='col_name', ...)`; array-in surfaces (`stute_test`/`yatchew_hr_test`/`stute_joint_pretest`/`qug_test`) point to `survey_design=make_pweight_design(arr)` (for pweight-only) or `survey_design=<pre-resolved ResolvedSurveyDesign>` (for full PSU/strata/FPC). Array-in helpers reject `survey_design=SurveyDesign(...)` with `TypeError` since they have no `data` to resolve column names against. The `make_pweight_design(weights: np.ndarray) -> ResolvedSurveyDesign` factory is exported from the `diff_diff` top level (formerly `survey._make_trivial_resolved`, kept as a permanent private alias for back-compat).
 
 *Weighted 2SLS (Phase 4.5 B):* `_fit_mass_point_2sls(..., weights=, return_influence=)` extends the Wald-IV / 2SLS sandwich with pweight semantics:

tests/test_had_dual_knob_deprecation.py

@@ -134,18 +134,40 @@ def test_make_pweight_design_eq_underscore_alias(self):
 
 
 class TestArrayInTypeGuard:
-    """Array-in helpers reject SurveyDesign (cannot resolve column names)."""
+    """Array-in helpers reject SurveyDesign (cannot resolve column names).
+
+    Both the canonical `survey_design=SurveyDesign(...)` form AND the
+    deprecated `survey=SurveyDesign(...)` alias trigger the same TypeError
+    (PR #376 R1 P1: alias must behave identically to the canonical kwarg).
+    """
 
     def test_stute_test_rejects_SurveyDesign(self, array_in_data):
         d, dy = array_in_data
         with pytest.raises(TypeError, match="make_pweight_design"):
             stute_test(d, dy, survey_design=SurveyDesign(weights="w"), n_bootstrap=199, seed=0)
 
+    def test_stute_test_rejects_SurveyDesign_via_legacy_alias(self, array_in_data):
+        """PR #376 R1 P1: `survey=SurveyDesign(...)` (deprecated alias) must
+        trigger the same TypeError as `survey_design=SurveyDesign(...)`."""
+        d, dy = array_in_data
+        with pytest.raises(TypeError, match="make_pweight_design"):
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", DeprecationWarning)
+                stute_test(d, dy, survey=SurveyDesign(weights="w"), n_bootstrap=199, seed=0)
+
     def test_yatchew_hr_test_rejects_SurveyDesign(self, array_in_data):
         d, dy = array_in_data
         with pytest.raises(TypeError, match="make_pweight_design"):
             yatchew_hr_test(d, dy, survey_design=SurveyDesign(weights="w"))
 
+    def test_yatchew_hr_test_rejects_SurveyDesign_via_legacy_alias(self, array_in_data):
+        """PR #376 R1 P1: alias parity with canonical kwarg."""
+        d, dy = array_in_data
+        with pytest.raises(TypeError, match="make_pweight_design"):
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", DeprecationWarning)
+                yatchew_hr_test(d, dy, survey=SurveyDesign(weights="w"))
+
     def test_stute_joint_pretest_rejects_SurveyDesign(self):
         rng = np.random.default_rng(3)
         G = 30
@@ -164,6 +186,27 @@ def test_stute_joint_pretest_rejects_SurveyDesign(self):
                 seed=0,
             )
 
+    def test_stute_joint_pretest_rejects_SurveyDesign_via_legacy_alias(self):
+        """PR #376 R1 P1: alias parity with canonical kwarg."""
+        rng = np.random.default_rng(3)
+        G = 30
+        d = rng.uniform(0, 1, size=G)
+        residuals = {0: rng.normal(0, 0.1, G)}
+        fitted = {0: np.zeros(G)}
+        X = np.column_stack([np.ones(G), d])
+        with pytest.raises(TypeError, match="make_pweight_design"):
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", DeprecationWarning)
+                stute_joint_pretest(
+                    residuals_by_horizon=residuals,
+                    fitted_by_horizon=fitted,
+                    doses=d,
+                    design_matrix=X,
+                    survey=SurveyDesign(weights="w"),
+                    n_bootstrap=199,
+                    seed=0,
+                )
+
 
 class TestScaleInvariance:
     """Bit-exact normalization-order invariant (Stability invariant #7).