quantum-cortex 1.0.0__py3-none-any.whl

cortex_eval/recurrent_ladder.py

@@ -0,0 +1,159 @@
+"""cortex_eval.recurrent_ladder — the recurrent-family ladder (D19 Level 1c, refined).
+
+The founder's question: "custom GLA vs official Mamba — isn't there an
+intermediate?" — and the answer: the space between them is CONTINUOUS. Mamba is
+the canonical gated linear attention PLUS a stack of documented refinements.
+So instead of one custom GLA or one official Mamba, we build a LADDER: the
+canonical GLA, then each refinement added one at a time behind a flag, each
+re-implemented from its paper (zero borrowed code), each measured. Our own
+ablation discipline (one variable at a time, equal at everything) applied to
+the construction of the reference itself.
+
+The rungs (each credited to the paper that introduced the idea):
+  L0  canonical GLA        S_t = g ⊙ S_{t-1} + k vᵀ ; o = q S           (linear attention lineage)
+  L1  + input-dependent gate  g_t = σ(W_g x_t)  — Mamba's "selectivity" (Gu & Dao 2023)
+  L2  + channel-wise decay    per-channel forget instead of per-head   (Kimi Linear's KDA finding)
+  L3  + short local conv      a depthwise conv on the input before mixing (Mamba / RWKV lineage)
+  L4  + delta-rule write      S += β k (v − Sᵀk)ᵀ with L2-normalised keys (DeltaNet / KDA)
+
+Reading rule (the founder's curve principle): read the CURVE of MQAR accuracy
+vs rung, not one point. Note L4 is exactly our own DeltaMemory — so the top of
+the ladder places our component INSIDE the recurrent family, and "L4 pure" vs
+"our hybrid (L4 + attention)" isolates the contribution of hybridisation.
+
+Claim discipline: we compare to "GLA + <named rungs>", never to "Mamba" — an
+official pre-trained Mamba/RWKV remains a separate, non-equalised external
+reference (a later job, license-checked at ingestion).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+import numpy as np
+
+from cortex_eval.mqar import MQARTier, make_batch
+
+VOCAB = 256 + 8
+
+
+@dataclass
+class Rung:
+    name: str
+    selective_gate: bool = False    # L1
+    channel_decay: bool = False     # L2
+    local_conv: bool = False        # L3
+    delta_rule: bool = False        # L4
+
+
+LADDER = [
+    Rung("L0-canonical-gla"),
+    Rung("L1-+selective-gate", selective_gate=True),
+    Rung("L2-+channel-decay", selective_gate=True, channel_decay=True),
+    Rung("L3-+local-conv", selective_gate=True, channel_decay=True, local_conv=True),
+    Rung("L4-+delta-rule", selective_gate=True, channel_decay=True, local_conv=True, delta_rule=True),
+]
+
+
+def _build(rung: Rung, d_model: int, n_head: int):
+    import torch, torch.nn as nn
+    dk = d_model // n_head
+
+    class RecurrentRung(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.emb = nn.Embedding(VOCAB, d_model)
+            self.ln = nn.LayerNorm(d_model)
+            self.conv = (nn.Conv1d(d_model, d_model, kernel_size=3, padding=2, groups=d_model)
+                         if rung.local_conv else None)                       # L3: depthwise, causal (crop)
+            self.qkv = nn.Linear(d_model, 3 * d_model, bias=False)
+            # gate: constant-per-head (L0) or input-dependent (L1); per-head or per-channel (L2)
+            gate_out = n_head * dk if rung.channel_decay else n_head
+            self.gate = (nn.Linear(d_model, gate_out, bias=True) if rung.selective_gate
+                         else nn.Parameter(torch.zeros(gate_out)))          # L0: learned constant
+            self.beta = nn.Linear(d_model, n_head, bias=True) if rung.delta_rule else None  # L4
+            self.out = nn.Linear(d_model, d_model, bias=False)
+            self.ln2 = nn.LayerNorm(d_model)
+            self.mlp = nn.Sequential(nn.Linear(d_model, 4 * d_model), nn.GELU(),
+                                     nn.Linear(4 * d_model, d_model))
+            self.head = nn.Linear(d_model, VOCAB, bias=False)
+
+        def forward(self, idx):
+            x = self.emb(idx)
+            b, T, c = x.shape
+            z = self.ln(x)
+            if self.conv is not None:                                         # L3
+                z = self.conv(z.transpose(1, 2))[:, :, :T].transpose(1, 2)    # causal crop
+            q, k, v = self.qkv(z).split(c, dim=2)
+            q = torch.nn.functional.normalize(q.view(b, T, n_head, dk), dim=-1)
+            k = torch.nn.functional.normalize(k.view(b, T, n_head, dk), dim=-1)
+            v = v.view(b, T, n_head, dk)
+            if rung.selective_gate:                                           # L1
+                g_raw = torch.sigmoid(self.gate(z))
+            else:                                                             # L0
+                g_raw = torch.sigmoid(self.gate).expand(b, T, -1)
+            if rung.channel_decay:                                            # L2
+                g = g_raw.view(b, T, n_head, dk)
+            else:
+                g = g_raw.view(b, T, n_head, 1).expand(b, T, n_head, dk)
+            beta = torch.sigmoid(self.beta(z)).view(b, T, n_head, 1) if rung.delta_rule else None
+            S = torch.zeros(b, n_head, dk, dk, device=x.device)
+            outs = []
+            for i in range(T):
+                S = S * g[:, i].unsqueeze(2)                                   # forget (columns)
+                if rung.delta_rule:                                           # L4
+                    u = torch.einsum('bhij,bhi->bhj', S, k[:, i])
+                    S = S + beta[:, i].unsqueeze(-1) * torch.einsum('bhi,bhj->bhij', k[:, i], v[:, i] - u)
+                else:                                                         # L0–L3: plain write
+                    S = S + torch.einsum('bhi,bhj->bhij', k[:, i], v[:, i])
+                outs.append(torch.einsum('bhi,bhij->bhj', q[:, i], S).reshape(b, c))
+            o = torch.stack(outs, 1)
+            x = x + self.out(o)
+            x = x + self.mlp(self.ln2(x))
+            return self.head(x)
+
+    return RecurrentRung()
+
+
+def run_rung(rung: Rung, 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) -> float:
+    import torch, torch.nn as nn
+    torch.manual_seed(seed)
+    model = _build(rung, d_model, n_head)
+    opt = torch.optim.AdamW(model.parameters(), lr=lr)
+    for step in range(steps):
+        X, Y = make_batch(tier, batch, seed=seed + step)
+        logits = model(torch.from_numpy(X))
+        loss = nn.functional.cross_entropy(logits.view(-1, VOCAB),
+                                           torch.from_numpy(Y).view(-1), ignore_index=-100)
+        if not torch.isfinite(loss):
+            return float("nan")                     # circuit-breaker spirit
+        opt.zero_grad(); loss.backward()
+        nn.utils.clip_grad_norm_(model.parameters(), 1.0); opt.step()
+    Xe, Ye = make_batch(tier, eval_batch, seed=seed + 10_000)
+    with torch.no_grad():
+        preds = model(torch.from_numpy(Xe)).argmax(-1).numpy()
+    mask = Ye != -100
+    return float((preds[mask] == Ye[mask]).mean())
+
+
+def run_ladder(tiers: list[MQARTier] | None = None, steps: int = 1500, seed: int = 1337,
+               rungs: list[Rung] | None = None, **kw) -> dict:
+    tiers = tiers or [MQARTier(kv_pairs=4, seq_len=128), MQARTier(kv_pairs=8, seq_len=128),
+                      MQARTier(kv_pairs=16, seq_len=128)]
+    rungs = rungs or LADDER
+    curve = []
+    for rung in rungs:
+        accs = [run_rung(rung, t, steps, seed, **kw) for t in tiers]
+        auc = float(np.nanmean(accs)) if any(a == a for a in accs) else float("nan")
+        curve.append({"rung": rung.name, "per_tier": accs, "auc": round(auc, 4)})
+        print(f"[ladder] {rung.name:22s} -> auc={auc:.4f}")
+    return {
+        "benchmark": "recurrent_ladder",
+        "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+        "regime": {"tiers": [(t.kv_pairs, t.seq_len) for t in tiers], "steps": steps, "seed": seed},
+        "curve": curve,
+        "reading": "MQAR AUC vs recurrent refinement rung. L4 (delta-rule, normalised keys) is our own "
+                   "DeltaMemory — the top of the ladder places our component inside the recurrent family; "
+                   "'L4 pure' vs our hybrid isolates hybridisation. Compare to 'GLA + named rungs', never to 'Mamba'.",
+    }

cortex_eval/resumable_ladder.py

@@ -0,0 +1,231 @@
+"""cortex_eval.resumable_ladder — the 8-seed ladder that survives a quota cut.
+
+The lesson of run B (2026-09-09): a run that writes only at the end loses
+everything when Kaggle kills the session. This runner makes the ladder
+**resumable at the unit level**:
+
+  unit = (rung, seed, tier) → one small JSON file, written the moment the unit
+         finishes, in a checkpoint directory.
+
+On start, the runner scans the checkpoint directory (and any *previous*
+checkpoint directories mounted as Kaggle Inputs), loads every finished unit,
+and skips them. A session cut at unit 37 of 80 restarts at unit 38. Nothing is
+ever recomputed; nothing is ever lost.
+
+Kaggle specifics: a killed session loses /kaggle/working, but the Output of the
+previous *version* is retained and can be mounted as an Input of the next
+version. So we READ from every directory in `resume_from` (the mounted Inputs)
+and WRITE to `ckpt_dir` (the current Output). Same pattern as the N1 trainer's
+--resume from an Input-mounted checkpoint.
+
+Time budget: `--time-budget-min` stops cleanly before the quota wall (units
+are small, ~6-10 min each, so the loss at the wall is at most one unit).
+
+When every unit exists, the aggregate (per-rung stats, CIs, paired tests) is
+computed from the unit files — deterministic, reproducible from the units alone.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+
+from cortex_eval.mqar import MQARTier
+from cortex_eval.recurrent_ladder import LADDER, Rung, run_rung
+from cortex_eval.multiseed import _mean_ci, _paired_test
+from cortex_eval.run_mqar import run_curriculum
+
+# The three ARCHITECTURE paths measured alongside the pure ladder, same seeds, same
+# tiers, same steps — so every comparison below is a PAIRED test on identical data.
+ARCH = ("none", "hopfield", "delta")     # control / Hopfield hybrid / delta hybrid
+ARCH_EXTRA = ("none+local-conv",)         # the control plus a local convolution (Rev60): a declared reference, --paths only,
+                                          # never part of the full ladder's 128 units nor of its aggregate
+
+DEFAULT_SEEDS = (1337, 2024, 7, 42, 99, 3, 11, 2026)      # 8 seeds → df 7, t_crit 2.365
+DEFAULT_TIERS = [MQARTier(kv_pairs=16, seq_len=128), MQARTier(kv_pairs=8, seq_len=128)]
+
+
+def unit_id(rung, seed: int, tier: MQARTier) -> str:
+    """rung is a Rung (pure ladder) or a str in ARCH (control / hybrids)."""
+    name = rung.name if isinstance(rung, Rung) else f"ARCH-{rung}"
+    return f"{name}__s{seed}__kv{tier.kv_pairs}_seq{tier.seq_len}"
+
+
+def run_unit(rung, tier: MQARTier, steps: int, seed: int, **kw) -> float:
+    if isinstance(rung, Rung):
+        return run_rung(rung, tier, steps, seed, **kw)
+    if rung == "none+local-conv":                                       # Rev60: the control, one variable added
+        res = run_curriculum(c2_variant="none", attn_local_conv=True, steps=steps, tiers=[tier], seed=seed, **kw)
+        return float(res.per_tier[0]["accuracy"])
+    res = run_curriculum(c2_variant=rung, steps=steps, tiers=[tier], seed=seed, **kw)
+    return float(res.per_tier[0]["accuracy"])
+
+
+def load_done(dirs: list[Path]) -> dict[str, dict]:
+    """Every finished unit across all given directories (later dirs win on duplicates)."""
+    done = {}
+    for d in dirs:
+        if not d or not d.exists():
+            continue
+        for p in sorted(d.glob("unit-*.json")):
+            try:
+                u = json.loads(p.read_text())
+                if u.get("status") == "done" and u.get("accuracy") == u.get("accuracy"):
+                    done[u["unit_id"]] = u
+            except Exception:
+                continue
+    return done
+
+
+def run_resumable_ladder(seeds=DEFAULT_SEEDS, tiers=None, steps: int = 1500,
+                         ckpt_dir: str | Path = "metrics/mqar/ladder8-ckpt",
+                         resume_from: list[str | Path] | None = None,
+                         time_budget_min: float | None = None, paths: list[str] | None = None,
+                         relay: str | None = None, **kw) -> dict:
+    """`paths` (optional): restrict the run to these path names (e.g. the sigma run of
+    the convergence, L3 alone at 3000 steps on the seeds that stayed at the floor).
+    A subset writes its units and a SUBSET aggregate (per path stats, no paired
+    tests against absent paths); the full readout needs all eight paths."""
+    tiers = tiers or DEFAULT_TIERS
+    ckpt = Path(ckpt_dir); ckpt.mkdir(parents=True, exist_ok=True)
+    if relay:                                            # the checkpoint relay: the last push, before anything else
+        import tempfile
+        from cortex_data import relay as _relay
+        pulled = Path(tempfile.mkdtemp(prefix="relay-")) / ckpt.name
+        if _relay.pull(relay, pulled):
+            resume_from = list(resume_from or []) + [pulled]
+    dirs = [Path(p) for p in (resume_from or [])] + [ckpt]
+    done = load_done(dirs)
+    all_paths = list(LADDER) + list(ARCH)
+    if paths:
+        names = {(r.name if isinstance(r, Rung) else f"ARCH-{r}"): r for r in all_paths + list(ARCH_EXTRA)}
+        unknown = [n for n in paths if n not in names]
+        if unknown:
+            raise SystemExit(f"unknown paths {unknown}; known: {sorted(names)}")
+        all_paths = [names[n] for n in paths]
+    units = [(r, s, t) for r in all_paths for s in seeds for t in tiers]
+    todo = [u for u in units if unit_id(*u) not in done]
+    print(f"[resumable] {len(units)} units total, {len(done)} already done, {len(todo)} to run")
+    t0 = time.time()
+    stopped_early = False
+    for rung, seed, tier in todo:
+        if time_budget_min is not None and (time.time() - t0) / 60.0 > time_budget_min:
+            print(f"[resumable] time budget reached — stopping cleanly; rerun to resume")
+            stopped_early = True
+            break
+        uid = unit_id(rung, seed, tier)
+        t1 = time.time()
+        acc = run_unit(rung, tier, steps, seed, **kw)
+        rec = {"unit_id": uid, "rung": rung.name if isinstance(rung, Rung) else f"ARCH-{rung}", "seed": seed, "kv_pairs": tier.kv_pairs,
+               "seq_len": tier.seq_len, "steps": steps, "accuracy": acc,
+               "status": "done" if acc == acc else "diverged",
+               "wall_s": round(time.time() - t1, 1), "written_utc": datetime.now(timezone.utc).isoformat()}
+        (ckpt / f"unit-{uid}.json").write_text(json.dumps(rec) + "\n")   # written THE MOMENT it finishes
+        done[uid] = rec
+        if relay:
+            from cortex_data import relay as _relay
+            _relay.push(ckpt, relay, uid)                                  # small files: a blocking push, seconds
+        print(f"[unit] {uid} -> acc={acc:.4f} ({rec['wall_s']}s)  [{len(done)}/{len(units)}]")
+    complete = all(unit_id(*u) in done for u in units)
+    result = {"benchmark": "recurrent_ladder_8seed_resumable",
+              "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+              "regime": {"seeds": list(seeds), "n_seeds": len(seeds), "steps": steps,
+                         "tiers": [(t.kv_pairs, t.seq_len) for t in tiers]},
+              "units_done": len(done), "units_total": len(units), "complete": complete,
+              "stopped_early": stopped_early}
+    if complete and paths:
+        result["subset"] = list(paths)
+        result["stats"] = {}
+        for r in all_paths:
+            name = r.name if isinstance(r, Rung) else f"ARCH-{r}"
+            vals = [float(np.mean([done[unit_id(r, s, t)]["accuracy"] for t in tiers])) for s in seeds]
+            per_tier = {f"kv{t.kv_pairs}": [done[unit_id(r, s, t)]["accuracy"] for s in seeds] for t in tiers}
+            result["stats"][name] = {**_mean_ci(vals), "per_seed": vals, "per_tier": per_tier}
+        tag = "-".join(paths).replace("+", "").replace("/", "")[:40]
+        (ckpt / f"SUBSET-{tag}-{steps}steps.json").write_text(json.dumps(result, indent=2) + "\n")
+        print(f"[resumable] COMPLETE (subset {paths}) — per path stats written; no paired tests on a subset")
+    elif complete:
+        result.update(aggregate(done, seeds, tiers))
+        (ckpt / "LATEST-ladder8.json").write_text(json.dumps(result, indent=2) + "\n")
+        print("[resumable] COMPLETE — aggregate written")
+    else:
+        (ckpt / "PROGRESS-ladder8.json").write_text(json.dumps(result, indent=2) + "\n")
+        print(f"[resumable] incomplete ({len(done)}/{len(units)}) — progress written; rerun with this dir as Input to resume")
+    return result
+
+
+def aggregate(done: dict, seeds, tiers) -> dict:
+    """Per-rung AUC per seed (mean over tiers), then stats + paired tests. Deterministic
+    from the unit files alone — re-runnable offline on the committed units."""
+    per_rung: dict[str, list[float]] = {}
+    for r in LADDER:
+        vals = []
+        for s in seeds:
+            accs = [done[unit_id(r, s, t)]["accuracy"] for t in tiers]
+            vals.append(float(np.mean(accs)))
+        per_rung[r.name] = vals
+    per_arch: dict[str, list[float]] = {}
+    for a in ARCH:
+        vals = []
+        for s in seeds:
+            accs = [done[unit_id(a, s, t)]["accuracy"] for t in tiers]
+            vals.append(float(np.mean(accs)))
+        per_arch[a] = vals
+    stats = {r: _mean_ci(v) for r, v in {**per_rung, **{f"ARCH-{a}": v for a, v in per_arch.items()}}.items()}
+    best_pure = max(per_rung, key=lambda r: np.mean(per_rung[r]))
+    n = len(seeds)
+    tests = {
+        "hopfield_hybrid_vs_best_pure": _paired_test(per_arch["hopfield"], per_rung[best_pure]),
+        "delta_hybrid_vs_best_pure":    _paired_test(per_arch["delta"],    per_rung[best_pure]),
+        "control_vs_best_pure":         _paired_test(per_arch["none"],     per_rung[best_pure]),
+        "hopfield_vs_control":          _paired_test(per_arch["hopfield"], per_arch["none"]),
+        "delta_vs_control":             _paired_test(per_arch["delta"],    per_arch["none"]),
+        "L4_vs_L3":                     _paired_test(per_rung["L4-+delta-rule"], per_rung["L3-+local-conv"]),
+    }
+    gate = {k: bool(v.get("significant_95")) and n >= 3 for k, v in tests.items()}
+    return {"per_rung_per_seed": per_rung, "per_arch_per_seed": per_arch, "stats": stats,
+            "best_pure_rung": best_pure, "paired_tests": tests, "gate_readout": gate,
+            "note": "every test is paired on seed at identical steps/tiers; gated = significant at 95% with >= 3 seeds."}
+
+
+def _cli():
+    ap = argparse.ArgumentParser(description="Resumable 8-seed recurrent ladder")
+    ap.add_argument("--steps", type=int, default=1500)
+    ap.add_argument("--seeds", type=int, nargs="+", default=list(DEFAULT_SEEDS))
+    ap.add_argument("--ckpt-dir", default="metrics/mqar/ladder8-ckpt")
+    ap.add_argument("--resume-from", nargs="*", default=[],
+                    help="previous checkpoint dirs (e.g. Kaggle Inputs) whose finished units are reused")
+    ap.add_argument("--time-budget-min", type=float, default=None)
+    ap.add_argument("--paths", nargs="*", default=None,
+                    help="restrict to these path names (e.g. L3-+local-conv for the sigma run)")
+    ap.add_argument("--tiers", nargs="*", default=None, help="restrict to these tiers as KVxSEQ (e.g. 8x128 for the tier where L3 takes off); a subset aggregate, never a paired claim across tiers")
+    ap.add_argument("--relay", default=None, help="checkpoint relay: a private Kaggle dataset slug pulled before the resume lookup and pushed after every unit")
+    ap.add_argument("--quick", action="store_true")
+    args = ap.parse_args()
+    tiers = parse_tiers(args.tiers)
+    if args.quick:
+        run_resumable_ladder(seeds=(1, 2), tiers=tiers or [MQARTier(kv_pairs=4, seq_len=32)], steps=40,
+                             ckpt_dir=args.ckpt_dir, resume_from=args.resume_from, d_model=32, paths=args.paths, relay=args.relay)
+    else:
+        run_resumable_ladder(seeds=tuple(args.seeds), tiers=tiers, steps=args.steps, ckpt_dir=args.ckpt_dir,
+                             resume_from=args.resume_from, time_budget_min=args.time_budget_min, paths=args.paths, relay=args.relay)
+
+
+def parse_tiers(spec):
+    """'8x128 16x128' -> [MQARTier(8, 128), MQARTier(16, 128)]; None -> None (the default tiers)."""
+    if not spec:
+        return None
+    out = []
+    for s in spec:
+        kv, seq = s.lower().split("x")
+        out.append(MQARTier(kv_pairs=int(kv), seq_len=int(seq)))
+    return out
+
+
+if __name__ == "__main__":
+    _cli()

