cortexm 0.3.0__py3-none-any.whl

cortexm/bench/harness.py

@@ -0,0 +1,211 @@
+"""BEAM-style harness runner.
+
+Protocol (mirrors the plan's Phase 2 "Proof of God" benchmark):
+  1. Generate a seeded synthetic conversation at bucket scale
+     (128K / 500K / 1M / 10M estimated tokens).
+  2. Ingest under the μ=0 protocol — zero LLM calls, asserted.
+  3. Probe with questions across the 10 BEAM abilities.
+  4. Score with the deterministic nugget judge (offline, reproducible).
+  5. Compare against BM25-RAG and vector-only baselines.
+  6. Report per-ability accuracy, ingest throughput, storage, latency,
+     and trust metrics (provenance completeness, audit latency, cost).
+
+A pluggable LLM reader/judge slot (canonical protocol: gpt-5 reader +
+judge) is exposed via ``llm_judge=None``; the deterministic judge keeps
+the whole harness honest and free.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from cortexm import metrics
+from cortexm.api.memory import Memory
+from cortexm.bench.abilities import (ABILITY_NAMES, ABILITIES, build_probes,
+                                       judge)
+from cortexm.bench.baselines import BM25Index, bm25_context, vector_only_context
+from cortexm.bench.generator import generate
+
+
+@dataclass
+class BucketResult:
+    bucket: str
+    n_questions: int = 0
+    per_ability: dict = field(default_factory=dict)
+    per_system: dict = field(default_factory=dict)
+    ingest: dict = field(default_factory=dict)
+    corpus: dict = field(default_factory=dict)
+    trust: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "bucket": self.bucket, "n_questions": self.n_questions,
+            "per_ability": self.per_ability, "per_system": self.per_system,
+            "ingest": self.ingest, "corpus": self.corpus, "trust": self.trust,
+        }
+
+
+def run_bucket(bucket: str, seed: int = 42, systems=("context_m", "vector_only", "bm25"),
+               db_path: str = ":memory:", max_probes: int | None = None,
+               llm_judge=None) -> BucketResult:
+    res = BucketResult(bucket=bucket)
+    t0 = time.time()
+    corpus = generate(bucket, seed=seed)
+    res.corpus = {
+        "sessions": len(corpus.sessions),
+        "personas": len(corpus.personas),
+        "estimated_tokens": corpus.total_tokens,
+        "generation_seconds": round(corpus.generation_seconds, 2),
+    }
+
+    from cortexm.config import Config as _Cfg
+    cfg = _Cfg(db_path=db_path) if db_path != ":memory:" else _Cfg()
+    cfg.apply_rules_each_add = False          # bulk mode: Datalog after ingest
+    memory = Memory(cfg)
+    metrics.reset_counters()
+
+    # ---- ingest (μ=0) ----------------------------------------------------
+    t_ingest = time.time()
+    n_msgs = 0
+    for user_id, date, msgs in corpus.sessions:
+        payload = [{"role": role, "content": text, "timestamp": date}
+                   for role, text in msgs]
+        n_msgs += len(msgs)
+        memory.add(payload, user_id=user_id, timestamp=date)
+    n_derived = memory.apply_rules()
+    ingest_s = time.time() - t_ingest
+    stats = memory.stats()
+    res.ingest = {
+        "wall_seconds": round(ingest_s, 2),
+        "messages": n_msgs,
+        "tokens_per_second": int(corpus.total_tokens / max(ingest_s, 1e-9)),
+        "messages_per_second": round(n_msgs / max(ingest_s, 1e-9), 1),
+        "llm_calls": metrics.counters()["llm_calls"],
+        "u0_protocol": stats["u0_protocol"],
+        "facts": stats["facts"],
+        "active_facts": stats["active_facts"],
+        "chunks": stats["chunks"],
+        "commits": stats["commits"],
+        "derived_facts": stats["derived"],
+        "deferred_rule_pass": True,
+    }
+
+    # ---- probes -----------------------------------------------------------
+    probes = build_probes(corpus.personas, __import__("random").Random(seed))
+    by_ability: dict[str, list] = {a: [] for a in ABILITIES}
+    for p in probes:
+        by_ability[p.ability].append(p)
+    if max_probes:
+        for a in ABILITIES:
+            by_ability[a] = by_ability[a][:max_probes]
+    res.n_questions = sum(len(v) for v in by_ability.values())
+
+    # ---- baseline indexes ---------------------------------------------------
+    chunks_by_user: dict[str, list[dict]] = {}
+    for user_id, date, msgs in corpus.sessions:
+        docs = chunks_by_user.setdefault(user_id, [])
+        for i, (role, text) in enumerate(msgs):
+            if len(text) > 12:  # skip tiny interjections
+                docs.append({"id": f"{user_id}:{len(docs)}", "text": text})
+    bm25 = {uid: BM25Index(docs) for uid, docs in chunks_by_user.items()}
+
+    # ---- evaluate ---------------------------------------------------------
+    per_system: dict[str, dict[str, float]] = {s: {a: 0.0 for a in ABILITIES}
+                                               for s in systems}
+    counts = {a: len(by_ability[a]) for a in ABILITIES}
+    details: list[dict] = []
+    latencies = {s: [] for s in systems}
+    provenance_ok = 0
+    provenance_checks = 0
+
+    for ability in ABILITIES:
+        for probe in by_ability[ability]:
+            for system in systems:
+                t_q = time.time()
+                if system == "context_m":
+                    out = memory.search(probe.question, user_id=probe.user_id, k=12)
+                    context = out["context_block"]
+                    provenance_checks += 1
+                    if out["provenance"]["verification"]:
+                        provenance_ok += 1
+                elif system == "vector_only":
+                    context = vector_only_context(memory, probe.question,
+                                                  probe.user_id)
+                elif system == "bm25":
+                    context = bm25_context(bm25[probe.user_id], probe.question)
+                latencies[system].append(time.time() - t_q)
+                score_fn = llm_judge if llm_judge else judge
+                score, detail = score_fn(probe, context)
+                per_system[system][ability] += score
+                if system == "context_m":
+                    details.append({"ability": ability,
+                                    "question": probe.question,
+                                    "score": score, "detail": detail,
+                                    "context": context[:400]})
+
+    for system in systems:
+        res.per_system[system] = {
+            "overall": round(sum(per_system[system][a] for a in ABILITIES)
+                             / max(res.n_questions, 1), 4),
+            "per_ability": {
+                a: round(per_system[system][a] / max(counts[a], 1), 4)
+                for a in ABILITIES if counts[a]
+            },
+            "mean_latency_ms": round(
+                sum(latencies[system]) / max(len(latencies[system]), 1) * 1e3, 2),
+        }
+    res.per_ability = res.per_system.get("context_m", {}).get("per_ability", {})
+    res.trust = {
+        "provenance_completeness": round(
+            provenance_ok / max(provenance_checks, 1), 4),
+        "audit_latency_ms": round(
+            sum(latencies.get("context_m", [])) /
+            max(len(latencies.get("context_m", [])), 1) * 1e3, 2),
+        "u0_ingest_llm_calls": metrics.counters()["llm_calls"],
+        "storage": memory.storage_stats(),
+        "hash_provider": stats["hash_provider"],
+        "codec": stats["codec"],
+        "vsa_mode": stats["vsa_mode"],
+        "wall_seconds_total": round(time.time() - t0, 2),
+    }
+    memory.close()
+    res.details = details  # type: ignore[attr-defined]
+    return res
+
+
+def format_report(results: list[BucketResult]) -> str:
+    lines = ["# Context-M — BEAM-Style Benchmark Results", ""]
+    for r in results:
+        lines.append(f"## Bucket: {r.bucket.upper()} "
+                     f"({r.corpus['estimated_tokens']:,} est. tokens, "
+                     f"{r.n_questions} questions)")
+        lines.append("")
+        sys_names = list(r.per_system.keys())
+        header = "| System | Overall | " + " | ".join(ABILITIES) + " |"
+        sep = "|---" * (2 + len(ABILITIES)) + "|"
+        lines.append(header)
+        lines.append(sep)
+        for s in sys_names:
+            d = r.per_system[s]
+            row = [f"**{d['overall']:.1%}**" if s == "context_m" else f"{d['overall']:.1%}"]
+            for a in ABILITIES:
+                v = d["per_ability"].get(a)
+                row.append(f"{v:.0%}" if v is not None else "—")
+            lines.append(f"| {s} | " + " | ".join(row) + " |")
+        lines.append("")
+        lines.append(f"- Ingest: {r.ingest['wall_seconds']}s for "
+                     f"{r.ingest['tokens_per_second']:,} tokens/s "
+                     f"(μ=0: {r.ingest['u0_protocol']}, "
+                     f"{r.ingest['llm_calls']} LLM calls)")
+        lines.append(f"- Memory: {r.ingest['facts']:,} facts / "
+                     f"{r.ingest['chunks']:,} chunks / "
+                     f"{r.ingest['commits']:,} commits "
+                     f"({r.ingest['derived_facts']} derived by Datalog)")
+        lines.append(f"- Provenance completeness: "
+                     f"{r.trust['provenance_completeness']:.1%} | "
+                     f"retrieval latency p50≈{r.trust['audit_latency_ms']}ms")
+        lines.append("")
+    return "\n".join(lines)

cortexm/bench/messy.py

@@ -0,0 +1,218 @@
+"""Messy persona generator — slang / compound sentences / misspellings.
+
+The default ``cortexm.bench.generator`` produces clean, grammatical
+persona messages ("My name is Alice. I work at Google as a software
+engineer."). On that corpus, the μ=0 pattern extractor scores ~1.0
+recall because every fact sits in a clean SVO clause. Unmess + dissim
+have nothing to fix.
+
+This module applies a *messifier* to the same persona timeline:
+- run-on compound sentences stitched with "and" / "so" / "ngl" / "tbh"
+- slang tokens: bruh, ngl, tbh, fr fr, no cap, smh, rn, nvm, wyd, ykwis
+- common misspellings: defo, prolly, kinda, kinda-sorta, tmr, b4, 2
+- text-speak: u / ur / 2 / 4 / k / lol / omg / lmao / rn
+- code-switching: inject "yo", "tbh idk", "ngl that's wild" mid-sentence
+- contraction chains: "I'ma", "I'd've", "shouldn't've"
+- capitalization chaos: drop sentence-initial caps, ALL-CAPS bursts
+- emoji-free but punctuation-sparse: drop periods, use commas instead
+
+The output is intentionally HARD for clean pattern matchers — the
+unmess / dissim / fuzzy / idiolect stack has actual work to do. This
+is what the user asked for ("current synthetic corpus is too clean
+to show the win") so the BEAM numbers actually move when the arxiv
+improvements are toggled on.
+
+Deterministic (seeded). Same persona → same messified text.
+"""
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from cortexm.bench.generator import (
+    Persona, make_persona, _month, SMALLTALK,
+)
+
+
+# slang / filler / discourse markers — injected at clause boundaries
+SLANG_FILLERS = [
+    "ngl", "tbh", "fr fr", "no cap", "lowkey", "highkey", "smh",
+    "rn", "nvm", "wyd", "ykwis", "lowkey", "istg", "bruh", "bro",
+    "ye", "yeah", "ya", "ok so", "anyway", "like", "tbh idk",
+    "ngl that's wild", "ya feel me", "y'know", "like honestly",
+]
+
+# text-speak substitutions (applied via simple regex / str.replace)
+TEXTSPEAK = {
+    "you": "u", "your": "ur", "you're": "ur", "you are": "u r",
+    "to": "2", "too": "2", "for": "4", "before": "b4",
+    "tomorrow": "tmr", "definitely": "defo", "probably": "prolly",
+    "kind of": "kinda", "sort of": "sorta", "give me": "gimme",
+    "let me": "lemme", "want to": "wanna", "going to": "gonna",
+    "got to": "gotta", "out of": "outta", "because": "bc",
+    "don't know": "dk", "i don't know": "idk", "right now": "rn",
+    "with": "w/", "without": "w/o", "people": "ppl", "thanks": "thx",
+    "okay": "k", "ok": "k", "really": "rly", "though": "tho",
+}
+
+# common misspellings applied with low probability per word
+MISSPELLINGS = {
+    "the": "teh", "and": "an", "is": "iz", "my": "mah",
+    "like": "liek", "work": "wrk", "at": "@", "name": "naem",
+    "live": "liv", "sister": "sis", "brother": "bro",
+    "manager": "mgr", "team": "tm", "started": "strt'd",
+}
+
+# discourse markers for compound sentence stitching
+STITCHERS = [
+    "and tbh", "so like", "and ykwis", "ngl", "and then",
+    "and like", "so anyway", "and ya", "but like", "and ok",
+    "so basically", "and honestly", "but fr", "so ngl",
+]
+
+# Casual smalltalk that's even less grammatical
+MESSY_SMALLTALK = [
+    "yo wassup", "ayy hows it goin", "lol ok", "smh not again",
+    "ngl thats wild", "bruh fr??", "ok ok i got u", "ye i feel u",
+    "lol same", "rip", "yooo thats crazy", "ok wait what", "tbh idk man",
+    "ya im here", "eh could be worse", "ok cool cool cool", "ha nice",
+    "ngl kinda tired tbh", "wait gimme a sec", "ya ya sry", "eh whatever",
+]
+
+
+@dataclass
+class MessyCorpus:
+    """Result of messifying — keeps the underlying persona for ground
+    truth comparison. Same shape as the clean persona dict so the
+    existing BEAM benchmark can consume it unchanged."""
+    user_id: str
+    text: str
+    facts: list
+
+
+def _messify_text(text: str, rng: random.Random,
+                  textspeak_p: float = 0.45,
+                  misspell_p: float = 0.10,
+                  filler_p: float = 0.55) -> str:
+    """Apply slang / textspeak / misspellings / fillers to a clean text.
+
+    Probabilities are tuned so the result is recognizable but messy:
+    - textspeak_p: chance per word to apply a text-speak substitution
+    - misspell_p: chance per word to apply a common misspelling
+    - filler_p: chance at each clause boundary to inject a slang filler
+    """
+    if not text:
+        return text
+
+    # 1) text-speak substitutions (word-boundary preserving)
+    out = text
+    for src, dst in TEXTSPEAK.items():
+        if rng.random() < textspeak_p:
+            # case-insensitive replace, preserve first-letter case
+            import re
+            def _sub(m, dst=dst):
+                w = m.group(0)
+                return dst if w.islower() else dst.capitalize()
+            out = re.sub(rf"\b{src}\b", _sub, out, flags=re.IGNORECASE)
+
+    # 2) word-level misspellings
+    words = out.split()
+    out_words = []
+    for w in words:
+        # strip trailing punctuation for lookup, keep it
+        import re as _re
+        m = _re.match(r"^(\W*)(\w+)(\W*)$", w)
+        if not m:
+            out_words.append(w)
+            continue
+        pre, core, post = m.groups()
+        lower = core.lower()
+        if lower in MISSPELLINGS and rng.random() < misspell_p:
+            new_core = MISSPELLINGS[lower]
+            # preserve capitalization of first letter
+            if core[0].isupper():
+                new_core = new_core[:1].upper() + new_core[1:]
+            out_words.append(pre + new_core + post)
+        else:
+            out_words.append(w)
+    out = " ".join(out_words)
+
+    # 3) drop sentence-final periods with some probability (text-style)
+    if rng.random() < 0.6:
+        out = out.replace(".", "")
+        out = out.replace("!", "")
+        out = out.replace("?", "")
+
+    # 4) lowercase sentence-initial letters with some probability
+    if out and rng.random() < 0.5:
+        out = out[0].lower() + out[1:]
+
+    # 5) inject slang fillers at clause boundaries (commas / conjunctions)
+    import re
+    # split keeping delimiters
+    parts = re.split(r"(\s+(?:and|but|so|because|although|while|when|if)\s+)", out)
+    out_parts = []
+    for i, p in enumerate(parts):
+        out_parts.append(p)
+        # if this is a conjunction delimiter and next part is non-empty,
+        # maybe inject a filler after the conjunction
+        if i % 2 == 1 and rng.random() < filler_p:
+            filler = rng.choice(SLANG_FILLERS)
+            out_parts.append(f" {filler} ")
+    out = "".join(out_parts)
+
+    # 6) occasional ALL-CAPS burst on short sentences (≤4 words) for emphasis
+    words_now = out.split()
+    if len(words_now) <= 4 and rng.random() < 0.15:
+        out = out.upper()
+
+    return out.strip()
+
+
+def messify_messages(persona: Persona, rng: random.Random,
+                     session_date, part: int) -> list[tuple[str, str]]:
+    """Run the clean persona_messages generator, then messify each line.
+
+    Returns the same list-of-(role, text) shape, but each text is
+    slang-ified. Ground truth is still derivable from the persona.
+    """
+    from cortexm.bench.generator import persona_messages
+    clean = persona_messages(persona, rng, session_date, part)
+    messy = []
+    for role, text in clean:
+        if role == "user":
+            mtext = _messify_text(text, rng)
+            messy.append((role, mtext))
+        else:
+            messy.append((role, text))
+    # splice in extra messy smalltalk
+    for _ in range(rng.randrange(1, 3)):
+        messy.append(("user", rng.choice(MESSY_SMALLTALK)))
+    return messy
+
+
+def make_messy_persona(rng: random.Random, idx: int, t0) -> Persona:
+    """Same persona generator as the clean one — personas themselves
+    don't need to be messy, only the surface text does."""
+    return make_persona(rng, idx, t0)
+
+
+# Tiny end-to-end demo used by the BEAM bench harness when `--messy` is
+# passed — converts a clean persona dict into a messy one.
+def messify_persona_dict(p: dict, rng: random.Random) -> dict:
+    """Take a {user_id, text, facts} dict from the clean persona
+    generator and produce a messified copy. Facts list is preserved
+    (ground truth unchanged)."""
+    return {
+        "user_id": p["user_id"],
+        "text": _messify_text(p["text"], rng),
+        "facts": p["facts"],
+    }
+
+
+__all__ = [
+    "MessyCorpus", "make_messy_persona", "messify_messages",
+    "messify_persona_dict", "_messify_text",
+    "SLANG_FILLERS", "TEXTSPEAK", "MISSPELLINGS", "STITCHERS",
+    "MESSY_SMALLTALK",
+]

cortexm/bench/micro.py

@@ -0,0 +1,251 @@
+"""Micro-benchmarks — the engineering claims behind the fabric.
+
+  1. Retrieval latency & tree-index recall at 10K/50K/100K vectors
+     (plan milestone: <1ms retrieval on 100K memories)
+  2. Codec ablation: recall@10 vs FP32 brute force + bytes/vector
+     (the cortexm-compress tier table)
+  3. Self-healing memory: recall under bit-flip corruption, with and
+     without TMR, before/after healing (the "Proof of God" demo)
+  4. SLB hit rate & latency under conversational locality replay
+  5. Ingest throughput (tokens/s, facts/s) and μ=0 assertion
+"""
+
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+from cortexm import metrics
+from cortexm.config import Config
+from cortexm.vsa.codecs import make_codec
+from cortexm.vsa.ops import VSA
+from cortexm.text.embedder import HashingEmbedder
+
+
+def _synthetic_corpus(n: int, dims: int = 768, seed: int = 7):
+    """n fact holograms with genuine kNN structure: facts about the same
+    subject share lexical content, so true neighbors = same-subject facts."""
+    rng = np.random.default_rng(seed)
+    emb = HashingEmbedder(dims, seed)
+    vsa = VSA(dims, "perm", seed)
+    n_subj = max(50, n // 40)
+    subjects = [f"Person{i}" for i in range(n_subj)]
+    relations = ["works_at", "lives_in", "prefers", "has_skill", "event"]
+    facts, vecs = [], []
+    for i in range(n):
+        s = subjects[i % n_subj]
+        r = relations[i % len(relations)]
+        v = f"{s}-thing{(i // n_subj) % 40}"
+        facts.append((s, r, v))
+        vecs.append(vsa.encode_fact(emb.embed(s), emb.embed(r), emb.embed(v)))
+    return facts, np.stack(vecs), emb
+
+
+def latency_and_recall():
+    from cortexm.vsa.index import TreeIndex
+
+    out = {}
+    for n in (10_000, 50_000, 100_000):
+        facts, vecs, emb = _synthetic_corpus(n)
+        ids = [f"fact{i}" for i in range(n)]
+        codec = make_codec("int8", 768)
+        packed = np.stack([codec.encode_packed(v) for v in vecs])
+        aux = np.array([codec.encode_scale(v) for v in vecs])
+
+        def getter(rows):
+            return packed[rows], aux[rows]
+
+        # queries: text of a random fact (its own hologram is the target)
+        rng = np.random.default_rng(11)
+        q_idx = rng.choice(n, 100, replace=False)
+        queries = [emb.embed(" ".join(facts[i])) for i in q_idx]
+
+        # brute force ground truth
+        t0 = time.perf_counter()
+        gt, gt_scores = [], []
+        for q in queries:
+            sc = codec.scores(packed, q, aux)
+            top = np.argsort(-sc)[:10]
+            gt.append(set(top.tolist()))
+            gt_scores.append(float(np.sort(sc)[::-1][:10].mean()))
+        flat_ms = (time.perf_counter() - t0) / len(queries) * 1e3
+
+        # tree index
+        t0 = time.perf_counter()
+        idx = TreeIndex(codec, getter, n, branch=8, leaf=512, seed=3)
+        idx.build()
+        build_s = time.perf_counter() - t0
+
+        t0 = time.perf_counter()
+        hits = 0
+        overlap = 0.0
+        quality = 0.0
+        lat = []
+        for q, want, want_score in zip(queries, gt, gt_scores):
+            t1 = time.perf_counter()
+            rows, scores = idx.search(q, 10, beam=8)
+            lat.append(time.perf_counter() - t1)
+            got = set(rows.tolist())
+            if got & want:
+                hits += 1
+            overlap += len(got & want) / 10
+            if len(scores):
+                quality += float(np.sort(scores)[::-1][:10].mean()) / max(want_score, 1e-9)
+        lat = np.array(lat) * 1e3
+        out[f"n={n}"] = {
+            "flat_ms": round(flat_ms, 2),
+            "tree_p50_ms": round(float(np.percentile(lat, 50)), 3),
+            "tree_p99_ms": round(float(np.percentile(lat, 99)), 3),
+            "any_hit@10": round(hits / len(queries), 4),
+            "overlap@10": round(overlap / len(queries), 4),
+            "quality_ratio": round(quality / len(queries), 4),
+            "index_build_s": round(build_s, 2),
+            "rows_scanned_avg": round(idx.leaf_rows_scanned / len(queries), 0),
+        }
+    return out
+
+
+def codec_ablation(n: int = 20_000, k: int = 10):
+    emb = HashingEmbedder(768, 7)
+    vsa = VSA(768, "perm", 7)
+    n_subj = max(50, n // 40)
+    subjects = [f"Person{i}" for i in range(n_subj)]
+    relations = ["works_at", "lives_in", "prefers", "has_skill", "event"]
+    vecs, queries = [], []
+    for i in range(n):
+        s = subjects[i % n_subj]
+        r = relations[i % len(relations)]
+        v = f"{s}-thing{(i // n_subj) % 40}"
+        vecs.append(vsa.encode_fact(emb.embed(s), emb.embed(r), emb.embed(v)))
+        if i % (n // 200) == 0:
+            queries.append((vecs[-1], i))
+    vecs = np.stack(vecs)
+
+    gt = []
+    for q, i in queries:
+        sc = vecs @ q
+        top = np.argsort(-sc)[:k].tolist()
+        gt.append((i, set(top)))
+
+    out = {}
+    for name in ("int8", "binary", "rabitq", "pq"):
+        t0 = time.perf_counter()
+        codec = make_codec(name, 768, seed=7)
+        if name == "pq":
+            codec.train(vecs[: min(n, 4096)])
+        packed = np.stack([codec.encode_packed(v) for v in vecs])
+        enc_s = time.perf_counter() - t0
+        # hologram probes: self-hit + neighborhood preservation vs fp32
+        hits = 0
+        overlap = 0.0
+        shortlist = 0.0
+        t0 = time.perf_counter()
+        if name == "int8":
+            aux = np.array([codec.encode_scale(v) for v in vecs])
+        for (q, i), (self_idx, want) in zip(queries, gt):
+            sc = (codec.scores(packed, q, aux) if name == "int8"
+                  else codec.scores(packed, q))
+            order = np.argsort(-sc)
+            got = order[:k].tolist()
+            if i in got:
+                hits += 1
+            overlap += len(set(got) & want) / k
+            # shortlist usage: fp32 top-10 within codec top-50
+            shortlist += len(set(order[:50].tolist()) & want) / k
+        out[name] = {
+            "bytes_per_vector": codec.bytes_per_vector,
+            "mb_per_million": round(codec.bytes_per_vector, 1),
+            "self_hit@10": round(hits / len(queries), 4),
+            "overlap@10_vs_fp32": round(overlap / len(queries), 4),
+            "recall@10_in_top50": round(shortlist / len(queries), 4),
+            "encode_ms_per_1k": round(enc_s / n * 1000 * 1e3, 2),
+            "query_ms_flat_20k": round((time.perf_counter() - t0) / len(queries) * 1e3, 3),
+        }
+    out["fp32_reference"] = {"bytes_per_vector": 3072, "mb_per_million": 3072.0,
+                             "recall@10": 1.0}
+    return out
+
+
+def self_healing(n: int = 5000):
+    """Recall under corruption — binary HDC tolerance + TMR majority vote.
+
+    Self-identification test: a corrupted hypervector must still rank
+    ITSELF as the nearest neighbor among n stored vectors (HDC's
+    error-correction radius), with and without TMR.
+    """
+    from cortexm.vsa.codecs import BinaryCodec
+
+    emb = HashingEmbedder(768, 7)
+    vsa = VSA(768, "perm", 7)
+    n_subj = max(50, n // 40)
+    subjects = [f"Person{i}" for i in range(n_subj)]
+    vecs = []
+    for i in range(n):
+        s = subjects[i % n_subj]
+        v = f"{s}-thing{(i // n_subj) % 40}"
+        vecs.append(vsa.encode_fact(emb.embed(s), emb.embed("works_at"),
+                                    emb.embed(v)))
+    vecs = np.stack(vecs)
+    q_idx = list(range(0, n, 50))           # 100 probe vectors
+
+    out = {}
+    for tmr in (False, True):
+        codec = BinaryCodec(768, tmr=tmr)
+        packed = np.stack([codec.encode_packed(v) for v in vecs])
+        crng = np.random.default_rng(99)
+        for rate in (0.0, 0.01, 0.05, 0.10, 0.20):
+            corrupted = packed.copy()
+            if rate > 0:
+                for row in q_idx:           # corrupt the probe vectors
+                    corrupted[row] = codec.corrupt(corrupted[row], rate, crng)
+            hits = 0
+            for i in q_idx:
+                sc = codec.scores(corrupted, vecs[i])
+                if int(np.argmax(sc)) == i:
+                    hits += 1
+            out[f"{'tmr' if tmr else 'plain'}@{int(rate*100)}%"] = {
+                "self_identification": round(hits / len(q_idx), 3)}
+    return out
+
+
+def slb_replay(n_queries: int = 400):
+    from cortexm.vsa.slb import SemanticLookasideBuffer
+
+    emb = HashingEmbedder(768, 7)
+    slb = SemanticLookasideBuffer(64, 0.97, 768)
+    rng = np.random.default_rng(3)
+    topics = [f"project {i} status update" for i in range(40)]
+    hit_lat, miss_lat = [], []
+    for i in range(n_queries):
+        # conversational locality: follow-ups repeat the previous topic
+        base = topics[rng.integers(len(topics))]
+        q = emb.embed(base + (" again" if i % 3 else ""))
+        t0 = time.perf_counter()
+        got = slb.lookup(q)
+        if got is not None:
+            hit_lat.append(time.perf_counter() - t0)
+        else:
+            miss_lat.append(time.perf_counter() - t0)
+            slb.store(q, [("f1", 0.5), ("f2", 0.4)])
+    return {
+        "hit_rate": round(slb.hits / n_queries, 3),
+        "avg_hit_latency_us": round(sum(hit_lat) / max(len(hit_lat), 1) * 1e6, 1),
+        "avg_miss_latency_us": round(sum(miss_lat) / max(len(miss_lat), 1) * 1e6, 1),
+    }
+
+
+def run_micro() -> dict:
+    metrics.reset_counters()
+    out = {
+        "latency_recall": latency_and_recall(),
+        "codec_ablation": codec_ablation(),
+        "self_healing": self_healing(),
+        "slb_replay": slb_replay(),
+        "u0_llm_calls": metrics.llm_calls(),
+    }
+    return out
+
+
+if __name__ == "__main__":
+    print(run_micro())