Address PR #376 R11 P3 (HAD.fit weights= deprecation message)

R11 P3 (informational): HAD.fit's `weights=` deprecation message used the
shared HAD_DEPRECATION_MSG_WEIGHTS_KWARG_DATA_IN constant, which suggests
migrating to `survey_design=SurveyDesign(weights='col_name')`. On the
workflow + joint data-in wrappers that migration is inference-equivalent
(both go through _resolve_pretest_unit_weights to per-unit weights, then
through the shared Stute / Yatchew kernels). On HAD.fit it is NOT
inference-equivalent today: the deprecated `weights=arr` shortcut keeps
`variance_formula="pweight"` / `"pweight_2sls"` (CCT-2014 weighted-robust
/ 2SLS pweight-sandwich), while `survey_design=SurveyDesign(weights=col)`
composes Binder-TSL (`"survey_binder_tsl"` / `"survey_binder_tsl_2sls"`).
Following the migration changes the SE family — the long-term unification
is tracked in TODO row 102 for the next minor.

Fix: add a HAD.fit-specific HAD_DEPRECATION_MSG_WEIGHTS_KWARG_HAD_FIT
constant that says the long-term API is still survey_design= but
explicitly notes the SE-family caveat applies in the current release.
HAD.fit consumes this new constant; the workflow + joint wrappers keep
the original HAD_DEPRECATION_MSG_WEIGHTS_KWARG_DATA_IN (no SE-family
divergence on those surfaces).

561 tests pass.

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

Author: igerber

diff_diff/had.py

@@ -78,7 +78,7 @@
 )
 from diff_diff.survey import (
     HAD_DEPRECATION_MSG_SURVEY_KWARG,
-    HAD_DEPRECATION_MSG_WEIGHTS_KWARG_DATA_IN,
+    HAD_DEPRECATION_MSG_WEIGHTS_KWARG_HAD_FIT,
     HAD_DUAL_KNOB_MUTEX_MSG_DATA_IN,
     SurveyMetadata,
     compute_survey_metadata,
@@ -2927,7 +2927,7 @@ def fit(
             survey_design = survey
         elif weights is not None:
             warnings.warn(
-                HAD_DEPRECATION_MSG_WEIGHTS_KWARG_DATA_IN,
+                HAD_DEPRECATION_MSG_WEIGHTS_KWARG_HAD_FIT,
                 DeprecationWarning,
                 stacklevel=2,
             )

diff_diff/survey.py

@@ -785,6 +785,28 @@ def make_pweight_design(weights: np.ndarray) -> "ResolvedSurveyDesign":
     "`data` and pass `survey_design=SurveyDesign(weights='col_name')` "
     "instead. Will be removed in the next minor release."
 )
+# PR #376 R11 P3: HAD.fit-specific weights= deprecation message — the
+# generic data-in suggestion above (use `survey_design=SurveyDesign(...)`)
+# is the long-term API target, but on `HeterogeneousAdoptionDiD.fit` the
+# two paths currently produce different SE families: the deprecated
+# `weights=np.ndarray` shortcut yields `variance_formula="pweight"` /
+# `"pweight_2sls"` (CCT-2014 weighted-robust / 2SLS pweight-sandwich)
+# while `survey_design=SurveyDesign(...)` yields `"survey_binder_tsl"` /
+# `"survey_binder_tsl_2sls"`. The next-minor cleanup (TODO row 102) will
+# unify the two; until then, document the SE-family caveat explicitly so
+# users know what changes when they migrate.
+HAD_DEPRECATION_MSG_WEIGHTS_KWARG_HAD_FIT = (
+    "`weights=np.ndarray` is deprecated on HeterogeneousAdoptionDiD.fit; "
+    "the long-term API is to add the weights as a column on `data` and "
+    "pass `survey_design=SurveyDesign(weights='col_name')`. Will be "
+    "removed in the next minor release. NOTE: in the current release the "
+    "two paths produce different SE families on this surface — the "
+    "`weights=` shortcut keeps the analytical CCT-2014 / 2SLS pweight-"
+    "sandwich (`variance_formula='pweight'` or `'pweight_2sls'`), while "
+    "`survey_design=SurveyDesign(...)` composes Binder-TSL "
+    "(`'survey_binder_tsl'` or `'survey_binder_tsl_2sls'`). The "
+    "long-term unification is tracked for the next minor release."
+)
 HAD_DEPRECATION_MSG_WEIGHTS_KWARG_ARRAY_IN = (
     "`weights=np.ndarray` is deprecated on array-in pretest helpers; use "
     "`survey_design=make_pweight_design(weights)` instead "