Codex CI R4 P1: enforce zero diagonal on callable conley_metric

P1 [new in R4] — `_validate_callable_metric_result` accepted any
symmetric / finite / non-negative matrix, even when d(i, i) > 0. The
Conley sandwich relies on K(0) = 1 to reduce the i=j term to the HC0
diagonal X_i ε_i² X_i'; a positive self-distance silently attenuates
the HC0 contribution by K(d_ii / h) < 1 and misstates Conley SEs.
Built-in metrics ("haversine", "euclidean") satisfy d(i, i) = 0 by
construction, so the existing parity tests didn't catch this gap on
the callable surface.

Adds a sixth check to the callable validator:
  |d(i, i)| <= 1e-10 for all i, else ValueError naming the violated
  invariant ("nonzero self-distance ... requires d(i, i) = 0 so the
  kernel reduces to K(0) = 1 on the HC0 diagonal contribution").

Tests:
  - test_callable_metric_nonzero_diagonal_raises: symmetric / finite /
    non-negative with d(i, i) = 0.5 raises.
  - test_callable_metric_near_zero_diagonal_accepted: sub-tolerance
    diagonal noise (1e-13) accepted, mirroring the symmetry contract.
  - test_pairwise_distance_callable updated: the constant_metric
    fixture now zeroes its diagonal (otherwise it would fail the new
    check); behaviorally equivalent off-diagonal coverage.

Docs:
  - docs/methodology/REGISTRY.md § "Callable conley_metric validation"
    extended: 6th check added to the list + a paragraph explaining the
    HC0-reduction rationale.

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

Author: igerber

diff_diff/conley.py

@@ -118,10 +118,19 @@ def _validate_callable_metric_result(result: object, n: int) -> np.ndarray:
     """Validate the output of a user-supplied callable ``conley_metric``.
 
     A user-supplied distance callable must return an ``(n, n)`` matrix of
-    finite, non-negative, symmetric values; otherwise downstream code
-    produces opaque BLAS errors or silently-wrong vcov estimates. This
-    helper performs all five checks at the boundary and produces a
-    targeted :class:`ValueError` for each failure.
+    finite, non-negative, symmetric values with **zero diagonal**;
+    otherwise downstream code produces opaque BLAS errors or silently-
+    wrong vcov estimates. This helper performs all six checks at the
+    boundary and produces a targeted :class:`ValueError` for each
+    failure.
+
+    The zero-diagonal invariant is load-bearing for the Conley sandwich:
+    the ``i = j`` term contributes ``K(d_ii / h) · X_i ε_i² X_i'``, which
+    must reduce to the HC0 diagonal ``X_i ε_i² X_i'`` (i.e., ``K(0) = 1``).
+    A callable with positive self-distance would attenuate the HC0
+    contribution by ``K(d_ii / h) < 1`` and silently misstate Conley SEs.
+    Built-in metrics (``"haversine"``, ``"euclidean"``) satisfy this by
+    construction.
 
     Returns
     -------
@@ -133,7 +142,8 @@ def _validate_callable_metric_result(result: object, n: int) -> np.ndarray:
     ValueError
         Result cannot cast to ``float64``; shape is not ``(n, n)``;
         contains NaN/inf; contains negative entries; is not symmetric
-        within ``atol=1e-10``.
+        within ``atol=1e-10``; or has any nonzero diagonal entry
+        ``|d(i, i)| > 1e-10``.
     """
     try:
         arr = np.asarray(result, dtype=np.float64)
@@ -164,6 +174,15 @@ def _validate_callable_metric_result(result: object, n: int) -> np.ndarray:
             "distance matrix must satisfy d(i, j) = d(j, i). Max |D - D.T| = "
             f"{asymmetry:.2e}, tolerance 1e-10."
         )
+    diag_max = float(np.max(np.abs(np.diag(arr)))) if arr.size else 0.0
+    if diag_max > 1e-10:
+        raise ValueError(
+            "conley_metric callable returned a matrix with nonzero self-"
+            "distance on the diagonal; the Conley sandwich requires "
+            "d(i, i) = 0 so the kernel reduces to K(0) = 1 on the HC0 "
+            f"diagonal contribution. Max |diag(D)| = {diag_max:.2e}, "
+            "tolerance 1e-10."
+        )
     return arr
 
 

docs/methodology/REGISTRY.md

@@ -3130,9 +3130,16 @@ validated at the boundary via `_validate_callable_metric_result`:
 3. All entries are finite (NaN/inf raises).
 4. All entries are non-negative (negative distances raise).
 5. Symmetric to within `atol=1e-10` (asymmetric matrix raises).
+6. Zero diagonal: `|d(i, i)| ≤ 1e-10` for all `i` (nonzero diagonal raises).
 
 Each failure produces a `ValueError` naming the violated invariant.
