Revert SyntheticDiD deprecation removal; keep warning-only through 3.x

Per CI review feedback (#316): removing public kwargs under a patch version
violates Semantic Versioning, which CHANGELOG.md explicitly claims to adhere to.
Restore lambda_reg and zeta handling in SyntheticDiD.__init__ and set_params
as warning-only, and bump the removal target in the DeprecationWarning text
from "v3.1" to "v4.0.0". The 3.1.2 release now carries only the four fix/doc
PRs (#312 SDID scale, #313 roadmap, #314 FE imputation convergence, #315
Frank-Wolfe convergence) with no breaking changes.

- diff_diff/synthetic_did.py: restore deprecated kwargs + warnings (v4.0.0 text)
- tests/test_methodology_sdid.py: restore TestDeprecatedParams class + set_params deprecation test
- tests/test_estimators.py: restore test_deprecated_params
- CHANGELOG.md: drop Removed section; add Changed entry documenting the v3.1 -> v4.0.0 bump in the removal target
- TODO.md: restore Deprecated Code section with v4.0.0 removal target and SemVer rationale

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

Author: igerber

CHANGELOG.md

@@ -16,9 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Refresh `ROADMAP.md` to drop top-level phase numbering and reflect shipped state through v3.1.1 (PR #313). Absorbs dCDH into the Current State estimator list; adds Recently Shipped summary; reorganizes open work as Shipping Next / Under Consideration / AI-Agent Track / Long-term. Updates `docs/business-strategy.md`, `docs/survey-roadmap.md`, `docs/practitioner_decision_tree.rst`, `docs/choosing_estimator.rst`, `docs/api/chaisemartin_dhaultfoeuille.rst`, `README.md`, and `diff_diff/guides/llms-full.txt` to remove stale phase-deferral language now that the deferred items have shipped.
-
-### Removed
-- **`SyntheticDiD(lambda_reg=...)` and `SyntheticDiD(zeta=...)`** - deprecated since v2.3.1 (2026-02-10) in favor of `zeta_omega` / `zeta_lambda`, which match R `synthdid`'s unit-weight / time-weight split. Passing the old kwargs now raises `TypeError` at `__init__` and `ValueError: Unknown parameter` at `set_params`. Internal helpers that take a `lambda_reg` ridge parameter (`compute_synthetic_weights`, `rank_control_units`, Rust FFI bindings) are unaffected - they remain supported.
+- Bump the `SyntheticDiD(lambda_reg=...)` and `SyntheticDiD(zeta=...)` deprecation warnings' removal target from `v3.1` to `v4.0.0`. Removing public kwargs in a patch / minor release would violate Semantic Versioning; the deprecation stays warning-only throughout the `3.x` line and will be removed in the next major release. Use `zeta_omega` / `zeta_lambda` instead.
 
 ## [3.1.1] - 2026-04-16
 

TODO.md

@@ -118,6 +118,16 @@ Different estimators compute SEs differently. Consider unified interface.
 Mypy reports 0 errors. All mixin `attr-defined` errors resolved via
 `TYPE_CHECKING`-guarded method stubs in bootstrap mixin classes.
 
+## Deprecated Code
+
+Deprecated parameters still present for backward compatibility:
+
+- `lambda_reg` and `zeta` in `SyntheticDiD` (`synthetic_did.py`)
+  - Deprecated in favor of `zeta_omega`/`zeta_lambda` parameters
+  - Remove in v4.0.0 (SemVer-safe: public kwarg removal requires a major bump)
+
+---
+
 ## Test Coverage
 
 **Note**: 21 visualization tests are skipped when matplotlib unavailable—this is expected.

diff_diff/synthetic_did.py

@@ -141,7 +141,26 @@ def __init__(
         variance_method: str = "placebo",
         n_bootstrap: int = 200,
         seed: Optional[int] = None,
+        # Deprecated — accepted for backward compat, ignored with warning
+        lambda_reg: Optional[float] = None,
+        zeta: Optional[float] = None,
     ):
+        if lambda_reg is not None:
+            warnings.warn(
+                "lambda_reg is deprecated and ignored. Regularization is now "
+                "auto-computed from data. Use zeta_omega to override unit weight "
+                "regularization. Will be removed in v4.0.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if zeta is not None:
+            warnings.warn(
+                "zeta is deprecated and ignored. Use zeta_lambda to override "
+                "time weight regularization. Will be removed in v4.0.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         super().__init__(robust=True, cluster=None, alpha=alpha)
         self.zeta_omega = zeta_omega
         self.zeta_lambda = zeta_lambda
@@ -1446,8 +1465,17 @@ def get_params(self) -> Dict[str, Any]:
 
     def set_params(self, **params) -> "SyntheticDiD":
         """Set estimator parameters."""
+        # Deprecated parameter names — emit warning and ignore
+        _deprecated = {"lambda_reg", "zeta"}
         for key, value in params.items():
-            if hasattr(self, key):
+            if key in _deprecated:
+                warnings.warn(
+                    f"{key} is deprecated and ignored. Use zeta_omega/zeta_lambda "
+                    f"instead. Will be removed in v4.0.0.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            elif hasattr(self, key):
                 setattr(self, key, value)
             else:
                 raise ValueError(f"Unknown parameter: {key}")

tests/test_estimators.py

@@ -2758,6 +2758,27 @@ def test_get_set_params(self):
         sdid.set_params(variance_method="bootstrap")
         assert sdid.variance_method == "bootstrap"
 
+    def test_deprecated_params(self):
+        """Test that old parameter names emit DeprecationWarning."""
+        import warnings as _warnings
+
+        with _warnings.catch_warnings(record=True) as w:
+            _warnings.simplefilter("always")
+            sdid = SyntheticDiD(lambda_reg=1.0, zeta=0.5)
+            dep_warnings = [x for x in w if issubclass(x.category, DeprecationWarning)]
+            assert len(dep_warnings) == 2
+
+        # Deprecated params are ignored — auto-computed regularization is used
+        assert sdid.zeta_omega is None
+        assert sdid.zeta_lambda is None
+
+        # set_params with deprecated names also warns
+        with _warnings.catch_warnings(record=True) as w:
+            _warnings.simplefilter("always")
+            sdid.set_params(lambda_reg=2.0)
+            dep_warnings = [x for x in w if issubclass(x.category, DeprecationWarning)]
+            assert len(dep_warnings) == 1
+
     def test_missing_unit_column(self, sdid_panel_data):
         """Test error when unit column is missing."""
         sdid = SyntheticDiD()

tests/test_methodology_sdid.py

@@ -1064,15 +1064,55 @@ def test_set_params_new_names(self):
         assert sdid.zeta_omega == 2.0
         assert sdid.zeta_lambda == 0.1
 
+    def test_set_params_deprecated_names_warn(self):
+        """set_params with old names should emit DeprecationWarning."""
+        sdid = SyntheticDiD()
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            sdid.set_params(lambda_reg=1.0)
+            dep_warnings = [x for x in w if issubclass(x.category, DeprecationWarning)]
+            assert len(dep_warnings) == 1
+
     def test_set_params_unknown_raises(self):
         """set_params with unknown name should raise ValueError."""
         sdid = SyntheticDiD()
         with pytest.raises(ValueError, match="Unknown parameter"):
             sdid.set_params(nonexistent_param=1.0)
 
 
-class TestDefaultVarianceMethod:
-    """Default variance_method sanity."""
+class TestDeprecatedParams:
+    """Test deprecated parameter handling in __init__."""
+
+    def test_lambda_reg_warns(self):
+        """SyntheticDiD(lambda_reg=...) emits DeprecationWarning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            sdid = SyntheticDiD(lambda_reg=0.1)
+            dep = [x for x in w if issubclass(x.category, DeprecationWarning)]
+            assert len(dep) == 1
+            assert "lambda_reg" in str(dep[0].message)
+
+        # Deprecated param is ignored — auto-computed used
+        assert sdid.zeta_omega is None
+
+    def test_zeta_warns(self):
+        """SyntheticDiD(zeta=...) emits DeprecationWarning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            sdid = SyntheticDiD(zeta=2.0)
+            dep = [x for x in w if issubclass(x.category, DeprecationWarning)]
+            assert len(dep) == 1
+            assert "zeta" in str(dep[0].message)
+
+        assert sdid.zeta_lambda is None
+
+    def test_both_deprecated_params(self):
+        """Both deprecated params at once should emit two warnings."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            SyntheticDiD(lambda_reg=0.5, zeta=1.5)
+            dep = [x for x in w if issubclass(x.category, DeprecationWarning)]
+            assert len(dep) == 2
 
     def test_default_variance_method_is_placebo(self):
         """Default variance_method should be 'placebo' (matching R)."""