Release 3.1.2: SDID scale fix, convergence warnings, roadmap refresh

[igerber]

Summary

• Bump version to 3.1.2 across diff_diff/__init__.py, pyproject.toml, rust/Cargo.toml, diff_diff/guides/llms-full.txt.
• Populate CHANGELOG [3.1.2] entry covering four merged PRs: Fix SyntheticDiD catastrophic cancellation at extreme Y scale #312 (SyntheticDiD catastrophic cancellation at extreme Y scale), Refresh ROADMAP to drop phase numbering and reflect shipped state #313 (roadmap refresh, previously in Unreleased), Signal non-convergence in FE imputation alternating-projection solvers #314 (FE imputation / within_transform non-convergence signaling), Signal non-convergence in Frank-Wolfe SC weight solver (numpy path) #315 (SyntheticDiD Frank-Wolfe weight solver non-convergence signaling).
• Bump the SyntheticDiD(lambda_reg=...) and SyntheticDiD(zeta=...) deprecation-warning removal target from v3.1 to v4.0.0. The original v3.1 removal plan would have violated SemVer (removing public kwargs in a patch/minor release); the deprecation stays warning-only throughout the 3.x line. TODO.md updated with the new target and SemVer rationale.
• No breaking changes. 3.1.2 is a pure patch release.

Methodology references

• Method name(s): N/A — this release carries only numerical-stability / convergence-signaling fixes and version metadata. The underlying SyntheticDiD / ImputationDiD / TwoStageDiD / within_transform algorithms are unchanged; only floating-point conditioning and convergence-warning paths are touched.
• Paper / source link(s): N/A (no methodology change).
• Any intentional deviations from the source: None.

Validation

