feat(v4): PR 2 of the 4.0 cut - remove the 3.9 rename/wrapper/alias shims

[igerber]

Summary

PR 2 of the 4.0 cut (docs/v4-design.md section 9 "4.0 cut sequence", item 2). The 3.9 rename / wrapper / alias shims whose ledger rows are shimmed with removed_in: "4.0" are deleted and 62 docs/v4-deprecations.yaml rows flip terminal under the cut window opened by #854. __version__ stays 3.13.0; the release PR is the last step. No numerical behaviour changes.

• Renamed parameters lose their old spellings (now a plain TypeError): DifferenceInDifferences.fit(time=) -> post= (M-030) and the same on permutation_test / leave_one_out_test (M-137/M-138); WooldridgeDiD.fit(cohort=) -> first_treat= (M-032); dCDH fit(group=, controls=) -> unit=, covariates= (M-033/M-034) and twowayfeweights(group=) (M-097); every *_col spelling on HAD, RDD, RDPlot, the HAD pretest functions and trim_weights(weight_col=) (M-035..M-042, M-088/M-089, M-098..M-113); StackedDiD(clean_control=) -> control_group= (M-043); WooldridgeDiDResults.to_dataframe(aggregation=) / summary(aggregation=) -> level= (M-044/M-087); ContinuousDiD(covariates=) moves to fit() (M-084). The "event" level spelling is rejected in favour of "event_study" (M-086/M-136/M-150).
• robust= is dropped on DiD/TWFE/MultiPeriodDiD, TripleDifference, HAD and LinearRegression (M-045..M-047, M-115) together with the legacy-CR1 remap; resolve_vcov_type is a one-arg validator. The replicate-weight hc1 remap and _vcov_type_explicit plumbing stay. SyntheticDiD(lambda_reg=, zeta=) removed (M-001/M-002).
• Results-field aliases and their serialized dual keys go: SDiD placebo_effects (M-003), RDD treatment_col (M-094), StackedDiD(Results) clean_control (M-095), dCDH groups (M-114), CiC estimator (M-143). Every __setstate__ legacy-key migration is KEPT so 3.x pickles still load (Wooldridge now pops the stale "event" key unconditionally).
• The eight wrapper functions (imputation_did, two_stage_did, stacked_did, trop, synthetic_control, triple_difference, bacon_decompose, chaisemartin_dhaultfoeuille; M-070..M-077) and the CDiD/Stacked/Gardner aliases plus the module __getattr__ alias diet (M-132..M-135) are deleted. diff_diff.trop / .synthetic_control / .stacked_did / .chaisemartin_dhaultfoeuille now name the submodules.
• WooldridgeDiDResults.summary(alpha=None) is positional like every sibling, routed through the family alpha guard, and renders the headline row only (use aggregate(...) / to_dataframe(level=) for the tables); to_dataframe rejects unknown levels. BusinessReport.to_dict() schema 2.0 -> 3.0 (the assumption block's clean_control key is gone; control_group stays). practitioner_next_steps routes CiC by .method only.
• Enforcement: the matrix removed probe treats a resolved submodule as absent (wrapper shared its module's name) and accepts an explicit-signature absence despite **kwargs (+ self-tests); naming-guard allowlist entries for kept plumbing, __setstate__ keys and shared vocabulary; the M-143 pytest filter dropped; spec, migration guide, REPORTING/REGISTRY notes, guides, API rst, autosummary stubs, benchmarks and three notebooks updated; shim-test files converted to removal pins in place.
• Guide fix folded in: the fuzzy-RD migration sentence in llms-full.txt recommended treatment=; the surviving keyword is takeup=. A new tests/test_guides.py pin checks every "removed in 4.0 - use ..." sentence against the real fit() signature.

Methodology references (required if estimator / math changes)

• Method name(s): N/A - interface-only removals. No estimator formula, weighting, control-group or variance computation changes; HAD keeps its classical default, DiD keeps hc1, the replicate-weight remap is untouched.
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None

Validation

• Tests added/updated: 45 test files. Shim suites converted in place to removal pins (tests/test_v4_rename_mechanical.py, tests/test_v4_rename_semantic.py, tests/test_v4_wrapper_shims.py, tests/test_aliases.py, tests/test_methodology_sdid.py, tests/test_v4_merge_cic.py); matrix probe self-tests in tests/test_v4_matrix.py; naming-guard re-pin in tests/test_naming_guard.py; migration-sentence pin in tests/test_guides.py; ~35 estimator suites migrated to the canonical spellings.
• Local runs: guard/matrix/shim/IA suites, the full set of touched estimator suites, the trop rust-backend tests, a warnings-as-errors spot-check over the touched surfaces, black/ruff/mypy, changelog_compile.py check, Sphinx -W build, py_compile + 20-row smoke of the edited benchmarks, nbmake on 24_staggered_vs_collapsed_power.ipynb (the one notebook with a code-cell edit). Gate simulation: 0 / 63 / 56 due problems at 3.13.0 / 3.14.0 / 4.0.0, as the spec predicts.
• Backtest / simulation / notebook evidence (if applicable): N/A (notebooks 08/10 are markdown-only edits; 24 re-executed under nbmake).

Security / privacy

• Confirm no secrets/PII in this PR: Yes

Changelog

• changelog.d/ fragment added (or N/A - no user-visible change): Yes - changelog.d/20261018-v4-pr2-shim-removals.md

[github-actions]

✅ Looks good

No unmitigated P0/P1 findings identified in the supplied diff.

Executive summary

• Estimation formulas, weighting, control groups, and inference remain unchanged.
• Canonical variance defaults are preserved after removing robust=.
• Caller propagation, parameter introspection, and result serialization appear consistent with the removal ledger.
• Breaking changes have a changelog fragment and migration guidance.
• All 86 changed Python files passed syntax parsing. Estimator tests were not run because NumPy is unavailable.

Methodology

No findings. Checked affected variance routing against docs/methodology/REGISTRY.md, docstrings, and local cited-paper reviews. DiD/LinearRegression retain HC1; HAD retains its classical mass-point default and survey compatibility guards (diff_diff/linalg.py:L2062-L2104, diff_diff/had.py:L3787-L3817). No undocumented methodological deviation or new inference inconsistency was identified.

Code Quality

No findings. The reviewed callers use canonical parameters, and removed imports and configuration attributes have no remaining production references.

Performance

No findings. The changes introduce no new numerical workloads or retained-data requirements.

Maintainability

No findings. Removal probes account for submodule name collisions, and dedicated tests pin rejection of removed interfaces (tests/test_v4_matrix.py:L407-L468).

Tech Debt

No findings. Existing tracked limitations do not become new silent correctness failures through these changes.

Security

No findings in the changed code. No apparent secrets or new security-sensitive behavior.

Documentation/Tests

No findings. The fragment changelog.d/20261018-v4-pr2-shim-removals.md:L1-L59 documents parameter removals, positional shifts, reporting changes, and the schema bump. Removal tests cover canonical replacements and legacy pickle migrations.

Validation confidence is limited to source inspection and syntax checks; runtime statistical tests remain unverified in this environment.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 3063a46bf6e2c6c3ace231758b924e0f73fee6dd

---

✅ Looks good

No unmitigated P0/P1 findings. The prior approval remains appropriate.

Executive summary

• Canonical variance defaults and numerical calculations are preserved.
• Removed parameters, wrappers, and result aliases appear consistently migrated.
• One P2 documentation finding: the Python 3.15 exclusion lacks a release note.
• All 86 changed Python files passed syntax parsing; the changelog compiler check passed.
• Runtime tests could not run because NumPy, pandas, SciPy, and pytest are unavailable.

Methodology

No findings. Checked changed variance selection against docs/methodology/REGISTRY.md, docstrings, and local cited-paper reviews. DiD/LinearRegression retain HC1; HAD retains its classical mass-point default and its guard against composing classical inference with an HC1-scaled survey influence function (diff_diff/had.py:L3787-L3816). No undocumented methodological deviation was identified.

Code Quality

No findings. Production callers inspected use canonical parameters; no remaining uses of removed robust= constructor arguments were found.

Performance

No findings. The changes introduce no additional numerical workloads.

Maintainability

No findings. Removal probes cover submodule name collisions, and legacy result-state migrations remain available.

Tech Debt

No findings. No new untracked correctness limitation was identified.

Security

No findings in the changed code. No apparent secrets or new security-sensitive behavior.

Documentation/Tests

• P2 — Document the Python 3.15 exclusion.
  Location: pyproject.toml:L11; changelog.d/20261018-v4-pr2-shim-removals.md:L49-L52.
  Impact: Changing requires-python from <3.16 to <3.15 prevents installation on Python 3.15. The PR deletes the earlier support fragment without documenting this compatibility change in its replacement fragment.
  Concrete fix: Add a breaking-change entry stating that supported Python versions are now 3.9–3.14.

Validation completed: syntax parsing of all 86 changed Python files and changelog_compile.py check. Statistical behavior remains unverified at runtime in this environment.