Address CI AI review: boundary check, stage guards, docstring refresh

P1 #1 (methodology): mse_optimal_bandwidth now rejects boundary > d.min()
with a clear ValueError. The Phase 1b wrapper is scoped to the HAD
lower-boundary case (Design 1' with d_0 = 0 or Design 1 continuous-near-
d_lower with d_0 = min D_2). Interior or upper-boundary inputs would
silently run the boundary selector with a symmetric kernel and return
a bandwidth incompatible with the one-sided fitter. The port remains
available for interior / broader surface via
_nprobust_port.lpbwselect_mse_dpi.

P1 #2 (code quality): lprobust_bw validates in-window observation
counts at each of the three local-poly fits before calling qrXXinv:
  - variance: n_V >= o+1
  - B1: n_B1 >= o_B+1
  - B2: n_B2 >= o_B+2
Each guard raises a targeted ValueError naming the failing stage, the
bandwidth, and suggested remediation. Previously these failed with
opaque LinAlgError from Cholesky on under-determined designs.

P3 (doc): local_linear.py module docstring updated to say Phase 1b
"ships" instead of "will add"; tiny-sample test now asserts the new
ValueError contract instead of accepting any non-IndexError failure.

New behavioral tests:
- test_interior_boundary_rejected: boundary=0.5 on U(0,1) rejected
- test_upper_boundary_rejected: boundary=d.max() rejected
- test_boundary_equal_to_min_d_accepted: boundary=min(d) accepted
  (Design 1 continuous-near-d_lower path)
