Address PR #402 R5 review (1 P3, doc-drift fix)

P3 dataclass-docstring drift: PR #402 R3 fixed the llms-full.txt field
descriptions to acknowledge that weighted mass-point HAD fits populate
variance_formula in {"pweight_2sls", "survey_binder_tsl_2sls"} and
effective_dose_mean as the weighted Wald-IV dose gap (per
had.py:3585-3660), but the HeterogeneousAdoptionDiDResults dataclass
field docstrings in had.py:347-366 still said those fields were
continuous-only / None on mass-point - leaving two source-of-truth
surfaces disagreeing about the same public result object.

Updated both field docstrings to enumerate all four variance_formula
labels (continuous + mass-point variants under both `weights=` shortcut
and `survey_design=` paths) and to describe the mass-point weighted
Wald-IV dose-gap denominator semantics (`mean(D | Z=1, w) -
mean(D | Z=0, w)` where Z = 1{D > d_lower}).

Tests added (1 new, 90 total):
- test_had_results_dataclass_docstrings_match_weighted_mass_point_contract:
  uses inspect.getsource(HeterogeneousAdoptionDiDResults) to scan the
  class source and assert the variance_formula docstring mentions both
  pweight_2sls and survey_binder_tsl_2sls labels, and the
  effective_dose_mean docstring mentions mass-point Wald-IV semantics.
  Locks both field docstrings against drift back to the
  continuous-only framing now that the llms-full.txt guide and the
  actual fit() code populate these on mass-point fits.

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

Author: igerber

diff_diff/had.py

@@ -345,25 +345,31 @@ class HeterogeneousAdoptionDiDResults:
 
     # Phase 4.5 weighted-path extras (optional so unweighted fits stay unchanged)
     variance_formula: Optional[str] = None
-    """HAD-specific label for the SE formula on the weighted continuous
-    path: ``"pweight"`` (weighted-robust CCT 2014) under ``weights=``,
-    ``"survey_binder_tsl"`` (Binder 1983 TSL with PSU/strata/FPC) under
-    ``survey=SurveyDesign(...)``, ``None`` on unweighted or mass-point
-    fits. Orthogonal to ``survey_metadata`` which is the repo-standard
-    :class:`diff_diff.survey.SurveyMetadata` shared with downstream
-    report/diagnostic consumers (no HAD-specific leakage)."""
+    """HAD-specific label for the SE formula on weighted fits, populated
+    on BOTH continuous and mass-point designs (Phase 4.5 A / B):
+    ``"pweight"`` (continuous, weighted-robust CCT 2014 under the
+    ``weights=`` shortcut), ``"survey_binder_tsl"`` (continuous, Binder
+    1983 TSL with PSU/strata/FPC under ``survey_design=SurveyDesign(...)``),
+    ``"pweight_2sls"`` (mass-point, weighted 2SLS HC1/CR1 sandwich
+    under the ``weights=`` shortcut), or ``"survey_binder_tsl_2sls"``
+    (mass-point, Binder 1983 TSL under ``survey_design=``). ``None`` on
+    unweighted fits. Orthogonal to ``survey_metadata`` which is the
+    repo-standard :class:`diff_diff.survey.SurveyMetadata` shared with
+    downstream report/diagnostic consumers (no HAD-specific leakage)."""
     effective_dose_mean: Optional[float] = None
