@hviana/sema 0.6.0 → 0.7.2

package/test/89-completion-recursion.test.mjs

@@ -0,0 +1,230 @@
+// 89-completion-recursion.test.mjs — the completion recursion must be
+// OUTPUT-SENSITIVE.
+//
+// AGENTS §2.8: "No per-query read may grow with the corpus."  §2.8 enforces
+// that per READ (nextFirst, bytesPrefix, …), and every one of those caps holds.
+// What no guard covered is the NUMBER of reads: `recompleteNode`
+// (src/mind/graph-search.ts) re-covers a produced node by calling `solve`
+// recursively, and each nested solve builds its own agenda and chart.  Its own
+// doc states the intent —
+//
+//     "its cost tracks the ANSWER's own structure, not how densely the corpus
+//      interconnects the nodes passed through"
+//
+// — but argues termination from "Distinct node ids are finite and each finished
+// completion is memoised".  Finite-in-the-corpus is exactly the bound §2.8
+// forbids, and the recursion is emitted at `cost: 0` while the nested cover's
+// own `cost` is computed and discarded, so A* has no gradient against depth.
+//
+// MEASURED on a trained store (18,938,834 nodes, edgeSourceCount 796,528):
+// `respond("Hi")` reached recursion depth 331 and 9.1 GB RSS in 56 s without
+// terminating.  Every level was a "Hi…" opener — a 2-byte hub re-entering
+// itself — and the descent visited whole utterances unrelated to the answer
+// ("Who's their goalkeeper?", "Glad I could assist, have a great day.").  That
+// is what killed a 5 h training run at a checkpoint recall: the 15 s
+// withTimeout around it is a setTimeout, and a synchronous search never yields
+// to the timer phase, so it cannot fire.
+//
+// WHY THE EXISTING GUARD MISSES IT.  14-scaling.test.mjs asserts this same law
+// ("inference: cost is sublinear in corpus size"), but builds each size point
+// from a DISJOINT salted corpus and queries it with `unknownInput()`, whose
+// "tokens are substrings of no learned form".  A query that recognises nothing
+// never enters the graph, so it never reaches the fixpoint that gates the
+// recursion.  Both assumptions are load-bearing; this file drops them.
+//
+// THE CORPUS.  Real English fragments taken from the repo's own *.md prose and
+// recombined, plus the query deposited as a standalone context with several
+// continuations (what makes a greeting a hub in real dialogue).  Eight
+// hand-written generators failed to reproduce this — chains stop after two
+// rungs, dense graphs never reach a fixpoint, and a query the pipeline declines
+// never reaches `cover` at all.  Real prose plus a deposited hub does it.
+// Nothing is added to the tree: the corpus is the documentation already here.
+//
+// MEASURED HERE, on the deterministic public counters (mind.lastCost), answer
+// byte-identical at every size:
+//
+//        pairs   searches      pops     maxDepth
+//         1508        126    55,208           71
+//         2008        196    88,241          127
+//         3008        309   146,282          207
+//         4008        416   201,174          270      (22 s for a 3-byte query)
+//
+//   growth exponent k ≈ 1.25 (searches), 1.32 (pops) — SUPER-linear.
+//
+// With the recursion bounded, the same corpus gives searches 10→13 and pops
+// 3,946→5,826 (k ≈ 0.27 / 0.40) in 0.31 s→0.76 s, and the answer does not
+// change.  So this file's thresholds are achievable, and the fix costs nothing
+// in output on this corpus.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// ── corpus ────────────────────────────────────────────────────────────────
+// Deterministic scrambler: the suite forbids Math.random in fixtures, and the
+// whole point of the counters is that two runs are diffable.
+const mix = (x) => {
+  x = (x ^ 61) ^ (x >>> 16);
+  x = x + (x << 3);
+  x = x ^ (x >>> 4);
+  x = Math.imul(x, 0x27d4eb2d);
+  return (x ^ (x >>> 15)) >>> 0;
+};
+
+/** Four-word windows of the repo's own English prose.  Code fences, inline
+ *  code and link targets are stripped so what is left is language, which is
+ *  where the fragment overlap lives. */
+function fragments() {
+  const out = [];
+  for (const f of readdirSync(REPO).filter((f) => f.endsWith(".md")).sort()) {
+    let t = readFileSync(join(REPO, f), "utf8");
+    t = t.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ");
+    t = t.replace(/\[[^\]]*\]\([^)]*\)/g, " ");
+    t = t.toLowerCase().replace(/[^a-z ]+/g, " ").replace(/\s+/g, " ");
+    const w = t.split(" ").filter(Boolean);
+    for (let i = 0; i + 4 < w.length; i += 2) {
+      out.push(w.slice(i, i + 4).join(" "));
+    }
+  }
+  return out;
+}
+
+const FRAG = fragments();
+const QUERY = "hi.";
+
+const utter = (i) =>
+  [
+    FRAG[mix(i * 3 + 1) % FRAG.length],
+    FRAG[mix(i * 5 + 2) % FRAG.length],
+    FRAG[mix(i * 7 + 3) % FRAG.length],
+  ].join(" ");
+
+/** n recombined utterance pairs, plus the query as a standalone context with
+ *  eight distinct continuations — the hub.  Every pair's answer is itself a
+ *  context (multi-turn), so a completed form has somewhere to continue. */
+function corpus(n) {
+  const pairs = [];
+  for (let k = 0; k < 8; k++) pairs.push([QUERY, utter(k * 101 + 7)]);
+  for (let i = 0; i < n; i++) {
+    pairs.push([utter(i), utter(i * 3 + 1)]);
+    pairs.push([utter(i * 3 + 1), utter(i * 7 + 2)]);
+  }
+  return pairs;
+}
+
+/** Power-law exponent k in work ≈ c·n^k, by log–log least squares — the same
+ *  statistic and the same k < 0.6 bar 14-scaling.test.mjs uses. */
+function logLogSlope(sizes, ys) {
+  const n = sizes.length;
+  const xs = sizes.map(Math.log), ly = ys.map((v) => Math.log(Math.max(v, 1)));
+  const mx = xs.reduce((a, b) => a + b, 0) / n;
+  const my = ly.reduce((a, b) => a + b, 0) / n;
+  let num = 0, den = 0;
+  for (let i = 0; i < n; i++) {
+    num += (xs[i] - mx) * (ly[i] - my);
+    den += (xs[i] - mx) ** 2;
+  }
+  return num / den;
+}
+
+// `corpus(n)` emits two pairs per turn plus the eight hub pairs, so these are
+// the 1508 / 2008 / 3008-pair points of the table above.
+const SIZES = [750, 1000, 1500];
+
+test("completion recursion: per-query work does not grow with the corpus", async () => {
+  assert.ok(
+    FRAG.length > 4000,
+    `only ${FRAG.length} prose fragments found in ${REPO}/*.md — this test ` +
+      `draws its corpus from the repo's own documentation; with the prose gone ` +
+      `it can no longer exercise the completion recursion at all`,
+  );
+
+  const searches = [], pops = [], answers = [], secs = [];
+
+  for (const n of SIZES) {
+    const store = new SQliteStore({ path: ":memory:", D: 1024 });
+    const mind = new Mind({ seed: 7, store, profile: true });
+    await mind.ingest(corpus(n));
+
+    const t0 = performance.now();
+    const answer = String(await mind.respondText(QUERY));
+    secs.push((performance.now() - t0) / 1000);
+
+    const c = mind.lastCost.counters;
+    searches.push(c.searches ?? 0);
+    pops.push(c.searchPops ?? 0);
+    answers.push(answer);
+    await store.close();
+  }
+
+  console.log("    completion recursion vs corpus size (fixed 3-byte query):");
+  SIZES.forEach((n, i) =>
+    console.log(
+      `      pairs=${String(n * 2 + 8).padStart(5)}  searches=${
+        String(searches[i]).padStart(5)
+      }  pops=${String(pops[i]).padStart(8)}  ${secs[i].toFixed(2)}s`,
+    )
+  );
+
+  // NON-VACUITY.  If the corpus stopped reaching the recursion, every counter
+  // would be flat at zero and the growth assertions below would pass while
+  // proving nothing.  A test that can go green by not exercising the code is
+  // worse than no test, so this fails loudly instead.
+  assert.ok(
+    searches.every((s) => s > 0),
+    `the graph search never ran (searches=${JSON.stringify(searches)}) — the ` +
+      `corpus no longer engages cover(), so this file is not testing anything`,
+  );
+
+  // NO OUTPUT CONFOUND.  Work is allowed to grow with the ANSWER.  Pinning the
+  // answer byte-for-byte across every size removes that defence entirely: any
+  // growth measured below bought exactly nothing.
+  assert.ok(
+    answers.every((a) => a === answers[0]),
+    `the answer changed across corpus sizes (${
+      JSON.stringify(answers.map((a) => a.slice(0, 40)))
+    }) — with the output moving, work growth is no longer attributable to the ` +
+      `corpus alone`,
+  );
+
+  const kSearches = logLogSlope(SIZES, searches);
+  const kPops = logLogSlope(SIZES, pops);
+  console.log(
+    `      growth exponent k ≈ ${kSearches.toFixed(2)} (nested searches), ${
+      kPops.toFixed(2)
+    } (agenda pops) — target ≪ 1 (sublinear in the corpus)`,
+  );
+
+  // THE LAW.  Same answer, more corpus, so cost must not move.  k ≈ 0 is flat,
+  // k ≈ 1 is linear in the corpus — the bound §2.8 forbids outright.
+  //
+  // `searches` counts nested solve() calls, which is the recursion itself and
+  // nothing else, so it gets 14-scaling.test.mjs's stricter 0.6 bar.  Measured
+  // 1.28 unfixed, 0.38 fixed.
+  assert.ok(
+    kSearches < 0.6,
+    `nested searches grew with exponent k=${kSearches.toFixed(2)} in corpus ` +
+      `size (${searches.join(" → ")}) for a byte-identical answer — each ` +
+      `nested solve() builds its own agenda and chart, so this is the ` +
+      `completion recursion doing work the answer never asked for`,
+  );
+  // A LOOSER BAR, FOR A REASON.  `searchPops` aggregates the TOP-LEVEL cover's
+  // agenda too, and that one legitimately carries some corpus sensitivity: a
+  // bigger store recognises more sites inside the same query, so more items are
+  // admissible.  Only outright linear growth is the forbidden case (§2.8), so
+  // this asserts the law itself, k < 1, rather than the stricter 0.6 that suits
+  // a counter the fix governs end to end.  Measured 1.40 unfixed, 0.54 fixed.
+  assert.ok(
+    kPops < 1,
+    `agenda pops grew with exponent k=${kPops.toFixed(2)} in corpus size (${
+      pops.join(" → ")
+    }) for a byte-identical answer — k≈1 is work LINEAR in the corpus, which ` +
+      `is the bound §2.8 forbids outright`,
+  );
+});

