feat(learn): retrieval and the evaluation boundary (decision-engine 6.3)

learn/retrieve.py: stage 1 is a per-instrument Gower distance over the
profile's allow-listed features with explicit missing (both ran: mean
feature distance; differing states 1; same non-ran state 0; null in one 1;
priors dropped with priors=off), n1 = 40 with seeded tie-breaks; stage 2
re-ranks by r = lam(1 - D) + (1 - lam)cos, signals_only without the
target's vector; the balance rule takes k_ret = 6 (<= k/2 per label, <= 2
per group, <= 2 other families; `short` recorded). eligible() is the only
way into a prompt: not the target's group, not an evaluated group, not the
held-out source or framework, and outside deployment not a near-duplicate
(cos >= 0.98). assert_boundary repeats the check on rendered ids;
demonstrations of a held-out framework swap to their alternates;
deployment_fold excludes a scanned repository that is a corpus group;
seed_memory never hands a case its own group.

learn/folds.py: compile split (25% of groups per primary family, 60/40
boot/val), outer grouped 5-fold stratified by family and label mix,
leave-one-source-out, leave-one-framework-out (insufficient data below 10
groups), assert_disjoint and a folds digest; all seeded.

Tests: test_learn_retrieve.py (hand-computed Gower, lam 0/0.5, balance,
near-duplicates, test_boundary over outer/LOSO/LOFO folds with
demonstrations), test_learn_folds.py.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo

tests/learn_fixtures.py

@@ -0,0 +1,64 @@
+"""Shared fixtures for the decision-engine tests: example rows with valid feature records, and scripted clients."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from openultrasast.learn.examples import Example
+from openultrasast.learn.features import NOT_APPLICABLE, Part, engine_part, quick_part, record
+
+
+def x_record(*, hits: int = 0, engine: str = "ran", findings: int = 0, language: str = "python", prior_hits: int = 0) -> dict[str, Any]:
+    """A valid ``static`` record: ``hits`` enabled quick hits, the engine in state ``engine`` with ``findings``."""
+    quick = quick_part([("r", "enabled")] * hits, {})
+    quick = Part("ran", {**quick.values, "qr.prior_hits": prior_hits}, None)
+    parts: dict[str, Part] = {"quick": quick, "delta": NOT_APPLICABLE, "facts": NOT_APPLICABLE}
+    if engine == "ran":
+        parts["engine"] = engine_part([{"rung": "suspicion"}] * findings, completion=1.0, degraded=False)
+    elif engine != "none":
+        parts["engine"] = Part(engine)
+    return record("a.py::f", "injection", language, "static", parts)
+
+
+def example(
+    name: str,
+    *,
+    group: str,
+    label: int,
+    family: str = "injection",
+    source: str = "pairs",
+    frameworks: Sequence[str] = (),
+    hits: int = 0,
+    engine: str = "ran",
+    findings: int = 0,
+    license: str = "",
+) -> Example:
+    rec = x_record(hits=hits, engine=engine, findings=findings)
+    return Example(
+        id=hashlib.sha256(name.encode()).hexdigest(), group=group, source=source, frameworks=tuple(frameworks), family=family, label=label,
+        language="python", profile="static", unit="pin", x=rec["x"], instruments=rec["instruments"], roles=(),
+        excerpt_sha=hashlib.sha256(f"excerpt:{name}".encode()).hexdigest(), license=license,
+    )  # fmt: skip
+
+
+def corpus(groups: int = 12, per_group: int = 4) -> list[Example]:
+    """``groups`` repository groups over three sources and two frameworks, each with positives and negatives."""
+    out: list[Example] = []
+    for g in range(groups):
+        source = ("pairs", "population-v1", "population-v2")[g % 3]
+        frameworks = ("flask",) if g % 4 == 0 else ("django",) if g % 4 == 1 else ()
+        family = ("injection", "path")[g % 2]
+        for i in range(per_group):
+            out.append(
+                example(
+                    f"g{g}-e{i}", group=f"org{g}/repo{g}", label=i % 2, family=family, source=source, frameworks=frameworks,
+                    hits=(g + i) % 5, findings=i % 3,
+                )
+            )  # fmt: skip
+    return out
+
+
+def by_id(examples: Sequence[Example]) -> Mapping[str, Example]:
+    return {e.id: e for e in examples}