Address PR #346 CI review round 4: P1 d_lower > 0 on Design 1 paths

**P1 (Methodology): Design 1 paths must reject d_lower = 0**

Paper Section 3.2 partitions HAD by regime: `d_lower = 0` is Design 1'
(`continuous_at_zero`); `d_lower > 0` is Design 1 (`continuous_near_
d_lower` or `mass_point`). The auto-detect rule already respects this
partition, but explicit overrides previously allowed
`design="mass_point", d_lower=0` and `design="continuous_near_d_lower"`
on a `d.min()==0` sample to run silently, returning a
paper-incompatible estimand (2SLS with degenerate single-unit mass for
mass_point; Design 1' algebra relabeled as `WAS_d_lower` with a
spurious Assumption 5/6 warning for continuous_near_d_lower).

Fix: add a fit-time guard that raises `ValueError` when
`resolved_design in ("mass_point", "continuous_near_d_lower")` and the
resolved `d_lower_val` is within float tolerance of zero (same
tolerance family as `_detect_design`'s d.min()==0 tie-break). The
error message points users to `continuous_at_zero` or `auto` for
samples with support infimum at zero.

**Docstring + test updates:**

- Rewrote the `design` parameter docstring to document the
  regime-partition contract precisely: each explicit override is
  now described with its d_lower precondition and mass-point
  compatibility.
- Rewrote the `d_lower` parameter docstring to note the
  Design-1-requires-positive contract.
- Inverted the prior `test_force_mass_point_on_continuous_data_at_
  support_infimum` test (which incorrectly codified the unsupported
  behavior) into three rejection regressions:
  `test_force_mass_point_on_d_lower_zero_sample_raises`,
  `test_force_continuous_near_d_lower_on_d_lower_zero_sample_raises`,
  `test_force_mass_point_d_lower_none_on_zero_sample_raises`.

Targeted regression: 135 HAD tests + 514 total across Phase 1 and
adjacent surfaces, all green.

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

Author: igerber

diff_diff/had.py

@@ -828,13 +828,36 @@ class HeterogeneousAdoptionDiD:
     design : {"auto", "continuous_at_zero", "continuous_near_d_lower", "mass_point"}
         Design-dispatch strategy. Defaults to ``"auto"`` which resolves
         via the REGISTRY auto-detect rule on the fitted dose data
-        (see :func:`_detect_design`). Explicit overrides run the chosen
-        path without auto-reject (e.g., forcing Design 1' on mass-point
-        data runs the nonparametric fit even though the paper would
-        counsel the 2SLS path).
+        (see :func:`_detect_design`).
+
+        Explicit overrides are checked against the paper's
+        regime-partition contract (Section 3.2) at fit time:
+
+        - ``"continuous_at_zero"`` (Design 1'): paper requires the
+          support infimum ``d_lower = 0``. Phase 1c's
+          ``_validate_had_inputs`` rejects mass-point samples passed
+          to this path.
+        - ``"continuous_near_d_lower"`` (Design 1, continuous density
+          near ``d_lower``): requires ``d_lower > 0`` and a
+          non-mass-point sample (modal fraction at ``d.min()`` must be
+          <= 2%). ``d_lower`` must equal ``float(d.min())`` within
+          float tolerance; non-support-infimum thresholds are off-
+          support and raise.
+        - ``"mass_point"`` (Design 1 mass-point): requires
+          ``d_lower > 0`` and ``d_lower == float(d.min())`` within
+          float tolerance. Forcing this design on a ``d_lower = 0``
+          sample raises (use ``"continuous_at_zero"`` or ``"auto"``).
+
+        Mismatched overrides raise ``ValueError`` pointing at the
+        correct design rather than silently identifying a different
+        estimand.
     d_lower : float or None
         Support infimum ``d_lower``. ``None`` means use ``0.0`` on the
         Design 1' path and ``float(d.min())`` on the other two paths.
+        On Design 1 paths (``continuous_near_d_lower`` and
+        ``mass_point``), an explicit ``d_lower`` must equal
+        ``float(d.min())`` within float tolerance AND must be strictly
+        positive; zero-valued or mismatched thresholds raise.
     kernel : {"epanechnikov", "triangular", "uniform"}
         Forwarded to :func:`bias_corrected_local_linear` on the continuous
         paths. Ignored on the mass-point path.
@@ -1070,6 +1093,29 @@ def fit(
         else:
             d_lower_val = float(d_lower_arg)
 
+        # ---- Regime partition: d_lower > 0 for Design 1 paths ----
+        # Paper Section 3.2 partitions HAD into d_lower = 0 (Design 1',
+        # continuous_at_zero) and d_lower > 0 (Design 1, continuous_near
+        # _d_lower or mass_point). The auto-detect rule already enforces
+        # this partition; explicit overrides must respect it too, otherwise
+        # `design="mass_point", d_lower=0` returns a finite but
+        # paper-incompatible 2SLS result and `design="continuous_near_d_lower"`
+        # with d_lower=0 reduces to Design 1' algebra while mislabeling the
+        # estimand as `WAS_d_lower` and emitting the wrong Assumption 5/6
+        # warning. Use the same float-tolerance family as _detect_design's
+        # d.min()==0 tie-break.
+        if resolved_design in ("mass_point", "continuous_near_d_lower"):
+            scale = max(1.0, float(np.max(np.abs(d_arr))))
+            if abs(d_lower_val) <= 1e-12 * scale:
+                raise ValueError(
+                    f"design={resolved_design!r} requires d_lower > 0 (paper "
+                    f"Section 3.2 reserves the d_lower=0 regime for Design 1' "
+                    f"/ `continuous_at_zero`). Got d_lower={d_lower_val!r}. "
+                    f"Use design='continuous_at_zero' (explicit) or "
+                    f"design='auto' (auto-detect) for samples with support "
+                    f"infimum at zero."
+                )
+
         # ---- Original-scale mass-point check before the regressor shift ----
         # When a user explicitly forces design="continuous_near_d_lower"
         # on a sample that is actually a mass-point sample (modal fraction

tests/test_had.py

@@ -1108,20 +1108,36 @@ def test_force_continuous_at_zero_on_mass_point_data(self):
         with pytest.raises(NotImplementedError, match="mass-point"):
             est.fit(panel, "outcome", "dose", "period", "unit")
 
-    def test_force_mass_point_on_continuous_data_at_support_infimum(self):
-        """Forcing mass-point on continuous data with d_lower=d.min() runs.
+    def test_force_mass_point_on_d_lower_zero_sample_raises(self):
+        """Review P1 round 4: Design 1 paths require d_lower > 0.
 
-        d.min()==0 exactly in this DGP, so d_lower=0.0 is the paper-consistent
-        support-infimum threshold. The resulting mass=1 case exercises the
-        degenerate-mass boundary (only unit 0 is "at d_lower"; rest are above).
+        Paper Section 3.2 reserves the d_lower=0 regime for Design 1'
+        (continuous_at_zero). Forcing `mass_point` on a sample with
+        d.min()==0 must raise, pointing the user to continuous_at_zero
+        or auto.
         """
         d, dy = _dgp_continuous_at_zero(500, seed=0)
         panel = _make_panel(d, dy)
-        # d.min() == 0 exactly (d[0]=0 by construction); d_lower must match.
         est = HeterogeneousAdoptionDiD(design="mass_point", d_lower=0.0)
-        r = est.fit(panel, "outcome", "dose", "period", "unit")
-        assert r.design == "mass_point"
-        assert r.d_lower == 0.0
+        with pytest.raises(ValueError, match=r"d_lower > 0|Design 1'"):
+            est.fit(panel, "outcome", "dose", "period", "unit")
+
+    def test_force_continuous_near_d_lower_on_d_lower_zero_sample_raises(self):
+        """Parallel: continuous_near_d_lower must also reject d_lower=0."""
+        d, dy = _dgp_continuous_at_zero(500, seed=0)
+        panel = _make_panel(d, dy)
+        est = HeterogeneousAdoptionDiD(design="continuous_near_d_lower")
+        # d_lower auto-resolves to float(d.min()) == 0.0 on this DGP.
+        with pytest.raises(ValueError, match=r"d_lower > 0|Design 1'"):
+            est.fit(panel, "outcome", "dose", "period", "unit")
+
+    def test_force_mass_point_d_lower_none_on_zero_sample_raises(self):
+        """d_lower=None on a d.min()==0 sample resolves to 0; must still raise."""
+        d, dy = _dgp_continuous_at_zero(500, seed=0)
+        panel = _make_panel(d, dy)
+        est = HeterogeneousAdoptionDiD(design="mass_point", d_lower=None)
+        with pytest.raises(ValueError, match=r"d_lower > 0"):
+            est.fit(panel, "outcome", "dose", "period", "unit")
 
 
 # =============================================================================