package/test/90-connector-read-cap.test.mjs

@@ -0,0 +1,130 @@
+// 90-connector-read-cap.test.mjs — the "already answered" probe must read by
+// the QUERY, not by the corpus.
+//
+// `resolveConnectors` (src/mind/mechanisms/cover.ts) drops a site whose
+// continuation already appears elsewhere in the query — stale transcript
+// evidence, whose bridges would only be discarded later.  The test is a
+// substring search, so it needs the candidate's bytes; it used to reconstruct
+// them in FULL via `read(ctx, answer)`, whose maxLen defaults to ALL.
+//
+// AGENTS §2.8, prefix-capped reads: "a candidate that exceeds the cap is
+// rejected without reconstructing it — the weave, the junction walks and the
+// bridge all read this way, and uncapped reads there cost seconds per query on
+// a large store."  This probe was the exception, and it runs hubBound(ctx) = √N
+// times PER SITE.
+//
+// The probe's corpus-scale cost was once claimed from a trained-store
+// measurement — "88,581 byte reconstructions / 20.5 MB for one 1,314-byte
+// prompt" — but that number was measured on a `respond()` query, where the
+// probe does NOT execute (`answeredSpans` is empty there, so the enclosing
+// guard returns first).  It is therefore not attributable to the probe and is
+// not repeated here (§2.16: a comment asserting a measurement inherits Gate 1).
+// The probe runs only on a multi-turn `respondTurn` response; its benefit there
+// is still unmeasured.
+//
+// WHAT THIS PINS.  The cap cannot reduce the read COUNT — only a semantic change
+// could (see below).  It bounds each read by the QUERY, which is what §2.8 asks
+// and what rescues a SHORT query: candidates averaged 231 B reconstructed
+// against a 3-byte prompt.  So the invariant here is per-read SIZE.
+//
+// It is measured by calling `resolveConnectors` DIRECTLY and diffing the meter
+// across it.  A whole-response counter cannot express this: `bytesRead` sums
+// every reader in the pipeline, and the answer itself is a long continuation
+// that is legitimately read in full — an earlier draft of this file asserted on
+// the response total and failed even with the fix applied, for that reason.
+//
+// NOT fixed here, deliberately: the READ COUNT is still O(sites × √N).  Removing
+// it means replacing the byte-substring test with membership in the query's
+// already-computed recognised sites — an O(1) id-set test.  That is NOT
+// equivalent: recognition is a "longest-known-leaf re-segmentation"
+// (src/mind/recognition.ts), so it does not enumerate every learnt form; the set
+// test would filter fewer sites, change which connectors exist, and can change
+// answers.  A semantic decision, not a performance one.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+import { resolveConnectors } from "../dist/src/mind/mechanisms/cover.js";
+
+/** Learnt CONTINUATIONS far longer than the query that will be asked — the
+ *  shape the cap governs: an uncapped probe reconstructs each one in full
+ *  merely to discover it cannot fit inside a short query. */
+const LONG = (i) =>
+  `answer ${i} this is a deliberately long learnt continuation whose bytes go ` +
+  `on well past anything the short query could contain, clause after clause, ` +
+  `so that reconstructing it in full is plainly more work than the query ` +
+  `justifies, and it keeps going for a while yet in variant ${i}`;
+
+// ONE context with MANY learnt continuations, so `nextFirst(site, hubBound)`
+// returns a wide fan and the probe does real work on a single site.
+function corpus(n) {
+  const pairs = [];
+  for (let i = 0; i < n; i++) {
+    pairs.push([`ask topic`, LONG(i)]);
+    pairs.push([LONG(i), `ask topic`]);
+  }
+  return pairs;
+}
+
+test("connector probe reads by the query, not by the learnt continuation", async () => {
+  const store = new SQliteStore({ path: ":memory:", D: 256 });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  await mind.ingest(corpus(300));
+
+  const QUERY = "ask topic";
+  const bytes = new TextEncoder().encode(QUERY);
+
+  // beginResponse builds the per-response memos AND the meter this reads.
+  mind.beginResponse();
+  try {
+    const { sites } = mind.recogniseSpan(bytes);
+    // EXACT ISOLATION.  resolveConnectors also reads bytes the probe has
+    // nothing to do with (the n-ary bridge reads each ordered node in full, and
+    // legitimately so).  The probe itself early-returns when answeredSpans is
+    // empty, so running the SAME call both ways and differencing leaves exactly
+    // the probe's own reads and nothing else.
+    const m = mind.meter;
+    mind.answeredSpans = [];
+    const a0 = m.byteReads, b0 = m.bytesRead;
+    await resolveConnectors(mind, sites, bytes);
+    const baseReads = m.byteReads - a0, baseBytes = m.bytesRead - b0;
+
+    mind.answeredSpans = [[0, 1]];
+    const a1 = m.byteReads, b1 = m.bytesRead;
+    await resolveConnectors(mind, sites, bytes);
+    const reads = (m.byteReads - a1) - baseReads;
+    const read = (m.bytesRead - b1) - baseBytes;
+
+    console.log(
+      `    ${sites.length} sites, query ${QUERY.length} B → ` +
+        `byteReads=${reads} bytesRead=${read} ` +
+        `(${(read / Math.max(reads, 1)).toFixed(0)} B per read)`,
+    );
+
+    // NON-VACUITY: the probe must actually have read something, or the bound
+    // below is trivially true and proves nothing.
+    assert.ok(
+      reads > 0,
+      `resolveConnectors made no byte reads — the probe never ran (sites=${sites.length}), ` +
+        `so this file is not testing anything`,
+    );
+
+    // THE BOUND.  Every read here tests a candidate for containment in the
+    // query, so none can need more than the query's own length plus the single
+    // overflow byte that makes the test exact.  Continuations here are ~230 B
+    // against an 11 B query, so an uncapped read cannot satisfy this and a
+    // capped one cannot violate it.
+    const perRead = read / Math.max(reads, 1);
+    assert.ok(
+      perRead <= QUERY.length + 1,
+      `the connector probe averaged ${perRead.toFixed(0)} B per read for a ` +
+        `${QUERY.length} B query — a candidate longer than the query cannot ` +
+        `occur inside it, so it must be rejected on an overflow probe of ` +
+        `${QUERY.length + 1} B, not reconstructed in full (AGENTS §2.8)`,
+    );
+  } finally {
+    mind.endResponse();
+  }
+  await mind.store.close();
+});

