quantum-cortex 1.0.0__py3-none-any.whl

cortex_eval/ingest_confirmation.py

@@ -0,0 +1,194 @@
+"""cortex_eval.ingest_confirmation — grave the confirmation result in one command.
+
+Reads the REAL `metrics/mqar/LATEST-confirmation.json` (the Kaggle output — the
+record of truth), applies the whitepaper's admission gate to each comparison,
+and updates three documents mechanically, never inventing a number:
+
+  1. docs/RESULTS.md      — rows 10 (delta vs control) and a new row for Hopfield
+                            vs control get their real numbers and a status from the
+                            fixed vocabulary: gated (passes) / held (not established)
+  2. docs/WHITEPAPER.md   — §4.4's table is rewritten from the artefact; the
+                            prose states which rows pass, in the same register
+  3. metrics/mqar/domain-map.* — regenerated (domain_map.py reads the artefact)
+
+Gate applied here (rules 1 and 5 of the six; the others are properties of the
+run, already satisfied or stated): a comparison is **gated** iff the paired
+t-test over seeds is significant at 95% AND n_seeds >= 3; otherwise **held**.
+The reserve line is written for every row, passing or not.
+
+Usage:   python -m cortex_eval.ingest_confirmation            # after committing the artefact
+         python -m cortex_eval.ingest_confirmation --dry-run  # print what would change
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+ART = REPO / "metrics" / "mqar" / "LATEST-confirmation.json"
+RESULTS = REPO / "docs" / "RESULTS.md"
+WP = REPO / "docs" / "WHITEPAPER.md"
+
+
+def _status(test: dict, n_seeds: int) -> str:
+    return "gated" if (test.get("significant_95") and n_seeds >= 3) else "held"
+
+
+def read_artefact(path: Path = ART) -> dict:
+    r = json.loads(path.read_text())
+    seeds = r["regime"]["seeds"]; n = len(seeds)
+    pt = r["c2_ablation"]["paired_tests"]; st = r["c2_ablation"]["stats"]
+    rows = {}
+    for key, a, b in (("hopfield_vs_control", "hopfield", "none"),
+                      ("delta_vs_control", "delta", "none"),
+                      ("delta_vs_hopfield", "delta", "hopfield")):
+        # the artefact may name the third comparison the other way round
+        # (multiseed.py writes "hopfield_vs_delta"); accept both, flip the sign.
+        if key in pt:
+            t = dict(pt[key])
+        else:
+            rev = "_vs_".join(reversed(key.split("_vs_")))
+            if rev not in pt:
+                raise KeyError(f"artefact has neither {key!r} nor {rev!r}")
+            t = dict(pt[rev])
+            t["mean_diff"] = -t["mean_diff"]
+            if t.get("t") is not None:
+                t["t"] = -t["t"]
+        rows[key] = {
+            "a": a, "b": b, "mean_a": st[a]["mean"], "mean_b": st[b]["mean"],
+            "diff": t["mean_diff"], "t": t.get("t"), "df": t.get("df"),
+            "t_crit": t.get("t_crit_95"), "sig": bool(t.get("significant_95")),
+            "status": _status(t, n),
+            "pct": (t["mean_diff"] / st[b]["mean"] * 100) if st[b]["mean"] else None,
+        }
+    hyb = r.get("hybrid_vs_pure", {})
+    lad = r.get("recurrent_ladder", {})
+    return {
+        "seeds": seeds, "n_seeds": n, "steps": r["regime"]["steps"],
+        "tiers": r["regime"]["tiers"], "rows": rows,
+        "per_seed": r["c2_ablation"]["per_seed_auc"],
+        "hybrid_vs_pure": hyb, "ladder_L4_vs_L3": lad.get("L4_vs_L3"),
+        "gate_readout": r.get("gate_readout", {}),
+    }
+
+
+# ---------------------------------------------------------------------------- #
+# RESULTS.md                                                                     #
+# ---------------------------------------------------------------------------- #
+def _results_row(n: int, stmt: str, status: str, number: str, artefact: str, test: str, reserve: str) -> str:
+    return f"| {n} | {stmt} | **{status}** | {number} | `{artefact}` | `{test}` | {reserve} |"
+
+
+def update_results(a: dict, dry: bool = False) -> str:
+    t = RESULTS.read_text(encoding="utf-8")
+    n, steps, tiers = a["n_seeds"], a["steps"], a["tiers"]
+    tiers_s = ", ".join(f"kv{kv}/seq{sq}" for kv, sq in tiers)
+    art = "metrics/mqar/LATEST-confirmation.json"
+    d = a["rows"]["delta_vs_control"]; h = a["rows"]["hopfield_vs_control"]
+    def num(x):
+        return (f"{x['diff']:+.4f} ({x['pct']:+.0f}%), {n}/{n} seeds' mean {x['mean_a']:.4f} vs {x['mean_b']:.4f}, "
+                f"t = {x['t']} vs t_crit {x['t_crit']} (df {x['df']})")
+    def reserve(x):
+        return (f"{n} seeds, {steps} steps, tiers {tiers_s}; " +
+                ("passes rules 1–6 at this regime" if x["status"] == "gated" else
+                 "visible signal, not established at this seed count"))
+    new_delta = _results_row(10, f"Delta > control on the discriminating tiers, {n} seeds", d["status"], num(d),
+                             art, "tests/test_multiseed.py", reserve(d))
+    new_hop = _results_row("10b", f"Hopfield > control on the discriminating tiers, {n} seeds", h["status"], num(h),
+                           art, "tests/test_multiseed.py", reserve(h))
+    # replace row 10 (whatever its current text) and insert 10b after it
+    lines = t.splitlines()
+    out = []; done = False
+    for l in lines:
+        if l.startswith("| 10 |") and not done:
+            out.append(new_delta); out.append(new_hop); done = True
+        elif l.startswith("| 10b |"):
+            continue
+        else:
+            out.append(l)
+    t2 = "\n".join(out) + "\n"
+    # gate status line
+    gated = [k for k, v in a["rows"].items() if v["status"] == "gated" and k != "delta_vs_hopfield"]
+    stamp = datetime.now(timezone.utc).date().isoformat()
+    line = (f"**Gate status (whitepaper §2.6):** as of {stamp}, **{len(gated)}** comparison(s) have passed the six-rule gate"
+            + (f" — {', '.join(gated)}" if gated else "") +
+            f" (confirmation run: {n} seeds, {steps} steps).")
+    t2 = re.sub(r"\*\*Gate status \(whitepaper §2\.6\):\*\*[^\n]*", line, t2, count=1)
+    if not dry:
+        RESULTS.write_text(t2, encoding="utf-8")
+    return t2
+
+
+# ---------------------------------------------------------------------------- #
+# WHITEPAPER §4.4                                                                 #
+# ---------------------------------------------------------------------------- #
+def update_whitepaper(a: dict, dry: bool = False) -> str:
+    t = WP.read_text(encoding="utf-8")
+    start = t.index("**4.4 What passes the gate")
+    end = t.index("**4.5 ")
+    n, steps = a["n_seeds"], a["steps"]
+    tiers_s = " and ".join(f"kv {kv} at seq {sq}" for kv, sq in a["tiers"])
+    R = a["rows"]
+    def row(label, x):
+        verdict = "**passes**" if x["status"] == "gated" else "does not pass"
+        return f"| {label} | **{x['diff']:+.4f}** ({x['pct']:+.0f}%) | {x['t']} | {x['t_crit']} | {verdict} |"
+    table = "\n".join([
+        "| comparison | mean gap | paired t (df = %d) | t_crit 95%% | verdict |" % (n - 1),
+        "|:--|--:|--:|--:|:--|",
+        row("delta vs control", R["delta_vs_control"]),
+        row("Hopfield vs control", R["hopfield_vs_control"]),
+        row("delta vs Hopfield", R["delta_vs_hopfield"]),
+    ])
+    gated = [k for k, v in R.items() if v["status"] == "gated" and k != "delta_vs_hopfield"]
+    per = a["per_seed"]
+    ps = "; ".join(f"{k}: " + " / ".join(f"{v:.3f}" for v in vals) for k, vals in per.items())
+    if gated:
+        names = " and ".join(k.replace("_vs_control", "") for k in gated)
+        prose = (f"At {n} seeds the critical value falls to {R['delta_vs_control']['t_crit']}, and **{names} now pass{'es' if len(gated)==1 else ''} the gate**: "
+                 f"the comparison{'s' if len(gated)>1 else ''} enter{'s' if len(gated)==1 else ''} §4.3 as a claim on the discriminating regime. "
+                 f"Per-seed AUC ({ps}). The remaining rows are held as visible signal.")
+    else:
+        prose = (f"No comparison passes at {n} seeds (per-seed AUC: {ps}). The signal is held, not claimed; "
+                 f"rule 6 asks which context factor the inter-seed variance carries before a larger run is scheduled.")
+    new = (f"**4.4 What passes the gate — the confirmation run ({n} seeds, {steps} steps, tiers {tiers_s}).**\n\n"
+           f"{table}\n\n{prose}\n\n")
+    t2 = t[:start] + new + t[end:]
+    if not dry:
+        WP.write_text(t2, encoding="utf-8")
+    return new
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--artefact", default=str(ART))
+    ap.add_argument("--expect-seeds", type=int, default=None,
+                    help="refuse to write unless the artefact has exactly this many seeds "
+                         "(guards against ingesting the wrong run — lesson of 2026-09-09)")
+    args = ap.parse_args()
+    a = read_artefact(Path(args.artefact))
+    if args.expect_seeds is not None and a["n_seeds"] != args.expect_seeds and not args.dry_run:
+        raise SystemExit(f"refusing to write: artefact has {a['n_seeds']} seeds, expected {args.expect_seeds} "
+                         f"(is this the right run? see metrics/mqar/PROVENANCE-confirmation.json)")
+    print(f"=== confirmation artefact: {a['n_seeds']} seeds, {a['steps']} steps, tiers {a['tiers']} ===")
+    for k, x in a["rows"].items():
+        print(f"  {k:22s} diff {x['diff']:+.4f}  t={x['t']}  crit={x['t_crit']}  -> {x['status'].upper()}")
+    if a["ladder_L4_vs_L3"]:
+        print(f"  ladder L4 vs L3: {a['ladder_L4_vs_L3']}")
+    print()
+    r = update_results(a, dry=args.dry_run)
+    w = update_whitepaper(a, dry=args.dry_run)
+    if args.dry_run:
+        print("--- would write to WHITEPAPER §4.4 ---\n" + w)
+        print("--- RESULTS.md gate line ---")
+        print([l for l in r.splitlines() if l.startswith("**Gate status")][0])
+    else:
+        print("RESULTS.md and WHITEPAPER.md §4.4 updated. Now regenerate the domain map:")
+        print("  python -m cortex_eval.domain_map")
+
+
+if __name__ == "__main__":
+    main()

cortex_eval/mqar.py

@@ -0,0 +1,122 @@
+"""cortex_eval.mqar — Multi-Query Associative Recall, by difficulty tiers.
+
+The canonical probe for associative memory (Arora et al. 2023, the Zoology
+lineage; validated as the C2 judge by Kimi Linear's KDA experiments, which
+sweep sequence length 256→2048 and report the *curve*, not a point).
+Re-implemented from scratch (the paper's format is simple); zero dependency.
+
+Format (Arora): a sequence  [k1,v1, ..., kn,vn, SEP, q1, ..., qm]  where each
+query qj repeats an earlier key kj, and the model must emit the associated vj.
+
+The founder's principle (2026-09-06): never measure at a single point that may
+be flat — sweep a difficulty scale and read the CURVE. Difficulty rises on two
+axes Kimi documents: number of kv pairs and sequence length. An architecture is
+characterised by *where its curve drops off*; the gap between two architectures'
+drop-off points is the clean signal (never flat, because we always read the
+regime where they separate). This also calibrates the (a)->(b) bridge: the tiers
+tell us at which difficulty to expect signal before probing a language model.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+
+# Reserved control tokens live at the top of the byte vocab (0..255); MQAR keys
+# and values are drawn from a symbol range that leaves a SEP slot free.
+SEP = 255  # separator symbol (distinct from keys/values below)
+
+
+@dataclass
+class MQARTier:
+    """One difficulty tier."""
+    kv_pairs: int
+    seq_len: int
+    n_symbols: int = 128        # key/value alphabet size (< SEP)
+    n_queries: int | None = None  # default = kv_pairs (query every key once)
+
+    def queries(self) -> int:
+        return self.n_queries if self.n_queries is not None else self.kv_pairs
+
+
+def make_batch(tier: MQARTier, batch: int, seed: int) -> tuple[np.ndarray, np.ndarray]:
+    """Generate an MQAR batch → (inputs, targets), both int64 (b, T).
+
+    targets are -100 (ignore) everywhere except at query positions, where they
+    hold the value associated with that query's key. This matches a standard
+    cross-entropy-with-ignore training/eval setup.
+    """
+    rng = np.random.default_rng(seed)
+    k = tier.kv_pairs
+    q = tier.queries()
+    # layout length: 2*k (pairs) + 1 (SEP) + q (queries). Pad/truncate to seq_len.
+    core = 2 * k + 1 + q
+    T = max(tier.seq_len, core)
+    X = np.zeros((batch, T), dtype=np.int64)
+    Y = np.full((batch, T), -100, dtype=np.int64)
+
+    for b in range(batch):
+        # distinct keys, random values (values may repeat across keys)
+        keys = rng.choice(tier.n_symbols, size=k, replace=False)
+        vals = rng.integers(0, tier.n_symbols, size=k)
+        kv = {int(keys[i]): int(vals[i]) for i in range(k)}
+
+        pos = 0
+        for i in range(k):
+            X[b, pos] = keys[i]; pos += 1
+            X[b, pos] = vals[i]; pos += 1
+        X[b, pos] = SEP; pos += 1
+        # choose which keys to query (with repetition allowed → "multi-query")
+        qkeys = rng.choice(keys, size=q, replace=True)
+        for j in range(q):
+            X[b, pos] = int(qkeys[j])
+            Y[b, pos] = kv[int(qkeys[j])]   # supervise the answer at the query slot
+            pos += 1
+        # remaining positions (if T > core) stay zero, targets stay ignore
+    return X, Y
+
+
+def standard_curriculum() -> list[MQARTier]:
+    """The tier ladder (Kimi/Zoology regime): kv ∈ {4,8,16,32}, seq ∈ {128,256,512}.
+    Easy tiers give non-zero signal even for the vanilla control (avoids the
+    flat-zero); hard tiers separate the architectures.
+    """
+    tiers = []
+    for seq in (128, 256, 512):
+        for kv in (4, 8, 16, 32):
+            tiers.append(MQARTier(kv_pairs=kv, seq_len=seq))
+    return tiers
+
+
+def accuracy(logits_at_queries: np.ndarray, targets_at_queries: np.ndarray) -> float:
+    """Exact-match accuracy over query positions. Inputs are already gathered
+    at query slots: preds (N,) argmax and targets (N,)."""
+    if len(targets_at_queries) == 0:
+        return float("nan")
+    return float((logits_at_queries == targets_at_queries).mean())
+
+
+@dataclass
+class MQARResult:
+    """The deliverable is the curve: accuracy per tier."""
+    per_tier: list[dict] = field(default_factory=list)
+
+    def add(self, tier: MQARTier, acc: float):
+        self.per_tier.append({"kv_pairs": tier.kv_pairs, "seq_len": tier.seq_len, "accuracy": acc})
+
+    def dropoff_kv(self, threshold: float = 0.5) -> int | None:
+        """The kv level (at the smallest seq_len) where accuracy first drops
+        below threshold — a scalar summary of *where the curve breaks*."""
+        by_seq = min((t["seq_len"] for t in self.per_tier), default=None)
+        if by_seq is None:
+            return None
+        row = sorted((t for t in self.per_tier if t["seq_len"] == by_seq),
+                     key=lambda t: t["kv_pairs"])
+        for t in row:
+            if t["accuracy"] < threshold:
+                return t["kv_pairs"]
+        return None  # never dropped below threshold in this range
+
+    def as_dict(self) -> dict:
+        return {"per_tier": self.per_tier, "dropoff_kv_@0.5": self.dropoff_kv()}

cortex_eval/multiseed.py

@@ -0,0 +1,148 @@
+"""cortex_eval.multiseed — make N2 unattackable (D19 Level 1a).
+
+A single-seed result is an anecdote. This module runs the C2 ablation across N
+seeds and reports, per variant: mean AUC, standard deviation, and a 95%
+confidence interval — then tests whether the gaps (hopfield vs control, delta vs
+control) are STATISTICALLY SIGNIFICANT. That is the difference between
+"Hopfield +14%" and "Hopfield +14% ± 3%, p < 0.05".
+
+Statistics kept simple and honest (from scratch, no scipy dependency):
+  - CI 95% via the t-distribution for small N (t critical values tabulated).
+  - Significance via a paired comparison across seeds (same seed → same data
+    order for all variants, so pairing is legitimate): a paired t-test on the
+    per-seed AUC differences. We report the t statistic and whether |t| exceeds
+    the two-sided 95% critical value — a claim only when it does.
+Honest-data rule: every seed's curve is stored; nothing is dropped.
+"""
+from __future__ import annotations
+
+import json
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+
+from cortex_eval.mqar import MQARTier, standard_curriculum
+from cortex_eval.run_mqar import run_curriculum
+
+VARIANTS = ("none", "hopfield", "delta")
+
+# two-sided 95% t critical values by degrees of freedom (df = n-1)
+_T95 = {1: 12.706, 2: 4.303, 3: 3.182, 4: 2.776, 5: 2.571, 6: 2.447,
+        7: 2.365, 8: 2.306, 9: 2.262, 10: 2.228, 15: 2.131, 20: 2.086, 30: 2.042}
+
+
+def _t95(df: int) -> float:
+    if df in _T95:
+        return _T95[df]
+    keys = sorted(_T95)
+    for k in keys:
+        if k >= df:
+            return _T95[k]
+    return 1.96
+
+
+def _auc(curve: list[dict]) -> float:
+    accs = [t["accuracy"] for t in curve if t["accuracy"] == t["accuracy"]]
+    return float(np.mean(accs)) if accs else float("nan")
+
+
+def _mean_ci(values: list[float]) -> dict:
+    v = np.asarray(values, dtype=float)
+    n = len(v)
+    mean = float(v.mean())
+    sd = float(v.std(ddof=1)) if n > 1 else 0.0
+    half = _t95(n - 1) * sd / math.sqrt(n) if n > 1 else float("nan")
+    return {"mean": round(mean, 4), "sd": round(sd, 4),
+            "ci95": [round(mean - half, 4), round(mean + half, 4)] if n > 1 else None,
+            "n": n}
+
+
+def _paired_test(a: list[float], b: list[float]) -> dict:
+    """Paired t-test on per-seed differences a - b. Returns t, df, significant@95%."""
+    d = np.asarray(a, dtype=float) - np.asarray(b, dtype=float)
+    n = len(d)
+    if n < 2:
+        return {"mean_diff": round(float(d.mean()), 4), "t": None, "df": n - 1,
+                "significant_95": None, "note": "need ≥2 seeds"}
+    md = float(d.mean()); sd = float(d.std(ddof=1))
+    t = md / (sd / math.sqrt(n)) if sd > 1e-12 else float("inf")
+    crit = _t95(n - 1)
+    return {"mean_diff": round(md, 4), "t": round(t, 3), "df": n - 1,
+            "t_crit_95": crit, "significant_95": bool(abs(t) > crit)}
+
+
+def run_multiseed(seeds: list[int], steps: int = 1500,
+                  tiers: list[MQARTier] | None = None, **kw) -> dict:
+    tiers = tiers or standard_curriculum()
+    per_seed: dict[str, list[float]] = {v: [] for v in VARIANTS}
+    curves: dict[str, list[list[dict]]] = {v: [] for v in VARIANTS}
+    for s in seeds:
+        for v in VARIANTS:
+            res = run_curriculum(c2_variant=v, steps=steps, tiers=tiers, seed=s, **kw)
+            per_seed[v].append(_auc(res.per_tier))
+            curves[v].append(res.per_tier)          # every curve stored, nothing dropped
+        print(f"[multiseed] seed={s}  " + "  ".join(f"{v}={per_seed[v][-1]:.4f}" for v in VARIANTS))
+
+    stats = {v: _mean_ci(per_seed[v]) for v in VARIANTS}
+    tests = {
+        "hopfield_vs_control": _paired_test(per_seed["hopfield"], per_seed["none"]),
+        "delta_vs_control": _paired_test(per_seed["delta"], per_seed["none"]),
+        "hopfield_vs_delta": _paired_test(per_seed["hopfield"], per_seed["delta"]),
+    }
+    # honest verdict: a claim only where the paired test is significant
+    claims = []
+    for name, tst in tests.items():
+        if tst.get("significant_95"):
+            sign = "+" if tst["mean_diff"] > 0 else ""
+            claims.append(f"{name}: {sign}{tst['mean_diff']} AUC (t={tst['t']}, df={tst['df']}) — significant at 95%")
+        else:
+            claims.append(f"{name}: {tst['mean_diff']} AUC — NOT significant at 95% (t={tst.get('t')})")
+    return {
+        "benchmark": "mqar_multiseed",
+        "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+        "regime": {"seeds": seeds, "n_seeds": len(seeds), "steps": steps, "tiers": len(tiers)},
+        "per_seed_auc": per_seed,
+        "stats": stats,
+        "paired_tests": tests,
+        "claims": claims,
+        "curves_per_seed": curves,
+        "note": "D19 Level 1a — the single-seed N2 result made statistical. Paired tests are legitimate "
+                "because the same seed fixes the data order across variants. A gap is claimed only when "
+                "significant at 95%; otherwise reported as not significant (honest data).",
+    }
+
+
+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"mqar-multiseed-{stamp}.json"
+    path.write_text(json.dumps(result, indent=2) + "\n")
+    (out / "LATEST-multiseed.json").write_text(json.dumps(result, indent=2) + "\n")
+    return path
+
+
+def _cli():
+    import argparse
+    ap = argparse.ArgumentParser(description="Multi-seed C2 ablation with CIs (D19 Level 1a)")
+    ap.add_argument("--seeds", type=int, nargs="+", default=[1337, 2024, 7, 42, 99])
+    ap.add_argument("--steps", type=int, default=1500)
+    ap.add_argument("--out", default="metrics/mqar")
+    ap.add_argument("--quick", action="store_true")
+    args = ap.parse_args()
+    tiers = [MQARTier(kv_pairs=4, seq_len=64), MQARTier(kv_pairs=16, seq_len=64)] if args.quick else None
+    steps = 300 if args.quick else args.steps
+    r = run_multiseed(args.seeds, steps=steps, tiers=tiers)
+    p = write_artefact(r, args.out)
+    print("\n=== multi-seed stats ===")
+    for v, st in r["stats"].items():
+        print(f"  {v:9s}: mean {st['mean']}  sd {st['sd']}  CI95 {st['ci95']}  (n={st['n']})")
+    print("=== claims ===")
+    for c in r["claims"]:
+        print("  ", c)
+    print(f"artefact: {p}")
+
+
+if __name__ == "__main__":
+    _cli()

cortex_eval/recurrent_base.py

@@ -0,0 +1,197 @@
+"""cortex_eval.recurrent_base -- the recurrent base hybrid family (register Rev38; hypotheses, no result yet).
+
+The 8 seed ladder (2026-09-12) showed two regimes: the pure recurrent rung with a
+local convolution (L3) takes off on 5 seeds out of 8 at 8 key value pairs
+(0.47 to 0.67) and stays at the floor at 16; the transformer control and the
+transformer based hybrids are stable around 0.09 and win at 16 pairs. The
+founder's frame inverts the hybridisation: L3 as the BASE, the attention as the
+ADDED path, zero initialised, taken only where it beats the recurrent. The risk
+named before any code: the attention learns the easy solution first and the
+recurrent never takes off (pre emption), as in the transformer based hybrids.
+
+Four arms, declared before the run, one variable at a time:
+
+  bare      the added attention open from step zero, no protection -- the base
+            line, and the direct measure of pre emption.
+  critical  the critical period (founder): the attention's gate stays closed
+            until the trunk's training loss plateaus (a measured criterion, not a
+            step count), then opens. Until it opens the arm IS L3, to the update.
+  cls       complementary learning systems (the assistant's design): the
+            attention learns immediately (the fast system); a consolidation
+            term trains the trunk only prediction to reproduce the full model's
+            prediction (the replay teaches the slow system); where the trunk
+            alone reaches the full model, the gate retracts geometrically (the
+            fast trace fades). Ratios: retraction 1/2 per phase, attention width
+            1/2 of the model.
+  cls-phi   the same with phi where a ratio is needed: retraction 1/phi,
+            attention width 1/phi^2 (0.382) of the model. A declared arm against
+            the 1/2 control -- nowhere else does phi enter.
+
+Every unit records the full model's accuracy (the paired comparisons), the trunk
+only accuracy (did the base take off?), the consolidation gap, the gate at the
+end, and when the gate opened or retracted. Written from scratch (our filon).
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, asdict
+
+import numpy as np
+
+from cortex_data import _hash_obj
+from cortex_eval.mqar import MQARTier, make_batch
+from cortex_eval.recurrent_ladder import LADDER, Rung, VOCAB, _build
+
+PHI = (1.0 + 5 ** 0.5) / 2.0
+L3 = next(r for r in LADDER if r.name == "L3-+local-conv")
+
+
+@dataclass(frozen=True)
+class RBArm:
+    name: str
+    mode: str                      # bare | critical | cls
+    retraction: float = 0.5        # gate multiplier per retraction (cls)
+    attn_frac: float = 0.5         # attention inner width as a fraction of d_model
+    plateau_window: int = 100      # critical: loss window (steps)
+    plateau_tol: float = 0.01      # critical: relative improvement under which the gate opens
+    plateau_min_steps: int = 200   # critical: never before
+    consolidation_weight: float = 1.0   # cls: weight of the replay term
+    retract_every: int = 100       # cls: phase length (steps)
+    takeoff_threshold: float = 0.3      # trunk only accuracy that counts as a take off
+    gap_epsilon: float = 0.02      # cls: retract when full - trunk only < epsilon (and the trunk took off)
+
+    def config_hash(self) -> str:
+        return _hash_obj(asdict(self))
+
+
+ARMS = [
+    RBArm("RB-bare", "bare"),
+    RBArm("RB-critical", "critical"),
+    RBArm("RB-cls", "cls", retraction=0.5, attn_frac=0.5),
+    RBArm("RB-cls-phi", "cls", retraction=1.0 / PHI, attn_frac=1.0 / PHI ** 2),
+]
+ARM_BY_NAME = {a.name: a for a in ARMS}
+
+
+def _build_rb(arm: RBArm, d_model: int, n_head: int, seed: int):
+    """The trunk is built FIRST, under the seed, so its parameters are exactly a
+    standalone L3's (the no op law is testable to the bit); the attention path
+    draws its parameters after."""
+    import torch, torch.nn as nn
+    torch.manual_seed(seed)
+    trunk = _build(L3, d_model, n_head)
+    attn_dim = max(n_head, int(round(arm.attn_frac * d_model)) // n_head * n_head)
+
+    class RecurrentBaseHybrid(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.trunk = trunk
+            self.ln_a = nn.LayerNorm(d_model)
+            self.qkv = nn.Linear(d_model, 3 * attn_dim, bias=False)
+            self.proj = nn.Linear(attn_dim, d_model, bias=False)
+            nn.init.zeros_(self.proj.weight)                  # the no op law: at init the model is L3
+            self.register_buffer("gate", torch.tensor(1.0 if arm.mode != "critical" else 0.0))
+            self.n_head, self.dk = n_head, attn_dim // n_head
+
+        def trunk_hidden(self, idx):
+            """The recurrent trunk up to its residual (the expensive scan), shared by
+            the full and the trunk only paths."""
+            t = self.trunk
+            x = t.emb(idx)
+            b, T, c = x.shape
+            z = t.ln(x)
+            z = t.conv(z.transpose(1, 2))[:, :, :T].transpose(1, 2)
+            q, k, v = t.qkv(z).split(c, dim=2)
+            nh, dk = n_head, c // n_head
+            q = torch.nn.functional.normalize(q.view(b, T, nh, dk), dim=-1)
+            k = torch.nn.functional.normalize(k.view(b, T, nh, dk), dim=-1)
+            v = v.view(b, T, nh, dk)
+            g = torch.sigmoid(t.gate(z)).view(b, T, nh, dk)
+            S = torch.zeros(b, nh, dk, dk, device=x.device)
+            outs = []
+            for i in range(T):
+                S = S * g[:, i].unsqueeze(2)
+                S = S + torch.einsum('bhi,bhj->bhij', k[:, i], v[:, i])
+                outs.append(torch.einsum('bhi,bhij->bhj', q[:, i], S).reshape(b, c))
+            return x + t.out(torch.stack(outs, 1))
+
+        def attention(self, h):
+            b, T, _ = h.shape
+            q, k, v = self.qkv(self.ln_a(h)).split(self.n_head * self.dk, dim=2)
+            q = q.view(b, T, self.n_head, self.dk).transpose(1, 2)
+            k = k.view(b, T, self.n_head, self.dk).transpose(1, 2)
+            v = v.view(b, T, self.n_head, self.dk).transpose(1, 2)
+            att = (q @ k.transpose(-2, -1)) * self.dk ** -0.5
+            mask = torch.tril(torch.ones(T, T, dtype=torch.bool, device=h.device))
+            att = att.masked_fill(~mask, float("-inf")).softmax(-1)
+            return self.proj((att @ v).transpose(1, 2).reshape(b, T, self.n_head * self.dk))
+
+        def forward(self, idx, gate=None):
+            """Returns (full logits, trunk only logits). The trunk is computed once;
+            the two paths differ by the gated attention term only."""
+            g = self.gate if gate is None else torch.as_tensor(float(gate))
+            t = self.trunk
+            h = self.trunk_hidden(idx)
+            trunk_only = t.head(h + t.mlp(t.ln2(h)))
+            if float(g) == 0.0:
+                return trunk_only, trunk_only
+            hf = h + g * self.attention(h)
+            full = t.head(hf + t.mlp(t.ln2(hf)))
+            return full, trunk_only
+
+    return RecurrentBaseHybrid()
+
+
+def _acc(model, tier: MQARTier, seed: int, batch: int, which: str) -> float:
+    import torch
+    Xe, Ye = make_batch(tier, batch, seed=seed)
+    with torch.no_grad():
+        full, trunk = model(torch.from_numpy(Xe))
+        preds = (full if which == "full" else trunk).argmax(-1).numpy()
+    mask = Ye != -100
+    return float((preds[mask] == Ye[mask]).mean())
+
+
+def run_rb_unit(arm: RBArm, tier: MQARTier, steps: int, seed: int, d_model: int = 64, n_head: int = 2,
+                batch: int = 32, lr: float = 3e-3, eval_batch: int = 64) -> dict:
+    """One unit: the arm on one tier, one seed. Same data, same optimiser, same
+    steps as the pure ladder, so the paired comparison against L3 is exact."""
+    import torch, torch.nn as nn
+    model = _build_rb(arm, d_model, n_head, seed)
+    opt = torch.optim.AdamW(model.parameters(), lr=lr)
+    losses, opened_at, retractions = [], None, []
+    for step in range(steps):
+        X, Y = make_batch(tier, batch, seed=seed + step)
+        idx, tgt = torch.from_numpy(X), torch.from_numpy(Y)
+        full, trunk = model(idx)
+        loss = nn.functional.cross_entropy(full.view(-1, VOCAB), tgt.view(-1), ignore_index=-100)
+        if arm.mode == "cls" and float(model.gate) > 0.0:
+            # the replay: the trunk alone learns the full model's prediction at the queries
+            m = (tgt != -100)
+            teacher = full.detach()[m].softmax(-1)
+            student = trunk[m].log_softmax(-1)
+            loss = loss + arm.consolidation_weight * nn.functional.kl_div(student, teacher, reduction="batchmean")
+        if not torch.isfinite(loss):
+            return {"accuracy": float("nan"), "status": "diverged"}
+        opt.zero_grad(); loss.backward()
+        nn.utils.clip_grad_norm_(model.parameters(), 1.0); opt.step()
+        losses.append(float(loss.detach()))
+        # the critical period: open the gate when the trunk's loss has plateaued
+        if arm.mode == "critical" and opened_at is None and step + 1 >= max(arm.plateau_min_steps, 2 * arm.plateau_window):
+            w = arm.plateau_window
+            recent, before = np.mean(losses[-w:]), np.mean(losses[-2 * w:-w])
+            if before - recent < arm.plateau_tol * before:
+                model.gate.fill_(1.0); opened_at = step + 1
+        # the retraction: where the trunk alone has caught up, the fast trace fades
+        if arm.mode == "cls" and (step + 1) % arm.retract_every == 0 and float(model.gate) > 1e-3:
+            af = _acc(model, tier, seed + 20_000, eval_batch, "full")
+            at = _acc(model, tier, seed + 20_000, eval_batch, "trunk")
+            if at >= arm.takeoff_threshold and af - at < arm.gap_epsilon:
+                model.gate.mul_(arm.retraction); retractions.append(step + 1)
+    acc_full = _acc(model, tier, seed + 10_000, eval_batch, "full")
+    acc_trunk = _acc(model, tier, seed + 10_000, eval_batch, "trunk")
+    return {"accuracy": acc_full, "accuracy_trunk_only": acc_trunk,
+            "consolidation_gap": round(acc_full - acc_trunk, 4),
+            "took_off": bool(acc_trunk >= arm.takeoff_threshold),
+            "gate_final": round(float(model.gate), 4), "opened_at": opened_at, "retractions": retractions,
+            "arm_hash": arm.config_hash(), "status": "done"}