Address CI AI review round 3: default boundary=0 classification, rank test

P1 (methodology): The boundary=0 default path now classifies inputs
per the REGISTRY-planned design="auto" rule. Previously the
mass-point guard only fired for boundary>0, so a dataset with
d.min()>0 and mass at d.min() would silently pass through the
default-boundary path as Design 1'. The new rule:

  - boundary=0 with min(d) < 0.01 * median(d): Design 1' accepted
    (support infimum effectively at 0).
  - boundary=0 with min(d) >= 0.01 * median(d):
      * modal fraction at min(d) > 2%: mass-point design -> raise
        NotImplementedError pointing to the 2SLS / Phase 2 path.
      * otherwise: ambiguous -> raise ValueError asking the caller
        to pass boundary=d.min() for the Design 1 continuous-
        near-d_lower path.
  - boundary>0 path unchanged (mass-point check already in place).

Removed the stale test_boundary_below_min_d_accepted: it used
U(0.01, 1) data which doesn't satisfy Design 1' under the stricter
rule. Replaced with three targeted tests:

  - test_boundary_zero_design_1_prime_accepted: U(0, 1) passes.
  - test_boundary_zero_with_positive_d_min_rejected: U(0.5, 1)
    raises "Ambiguous design".
  - test_boundary_zero_with_d_min_mass_point_rejected: mass at 0.1
    with boundary=0 raises mass-point NotImplementedError.

P3 (tests): Added test_full_stack_rank_deficient_raises_valueerror
driving a 3-distinct-value dataset through both lpbwselect_mse_dpi
and the public wrapper; both must raise ValueError (or
NotImplementedError), never LinAlgError or IndexError.

172 tests pass (up from 169).

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

Author: igerber

diff_diff/local_linear.py

@@ -633,21 +633,24 @@ def mse_optimal_bandwidth(
             f"separately parity-tested against nprobust."
         )
 
-    # Mass-point design check (REGISTRY.md plans `>2%` modal-min rule).
-    # If d_lower > 0 and the distribution bunches at d_lower, the paper
-    # (de Chaisemartin et al. 2026 Section 3.2.4) prescribes the 2SLS
-    # sample-average path, NOT the nonparametric CCF local-polynomial
-    # path. Detect bunching and redirect the caller.
+    # Design classification (REGISTRY.md Phase 2 design="auto" rule
+    # plus paper Section 3.2.4 mass-point redirection):
     #
-    # We only flag when boundary > 0 (Design 1 continuous-near-d_lower
-    # vs Design 1 mass-point). For boundary = 0 (Design 1' or "untreated
-    # units present" subcase), the paper accepts nonparametric even with
-    # mass at 0 (Garrett et al. 2020 application with 12/2954 at 0).
+    #   Design 1'        <=> d_lower = inf supp(D_2) = 0
+    #   Design 1 masspt  <=> d_lower > 0, P(D_2 = d_lower) > 0
+    #   Design 1 cont    <=> d_lower > 0, D_2 continuous near d_lower
+    #
+    # The CCF nonparametric selector is appropriate for Design 1' and
+    # Design 1 continuous-near-d_lower. Mass-point Design 1 requires a
+    # 2SLS sample-average estimator (Phase 2, not Phase 1b).
+    _MASS_POINT_THRESHOLD = 0.02  # REGISTRY rule: > 2% modal-min
+    eps_eq = 1e-12 * max(1.0, abs(d_min))
+    at_d_min_mask = np.abs(d - d_min) <= eps_eq
+    modal_fraction = float(np.mean(at_d_min_mask))
+
     if boundary > _boundary_tol:
-        eps_eq = 1e-12 * max(1.0, abs(d_min))
-        at_boundary_mask = np.abs(d - d_min) <= eps_eq
-        modal_fraction = float(np.mean(at_boundary_mask))
-        _MASS_POINT_THRESHOLD = 0.02  # REGISTRY rule: > 2% modal-min
+        # User supplied boundary = d_min > 0 explicitly. This is
+        # Design 1; distinguish mass-point vs continuous-near-d_lower.
         if modal_fraction > _MASS_POINT_THRESHOLD:
             raise NotImplementedError(
                 f"Detected mass-point design: the lower boundary "
@@ -662,6 +665,42 @@ def mse_optimal_bandwidth(
                 f"near-d_lower designs (modal fraction <= "
                 f"{_MASS_POINT_THRESHOLD:.2f}), this wrapper is applicable."
             )
+    else:
+        # User passed boundary <= 0 (default). Intent is Design 1'.
+        # Apply the REGISTRY's `min(d) < 0.01 * median(d)` rule: only
+        # accept when the support infimum is effectively 0 relative to
+        # the data scale. Otherwise force the user to disambiguate.
+        d_median = float(np.median(d))
+        _DESIGN_1_PRIME_RATIO = 0.01  # REGISTRY: min(d)/median(d) < 1%
+        # Guard against pathological all-zero or all-negative median.
+        effective_threshold = _DESIGN_1_PRIME_RATIO * max(abs(d_median), 1e-12)
+        if d_min > effective_threshold:
+            if modal_fraction > _MASS_POINT_THRESHOLD:
+                # Mass-point design dressed as Design 1': same
+                # NotImplementedError as the boundary>0 branch.
+                raise NotImplementedError(
+                    f"Detected mass-point design at d.min()={d_min!r} "
+                    f"(modal fraction {modal_fraction:.4f} > "
+                    f"{_MASS_POINT_THRESHOLD:.2f}), but boundary=0 "
+                    f"implies Design 1' intent. Either: (a) pass "
+                    f"boundary=d.min() to make the mass-point "
+                    f"classification explicit (which will then raise "
+                    f"NotImplementedError directing to the 2SLS path "
+                    f"per de Chaisemartin et al. 2026 Section 3.2.4), "
+                    f"or (b) reconsider whether the data is truly "
+                    f"Design 1' (support at 0)."
+                )
+            raise ValueError(
+                f"Ambiguous design: boundary=0 but d.min()={d_min!r} "
+                f"exceeds the Design 1' threshold of "
+                f"0.01 * median(d) = {effective_threshold!r}. This "
+                f"dataset does not satisfy Design 1' (support infimum "
+                f"at 0). Either: (a) pass boundary=d.min() for the "
+                f"Design 1 continuous-near-d_lower path, or (b) verify "
+                f"the data truly has support at 0 (in which case "
+                f"d.min() would be much closer to zero relative to the "
+                f"data scale)."
+            )
 
     # Defer heavy import to call time to avoid import-cycle risk.
     from diff_diff._nprobust_port import lpbwselect_mse_dpi

tests/test_bandwidth_selector.py

@@ -312,16 +312,41 @@ def test_boundary_equal_to_min_d_accepted(self):
         assert np.isfinite(h)
         assert h > 0.0
 
-    def test_boundary_below_min_d_accepted(self):
-        """Design 1' uses boundary = 0 when all D_2 > 0; boundary
-        below d.min() must pass."""
+    def test_boundary_zero_design_1_prime_accepted(self):
+        """Design 1' data: d.min() effectively 0 relative to median,
+        so boundary=0 passes the REGISTRY 1%-of-median rule."""
         rng = np.random.default_rng(20260419)
-        d = rng.uniform(0.01, 1.0, size=1500)  # d.min() > 0
-        y = d + d**2 + rng.normal(0, 0.5, size=1500)
+        # d.min() ~ 5e-4 << 0.01 * median(d) ~ 5e-3
+        d = rng.uniform(0.0, 1.0, size=3000)
+        y = d + d**2 + rng.normal(0, 0.5, size=3000)
         h = mse_optimal_bandwidth(d, y, boundary=0.0)
         assert np.isfinite(h)
         assert h > 0.0
 
+    def test_boundary_zero_with_positive_d_min_rejected(self):
+        """Default boundary=0 with d.min() substantially positive (>1%
+        of median) is not Design 1'; force the caller to pass
+        boundary=d.min() instead of silently misclassifying."""
+        rng = np.random.default_rng(2026)
+        # d.min() ~ 0.5, median ~ 0.75 -> ratio 0.67 >> 0.01.
+        d = rng.uniform(0.5, 1.0, size=1500)
+        y = d + rng.normal(0, 0.3, size=1500)
+        with pytest.raises(ValueError, match="Ambiguous design"):
+            mse_optimal_bandwidth(d, y, boundary=0.0)
+
+    def test_boundary_zero_with_d_min_mass_point_rejected(self):
+        """boundary=0 default path with d.min() > 0 AND mass at d.min()
+        must also be rejected, pointing to the 2SLS redirection."""
+        rng = np.random.default_rng(2026)
+        n_mass = 300  # 15% at 0.1
+        n_cont = 1700
+        d_mass = np.full(n_mass, 0.1)
+        d_cont = rng.uniform(0.1, 1.0, size=n_cont)
+        d = np.concatenate([d_mass, d_cont])
+        y = d + rng.normal(0, 0.5, size=d.size)
+        with pytest.raises(NotImplementedError, match="mass-point"):
+            mse_optimal_bandwidth(d, y, boundary=0.0)
+
     def test_mass_point_design_rejected(self):
         """Design 1 mass-point case (boundary > 0, modal fraction > 2%)
         must be rejected with NotImplementedError pointing to 2SLS."""
@@ -369,6 +394,31 @@ def test_rank_deficient_design_raises_valueerror(self):
         with pytest.raises(ValueError, match="qrXXinv"):
             qrXXinv(X)
 
+    def test_full_stack_rank_deficient_raises_valueerror(self):
+        """End-to-end rank-deficiency integration test: a sample with
+        enough rows but only a handful of distinct in-window d values
+        drives rank-deficient X'X at some DPI stage. The public wrapper
+        must surface a clear ValueError (either from qrXXinv's Cholesky
+        guard or from the stage-count guards), not IndexError or
+        LinAlgError.
+        """
+        from diff_diff._nprobust_port import lpbwselect_mse_dpi
+
+        # Only 3 distinct d values; each pilot stage's design matrix
+        # will have at most 3 independent rows, but the B2 fit needs
+        # o_B+2 = 5 or 6 columns -> rank deficient.
+        d = np.repeat([0.1, 0.2, 0.3], 50).astype(np.float64)
+        rng = np.random.default_rng(2026)
+        y = d + rng.normal(0, 0.1, size=d.size)
+        with pytest.raises(ValueError):
+            lpbwselect_mse_dpi(y, d, eval_point=0.0, bwcheck=None)
+        # Same through the public wrapper (boundary=0 is fine since
+        # d.min()=0.1 triggers either ambiguous-design or rank-deficient
+        # rejection; we only care that it is a ValueError and not an
+        # opaque linear-algebra crash).
+        with pytest.raises((ValueError, NotImplementedError)):
+            mse_optimal_bandwidth(d, y)
+
 
 class TestKernelDispatch:
     """Different kernels produce different bandwidths."""