package/test/91-branch-bytes-cache.test.mjs

@@ -0,0 +1,152 @@
+// 91-branch-bytes-cache.test.mjs — reconstructing a node twice must not
+// re-walk it.
+//
+// `bytesPrefix` rebuilds a node's bytes by descending the DAG, one `store.get`
+// per node visited.  `_prefix` consults `_bytesCache` for EVERY id but used to
+// populate it only for leaves, so a BRANCH re-walked its entire subtree on every
+// request — and because the DAG is hash-consed, the same children recur under
+// many different parents.
+//
+// MEASURED on the trained store (18,938,834 nodes), ONE 1,314-byte query:
+//   _prefix calls (all levels) : 20,021,474
+//   distinct ids               :    469,083   → 42.7x reuse
+//   avoidable by a cache       : 19,552,391   → 97.7%
+//   top-level calls            :     87,789 over 76,849 distinct (1.1x)
+//   hottest id                 : a single-byte leaf, 2,599,984 reconstructions
+//
+// The 1.1x at the top level is why this hid for so long: measured there, reuse
+// looks absent and a cache looks worthless.  All of the reuse is one level down.
+//
+// `_bytesCache` was already the right home — a byte-accounted BoundedMap with
+// "smallest"/"clock" eviction, the configuration this codebase reserves for a
+// TRANSPARENT cache (evicting costs a re-read and nothing else).  Reconstruction
+// is a pure function of the store, so it qualifies; only the population was
+// missing.
+//
+// WHAT THIS FILE ACTUALLY GUARDS — read this before trusting it.
+//
+// The re-walk assertion routes through `_prefix` (a CAPPED read), because that
+// is where the fix lives.  `bytesPrefix(id, ALL)` short-circuits to `bytes()`
+// (store.ts `bytesPrefix`: `maxLen >= 0x7fffffff → this.bytes(id)`), and
+// `bytes()` has its OWN, pre-existing branch cache — so a re-walk assertion
+// built on the ALL sentinel stays green when the `_prefix` fix is reverted and
+// guards nothing (this file once did exactly that, and its header claimed the
+// cause was "the node carries `flat` bytes", which is false: `flat` is
+// STRUCTURAL — a branch stores its bytes flat iff every kid is an implicit
+// single-byte leaf (store.ts `flatKidsBytes`) — and the fixture's node is
+// non-flat, kids of real chunk nodes.  There is no size threshold that drops
+// `flat`).
+//
+// With the fix, a capped read that completes the node caches the BRANCH
+// (`got < maxLen` guard), so a second capped read is a full-cache hit and costs
+// 0 node reads; with the fix reverted it re-reads the root (1 node read) because
+// only the LEAVES are cached.  The signal is small at fixture scale precisely
+// because the fixture's tree is shallow (root → flat chunks → leaves); the real
+// 5.4–7.7× nodeRecords reduction is verified on the trained store instead.
+//
+// The TRUNCATION assertion at the end IS a real guard, verified red: with the
+// `got < maxLen` condition removed, it fails with "a capped read poisoned the
+// cache: the full read came back 29 bytes instead of 59".  That is the
+// dangerous half of this fix — a truncated prefix served as a node's whole
+// content would silently corrupt every later reader — so that is the half worth
+// having a test for.
+//
+// The fix's real effect is verified on the trained store instead: identical
+// answers and identical `bytesRead`/`byteReads`/`junctionPops`, with
+// `nodeRecords` falling 1,182,651 → 218,449 · 2,462,577 → 321,794 ·
+// 2,492,035 → 381,020 (5.4–7.7×), and the 1,314-byte query 14.0 s → 9.4 s.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+import { Meter } from "../dist/src/meter.js";
+
+const ALL = 0x7fffffff;
+
+test("a branch's bytes are reconstructed once, not re-walked", async () => {
+  const store = new SQliteStore({ path: ":memory:", D: 256 });
+  const mind = new Mind({ seed: 7, store });
+  // Long deposits, so the nodes have real interior structure to re-walk.
+  await mind.ingest([
+    ["alpha", "the quick brown fox jumps over the lazy dog again and again"],
+    ["beta", "the quick brown fox jumps over the lazy cat again and again"],
+    ["gamma", "a quick brown fox once jumped over a lazy dog and then rested"],
+  ]);
+
+  // A branch node with interior structure — the deposit's own root.
+  const tree = mind.perceive(
+    "the quick brown fox jumps over the lazy dog again and again",
+  );
+  const id = mind.resolve(new TextEncoder().encode(
+    "the quick brown fox jumps over the lazy dog again and again",
+  ));
+  assert.ok(id !== null, "the deposited form resolves to a stored node");
+  assert.ok(tree.kids && tree.kids.length > 1, "and it has interior structure");
+
+  // Route through `_prefix`, not `bytes()`: the ALL sentinel short-circuits to
+  // `bytes()`, whose branch cache is pre-existing and would keep the assertion
+  // green even with the `_prefix` fix reverted.  A capped read past the node's
+  // full length completes the walk (so the branch gets cached, `got < maxLen`)
+  // while staying off the ALL fast path.  `contentLen` warms `_recCache`/`_lenCache`
+  // only, never `_bytesCache`, so the first read below starts cold.
+  const fullLen = store.contentLen(id);
+  store.meter = new Meter();
+  const capped = fullLen + 1;
+
+  // FIRST reconstruction — this one legitimately walks the subtree.
+  const first = store.bytesPrefix(id, capped);
+  const walked = store.meter.nodeRecords;
+  assert.ok(
+    first.length > 0,
+    "the node reconstructs to bytes",
+  );
+  // NON-VACUITY: if the first read did no node reads either, the store answered
+  // from some other cache and this test proves nothing about re-walking.
+  assert.ok(
+    walked > 0,
+    `the first reconstruction did no node reads at all (nodeRecords=${walked}), ` +
+      `so there is no re-walk for this test to detect`,
+  );
+
+  // SECOND reconstruction of the SAME node — must be free.
+  const before = store.meter.nodeRecords;
+  const second = store.bytesPrefix(id, capped);
+  const again = store.meter.nodeRecords - before;
+
+  console.log(
+    `    first reconstruction: ${walked} node reads; second: ${again}`,
+  );
+  assert.deepEqual(second, first, "the cached bytes are the same bytes");
+  assert.equal(
+    again,
+    0,
+    `re-reading the same node cost ${again} node reads (the first cost ` +
+      `${walked}) — reconstruction is a pure function of the store, so the ` +
+      `second request must be served from _bytesCache, not re-walked`,
+  );
+
+  // AND a truncated read must never be cached AS the whole node: serving a
+  // prefix as the full content would silently corrupt every later reader.
+  const cut = Math.max(1, first.length >> 1);
+  const store2 = new SQliteStore({ path: ":memory:", D: 256 });
+  const mind2 = new Mind({ seed: 7, store: store2 });
+  await mind2.ingest([[
+    "alpha",
+    "the quick brown fox jumps over the lazy dog again and again",
+  ]]);
+  const id2 = mind2.resolve(new TextEncoder().encode(
+    "the quick brown fox jumps over the lazy dog again and again",
+  ));
+  store2.bytesPrefix(id2, cut); // truncated FIRST, so a bad cache would poison
+  const whole = store2.bytesPrefix(id2, ALL);
+  assert.equal(
+    whole.length,
+    first.length,
+    `a capped read poisoned the cache: the full read came back ${whole.length} ` +
+      `bytes instead of ${first.length}`,
+  );
+
+  await store.close();
+  await store2.close();
+});