- test_boundary_below_min_d_accepted: boundary=0 with d.min()>0
  accepted (Design 1' path)
- test_bwcheck_none_on_tiny_sample_raises_valueerror: upgraded from
  "catch anything non-IndexError" to pytest.raises(ValueError,
  match="lprobust_bw").

153 tests pass (up from 149).

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

Author: igerber

diff_diff/_nprobust_port.py

@@ -371,6 +371,15 @@ def lprobust_bw(
     ``(V, B1, B2, R, bw)``. Called four times from ``lpbwselect_mse_dpi``.
 
     Parameters match the R signature argument-for-argument.
+
+    Raises
+    ------
+    ValueError
+        If any of the three local-polynomial fits has fewer in-window
+        observations than its required column count. Catches opaque
+        ``LinAlgError`` failures from downstream Cholesky inversion in
+        tiny-sample or mispositioned-boundary settings and surfaces a
+        targeted error naming the failing stage.
     """
     N = X.shape[0]
     eC: Optional[np.ndarray] = None
@@ -383,6 +392,14 @@ def lprobust_bw(
     eX = X[ind_V]
     eW = w[ind_V]
     n_V = int(np.sum(ind_V))
+    if n_V < o + 1:
+        raise ValueError(
+            f"lprobust_bw: variance stage has n_V={n_V} in-window "
+            f"observations at h_V={h_V:.6g} (boundary={c}, kernel={kernel!r}), "
+            f"but needs at least o+1={o + 1}. Increase sample size, choose "
+            f"a valid lower boundary with sufficient data to the right, "
+            f"or disable bwcheck=None-driven narrow windows."
+        )
     # Design matrix R.V in R; rename to R_V to avoid Python builtin conflict.
     R_V = np.empty((n_V, o + 1), dtype=np.float64)
     for j in range(o + 1):
@@ -443,6 +460,13 @@ def lprobust_bw(
     eX1 = X[ind1]
     eW1 = w1[ind1]
     n_B1 = int(np.sum(ind1))
+    if n_B1 < o_B + 1:
+        raise ValueError(
+            f"lprobust_bw: B1 stage has n_B1={n_B1} in-window observations "
+            f"at h_B1={h_B1:.6g} (boundary={c}, kernel={kernel!r}), but "
+            f"needs at least o_B+1={o_B + 1}. Increase sample size or "
+            f"widen the pilot bandwidth."
+        )
     R_B1 = np.empty((n_B1, o_B + 1), dtype=np.float64)
     for j in range(o_B + 1):
         R_B1[:, j] = (eX1 - c) ** j
@@ -493,6 +517,13 @@ def lprobust_bw(
     eX2 = X[ind2]
     eW2 = w2[ind2]
     n_B2 = int(np.sum(ind2))
+    if n_B2 < o_B + 2:
+        raise ValueError(
+            f"lprobust_bw: B2 stage has n_B2={n_B2} in-window observations "
+            f"at h_B2={h_B2:.6g} (boundary={c}, kernel={kernel!r}), but "
+            f"needs at least o_B+2={o_B + 2}. Increase sample size or "
+            f"widen the pilot bandwidth."
+        )
     R_B2 = np.empty((n_B2, o_B + 2), dtype=np.float64)
     for j in range(o_B + 2):
         R_B2[:, j] = (eX2 - c) ** j

diff_diff/local_linear.py

@@ -13,11 +13,13 @@
   the conditional mean ``m(d0) := E[Y | D = d0]`` at the boundary of ``D``'s
   support via kernel-weighted OLS.
 
-This module is used by future :class:`HeterogeneousAdoptionDiD` phases:
+This module is used by the :class:`HeterogeneousAdoptionDiD` phases:
 
 - Phase 1a ships the kernels and fitter (this module).
-- Phase 1b will add an MSE-optimal bandwidth selector (Calonico-Cattaneo-Farrell
-  2018) built on top of the fitter.
+- Phase 1b ships the MSE-optimal bandwidth selector
+  ``mse_optimal_bandwidth`` / ``BandwidthResult`` (this module), a thin
+  wrapper over the Calonico-Cattaneo-Farrell (2018) plug-in selector
+  ported in ``diff_diff/_nprobust_port.py``.
 - Phase 1c will add the bias-corrected confidence interval per Equation 8 of
   de Chaisemartin, Ciccia, D'Haultfoeuille & Knau (2026, arXiv:2405.04465v6).
 
@@ -603,6 +605,34 @@ def mse_optimal_bandwidth(
     if not np.isfinite(boundary):
         raise ValueError(f"boundary must be finite; got {boundary}")
 
+    # Boundary-applicability check (Phase 1b scope).
+    # The exported wrapper is scoped to the HAD LOWER-boundary case:
+    #   - Design 1' (d_0 = 0 with support infimum at 0), or
+    #   - Design 1 continuous-near-d_lower (d_0 = d_lower = min(D_2)).
+    # In both cases ``boundary`` must lie at or below the sample minimum:
+    # no observation should fall to the left of the evaluation point,
+    # because the downstream ``local_linear_fit`` uses a one-sided kernel
+    # restricted to ``d >= d_0``. An interior or upper-boundary
+    # evaluation would silently run the boundary selector branch with a
+    # symmetric kernel (see port's ``kernel_W``) and produce a bandwidth
+    # incompatible with the fitter. Reject those inputs here until an
+    # interior-point API is documented (Phase 2+).
+    d_min = float(d.min())
+    # Allow a small numerical tolerance so boundary = min(d) passes even
+    # under floating-point noise (e.g. ``d.min()`` equals ``boundary``
+    # within 1e-12 but not bit-exact).
+    _boundary_tol = 1e-12 * max(1.0, abs(d_min), abs(boundary))
+    if boundary > d_min + _boundary_tol:
+        raise ValueError(
+            f"boundary={boundary!r} exceeds the sample minimum "
+            f"d.min()={d_min!r}. The Phase 1b wrapper is scoped to the "
+            f"HAD lower-boundary case (d_0 <= min(d)). For interior or "
+            f"upper-boundary evaluation, use "
+            f"diff_diff._nprobust_port.lpbwselect_mse_dpi directly with "
+            f"interior=True; note that the non-boundary branches are not "
+            f"separately parity-tested against nprobust."
+        )
+
     # 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

@@ -253,24 +253,55 @@ def test_public_wrapper_fixes_vce_nn_nnmatch_3(self):
         assert via_wrapper.b_mse == via_port_nn.b_mse_dpi
         assert via_wrapper.c_bw == via_port_nn.c_bw
 
-    def test_bwcheck_none_on_tiny_sample_does_not_index_error(self):
-        """bwcheck=None should skip the NN floor.
-
-        The selector may still fail inside lprobust.bw on very small
-        samples (rank-deficient design), but any failure must be a
-        linear-algebra error, not an indexing crash in the bwcheck
-        clipping logic.
-        """
+    def test_bwcheck_none_on_tiny_sample_raises_valueerror(self):
+        """bwcheck=None on a tiny sample must raise a clear ValueError
+        from the per-stage support/rank guard in lprobust_bw, NOT an
+        opaque LinAlgError or IndexError."""
         from diff_diff._nprobust_port import lpbwselect_mse_dpi
 
         d = np.array([0.1, 0.2, 0.3, 0.4, 0.5])
         y = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
-        try:
+        with pytest.raises(ValueError, match="lprobust_bw"):
             lpbwselect_mse_dpi(y, d, eval_point=0.0, bwcheck=None)
-        except IndexError as exc:  # pragma: no cover - regression sentinel
-            pytest.fail(f"Unexpected IndexError from bwcheck path: {exc}")
-        except Exception:
-            pass
+
+    def test_interior_boundary_rejected(self):
+        """boundary strictly inside the support must be rejected by
+        the Phase 1b wrapper. Running the boundary selector at an
+        interior point would silently use a symmetric kernel and
+        produce a bandwidth incompatible with the one-sided fitter."""
+        rng = np.random.default_rng(2026)
+        d = rng.uniform(0.0, 1.0, size=500)
+        y = d + d**2 + rng.normal(0, 0.5, size=500)
+        with pytest.raises(ValueError, match="boundary"):
+            mse_optimal_bandwidth(d, y, boundary=0.5)
+
+    def test_upper_boundary_rejected(self):
+        """boundary at d.max() (upper support edge) must be rejected."""
+        rng = np.random.default_rng(2026)
+        d = rng.uniform(0.0, 1.0, size=500)
+        y = d + d**2 + rng.normal(0, 0.5, size=500)
+        with pytest.raises(ValueError, match="boundary"):
+            mse_optimal_bandwidth(d, y, boundary=float(d.max()))
+
+    def test_boundary_equal_to_min_d_accepted(self):
+        """Design 1 continuous-near-d_lower uses boundary = min(d)
+        exactly; this must pass the applicability check."""
+        rng = np.random.default_rng(20260419)
+        d = rng.uniform(1.0, 2.0, size=1500)
+        y = 3.0 + 0.5 * (d - 1.0) ** 2 + rng.normal(0, 0.3, size=1500)
+        h = mse_optimal_bandwidth(d, y, boundary=float(d.min()))
+        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."""
+        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)
+        h = mse_optimal_bandwidth(d, y, boundary=0.0)
+        assert np.isfinite(h)
+        assert h > 0.0
 
 
 class TestKernelDispatch: