feat(detection-core): anti-shortcut probes and fitted-component admission gate

src/openultrasast/core/probes.py

@@ -0,0 +1,67 @@
+"""Anti-shortcut probes for fitted components (Req 8, 9).
+
+A fitted prompt, threshold, or model must not separate a fix from its reversed fix
+using shape features (diff size, deletion count, line counts): that is pool-specific
+shortcut learning, the 2026-10-14 deletion-count 0.90 finding. A component making any
+detection claim must also carry per-repository holdout evidence and a GO admission on
+an untouched population.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+class ShortcutDetected(ValueError):
+    """A component separates a fix from its reversed fix by its decision features."""
+
+
+class FittedComponentBlocked(ValueError):
+    """A fitted component claims detection without holdout + admission evidence."""
+
+
+@dataclass(frozen=True)
+class ProbeResult:
+    """Outcome of one reversed-pair probe."""
+
+    separated: bool
+    fix_score: float
+    reversed_score: float
+
+
+def reversed_pair_probe(
+    score_fn: Callable[[Mapping[str, Any]], float], fix_change: Mapping[str, Any], reversed_change: Mapping[str, Any]
+) -> ProbeResult:
+    """Score a fix and its reversed fix; separated=True means the features shortcut."""
+    fix_score = float(score_fn(fix_change))
+    reversed_score = float(score_fn(reversed_change))
+    return ProbeResult(separated=fix_score != reversed_score, fix_score=fix_score, reversed_score=reversed_score)
+
+
+def assert_no_shortcut(
+    score_fn: Callable[[Mapping[str, Any]], float], fix_change: Mapping[str, Any], reversed_change: Mapping[str, Any]
+) -> None:
+    """Raise ShortcutDetected when the component separates fix from reversed fix."""
+    result = reversed_pair_probe(score_fn, fix_change, reversed_change)
+    if result.separated:
+        raise ShortcutDetected(f"shape shortcut: fix={result.fix_score} vs reversed={result.reversed_score}")
+
+
+def require_admission_evidence(*, holdout_passed: bool, admission_decision: str) -> None:
+    """Block any fitted-component claim without holdout and an admission GO (Req 8.2)."""
+    if not holdout_passed:
+        raise FittedComponentBlocked("fitted component lacks per-repository holdout evidence")
+    if admission_decision != "GO":
+        raise FittedComponentBlocked(f"fitted component admission decision is {admission_decision!r}, not GO")
+
+
+__all__ = [
+    "FittedComponentBlocked",
+    "ProbeResult",
+    "ShortcutDetected",
+    "assert_no_shortcut",
+    "require_admission_evidence",
+    "reversed_pair_probe",
+]