quantum-cortex 1.0.0__py3-none-any.whl

cortex_c2/__init__.py

@@ -0,0 +1,161 @@
+"""cortex_c2 — the multi-path C2 memory router (RES-18, ADR-006 D8), Slice A.
+
+C2 is not one memory nor a choice between Hopfield and delta: it is a ROUTER of
+memory paths on a guaranteed control floor. On any span, a memory is used only
+where it beats the control; if all are below, the control is used — so C2 can
+never degrade the model. (The ablation proved the floor is needed: the control
+won 3 of 12 MQAR tiers.)
+
+Slice A ships the FOUNDATION, retro-compatibility included from day one:
+  - a VERSIONED, stable Router interface (the contract every future version honours);
+  - RouterV1 = the upper-envelope oracle (picks, per span, the best of the known
+    path scores — the ceiling the learned router will chase: +21% vs control);
+  - version-tagged serialisation + a single-branch version dispatch (adding v2 is
+    one more branch, never a change to the existing one);
+  - a contract test (the guard) that any RouterVN must pass.
+
+What is deliberately deferred (not by caution but by logic): ACTIVE migration
+(transforming a v1 state into a v2 state) — impossible to write correctly before
+v2 exists, but MADE POSSIBLE by the contract fixed here. The router-per-block
+placement and soft/hard regime + breaker fallback are later slices (B, C).
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Sequence
+
+# Path identifiers — the control floor is always path 0.
+PATH_CONTROL = 0
+PATH_HOPFIELD = 1
+PATH_DELTA = 2
+PATH_NAMES = {PATH_CONTROL: "control", PATH_HOPFIELD: "hopfield", PATH_DELTA: "delta"}
+
+CURRENT_ROUTER_VERSION = 1
+
+
+@dataclass
+class RouteDecision:
+    """The stable output contract of any Router version.
+
+    path      : the chosen path id (PATH_CONTROL always available as the floor)
+    confidence: [0,1] — how sure the router is (drives soft/hard regime in Slice C)
+    weights   : optional soft mixture over paths (None = hard choice of `path`)
+    """
+    path: int
+    confidence: float = 1.0
+    weights: Sequence[float] | None = None
+
+    def is_hard(self) -> bool:
+        return self.weights is None
+
+
+class Router(ABC):
+    """The versioned, STABLE contract. Every future RouterVN implements exactly
+    this signature — versions EXTEND, they never break the interface. This is the
+    retro-compatibility promise, fixed at v1 so it precedes (not follows) the code.
+    """
+
+    version: int = 0  # each concrete version sets this
+
+    @abstractmethod
+    def route(self, *, span_ctx, path_scores: Sequence[float] | None = None,
+              state: dict | None = None) -> RouteDecision:
+        """Decide which path to use for a span.
+
+        span_ctx    : opaque context handle for the span (features the router may use)
+        path_scores : optional known per-path scores (the oracle uses these; a
+                      learned router predicts them from span_ctx instead)
+        state       : optional persistent router state (version-tagged; see below)
+        Returns a RouteDecision honouring the RouteDecision contract.
+        """
+        raise NotImplementedError
+
+    # -- version-tagged serialisation (the retro-compat machinery, one branch) --
+    def dump_state(self, state: dict | None = None) -> dict:
+        """Serialise router state WITH its version tag, so any future loader can
+        dispatch on it. v1 state is trivial; the envelope carries the tag."""
+        return {"router_version": self.version, "state": state or {}}
+
+    @staticmethod
+    def load_state(blob: dict) -> dict:
+        """Version dispatch — currently one branch (v1). Adding v2 is one more
+        `elif`, never a change to this branch. Retro-compat by construction.
+        Active migration (v1→v2 transform) is deferred until a v2 exists — the
+        contract here makes it POSSIBLE, it does not implement it."""
+        v = blob.get("router_version")
+        if v == 1:
+            return blob.get("state", {})
+        # future: elif v == 2: return _migrate_or_read_v2(blob)
+        raise ValueError(f"unknown router_version {v!r} — no reader registered")
+
+
+class RouterV1(Router):
+    """v1 = the upper-envelope ORACLE.
+
+    Given the known per-path scores for a span, pick the best path *that beats the
+    control floor*; if none beats it, choose the control. This is not a learned
+    router — it computes the CEILING (the ablation showed +21% vs control, +6%
+    over the best single path). Slice B replaces the oracle with a learned gate
+    that PREDICTS path_scores from span_ctx; it will implement this same interface.
+    """
+
+    version = 1
+
+    def __init__(self, floor_margin: float = 0.0):
+        # a memory must beat the control by at least floor_margin to be chosen
+        self.floor_margin = floor_margin
+
+    def route(self, *, span_ctx=None, path_scores: Sequence[float] | None = None,
+              state: dict | None = None) -> RouteDecision:
+        if not path_scores:
+            # no information → fall to the guaranteed floor (never degrade)
+            return RouteDecision(path=PATH_CONTROL, confidence=1.0)
+        scores = list(path_scores)
+        control = scores[PATH_CONTROL]
+        # candidate memories that clear the floor by the margin
+        best_path, best_score = PATH_CONTROL, control
+        for p in range(1, len(scores)):
+            if scores[p] > control + self.floor_margin and scores[p] > best_score:
+                best_path, best_score = p, scores[p]
+        # confidence = normalised gap to the runner-up (how decisive the choice is)
+        ordered = sorted(scores, reverse=True)
+        gap = (ordered[0] - ordered[1]) if len(ordered) > 1 else 1.0
+        conf = float(min(1.0, max(0.0, gap / (abs(ordered[0]) + 1e-6))))
+        return RouteDecision(path=best_path, confidence=conf)
+
+
+def make_router(version: int = CURRENT_ROUTER_VERSION, **kw) -> Router:
+    """Factory — version dispatch for construction. Retro-compat in action:
+    v2 is one more branch, v1 is untouched (the contract fixed at v1 holds)."""
+    if version == 1:
+        return RouterV1(**kw)
+    if version == 2:
+        from cortex_c2.router_v2 import RouterV2   # torch-dependent, imported lazily
+        return RouterV2(**kw)
+    raise ValueError(f"no Router implementation for version {version}")
+
+
+def upper_envelope_auc(per_tier_by_path: dict[str, list[float]]) -> dict:
+    """Compute the RouterV1-oracle result over a set of tiers: per tier, the
+    router picks max(control, hopfield, delta); the AUC of that choice is the
+    ceiling. Returns the envelope AUC and the routed path per tier."""
+    control = per_tier_by_path["control"]
+    hop = per_tier_by_path["hopfield"]
+    delta = per_tier_by_path["delta"]
+    n = len(control)
+    router = RouterV1()
+    routed_paths, routed_scores = [], []
+    for i in range(n):
+        d = router.route(path_scores=[control[i], hop[i], delta[i]])
+        routed_paths.append(PATH_NAMES[d.path])
+        routed_scores.append([control[i], hop[i], delta[i]][d.path])
+    env_auc = sum(routed_scores) / n
+    ctrl_auc = sum(control) / n
+    best_single = max(sum(hop) / n, sum(delta) / n, ctrl_auc)
+    return {
+        "envelope_auc": round(env_auc, 4),
+        "vs_control": round(env_auc - ctrl_auc, 4),
+        "vs_best_single_path": round(env_auc - best_single, 4),
+        "routed_paths": routed_paths,
+    }

cortex_c2/consolidation.py

@@ -0,0 +1,146 @@
+"""cortex_c2.consolidation — the consolidating, self-healing router controller.
+
+Slice C of RES-18 (ADR-006 D8). This is where the founder's three-message design
+becomes code, as ONE stateful object wrapping a Router:
+
+  1. Control floor (message 1): a memory path is used only where it beats the
+     control; else the control. Enforced by the router; re-checked here.
+  2. Regime = consolidation (message 2): a per-span-type decision that has been
+     LEARNED — the same path wins, confidently, over N passes — is HARDENED
+     (routed hard, one path, no soft mixture, minimal cost). Unsure decisions
+     stay SOFT (the router's mixture) and keep generating the learning signal.
+     Hardening is conservative (a high, declared confidence threshold + stability
+     count) — better stay soft too long than harden an error.
+  3. Breaker fallback (message 3): when an active path degrades or diverges, do
+     not kill — RE-ROUTE to the best remaining path above the control, else the
+     control, and RE-SOFTEN the decision (re-open deliberation). A declared
+     HYSTERESIS (cooldown) prevents flapping between paths.
+
+This is a textbook RES-17 type×state transition: a decision transitions
+soft → hardened → (on breaker) softened-again. It unifies C1 (routing), RES-4
+(confidence), RES-16 (consolidation + reminiscence), the endocrine explore/exploit
+dial, basal-ganglia habit + hyperdirect veto, and the circuit breaker D7 — one
+mechanism, seven windows.
+
+Pure-Python controller (no torch here); it drives any Router.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from cortex_c2 import Router, RouteDecision, PATH_CONTROL, PATH_NAMES
+
+
+@dataclass
+class DecisionState:
+    """Per-span-type consolidation state — the RES-17 (type, state) cell."""
+    hardened_path: int | None = None      # None = soft; an int = hardened to that path
+    stable_count: int = 0                 # consecutive passes the same path won confidently
+    last_path: int | None = None
+    cooldown: int = 0                     # hysteresis: passes remaining before a path may be re-chosen
+    banned_path: int | None = None        # a path in cooldown after a breaker fallback
+
+
+@dataclass
+class ConsolidationConfig:
+    harden_confidence: float = 0.75       # min confidence to count a pass toward hardening
+    harden_stability: int = 5             # consecutive confident passes required to harden (conservative)
+    hysteresis_cooldown: int = 8          # passes a path stays banned after a fallback (anti-flapping)
+    clear_recovery_margin: float = 0.05   # a banned path must beat control by this to be re-eligible early
+
+
+class ConsolidatingController:
+    """Wraps a Router and adds consolidation + breaker fallback, per span-type key.
+
+    `route(key, span_ctx, path_scores)` returns a RouteDecision:
+      - if the key is HARDENED and not in cooldown → a hard decision on the learned path;
+      - else the router's (soft) decision, with the control floor enforced, and
+        hardening bookkeeping updated.
+    `report_breaker(key, path)` is called when a path degraded/diverged on this key:
+      it re-routes (bans the path for a cooldown), re-softens, and never leaves a void.
+    """
+
+    def __init__(self, router: Router, cfg: ConsolidationConfig | None = None):
+        self.router = router
+        self.cfg = cfg or ConsolidationConfig()
+        self.states: dict = {}
+
+    def _state(self, key) -> DecisionState:
+        return self.states.setdefault(key, DecisionState())
+
+    def route(self, *, key, span_ctx=None, path_scores=None) -> RouteDecision:
+        st = self._state(key)
+
+        # HARDENED path: route hard, minimal cost — unless it is the banned path
+        if (st.hardened_path is not None and st.hardened_path != st.banned_path
+                and st.cooldown == 0):
+            self._tick_cooldown(st)
+            return RouteDecision(path=st.hardened_path, confidence=1.0)  # hard, no mixture
+
+        # otherwise ask the router (soft), then apply the floor + bookkeeping
+        d = self.router.route(span_ctx=span_ctx, path_scores=path_scores)
+
+        # if the chosen path is banned (still in cooldown), pull to control floor
+        if st.banned_path is not None and st.cooldown > 0 and d.path == st.banned_path:
+            d = RouteDecision(path=PATH_CONTROL, confidence=d.confidence, weights=d.weights)
+
+        # consolidation bookkeeping: count confident agreement toward hardening
+        if d.confidence >= self.cfg.harden_confidence and d.path == st.last_path:
+            st.stable_count += 1
+        else:
+            st.stable_count = 1
+        st.last_path = d.path
+
+        # harden once stable enough (conservative) and not the banned path
+        if (st.stable_count >= self.cfg.harden_stability
+                and d.path != PATH_CONTROL
+                and not (st.banned_path == d.path and st.cooldown > 0)):
+            st.hardened_path = d.path
+
+        self._tick_cooldown(st)      # decrement AFTER serving this pass
+        return d
+
+    def _tick_cooldown(self, st: DecisionState) -> None:
+        if st.cooldown > 0:
+            st.cooldown -= 1
+            if st.cooldown == 0:
+                st.banned_path = None
+
+    def report_breaker(self, *, key, path, path_scores=None) -> RouteDecision:
+        """A path degraded/diverged on this key → re-route with hysteresis.
+
+        Bans `path` for a cooldown (anti-flapping), re-softens (drops any
+        hardening), and returns the best remaining path above the control, else
+        the control. Never a void — completes the hyperdirect veto (redirect).
+        """
+        st = self._state(key)
+        st.banned_path = path
+        st.cooldown = self.cfg.hysteresis_cooldown
+        st.hardened_path = None          # re-soften: re-open deliberation (RES-16 reminiscence)
+        st.stable_count = 0
+        st.last_path = None
+
+        # choose the fallback: best remaining path above control, else control
+        if path_scores:
+            control = path_scores[PATH_CONTROL]
+            best_path, best_score = PATH_CONTROL, control
+            for p in range(len(path_scores)):
+                if p == path:
+                    continue  # the banned path is out
+                if p != PATH_CONTROL and path_scores[p] > control and path_scores[p] > best_score:
+                    best_path, best_score = p, path_scores[p]
+            return RouteDecision(path=best_path, confidence=0.5)
+        # no scores → fall to the guaranteed floor
+        return RouteDecision(path=PATH_CONTROL, confidence=1.0)
+
+    # -- introspection (RES-17: the system becomes legible) ------------------
+    def snapshot(self) -> dict:
+        """Inspectable view — how many keys are hardened, softened, in cooldown."""
+        hardened = sum(1 for s in self.states.values() if s.hardened_path is not None)
+        cooling = sum(1 for s in self.states.values() if s.cooldown > 0)
+        return {
+            "keys": len(self.states),
+            "hardened": hardened,
+            "soft": len(self.states) - hardened,
+            "in_cooldown": cooling,
+        }

cortex_c2/router_ablation.py

@@ -0,0 +1,254 @@
+"""cortex_c2.router_ablation — Slice D: does the learned router reach the ceiling?
+
+The closing question of N2 (RES-18, ADR-006 D8). Slice A gave the ORACLE ceiling
+(+21% vs control, +6% over the best single path) — but the oracle *reads* the
+truth. Slice B/C gave a router that *learns* to route from context alone and
+consolidates. Slice D measures whether that learned router, in practice,
+approaches the oracle ceiling — the test that validates (or not) that the whole
+multi-path system actually works, not just in oracle.
+
+Method (measure-first): build a synthetic routing task where each span-type has a
+context feature and a known best path (mirroring the ablation's per-tier domains:
+Hopfield-favoured, delta-favoured, control-favoured). Train RouterV2 on observed
+per-path scores; drive it through the ConsolidatingController; and compare four
+readings on held-out spans:
+  - control-only  (always the floor)
+  - best single memory (whichever single path scores best on average)
+  - the ORACLE (RouterV1: reads truth — the ceiling)
+  - the LEARNED router (RouterV2 + controller: predicts, never reads truth)
+The learned router's gap to the oracle is the Slice-D signal. Reaching most of
+the oracle's lift over the best single path means RES-18 pays off in practice.
+
+Pure enough to run on CPU in minutes; a fuller version trains on real MQAR spans.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+
+from cortex_c2 import PATH_CONTROL, PATH_HOPFIELD, PATH_DELTA, PATH_NAMES, RouterV1
+from cortex_c2.consolidation import ConsolidatingController, ConsolidationConfig
+
+REPO = Path(__file__).resolve().parents[1]
+N_PATHS = 3
+
+
+# --- the synthetic routing task (each span-type has a domain) ----------------
+def _span_scores(ctx0: float) -> list[float]:
+    """Known per-path scores as a function of the context feature — mirrors the
+    ablation's finding that each path has a domain."""
+    if ctx0 < -0.33:                       # Hopfield's domain (dense recall)
+        return [0.10, 0.30, 0.16]
+    elif ctx0 > 0.33:                      # delta's domain (intermediate)
+        return [0.10, 0.16, 0.30]
+    else:                                  # control's domain (memory hurts here)
+        return [0.28, 0.12, 0.12]
+
+
+def _make_spans(n: int, seed: int):
+    rng = np.random.default_rng(seed)
+    ctx = rng.standard_normal((n, 8)).astype(np.float32)
+    scores = np.array([_span_scores(float(ctx[i, 0])) for i in range(n)], dtype=np.float32)
+    return ctx, scores
+
+
+def _auc_of_choice(scores: np.ndarray, chosen_path: np.ndarray) -> float:
+    """Mean achieved score when each span uses its chosen path."""
+    return float(np.mean([scores[i, chosen_path[i]] for i in range(len(scores))]))
+
+
+def run_router_ablation(train_n: int = 4000, test_n: int = 1000,
+                        steps: int = 600, seed: int = 1337) -> dict:
+    import torch
+    from cortex_c2.router_v2 import RouterV2
+
+    # data
+    ctx_tr, sc_tr = _make_spans(train_n, seed)
+    ctx_te, sc_te = _make_spans(test_n, seed + 1)
+
+    # train the learned router (predict per-path scores from context)
+    torch.manual_seed(seed)
+    router = RouterV2(ctx_dim=8, floor_margin=0.0)
+    opt = torch.optim.Adam(router.parameters(), lr=1e-2)
+    Xtr = torch.from_numpy(ctx_tr); Ytr = torch.from_numpy(sc_tr)
+    bs = 128
+    for step in range(steps):
+        idx = torch.randint(0, train_n, (bs,))
+        loss = router.score_loss(Xtr[idx], Ytr[idx])
+        opt.zero_grad(); loss.backward(); opt.step()
+
+    # --- four readings on held-out spans ---
+    n = test_n
+    # 1) control-only
+    ctrl_choice = np.full(n, PATH_CONTROL)
+    auc_control = _auc_of_choice(sc_te, ctrl_choice)
+    # 2) best single memory (pick the path with best average score across spans)
+    avg = sc_te.mean(axis=0)
+    best_single_path = int(np.argmax(avg))
+    single_choice = np.full(n, best_single_path)
+    auc_best_single = _auc_of_choice(sc_te, single_choice)
+    # 3) oracle (RouterV1 reads truth)
+    oracle = RouterV1()
+    orc_choice = np.array([oracle.route(path_scores=sc_te[i].tolist()).path for i in range(n)])
+    auc_oracle = _auc_of_choice(sc_te, orc_choice)
+    # 4) learned router (RouterV2 + controller: predicts, never reads truth)
+    ctl = ConsolidatingController(router, ConsolidationConfig(harden_confidence=0.6,
+                                                             harden_stability=3))
+    learned_choice = np.zeros(n, dtype=int)
+    Xte = torch.from_numpy(ctx_te)
+    for i in range(n):
+        # key = the span-type bucket (so consolidation has something to harden)
+        c0 = float(ctx_te[i, 0])
+        key = "hop" if c0 < -0.33 else "delta" if c0 > 0.33 else "ctrl"
+        d = ctl.route(key=key, span_ctx=Xte[i])
+        learned_choice[i] = d.path
+    auc_learned = _auc_of_choice(sc_te, learned_choice)
+
+    # gaps
+    lift_oracle = auc_oracle - auc_best_single
+    lift_learned = auc_learned - auc_best_single
+    frac_of_ceiling = (lift_learned / lift_oracle) if lift_oracle > 1e-9 else float("nan")
+
+    return {
+        "benchmark": "router_ablation",
+        "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+        "regime": {"train_n": train_n, "test_n": test_n, "steps": steps, "seed": seed},
+        "auc": {
+            "control_only": round(auc_control, 4),
+            "best_single_memory": round(auc_best_single, 4),
+            "oracle_ceiling": round(auc_oracle, 4),
+            "learned_router": round(auc_learned, 4),
+        },
+        "best_single_path": PATH_NAMES[best_single_path],
+        "lift_over_best_single": {
+            "oracle": round(lift_oracle, 4),
+            "learned": round(lift_learned, 4),
+            "learned_fraction_of_oracle_ceiling": round(frac_of_ceiling, 3),
+        },
+        "controller": ctl.snapshot(),
+        "verdict": (
+            f"learned router captures {frac_of_ceiling*100:.0f}% of the oracle's lift "
+            f"over the best single path"
+            if lift_oracle > 1e-9 else
+            "no oracle lift on this task (paths do not separate)"
+        ),
+        "note": "RES-18 Slice D — the learned router predicts (never reads truth); "
+                "reaching most of the oracle ceiling means the multi-path design pays off. "
+                "Synthetic routing task; a fuller run trains on real MQAR spans.",
+    }
+
+
+def write_artefact(result: dict, out_dir: str | Path) -> Path:
+    out = Path(out_dir); out.mkdir(parents=True, exist_ok=True)
+    stamp = result["timestamp_utc"][:19].replace(":", "").replace("-", "")
+    path = out / f"router-ablation-{stamp}.json"
+    path.write_text(json.dumps(result, indent=2) + "\n")
+    (out / "LATEST-router.json").write_text(json.dumps(result, indent=2) + "\n")
+    return path
+
+
+def _cli():
+    ap = argparse.ArgumentParser(description="RES-18 router ablation (Slice D)")
+    ap.add_argument("--steps", type=int, default=600)
+    ap.add_argument("--out", default="metrics/mqar")
+    ap.add_argument("--quick", action="store_true")
+    args = ap.parse_args()
+    r = run_router_ablation(steps=200 if args.quick else args.steps,
+                            train_n=1000 if args.quick else 4000)
+    path = write_artefact(r, args.out)
+    print("\n=== RES-18 router ablation (Slice D) ===")
+    print(json.dumps(r["auc"], indent=2))
+    print(r["verdict"])
+    print(f"controller: {json.dumps(r['controller'])}")
+    print(f"artefact: {path}")
+
+
+if __name__ == "__main__":
+    _cli()
+
+
+# ============================================================================ #
+# (b) D19 Level 1b — the router on REAL MQAR spans, not the synthetic task     #
+# ============================================================================ #
+def _real_span_ctx(kv: int, seq: int) -> np.ndarray:
+    """Context feature for a real MQAR span-type: normalised (kv, seq) + simple
+    interactions. The router must learn which path wins from THIS, never from
+    the truth. (8 dims to stay compatible with RouterV2(ctx_dim=8).)"""
+    k = math.log2(kv) / 5.0          # kv ∈ {4..32} → ~0.4..1.0
+    s = math.log2(seq) / 9.0         # seq ∈ {128..512} → ~0.78..1.0
+    return np.array([k, s, k * s, k * k, s * s, k - s, 1.0 - k, 1.0 - s], dtype=np.float32)
+
+
+def run_router_ablation_on_real_mqar(curves_by_path: dict, steps: int = 800,
+                                     seed: int = 1337, holdout_frac: float = 0.34) -> dict:
+    """Train RouterV2 on real per-tier MQAR accuracies (from an ablation artefact)
+    and test on held-out tiers. curves_by_path = {"none": [...], "hopfield": [...],
+    "delta": [...]} where each item is {"kv_pairs","seq_len","accuracy"} (same tier
+    order). Held-out tiers are chosen by seed so the router never sees their scores.
+    """
+    import torch
+    from cortex_c2.router_v2 import RouterV2
+
+    tiers = [(t["kv_pairs"], t["seq_len"]) for t in curves_by_path["none"]]
+    n = len(tiers)
+    scores = np.array([[curves_by_path["none"][i]["accuracy"],
+                        curves_by_path["hopfield"][i]["accuracy"],
+                        curves_by_path["delta"][i]["accuracy"]] for i in range(n)],
+                      dtype=np.float32)
+    ctx = np.array([_real_span_ctx(kv, sq) for kv, sq in tiers], dtype=np.float32)
+
+    rng = np.random.default_rng(seed)
+    perm = rng.permutation(n)
+    n_test = max(2, int(round(n * holdout_frac)))
+    test_idx, train_idx = perm[:n_test], perm[n_test:]
+
+    torch.manual_seed(seed)
+    router = RouterV2(ctx_dim=8, floor_margin=0.0)
+    opt = torch.optim.Adam(router.parameters(), lr=1e-2)
+    Xtr = torch.from_numpy(ctx[train_idx]); Ytr = torch.from_numpy(scores[train_idx])
+    for _ in range(steps):
+        loss = router.score_loss(Xtr, Ytr)
+        opt.zero_grad(); loss.backward(); opt.step()
+
+    # readings on held-out tiers
+    te_scores = scores[test_idx]
+    auc_control = float(te_scores[:, PATH_CONTROL].mean())
+    avg = te_scores.mean(axis=0); best_single_path = int(np.argmax(avg))
+    auc_best_single = float(te_scores[:, best_single_path].mean())
+    oracle = RouterV1()
+    orc = [oracle.route(path_scores=te_scores[i].tolist()).path for i in range(len(test_idx))]
+    auc_oracle = float(np.mean([te_scores[i, orc[i]] for i in range(len(test_idx))]))
+    Xte = torch.from_numpy(ctx[test_idx])
+    learned = [router.route(span_ctx=Xte[i]).path for i in range(len(test_idx))]
+    auc_learned = float(np.mean([te_scores[i, learned[i]] for i in range(len(test_idx))]))
+
+    lift_o = auc_oracle - auc_best_single
+    lift_l = auc_learned - auc_best_single
+    frac = (lift_l / lift_o) if lift_o > 1e-9 else float("nan")
+    return {
+        "benchmark": "router_ablation_real_mqar",
+        "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+        "regime": {"n_tiers": n, "held_out": [tiers[i] for i in test_idx],
+                   "train": [tiers[i] for i in train_idx], "steps": steps, "seed": seed},
+        "auc_heldout": {
+            "control_only": round(auc_control, 4),
+            "best_single_memory": round(auc_best_single, 4),
+            "oracle_ceiling": round(auc_oracle, 4),
+            "learned_router": round(auc_learned, 4),
+        },
+        "best_single_path": PATH_NAMES[best_single_path],
+        "learned_routes_heldout": [PATH_NAMES[p] for p in learned],
+        "oracle_routes_heldout": [PATH_NAMES[p] for p in orc],
+        "lift_over_best_single": {"oracle": round(lift_o, 4), "learned": round(lift_l, 4),
+                                  "learned_fraction_of_oracle_ceiling": round(frac, 3) if frac == frac else None},
+        "verdict": (f"on REAL MQAR held-out tiers the learned router captures "
+                    f"{frac*100:.0f}% of the oracle lift" if frac == frac else
+                    "no oracle lift on held-out tiers (paths do not separate there)"),
+        "note": "D19 Level 1b — router trained/tested on real per-tier MQAR accuracies "
+                "(held-out tiers never seen). Small-N caveat: 12 tiers only; repeat across seeds/holdouts.",
+    }

