callaway-santanna: align docs with narrowed df_inference contract

Two P3 doc-only follow-ups:

1. llms-full.txt CS entry kept vcov_type before n_bootstrap in the
   pseudo-signature even after the constructor was reordered to append
   vcov_type at the end. Moved vcov_type to the end of the pseudo-
   signature so the generated guide matches the actual __init__ order
   (matches SA / WooldridgeDiD convention).

2. staggered_results.py class attribute docstring + inline field comment
   for df_inference still described it as populated on "Legitimate
   survey_design= fits" alongside survey_metadata. Updated to reflect
   the narrowed contract: df_inference is populated on the bare-cluster-
   synthesize path ONLY (where survey_metadata is None). When user
   provides survey_design=, df_inference stays None and the canonical
   df carrier is survey_metadata.df_survey. HonestDiD reads
   survey_metadata first, df_inference fallback.

3. test_explicit_survey_design_does_populate_survey_metadata docstring
   still said "+ df_inference also populated"; updated to match the
   body assertion (which already correctly asserts df_inference is None).

No source/test logic changes. All 80 targeted tests + test_honest_did
pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: igerber

diff_diff/guides/llms-full.txt

@@ -189,14 +189,14 @@ CallawaySantAnna(
     estimation_method: str = "dr",               # "dr", "ipw", or "reg"
     alpha: float = 0.05,
     cluster: str | None = None,                  # Cluster col; activates CR1 on the IF via synthesized SurveyDesign(psu=col). None → per-unit IF.
-    vcov_type: str = "hc1",                      # {"hc1"} only — IF-based variance per Callaway & Sant'Anna (2021). Analytical-sandwich {classical, hc2, hc2_bm} and conley REJECTED at __init__ (see REGISTRY.md IF-vs-sandwich subsection).
     n_bootstrap: int = 0,                        # 0 = analytical SEs, 999+ recommended
     bootstrap_weights: str | None = None,        # "rademacher", "mammen", or "webb"
     seed: int | None = None,
     rank_deficient_action: str = "warn",
     base_period: str = "varying",                # "varying" or "universal"
     cband: bool = True,                          # Simultaneous confidence bands
     pscore_trim: float = 0.01,                   # Propensity score trimming bound
+    vcov_type: str = "hc1",                      # {"hc1"} only — IF-based variance per Callaway & Sant'Anna (2021). Analytical-sandwich {classical, hc2, hc2_bm} and conley REJECTED at __init__ (see REGISTRY.md IF-vs-sandwich subsection).
 )
 ```
 

diff_diff/staggered_results.py

@@ -111,14 +111,19 @@ class CallawaySantAnnaResults:
         ``None`` when no clustering is active.
     df_inference : int, optional
         Cluster-level degrees of freedom for downstream inference (e.g.,
-        ``HonestDiD`` t-critical-value selection). Carried separately from
-        ``survey_metadata`` so consumers can distinguish "cluster df is
-        available" from "user provided a survey design": bare
-        ``CallawaySantAnna(cluster=X).fit(...)`` populates ``df_inference``
-        but leaves ``survey_metadata`` as ``None`` (preserving the
-        survey/non-survey contract for ``DiagnosticReport`` / ``summary()``).
-        Legitimate ``survey_design=`` fits populate both, and the two
-        surfaces agree (``df_inference == survey_metadata.df_survey``).
+        ``HonestDiD`` t-critical-value selection) on the bare-``cluster=``
+        synthesize path ONLY (the case where ``survey_metadata`` is
+        intentionally ``None`` to preserve the survey/non-survey contract
+        for ``DiagnosticReport`` / ``summary()``). When the user provides
+        an explicit ``survey_design=`` (inject or conflict branches),
+        ``df_inference`` stays ``None`` and the canonical df carrier is
+        ``survey_metadata.df_survey`` — which holds the actual CS-internal
+        df, including any post-resolve tightening (e.g., the
+        ``overall_effective_df`` recompute for replicate aggregations).
+        ``HonestDiD`` reads ``survey_metadata.df_survey`` first and falls
+        back to ``df_inference`` only when ``survey_metadata`` is absent.
+        Narrow contract prevents HonestDiD from silently overriding a
+        tightened survey df with the original ``resolved_survey.df_survey``.
     """
 
     group_time_effects: Dict[Tuple[Any, Any], Dict[str, Any]]
@@ -170,13 +175,16 @@ class CallawaySantAnnaResults:
     cluster_name: Optional[str] = None
     n_clusters: Optional[int] = None
     # df_inference: cluster-level degrees of freedom for downstream
-    # inference (e.g., HonestDiD's t-critical-value selection). Carried
-    # SEPARATELY from survey_metadata so consumers can distinguish
-    # "cluster df is available" from "user provided a survey design"
-    # — bare CS(cluster="state").fit(...) populates df_inference but
-    # leaves survey_metadata as None (DiagnosticReport / summary() must
-    # not treat a bare-cluster fit as survey-backed). Legitimate survey
-    # designs populate both (df_inference == survey_metadata.df_survey).
+    # inference, populated on the bare-cluster-synthesize path ONLY.
+    # When the user provides an explicit survey_design= (inject or
+    # conflict branches), df_inference stays None and the canonical df
+    # carrier is survey_metadata.df_survey (which holds the actual
+    # CS-internal df, including any post-resolve tightening via the
+    # overall_effective_df recompute at staggered.py:~1995-1999).
+    # HonestDiD reads survey_metadata.df_survey first and falls back to
+    # df_inference only when survey_metadata is absent. Narrow contract
+    # prevents HonestDiD from silently overriding a tightened survey df
+    # with the original resolved_survey.df_survey.
     df_inference: Optional[int] = None
 
     # --- Inference-field aliases (balance/external-adapter compatibility) ---

tests/test_staggered.py

@@ -4704,11 +4704,15 @@ def test_bare_cluster_does_not_set_survey_metadata(self):
         )
 
     def test_explicit_survey_design_does_populate_survey_metadata(self):
-        """Counterpart to the test above: when user provides a real
-        SurveyDesign, survey_metadata IS populated (regardless of bare
-        cluster= status). Verifies the 'inject' branch path:
-        SurveyDesign(weights=...) + cluster=X → survey_metadata populated
-        + df_inference also populated."""
+        """Counterpart to test_bare_cluster_does_not_set_survey_metadata:
+        when user provides a real SurveyDesign, survey_metadata IS
+        populated (regardless of bare cluster= status). Verifies the
+        'inject' branch path: SurveyDesign(weights=...) + cluster=X →
+        survey_metadata populated; df_inference stays None per the
+        narrowed contract (canonical df carrier when survey_metadata is
+        present is survey_metadata.df_survey, which holds CS-internal
+        post-resolve-tightened df). HonestDiD reads survey_metadata
+        first, df_inference only as fallback."""
         from diff_diff import SurveyDesign
 
         data = _generate_clustered_staggered_data(seed=75)