Address P3 documentation drift: REGISTRY formula, docstring key, ranking test

- REGISTRY.md: generalize ICC covariate variance to beta1²/beta2² formula
- Docstring: fix stratum_effects → base_stratum_effects key name
- Add direct covariate-ranking test: covariates dominate Y(0), verify
  weight assignment changes with nonzero vs zero covariate effects

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

Author: igerber

diff_diff/prep_dgp.py

@@ -1287,7 +1287,7 @@ def generate_survey_did_data(
     return_true_population_att : bool, default=False
         If True, attaches a diagnostic dict to ``df.attrs["dgp_truth"]``
         with keys: ``population_att`` (weight-weighted average of treated
-        true effects), ``deff_kish`` (1 + CV(w)^2), ``stratum_effects``
+        true effects), ``deff_kish`` (1 + CV(w)^2), ``base_stratum_effects``
         (base stratum TEs before dynamic/covariate modifiers),
         ``icc_realized`` (ANOVA-based
         ICC computed on period-1 data).

docs/methodology/REGISTRY.md

@@ -2519,8 +2519,10 @@ The 8-step workflow in `docs/llms-practitioner.txt` is adapted from Baker et al.
 
 - **Note:** The `icc` parameter calibrates `psu_re_sd` using the full variance
   decomposition `Var(Y) = sigma²_psu * (1 + psu_period_factor²) + sigma²_unit +
-  sigma²_noise + sigma²_cov`. When `add_covariates=True`, the covariate variance
-  `Var(0.5*x1) + Var(0.3*x2) = 0.2725` is included in the calibration.
+  sigma²_noise + sigma²_cov`. When `add_covariates=True`, covariate variance
+  `sigma²_cov = beta1² * Var(x1) + beta2² * Var(x2)` is included, where
+  `(beta1, beta2)` defaults to `(0.5, 0.3)` but is configurable via
+  `covariate_effects`.
 - **Note:** When `informative_sampling=True` and `add_covariates=True`, covariate
   contributions are included in the Y(0) ranking used for weight assignment.
   Covariates are pre-drawn before the ranking step (panel: once before the loop;

tests/test_prep.py

@@ -1721,6 +1721,41 @@ def test_informative_sampling_with_covariates_cross_section(self):
         assert corr > 0.1
         assert "x1" in df.columns
 
+    def test_informative_sampling_covariate_ranking_direct(self):
+        """Verify covariates actually affect weight assignment in ranking.
+
+        Use large covariate effects with tiny unit_fe_sd/psu_re_sd so
+        covariates dominate Y(0). Weights with nonzero vs zero covariate
+        effects should differ.
+        """
+        from diff_diff.prep_dgp import generate_survey_did_data
+
+        # Covariates dominate: large beta, tiny structural variance
+        df_with = generate_survey_did_data(
+            n_units=200,
+            informative_sampling=True,
+            add_covariates=True,
+            covariate_effects=(5.0, 0.0),
+            unit_fe_sd=0.01,
+            psu_re_sd=0.01,
+            noise_sd=0.01,
+            seed=42,
+        )
+        df_without = generate_survey_did_data(
+            n_units=200,
+            informative_sampling=True,
+            add_covariates=True,
+            covariate_effects=(0.0, 0.0),
+            unit_fe_sd=0.01,
+            psu_re_sd=0.01,
+            noise_sd=0.01,
+            seed=42,
+        )
+        # Weight assignments should differ when covariates dominate ranking
+        w_with = df_with[df_with["period"] == 1]["weight"].values
+        w_without = df_without[df_without["period"] == 1]["weight"].values
+        assert not np.allclose(w_with, w_without, atol=0.01)
+
     def test_heterogeneous_te_by_strata(self):
         """Unweighted mean TE should differ from population ATT."""
         from diff_diff.prep_dgp import generate_survey_did_data