cortex_c2/router_v2.py

@@ -0,0 +1,109 @@
+"""cortex_c2.router_v2 — the learned soft router (RES-18, ADR-006 D8), Slice B.
+
+Slice A's RouterV1 is an ORACLE: it *reads* the true per-path scores. That is the
+ceiling, not a usable router — at inference there is no label saying "Hopfield
+scores 0.06 here". RouterV2 is the real thing: a small head that **predicts** a
+score per path *from the span context alone*, then routes by weighting. It learns
+by a supervised signal — its predictions must correlate with the performances
+actually observed (the ablation gives those). The central challenge of the whole
+router: route without knowing the answer.
+
+RouterV2 honours the *same* `Router` interface as v1 (retro-compat in action:
+v2 is added, v1 stays; the version dispatch gains one branch). It emits a **soft**
+RouteDecision (a weighted mixture over paths) with a confidence; Slice C turns
+high-confidence decisions into hard routing and wires the breaker fallback.
+
+The control floor (RES-18) is preserved: the predicted-best path is used only if
+it clears the control's predicted score by a margin; else the mixture is pulled
+toward the control. C2 can never be made to degrade the model by the router.
+
+Depends on torch (kept out of cortex_c2/__init__.py so the core stays light).
+"""
+from __future__ import annotations
+
+from typing import Sequence
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from cortex_c2 import (Router, RouteDecision, PATH_CONTROL, PATH_HOPFIELD,
+                       PATH_DELTA, PATH_NAMES)
+
+N_PATHS = 3  # control, hopfield, delta
+
+
+class RouterV2(nn.Module, Router):
+    """A learned gate that predicts per-path scores from a context vector.
+
+    - `ctx_dim`: dimensionality of the span-context feature the router sees.
+    - forward(ctx) -> predicted score per path (b, N_PATHS).
+    - route(span_ctx=<tensor>) -> a soft RouteDecision (weights = softmax over the
+      predicted scores, with the control floor enforced), plus a confidence.
+    - training: `score_loss(ctx, observed)` regresses predictions onto the
+      observed per-path performances (the supervised signal from the ablation).
+
+    Version dispatch: `version = 2`; `Router.load_state` gains its v2 branch in
+    Slice C when v2 carries persistent state. For now v2's "state" is its weights,
+    saved by the normal torch checkpoint — the contract's tag still applies.
+    """
+
+    version = 2
+
+    def __init__(self, ctx_dim: int = 32, hidden: int = 64,
+                 floor_margin: float = 0.0, temperature: float = 1.0):
+        nn.Module.__init__(self)
+        self.ctx_dim = ctx_dim
+        self.floor_margin = floor_margin
+        self.temperature = temperature
+        self.net = nn.Sequential(
+            nn.Linear(ctx_dim, hidden),
+            nn.GELU(),
+            nn.Linear(hidden, N_PATHS),
+        )
+
+    # -- prediction ----------------------------------------------------------
+    def forward(self, ctx: torch.Tensor) -> torch.Tensor:
+        """ctx: (b, ctx_dim) -> predicted per-path score (b, N_PATHS)."""
+        return self.net(ctx)
+
+    # -- the Router contract -------------------------------------------------
+    def route(self, *, span_ctx=None, path_scores: Sequence[float] | None = None,
+              state: dict | None = None) -> RouteDecision:
+        """Route from the *predicted* scores. span_ctx is the context feature
+        (a tensor of shape (ctx_dim,) or (1, ctx_dim)); path_scores is ignored
+        (v2 predicts, it does not read the truth — that was v1's oracle)."""
+        if span_ctx is None:
+            return RouteDecision(path=PATH_CONTROL, confidence=1.0)  # floor
+        ctx = span_ctx if span_ctx.dim() == 2 else span_ctx.unsqueeze(0)
+        with torch.no_grad():
+            pred = self.forward(ctx).squeeze(0)          # (N_PATHS,)
+        # control floor: a memory competes only if it clears control + margin
+        adj = pred.clone()
+        control = pred[PATH_CONTROL]
+        for p in (PATH_HOPFIELD, PATH_DELTA):
+            if pred[p] <= control + self.floor_margin:
+                adj[p] = float("-inf")                    # remove from the mixture
+        weights = F.softmax(adj / self.temperature, dim=-1)
+        best = int(torch.argmax(weights).item())
+        # confidence = how peaked the mixture is (max weight, rescaled)
+        conf = float((weights.max() - 1.0 / N_PATHS) / (1.0 - 1.0 / N_PATHS))
+        conf = max(0.0, min(1.0, conf))
+        return RouteDecision(path=best, confidence=conf,
+                             weights=weights.tolist())
+
+    # -- training signal -----------------------------------------------------
+    def score_loss(self, ctx: torch.Tensor, observed: torch.Tensor) -> torch.Tensor:
+        """MSE between predicted and observed per-path scores.
+
+        ctx      : (b, ctx_dim)
+        observed : (b, N_PATHS) — the true per-path performances for those spans
+                   (from the ablation / online measurement). This is how the
+                   router learns to predict which path wins, from context alone.
+        """
+        pred = self.forward(ctx)
+        return F.mse_loss(pred, observed)
+
+
+def make_router_v2(ctx_dim: int = 32, **kw) -> RouterV2:
+    return RouterV2(ctx_dim=ctx_dim, **kw)