• Per-PR regression coverage ships in the already-merged PRs (Fix SyntheticDiD catastrophic cancellation at extreme Y scale #312 / Signal non-convergence in FE imputation alternating-projection solvers #314 / Signal non-convergence in Frank-Wolfe SC weight solver (numpy path) #315).
• Smoke-tested locally on release/3.1.2: pytest tests/test_methodology_sdid.py::TestDeprecatedParams tests/test_methodology_sdid.py::TestGetSetParams tests/test_estimators.py::TestSyntheticDiD — all pass. Deprecation-warning regression tests for both __init__ and set_params remain in place.
• Backtest / simulation / notebook evidence: N/A.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall Assessment

⚠️ Needs changes

Executive Summary

• The SyntheticDiD estimator, regularization, weighting, and placebo/bootstrap/jackknife inference code are unchanged; I found no methodology mismatch against the registry or in-code reference to Arkhangelsky et al.
• P1: this PR removes public SyntheticDiD kwargs while simultaneously releasing 3.1.2, which contradicts the repo’s stated Semantic Versioning contract and can break existing 3.1.1 caller code on a patch upgrade.
• I found no new NaN/Inf inference anti-patterns, control-group logic changes, or parameter-propagation gaps in the modified SDID code.
• No performance or security issues are introduced by the diff.
• I could not run the repo tests in this sandbox because pytest and numpy are not installed.

Methodology

• No findings. The diff only removes deprecated aliases from SyntheticDiD.__init__ and set_params; the estimator definition, auto-regularization, Frank-Wolfe weighting, and placebo/bootstrap/jackknife SE behavior still match the SyntheticDiD registry entry and the class docstring/reference to Arkhangelsky et al. docs/methodology/REGISTRY.md:L1391-L1545 diff_diff/synthetic_did.py:L26-L167

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• Severity: P1. Impact: this PR makes SyntheticDiD(lambda_reg=...) and SyntheticDiD(zeta=...) hard errors by removing them from the constructor signature and by letting set_params() reject them as unknown, but the same PR versions the package as 3.1.2 even though the changelog says the project adheres to Semantic Versioning. Existing 3.1.1 caller code can therefore fail immediately on what appears to be a safe patch upgrade. Prior deprecation warnings do not mitigate that release-contract break under SemVer. Concrete fix: either keep the deprecated aliases warning-only throughout the 3.x line, or change this release to the next major version and update all version declarations and release notes consistently. Evidence: CHANGELOG.md:L5-L21 pyproject.toml:L5-L8 diff_diff/init.py:L234-L234 diff_diff/synthetic_did.py:L136-L145 diff_diff/synthetic_did.py:L1447-L1453

Tech Debt

• No findings. Removing the completed deprecated-code TODO is consistent with the code change; I did not see new deferred-work items that need tracking.

Security

• No findings.

Documentation/Tests

• No findings in adjacent user docs; I did not find current SyntheticDiD examples in README.md, docs/, or diff_diff/guides that still advertise the removed aliases. The remaining suite still covers generic unknown-constructor and unknown-parameter rejection paths, although the exact deprecated names are no longer exercised directly. Review note: I could not execute the tests here because the sandbox lacks pytest and numpy. Evidence: tests/test_estimators.py:L3075-L3078 tests/test_methodology_sdid.py:L1067-L1071

Path to Approval

1. Choose a compatible release contract. If this remains 3.1.2, restore lambda_reg and zeta handling in SyntheticDiD.__init__ and set_params() with deprecation warnings. If the hard removal is intentional, bump the release to the next major version everywhere it is declared.
2. Add an explicit regression test for the chosen contract using the deprecated names in both constructor and set_params(), so future refactors cannot silently change the behavior again.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 9230c8f483827996f8cdabe8fced17a054a1a768

---

Overall Assessment

✅ Looks good

Executive Summary

• Re-review status: the prior P1 is resolved. SyntheticDiD.__init__ and set_params() still accept lambda_reg / zeta and only emit DeprecationWarning; this diff just moves the stated removal target to v4.0.0, so 3.1.2 no longer introduces a patch-level breaking API change. diff_diff/synthetic_did.py:L136-L160 diff_diff/synthetic_did.py:L1466-L1478 CHANGELOG.md:L5-L19 TODO.md:L123-L127
• Affected method: SyntheticDiD. Cross-checking the Methodology Registry against the changed code shows no change to the Arkhangelsky et al. estimator, weighting, auto-regularization, assumptions, or variance behavior; only deprecation messaging changed. docs/methodology/REGISTRY.md:L1391-L1445 diff_diff/synthetic_did.py:L136-L160
• Release/version metadata is consistent for 3.1.2 across Python, Rust, and the packaged LLM guide. pyproject.toml:L5-L8 diff_diff/init.py:L234-L234 rust/Cargo.toml:L1-L4 diff_diff/guides/llms-full.txt:L1-L5
• Regression tests for deprecated constructor kwargs and set_params() aliases are still present, so the restored warning-only contract remains covered. tests/test_methodology_sdid.py:L1067-L1115 tests/test_estimators.py:L2765-L2780
• I could not execute pytest here because pytest is not installed in the sandbox.

Methodology

• No findings. The diff does not alter identification assumptions, estimator math, weighting, or SE/inference logic for SyntheticDiD; it only updates the removal date in deprecation warnings. docs/methodology/REGISTRY.md:L1391-L1445 diff_diff/synthetic_did.py:L136-L160

Code Quality

• No findings. No new inline inference, NaN/Inf, control-group, or parameter-propagation anti-patterns are introduced in the changed lines; the relevant API behavior remains explicit and tested. diff_diff/synthetic_did.py:L1466-L1478 tests/test_methodology_sdid.py:L1067-L1115

Performance

• No findings. No estimator, solver, or numerical hot-path code changed in this re-review diff.

Maintainability

• No findings. The previous release-contract issue is addressed: changelog, code, and TODO now agree that deprecated public kwargs stay warning-only through the 3.x line and move to v4.0.0 for removal. CHANGELOG.md:L5-L19 TODO.md:L123-L127 diff_diff/synthetic_did.py:L136-L160

Tech Debt

• No findings. The deferred alias removal is explicitly tracked in TODO.md, so this PR does not introduce untracked debt. TODO.md:L123-L127

Security

• No findings. The diff is limited to version strings, release notes, TODO text, and warning messages.

Documentation/Tests

• No findings. The documentation now reflects the SemVer-safe deprecation timeline, and tests covering deprecated constructor/setter aliases remain present. I could not run them locally because pytest is unavailable here. CHANGELOG.md:L10-L19 tests/test_methodology_sdid.py:L1067-L1115 tests/test_estimators.py:L2765-L2780