package/test/93-regime-prediction.test.mjs

@@ -0,0 +1,148 @@
+// 93-regime-prediction.test.mjs — the retrieval/composition regime (R8) is
+// exposed as a structured trace step, without changing inference.
+//
+// After the FIRST mechanism runs (cover, which §2.6 places first and floors at
+// 0), the market's whole outcome is already determined by the one cost ladder:
+// the consensus climb runs exactly when `worthRunning(2 * STEP)` is true —
+// CAST (floor 2·STEP) is the cheapest mechanism that first-touches it.  An
+// incumbent at or below that floor prunes CAST and, with it, the climb
+// (retrieval); anything above — or no incumbent — runs the full market and the
+// climb (composition).  The step is purely observational: it is built only
+// under a trace (optional-chaining short-circuits it otherwise), and it never
+// alters which candidate wins.  The assertions here check the payload's
+// STRUCTURE and its consistency with the actual market outcome, never that
+// inference itself changed.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const mk = (seed = 7) =>
+  new Mind({ seed, store: new SQliteStore({ path: ":memory:", D: 256 }) });
+
+/** Collect the full step stream for one traced query. */
+async function trace(mind, q) {
+  const steps = [];
+  const ans = await mind.respondText(q, (s) => steps.push(s));
+  return { steps, ans };
+}
+
+function regimeStep(steps) {
+  return steps.filter((s) => s.mechanism.at(-1) === "regimePrediction");
+}
+
+test("1. a fully-grounding query predicts retrieval, and the market prunes", async () => {
+  const m = mk();
+  await m.ingest([
+    [
+      "who wrote romeo and juliet",
+      "William Shakespeare wrote Romeo and Juliet.",
+    ],
+  ]);
+  const { steps } = await trace(m, "who wrote romeo and juliet");
+  await m.store.close();
+
+  const r = regimeStep(steps);
+  assert.equal(r.length, 1, "exactly one regimePrediction step per response");
+  const d = r[0].data;
+  assert.equal(d.version, 1);
+  assert.equal(d.regime, "retrieval");
+  assert.ok(
+    d.incumbentGrade <= d.climbFloorGrade,
+    "incumbent grade at or under the climb floor",
+  );
+  assert.equal(
+    d.climbFloorGrade,
+    2,
+    "2·STEP = 2 (CAST's floor), in grade units",
+  );
+});
+
+test("2. an ungroundable query predicts composition with no incumbent", async () => {
+  const m = mk();
+  await m.ingest([["alpha", "beta"]]);
+  const { steps } = await trace(m, "qzx zzjf vbnm plkj");
+  await m.store.close();
+
+  const r = regimeStep(steps);
+  assert.equal(r.length, 1);
+  assert.equal(r[0].data.regime, "composition");
+  assert.equal(
+    r[0].data.incumbentGrade,
+    null,
+    "nothing grounded — no incumbent",
+  );
+});
+
+test("3. a partially-grounding query predicts composition (one unexplained byte outbids every floor)", async () => {
+  const m = mk();
+  await m.ingest([
+    ["the capital of france", "The capital of France is Paris."],
+  ]);
+  const { steps } = await trace(m, "what is the capital of france");
+  await m.store.close();
+
+  const r = regimeStep(steps);
+  assert.equal(r[0].data.regime, "composition");
+  assert.ok(
+    r[0].data.incumbentGrade > r[0].data.climbFloorGrade,
+    `incumbent grade ${r[0].data.incumbentGrade} must exceed the climb floor ` +
+      `${
+        r[0].data.climbFloorGrade
+      } — PASS prices each unexplained byte at 1000`,
+  );
+});
+
+test("5. a fully-covered multi-move query (grade above the climb floor) still predicts composition", async () => {
+  // Three contiguous trained forms cover the whole query with three STEP moves
+  // and NO unexplained bytes — incumbent grade 3, which the old
+  // `worthRunning(CONCEPT + STEP)` boundary (≤ 11) mislabelled "retrieval"
+  // even though CAST's 2·STEP floor still runs the consensus climb.  The
+  // regime must follow the climb, not the market's maximum floor.
+  const m = mk();
+  await m.ingest([
+    ["abcdefgh", "ABCDEFGH"],
+    ["ijklmnop", "IJKLMNOP"],
+    ["qrstuvwx", "QRSTUVWX"],
+  ]);
+  const { steps } = await trace(m, "abcdefghijklmnopqrstuvwx");
+  await m.store.close();
+
+  const r = regimeStep(steps);
+  assert.equal(r.length, 1);
+  const d = r[0].data;
+  assert.equal(d.regime, "composition", "the climb runs, so it is composition");
+  assert.ok(
+    d.incumbentGrade > d.climbFloorGrade,
+    `incumbent grade ${d.incumbentGrade} must exceed the climb floor ${d.climbFloorGrade}`,
+  );
+  // The prediction's own premise: the climb DID run (CAST first-touched it).
+  const climbed = steps.some((s) => s.mechanism.at(-1) === "climbConsensus");
+  assert.ok(climbed, "the consensus climb must actually run in this regime");
+});
+
+test("4. the prediction is observational — an untraced response is byte-identical", async () => {
+  const mk2 = () =>
+    new Mind({
+      seed: 7,
+      store: new SQliteStore({ path: ":memory:", D: 256 }),
+    });
+  const q = "who wrote romeo and juliet";
+  const corpus = [[
+    "who wrote romeo and juliet",
+    "William Shakespeare wrote Romeo and Juliet.",
+  ]];
+
+  const a = mk2();
+  await a.ingest(corpus);
+  const plain = await a.respondText(q);
+  await a.store.close();
+
+  const b = mk2();
+  await b.ingest(corpus);
+  const traced = await b.respondText(q, () => {});
+  await b.store.close();
+
+  assert.equal(traced, plain, "attaching a trace must not change the answer");
+});