-Sub-tolerance asymmetry (eps-level roundoff) is accepted.
+Sub-tolerance asymmetry (eps-level roundoff) is accepted. The zero-
+diagonal invariant is load-bearing for the Conley sandwich: the
+`i = j` term contributes `K(d_ii / h) · X_i ε_i² X_i'`, which must
+reduce to the HC0 diagonal `X_i ε_i² X_i'` (i.e., `K(0) = 1`). A
+callable with positive self-distance would attenuate the HC0 term
+by `K(d_ii / h) < 1` and silently misstate Conley SEs. Built-in
+metrics (`"haversine"`, `"euclidean"`) satisfy this by construction.
 
 **Edge cases / restrictions:**
 - `DifferenceInDifferences(vcov_type="conley")` is supported (Wave A #118): pass `unit=<col>` to `fit(...)` (NOT on `__init__`; unused unless Conley is set; not part of `get_params()` / `set_params()`).

tests/test_conley_vcov.py

@@ -164,16 +164,22 @@ def test_pairwise_distance_euclidean_matches_pdist(self):
         np.testing.assert_allclose(D, D_scipy, atol=1e-12)
 
     def test_pairwise_distance_callable(self):
-        """A user-supplied callable is dispatched and its output preserved."""
+        """A user-supplied callable is dispatched and its output preserved.
+        Output must satisfy the validator's invariants (zero diagonal, finite,
+        non-negative, symmetric)."""
         coords = np.array([[0.0, 0.0], [1.0, 1.0], [2.0, 2.0]])
 
-        def constant_metric(c1, c2):
+        def constant_offdiag_metric(c1, c2):
             n1 = len(c1)
             n2 = len(c2)
-            return np.full((n1, n2), 5.0)
+            out = np.full((n1, n2), 5.0)
+            np.fill_diagonal(out, 0.0)
+            return out
 
-        D = _pairwise_distance_matrix(coords, constant_metric)
-        np.testing.assert_allclose(D, np.full((3, 3), 5.0))
+        D = _pairwise_distance_matrix(coords, constant_offdiag_metric)
+        expected = np.full((3, 3), 5.0)
+        np.fill_diagonal(expected, 0.0)
+        np.testing.assert_allclose(D, expected)
 
     def test_pairwise_distance_unknown_metric_raises(self):
         """Unknown metric strings raise ValueError from the dispatcher."""
@@ -244,6 +250,43 @@ def asymmetric_metric(c1, c2):
         with pytest.raises(ValueError, match="asymmetric matrix"):
             _pairwise_distance_matrix(coords, asymmetric_metric)
 
+    def test_callable_metric_nonzero_diagonal_raises(self):
+        """Callable returning a symmetric/finite/non-negative matrix with a
+        positive self-distance still raises, because the Conley sandwich
+        requires d(i, i) = 0 (K(0) = 1 reduces the i=j term to the HC0
+        diagonal X_i ε_i² X_i'). A nonzero self-distance silently attenuates
+        the HC0 contribution by K(d_ii / h) < 1 and misstates Conley SEs.
+        Codex CI R4 P1."""
+        coords = np.array([[0.0, 0.0], [1.0, 1.0], [2.0, 2.0]])
+
+        def positive_diagonal_metric(c1, c2):
+            # Symmetric, finite, non-negative — but d(i, i) = 0.5 > 0.
+            n1 = len(c1)
+            n2 = len(c2)
+            out = np.full((n1, n2), 5.0)
+            np.fill_diagonal(out, 0.5)
+            return out
+
+        with pytest.raises(ValueError, match=r"nonzero self-distance"):
+            _pairwise_distance_matrix(coords, positive_diagonal_metric)
+
+    def test_callable_metric_near_zero_diagonal_accepted(self):
+        """Sub-tolerance diagonal (roundoff scale) is accepted, mirroring
+        the symmetry-tolerance contract."""
+        coords = np.array([[0.0, 0.0], [1.0, 1.0], [2.0, 2.0]])
+
+        def near_zero_diagonal_metric(c1, c2):
+            n1 = len(c1)
+            n2 = len(c2)
+            out = np.full((n1, n2), 5.0)
+            np.fill_diagonal(out, 0.0)
+            # Diagonal noise well below the 1e-10 tolerance
+            out[0, 0] = 1e-13
+            return out
+
+        D = _pairwise_distance_matrix(coords, near_zero_diagonal_metric)
+        assert D.shape == (3, 3)
+
     def test_callable_metric_non_array_result_raises(self):
         """Callable returning a non-castable result raises a targeted ValueError."""
         coords = np.array([[0.0, 0.0], [1.0, 1.0], [2.0, 2.0]])