cortex_eval/resumable_rb.py

@@ -0,0 +1,207 @@
+"""cortex_eval.resumable_rb -- the recurrent base hybrid run, resumable (Rev38; declared before the run).
+
+64 units = 4 arms (bare, critical, cls, cls-phi) x 8 seeds x 2 tiers, at the
+ladder's 1500 steps, each written the moment it finishes. The references are
+NOT retrained: the 8 seed ladder's units (`metrics/mqar/ladder8-ckpt/`) give L3
+pure and the transformer control at the same seeds, tiers and steps, so every
+comparison is paired on seed on identical data.
+
+The readout, declared 2026-09-12 before any unit ran:
+  per arm: mean full accuracy (mean over tiers per seed), trunk only accuracy,
+           take off rate (trunk only at 8 pairs >= 0.3), the 16 pair mean, the
+           consolidation gap, the gate at the end;
+  paired tests (95 %, n >= 3): each arm's full model vs L3 pure; each arm's full
+           model vs the control; each arm's trunk only vs L3 pure (did the base
+           keep or gain its take off?); cls-phi vs cls (phi against 1/2).
+  gated = significant at 95 %; a bimodal comparator gets its reserve written
+           next to the number, as for the ladder.
+No number here is a result until the units exist and the log is read cold.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+
+from cortex_eval.mqar import MQARTier
+from cortex_eval.multiseed import _mean_ci, _paired_test
+from cortex_eval.recurrent_base import ARMS, ARM_BY_NAME, RBArm, run_rb_unit
+from cortex_eval.resumable_ladder import DEFAULT_SEEDS, DEFAULT_TIERS, load_done
+
+REF_L3, REF_CONTROL = "L3-+local-conv", "ARCH-none"
+REF_CONTROL_CONV = "ARCH-none+local-conv"      # the control plus a local convolution (Rev60), a declared reference
+
+
+def rb_unit_id(arm: RBArm, seed: int, tier: MQARTier) -> str:
+    return f"{arm.name}__s{seed}__kv{tier.kv_pairs}_seq{tier.seq_len}"
+
+
+def ref_unit_id(name: str, seed: int, tier: MQARTier) -> str:
+    return f"{name}__s{seed}__kv{tier.kv_pairs}_seq{tier.seq_len}"
+
+
+def run_resumable_rb(seeds=DEFAULT_SEEDS, tiers=None, steps: int = 1500, relay: str | None = None, latest_name: str = "LATEST-rb.json",
+                     ckpt_dir: str | Path = "metrics/mqar/rb-ckpt",
+                     resume_from: list[str | Path] | None = None,
+                     reference_from: list[str | Path] | None = None,
+                     time_budget_min: float | None = None, arms: list[str] | None = None, **kw) -> dict:
+    tiers = tiers or DEFAULT_TIERS
+    ckpt = Path(ckpt_dir); ckpt.mkdir(parents=True, exist_ok=True)
+    if relay:                                            # the checkpoint relay: the last push, before anything else
+        import tempfile
+        from cortex_data import relay as _relay
+        pulled = Path(tempfile.mkdtemp(prefix="relay-")) / ckpt.name
+        if _relay.pull(relay, pulled):
+            resume_from = list(resume_from or []) + [pulled]
+    done = load_done([Path(p) for p in (resume_from or [])] + [ckpt])
+    refs = load_done([Path(p) for p in (reference_from or [])])
+    chosen = [ARM_BY_NAME[a] for a in arms] if arms else list(ARMS)
+    units = [(a, s, t) for a in chosen for s in seeds for t in tiers]
+    todo = [u for u in units if rb_unit_id(*u) not in done]
+    print(f"[resumable-rb] {len(units)} units total, {len(done)} already done, {len(todo)} to run; "
+          f"{len(refs)} reference units loaded")
+    t0 = time.time(); stopped_early = False
+    for arm, seed, tier in todo:
+        if time_budget_min is not None and (time.time() - t0) / 60.0 > time_budget_min:
+            print("[resumable-rb] time budget reached \u2014 stopping cleanly; rerun to resume")
+            stopped_early = True
+            break
+        uid = rb_unit_id(arm, seed, tier)
+        t1 = time.time()
+        r = run_rb_unit(arm, tier, steps, seed, **kw)
+        rec = {"unit_id": uid, "rung": arm.name, "arm": arm.name, "seed": seed, "kv_pairs": tier.kv_pairs,
+               "seq_len": tier.seq_len, "steps": steps, **r,
+               "wall_s": round(time.time() - t1, 1), "written_utc": datetime.now(timezone.utc).isoformat()}
+        (ckpt / f"unit-{uid}.json").write_text(json.dumps(rec) + "\n")   # written the moment it finishes
+        done[uid] = rec
+        if relay:
+            from cortex_data import relay as _relay
+            _relay.push(ckpt, relay, uid)
+        print(f"[unit] {uid} -> acc={r['accuracy']:.4f} trunk={r.get('accuracy_trunk_only', float('nan')):.4f} "
+              f"gate={r.get('gate_final')} ({rec['wall_s']}s)  [{len(done)}/{len(units)}]")
+    complete = all(rb_unit_id(*u) in done for u in units)
+    result = {"benchmark": "recurrent_base_hybrid_resumable", "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+              "regime": {"seeds": list(seeds), "n_seeds": len(seeds), "steps": steps,
+                         "tiers": [(t.kv_pairs, t.seq_len) for t in tiers], "arms": [a.name for a in chosen],
+                         "arm_hashes": {a.name: a.config_hash() for a in chosen}},
+              "units_done": len(done), "units_total": len(units), "complete": complete, "stopped_early": stopped_early}
+    if complete:
+        result.update(aggregate(done, refs, chosen, seeds, tiers))
+        (ckpt / latest_name).write_text(json.dumps(result, indent=2) + "\n")
+        print(f"[resumable-rb] COMPLETE \u2014 aggregate written ({latest_name})")
+    else:
+        (ckpt / "PROGRESS-rb.json").write_text(json.dumps(result, indent=2) + "\n")
+        print(f"[resumable-rb] incomplete ({len(done)}/{len(units)}) \u2014 progress written; rerun with this dir as Input")
+    return result
+
+
+def aggregate(done: dict, refs: dict, arms, seeds, tiers) -> dict:
+    """Deterministic from the unit files alone; references from the ladder8 units."""
+    kv8 = [t for t in tiers if t.kv_pairs == 8]
+    kv16 = [t for t in tiers if t.kv_pairs == 16]
+    per_full, per_trunk, stats = {}, {}, {}
+    for a in arms:
+        full = [float(np.mean([done[rb_unit_id(a, s, t)]["accuracy"] for t in tiers])) for s in seeds]
+        trunk = [float(np.mean([done[rb_unit_id(a, s, t)]["accuracy_trunk_only"] for t in tiers])) for s in seeds]
+        per_full[a.name], per_trunk[a.name] = full, trunk
+        st = {"full": _mean_ci(full), "trunk_only": _mean_ci(trunk),
+              "take_off_rate": (float(np.mean([done[rb_unit_id(a, s, t)]["took_off"] for s in seeds for t in kv8])) if kv8 else None),
+              "kv16_mean": (float(np.mean([done[rb_unit_id(a, s, t)]["accuracy"] for s in seeds for t in kv16])) if kv16 else None),
+              "gap_mean": float(np.mean([done[rb_unit_id(a, s, t)]["consolidation_gap"] for s in seeds for t in tiers])),
+              "gate_final_mean": float(np.mean([done[rb_unit_id(a, s, t)]["gate_final"] for s in seeds for t in tiers]))}
+        stats[a.name] = st
+    tests, missing = {}, []
+    def ref_values(name):
+        try:
+            return [float(np.mean([refs[ref_unit_id(name, s, t)]["accuracy"] for t in tiers])) for s in seeds]
+        except KeyError:
+            missing.append(name); return None
+    l3, ctrl = ref_values(REF_L3), ref_values(REF_CONTROL)
+    for a in arms:
+        if l3 is not None:
+            tests[f"{a.name}_full_vs_L3"] = _paired_test(per_full[a.name], l3)
+            tests[f"{a.name}_trunk_vs_L3"] = _paired_test(per_trunk[a.name], l3)
+        if ctrl is not None:
+            tests[f"{a.name}_full_vs_control"] = _paired_test(per_full[a.name], ctrl)
+    if "RB-cls-phi" in per_full and "RB-cls" in per_full:
+        tests["RB-cls-phi_vs_RB-cls"] = _paired_test(per_full["RB-cls-phi"], per_full["RB-cls"])
+    gate = {k: ("gated" if (v.get("significant_95") and len(seeds) >= 3) else "held") for k, v in tests.items()}
+    return {"stats": stats, "per_seed": {"full": per_full, "trunk_only": per_trunk},
+            "references": {"L3": l3, "control": ctrl, "missing": sorted(set(missing))},
+            "paired_tests": tests, "gate_readout": gate,
+            "note": "paired on seed at identical steps/tiers against the ladder8 units; gated = significant at 95% with >= 3 seeds; "
+                    "a bimodal comparator (L3) gets its reserve written next to the number."}
+
+
+def control_conv_readout(refs: dict, done: dict, arms, seeds, tiers) -> dict:
+    """Rev60, declared before the run: the control plus a local convolution against
+    the control (does the convolution lift the two layer transformer), against L3
+    pure (does it reach the recurrent trunk's level) and against each measured arm's
+    full accuracy (does the arm add anything beyond a convolved transformer). Paired
+    on seed at identical steps and tier; gated = significant at 95 % with >= 3 seeds.
+    Deterministic from the unit files alone."""
+    def ref_values(name):
+        return [float(np.mean([refs[ref_unit_id(name, s, t)]["accuracy"] for t in tiers])) for s in seeds]
+    cc, ctrl, l3 = ref_values(REF_CONTROL_CONV), ref_values(REF_CONTROL), ref_values(REF_L3)
+    tests = {"control_conv_vs_control": _paired_test(cc, ctrl), "control_conv_vs_L3": _paired_test(cc, l3)}
+    per_full = {}
+    for a in arms:
+        try:
+            per_full[a.name] = [float(np.mean([done[rb_unit_id(a, s, t)]["accuracy"] for t in tiers])) for s in seeds]
+        except KeyError:
+            continue
+        tests[f"{a.name}_full_vs_control_conv"] = _paired_test(per_full[a.name], cc)
+    gate = {k: ("gated" if (v.get("significant_95") and len(seeds) >= 3) else "held") for k, v in tests.items()}
+    return {"benchmark": "control_plus_local_conv_readout", "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+            "regime": {"seeds": list(seeds), "n_seeds": len(seeds), "tiers": [(t.kv_pairs, t.seq_len) for t in tiers]},
+            "stats": {REF_CONTROL_CONV: _mean_ci(cc), REF_CONTROL: _mean_ci(ctrl), REF_L3: _mean_ci(l3)},
+            "per_seed": {REF_CONTROL_CONV: cc, REF_CONTROL: ctrl, REF_L3: l3, "arms_full": per_full},
+            "paired_tests": tests, "gate_readout": gate,
+            "note": "Rev60: the readings were declared before the run; a subset readout, paired on seed at identical steps and tier"}
+
+
+def _cli():
+    ap = argparse.ArgumentParser(description="Resumable recurrent base hybrid run (4 arms)")
+    ap.add_argument("--steps", type=int, default=1500)
+    ap.add_argument("--seeds", type=int, nargs="+", default=list(DEFAULT_SEEDS))
+    ap.add_argument("--arms", nargs="*", default=None, help=f"subset of {[a.name for a in ARMS]}")
+    ap.add_argument("--ckpt-dir", default="metrics/mqar/rb-ckpt")
+    ap.add_argument("--resume-from", nargs="*", default=[])
+    ap.add_argument("--reference-from", nargs="*", default=["metrics/mqar/ladder8-ckpt"],
+                    help="dirs holding the ladder8 units (L3 pure and the control at the same seeds/tiers/steps)")
+    ap.add_argument("--time-budget-min", type=float, default=None)
+    ap.add_argument("--tiers", nargs="*", default=None, help="restrict to these tiers as KVxSEQ (e.g. 8x128 for the tier where L3 takes off); a subset aggregate, never a paired claim across tiers")
+    ap.add_argument("--relay", default=None, help="checkpoint relay: a private Kaggle dataset slug pulled before the resume lookup and pushed after every unit")
+    ap.add_argument("--quick", action="store_true")
+    ap.add_argument("--latest-name", default="LATEST-rb.json",
+                    help="the aggregate's file name in --ckpt-dir (Rev62: a 16 seed aggregate next to the 8 seed one, never over it)")
+    ap.add_argument("--control-conv-readout", default=None, metavar="OUT",
+                    help="Rev60: no training; read the control plus convolution units from --reference-from and the arms from "
+                         "--ckpt-dir, compute the declared paired tests, write them to OUT")
+    args = ap.parse_args()
+    from cortex_eval.resumable_ladder import parse_tiers
+    tiers = parse_tiers(args.tiers)
+    if args.control_conv_readout:
+        refs = load_done([Path(p) for p in args.reference_from])
+        done = load_done([Path(p) for p in args.resume_from] + [Path(args.ckpt_dir)])
+        arms = [ARM_BY_NAME[n] for n in (args.arms or [a.name for a in ARMS])]
+        r = control_conv_readout(refs, done, arms, tuple(args.seeds), tiers or list(DEFAULT_TIERS))
+        out = Path(args.control_conv_readout); out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(r, indent=2) + "\n")
+        print(out); print(json.dumps({k: r[k] for k in ("stats", "paired_tests", "gate_readout")}, indent=1))
+        return
+    if args.quick:
+        run_resumable_rb(seeds=(1, 2), tiers=tiers or [MQARTier(kv_pairs=4, seq_len=32)], steps=40, ckpt_dir=args.ckpt_dir,
+                         resume_from=args.resume_from, reference_from=args.reference_from, arms=args.arms, d_model=32, relay=args.relay)
+    else:
+        run_resumable_rb(seeds=tuple(args.seeds), tiers=tiers, steps=args.steps, ckpt_dir=args.ckpt_dir, resume_from=args.resume_from,
+                         reference_from=args.reference_from, time_budget_min=args.time_budget_min, arms=args.arms, relay=args.relay,
+                         latest_name=args.latest_name)
+
+
+if __name__ == "__main__":
+    _cli()