Address PR #402 R8 review (1 P3, to_dict() docstring drift)

P3 doc drift: PR #402 R3 fixed llms-full.txt, R5 fixed the dataclass
field docstrings, but HeterogeneousAdoptionDiDResults.to_dict() still
described variance_formula as continuous-only ("pweight" /
"survey_binder_tsl") and omitted the mass-point Wald-IV
effective_dose_mean semantics. Three internal source-of-truth surfaces
were now disagreeing about the same public result object's
to_dict() output shape.

Updated to_dict() docstring to enumerate all four variance_formula
labels (pweight, survey_binder_tsl, pweight_2sls,
survey_binder_tsl_2sls) and to describe the per-design
effective_dose_mean semantics (continuous mean of D / D - d_lower vs
mass-point weighted Wald-IV dose gap mean(D | Z=1, w) -
mean(D | Z=0, w)). Mirrors the field-docstring contract from R5.

Tests added (1 new, 95 total):
- test_had_results_to_dict_docstring_matches_weighted_mass_point_contract:
  reads HeterogeneousAdoptionDiDResults.to_dict.__doc__ and asserts it
  enumerates all four variance_formula labels and the mass-point
  Wald-IV effective_dose_mean semantics. Mirrors the existing
  dataclass-field-docstring lock.

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

Author: igerber

diff_diff/had.py

@@ -483,9 +483,20 @@ def to_dict(self) -> Dict[str, Any]:
           ``design_effect`` / ``sum_weights`` / ``weight_range`` +
           ``n_strata`` / ``n_psu`` / ``df_survey`` (latter three
           ``None`` on the ``weights=`` shortcut).
-        - ``variance_formula``: ``"pweight"`` or ``"survey_binder_tsl"``.
+        - ``variance_formula``: HAD-specific SE label, populated on BOTH
+          continuous and mass-point designs (Phase 4.5 A / B):
+          ``"pweight"`` (continuous, weighted-robust CCT 2014 under
+          ``weights=``), ``"survey_binder_tsl"`` (continuous, Binder
+          1983 TSL under ``survey_design=``), ``"pweight_2sls"``
+          (mass-point, weighted 2SLS HC1/CR1 sandwich under ``weights=``),
+          or ``"survey_binder_tsl_2sls"`` (mass-point, Binder 1983 TSL
+          under ``survey_design=``). See the field docstring above for
+          the full contract.
         - ``effective_dose_mean``: weighted denominator used by the
-          beta-scale rescaling."""
+          beta-scale rescaling - weighted ``mean(D)`` on
+          ``continuous_at_zero``, weighted ``mean(D - d_lower)`` on
+          ``continuous_near_d_lower``, or the weighted Wald-IV dose gap
+          ``mean(D | Z=1, w) - mean(D | Z=0, w)`` on ``mass_point``."""
         return {
             "att": self.att,
             "se": self.se,

tests/test_practitioner.py

@@ -730,6 +730,44 @@ def test_had_event_study_sup_t_snippet_uses_hc1_for_mass_point_survey_compatibil
             "fail at fit time on a mass-point panel."
         )
 
+    def test_had_results_to_dict_docstring_matches_weighted_mass_point_contract(self):
+        # Parallel to the dataclass-field-docstring regression below:
+        # PR #402 R8 P3 caught that HeterogeneousAdoptionDiDResults.to_dict()
+        # docstring still described variance_formula as continuous-only
+        # / "pweight" or "survey_binder_tsl", contradicting the field
+        # docstrings (fixed in R5) and llms-full.txt (fixed in R3).
+        # Lock the to_dict() docstring against drift back.
+        from diff_diff.had import HeterogeneousAdoptionDiDResults
+
+        doc = HeterogeneousAdoptionDiDResults.to_dict.__doc__ or ""
+        for label in (
+            "pweight",
+            "survey_binder_tsl",
+            "pweight_2sls",
+            "survey_binder_tsl_2sls",
+        ):
+            assert label in doc, (
+                f"HeterogeneousAdoptionDiDResults.to_dict() docstring "
+                f"must enumerate the {label!r} variance_formula label - "
+                f"weighted mass-point fits populate pweight_2sls / "
+                f"survey_binder_tsl_2sls per had.py:3585-3629. The "
+                f"to_dict() docstring is a public source-of-truth "
+                f"surface and must match the field docstrings + "
+                f"llms-full.txt HAD section."
+            )
+        # effective_dose_mean: must mention mass-point Wald-IV semantics.
+        assert "mass_point" in doc or "mass-point" in doc, (
+            "HeterogeneousAdoptionDiDResults.to_dict() docstring must "
+            "describe the mass-point effective_dose_mean semantics; "
+            "weighted mass-point fits populate it as the weighted "
+            "Wald-IV dose gap per had.py:3642-3660."
+        )
+        assert "Wald-IV" in doc or "Z=1" in doc, (
+            "HeterogeneousAdoptionDiDResults.to_dict() docstring must "
+            "describe the weighted Wald-IV dose gap semantics for "
+            "mass-point fits."
+        )
+
     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