-    """Weighted denominator used by the beta-scale rescaling on the
-    continuous path: ``sum(w_g · D_g) / sum(w_g)`` for
-    ``continuous_at_zero`` or ``sum(w_g · (D_g - d_lower)) / sum(w_g)``
-    for ``continuous_near_d_lower``. Reduces bit-exactly to
-    ``dose_mean`` / ``mean(D - d_lower)`` when weights are uniform or
-    absent. ``None`` when ``fit()`` was called without
-    ``survey=`` / ``weights=`` (use ``dose_mean`` there). Exists because
-    ``dose_mean`` is the raw sample mean of the dose column; under
-    weighted fits the estimator's actual denominator is the weighted
-    mean, and users reconstructing the β-scale value by hand need the
-    weighted one."""
+    """Weighted denominator used by the beta-scale rescaling, populated
+    on weighted fits across all designs: ``sum(w_g · D_g) / sum(w_g)``
+    on ``continuous_at_zero``, ``sum(w_g · (D_g - d_lower)) / sum(w_g)``
+    on ``continuous_near_d_lower``, and the weighted Wald-IV dose gap
+    ``mean(D | Z=1, w) - mean(D | Z=0, w)`` on ``mass_point`` (where
+    ``Z = 1{D > d_lower}``). On the continuous designs reduces
+    bit-exactly to ``dose_mean`` / ``mean(D - d_lower)`` when weights
+    are uniform or absent. ``None`` when ``fit()`` was called without
+    ``survey_design=`` / ``survey=`` / ``weights=`` (use ``dose_mean``
+    there). Exists because ``dose_mean`` is the raw sample mean of the
+    dose column; under weighted fits the estimator's actual denominator
+    is the weighted form above, and users reconstructing the β-scale
+    value by hand need the weighted one."""
 
     def __repr__(self) -> str:
         base = (

tests/test_practitioner.py

@@ -690,6 +690,55 @@ def test_handle_continuous_step_4_snippet_is_valid_python(self, mock_continuous_
             if code.strip():
                 ast.parse(code)  # raises SyntaxError on failure
 
+    def test_had_results_dataclass_docstrings_match_weighted_mass_point_contract(self):
+        # PR #402 R3 fixed the llms-full.txt field descriptions to
+        # acknowledge that weighted mass-point fits populate
+        # variance_formula in {"pweight_2sls", "survey_binder_tsl_2sls"}
+        # and effective_dose_mean as the weighted Wald-IV dose gap (per
+        # had.py:3585-3660). PR #402 R5 P3 caught that the dataclass
+        # field docstrings still said those fields were continuous-only
+        # / None on mass-point - leaving two source-of-truth surfaces
+        # disagreeing about the same public result object. Lock the
+        # dataclass docstrings against drift back to the continuous-only
+        # framing.
+        import inspect
+
+        from diff_diff.had import HeterogeneousAdoptionDiDResults
+
+        # Field docstrings live as raw __doc__ on the FieldDescriptor /
+        # in __dataclass_fields__'s metadata; read them via the type's
+        # source-level docstring attached to the class via the field's
+        # `__doc__` after assignment in the class body.
+        # Easier: read the class source via inspect.getsource() and check
+        # the field-docstring blocks we care about.
+        src = inspect.getsource(HeterogeneousAdoptionDiDResults)
+        # variance_formula docstring must enumerate all 4 labels.
+        assert "pweight_2sls" in src, (
+            "HeterogeneousAdoptionDiDResults.variance_formula docstring "
+            "must mention `pweight_2sls` (weighted mass-point HC1/CR1 "
+            "label per had.py:3585-3629). Otherwise the dataclass "
+            "docstring contradicts llms-full.txt and the actual "
+            "implementation."
+        )
+        assert "survey_binder_tsl_2sls" in src, (
+            "HeterogeneousAdoptionDiDResults.variance_formula docstring "
+            "must mention `survey_binder_tsl_2sls` (weighted mass-point "
+            "Binder-TSL label)."
+        )
+        # effective_dose_mean docstring must mention mass-point Wald-IV.
+        assert "mass_point" in src or "mass-point" in src, (
+            "HeterogeneousAdoptionDiDResults.effective_dose_mean "
+            "docstring must mention mass-point semantics; weighted "
+            "mass-point fits populate it as the weighted Wald-IV dose "
+            "gap per had.py:3642-3660."
+        )
+        assert "Wald-IV" in src or "Z=1" in src, (
+            "HeterogeneousAdoptionDiDResults.effective_dose_mean "
+            "docstring must describe the weighted Wald-IV dose gap "
+            "semantics (or the underlying Z=1/Z=0 subgroup-mean form) "
+            "for mass-point fits."
+        )
+
     def test_had_step_3_flags_qug_under_survey_deferral(
         self, mock_had_results, mock_had_event_study_results
     ):