@hviana/sema 0.4.6 → 0.5.0

package/test/13-conversation.test.mjs

@@ -18,6 +18,19 @@
 // accumulated bytes at inference.  The Conversation API tracks turn-boundary
 // offsets explicitly so no separator character is needed — the geometry never
 // inspects content to find turn boundaries.
+//
+// "NO SEPARATOR IS NEEDED" ≠ "A SEPARATOR IS A PROBLEM".  This file joins its
+// turns with nothing; example/train_base.ts joins its oasst2 turns with "\n".
+// Both are correct, and neither is a convention the other has to match: a
+// separator is CORPUS CONTENT, folded like any other byte, while a turn
+// boundary is an OFFSET the API carries beside the bytes.  A harness replaying
+// a "\n"-joined corpus simply passes `"\n" + turnText` to addTurn and gets the
+// trained byte stream back exactly.  See Mind.addTurn's "ON SEPARATORS" note
+// for the full statement — it exists because a review read the mismatch
+// between this file's join and the trainer's as an architectural
+// incompatibility, and it is not one.  If you are comparing this harness to a
+// corpus and getting poor recall, check that you are feeding the bytes that
+// were actually trained before concluding anything about the engine.
 // ─────────────────────────────────────────────────────────────────────────
 
 import { test } from "node:test";

package/test/57-fusion-order.test.mjs

@@ -82,6 +82,71 @@ test("2. reversing the question reverses the fused answer", async () => {
   await mind.store.close();
 });
 
+test("2b. a topic is never ECHOED back instead of answered", async () => {
+  // The failure this pins: "What is the capital of France? And what is the
+  // largest planet?" answered "The capital of France is Paris.What is the
+  // largest planet?" — one topic answered, the other repeated verbatim.
+  //
+  // It hinged on CASE. The comparison schema seats a directly-aligned analog
+  // by its own bytes rather than chasing a forward edge, which is correct when
+  // those bytes are an answer (test/43 pins that) and an echo when they are
+  // the question the asker just asked. The guard against that is a restatement
+  // check, and a BYTE-EXACT one missed here: the trained node is "What is the
+  // largest planet?" while the query says "And what is the largest planet?" —
+  // the same words, one capital apart. The check now reads the response's own
+  // injected canon, so it sees what the rest of the mind sees.
+  //
+  // SCOPE: this asserts only that nothing is echoed. Whether BOTH topics get
+  // fused is a separate, corpus- and seed-dependent property of the consensus
+  // climb — at this file's seed the second point is sometimes not committed at
+  // all, which is why test 1 above guards its ordering assertion on both names
+  // being present. Answering one topic and staying silent about the other is a
+  // coverage limit; answering one and parroting the other is a defect.
+  //
+  // Asserted in BOTH orders because the echo appeared in only one: which topic
+  // got echoed depended on whether the climb landed on the question node or
+  // the answer node, so a single-order test passes while the bug is live.
+  // ITS OWN CORPUS, DELIBERATELY. The file's shared `trained()` fixture cannot
+  // reproduce this: with five same-frame facts the climb often commits only
+  // ONE point, so there is no second topic to echo and the test would pass
+  // against the unfixed code (verified — it did). The echo needs exactly two
+  // topics, each a bare question node whose answer hangs off a forward edge.
+  const mind = new Mind({
+    seed: 7,
+    store: new SQliteStore({ path: ":memory:" }),
+  });
+  await mind.ingest([
+    ["What is the capital of France?", "The capital of France is Paris."],
+    ["What is the largest planet?", "The largest planet is Jupiter."],
+  ]);
+  for (
+    const q of [
+      "What is the capital of France? And what is the largest planet?",
+      "What is the largest planet? And what is the capital of France?",
+    ]
+  ) {
+    const a = await mind.respondText(q);
+    assert.ok(
+      !/And what is/i.test(a),
+      `the query was echoed rather than answered: ${JSON.stringify(a)} for ${
+        JSON.stringify(q)
+      }`,
+    );
+    assert.ok(
+      a.includes("Paris") && a.includes("Jupiter"),
+      `both topics must be ANSWERED, got ${JSON.stringify(a)} for ${
+        JSON.stringify(q)
+      }`,
+    );
+    // Nor may an answer be a bare restatement of one of the asked questions.
+    assert.ok(
+      !/^\s*What is the (largest planet|capital of France)\?\s*$/i.test(a),
+      `the answer is just the question restated: ${JSON.stringify(a)}`,
+    );
+  }
+  await mind.store.close();
+});
+
 test("3. a single-topic answer is unchanged by the ordering rule", async () => {
   const mind = await trained();
   assert.match(

package/test/65-ann-recall.test.mjs

@@ -0,0 +1,331 @@
+// 65-ann-recall.test.mjs — the ACCURACY half of rabitq-ivf's speed/accuracy
+// trade, pinned to a measured baseline.
+//
+// Every geometry constant in the sub-library (rotation `rounds`, `queryBits`,
+// `efSearch`/nprobe, SPLIT_MAX, and the estimator's own arithmetic) buys speed
+// by giving up recall. Nothing measured the recall, so nothing could be
+// changed: a faster encoder that quietly lost neighbours looked exactly like a
+// faster encoder. These assertions are that missing half — an optimisation is
+// free only if it holds this line.
+//
+// Deliberately SELF-CONTAINED: vectors are real Sema gists, but folded here
+// from generated text rather than read out of sema.*, so the test is
+// deterministic, needs no trained store, and cannot drift when one is
+// retrained.
+//
+// Absolute recall here (~78%) runs higher than the ~71% measured against the
+// trained store (100,000 gists sampled from sema.*, 400 queries, exact-cosine
+// ground truth): generated word-salad folds to an easier distribution than a
+// real corpus. The FLOORS are what matter, and they are set from what this
+// file itself measures, with margin for the estimator's quantisation noise —
+// never from what looked good on a different distribution.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { gistOf } from "../dist/src/mind/primitives.js";
+import { IvfIndex } from "../dist/src/rabitq-ivf/src/ivf.js";
+import { RaBitQuantizer } from "../dist/src/rabitq-ivf/src/rabitq.js";
+
+const SEED = 7;
+const K = 10;
+
+// A deterministic PRNG — the vectors must be identical on every run, or a
+// recall floor is a coin flip.
+const prng = (s) => () => {
+  s ^= s << 13;
+  s >>>= 0;
+  s ^= s >>> 17;
+  s ^= s << 5;
+  s >>>= 0;
+  return s / 4294967296;
+};
+
+const WORDS = [
+  "the",
+  "a",
+  "of",
+  "in",
+  "system",
+  "fold",
+  "vector",
+  "index",
+  "query",
+  "gist",
+  "node",
+  "edge",
+  "store",
+  "cluster",
+  "recall",
+  "code",
+  "byte",
+  "span",
+  "chunk",
+  "seed",
+  "paris",
+  "france",
+  "steel",
+  "ice",
+  "planet",
+  "sun",
+  "music",
+  "river",
+  "light",
+  "stone",
+];
+
+/** `n` distinct real Sema gists, folded from generated text. */
+function gists(n) {
+  const mind = new Mind({ seed: SEED });
+  const rnd = prng(20260729);
+  const enc = new TextEncoder();
+  const out = [];
+  const seen = new Set();
+  while (out.length < n) {
+    let s = "";
+    const len = 3 + ((rnd() * 14) | 0);
+    for (let i = 0; i < len; i++) {
+      s += (i ? " " : "") + WORDS[(rnd() * WORDS.length) | 0];
+    }
+    s += ".";
+    if (seen.has(s)) continue;
+    seen.add(s);
+    const g = gistOf(mind, enc.encode(s));
+    let sq = 0;
+    for (let i = 0; i < g.length; i++) sq += g[i] * g[i];
+    if (sq > 0) out.push(g);
+  }
+  return { vecs: out, D: mind.store.D };
+}
+
+function indexOf(vecs, D, rounds = 3) {
+  const idx = new IvfIndex(":memory:", {
+    dim: D,
+    rotationRounds: rounds,
+    seed: SEED,
+    cacheSizeMb: 64,
+  });
+  idx.begin();
+  for (let i = 0; i < vecs.length; i++) {
+    idx.insert(i, idx.encodeToBytes(vecs[i]));
+  }
+  idx.commit();
+  idx.commitFlush();
+  return idx;
+}
+
+const queryIds = (n, q) => {
+  const out = [];
+  for (let i = 0; i < q; i++) out.push(Math.floor((i + 0.5) * n / q));
+  return out;
+};
+
+/** Exact cosine top-k by brute force — the only true ground truth here. */
+function exactTopK(vecs, norms, qi, k) {
+  const q = vecs[qi], qn = norms[qi];
+  const ds = new Float64Array(vecs.length);
+  for (let j = 0; j < vecs.length; j++) {
+    const v = vecs[j];
+    let dot = 0;
+    for (let i = 0; i < q.length; i++) dot += q[i] * v[i];
+    const den = qn * norms[j];
+    ds[j] = den === 0 ? 1 : 1 - dot / den;
+  }
+  return new Set(
+    Array.from(ds.keys()).sort((a, b) => ds[a] - ds[b]).slice(0, k),
+  );
+}
+
+// ── QUANTIZATION: what 1-bit coding costs, with routing removed ─────────────
+
+test("quantization recall holds its measured floor (routing removed)", () => {
+  const { vecs, D } = gists(2000);
+  const norms = vecs.map((v) => {
+    let s = 0;
+    for (let i = 0; i < v.length; i++) s += v[i] * v[i];
+    return Math.sqrt(s);
+  });
+  const qs = queryIds(vecs.length, 100);
+  const truth = qs.map((qi) => exactTopK(vecs, norms, qi, K));
+
+  const idx = indexOf(vecs, D);
+  // nprobe = K clusters: every cluster is scanned, so the ONLY thing between
+  // the query and exact cosine is the 1-bit code.
+  const full = 4 * idx.clusterCount;
+  let hit = 0, want = 0;
+  for (let t = 0; t < qs.length; t++) {
+    for (const h of idx.searchKnn(vecs[qs[t]], K, full)) {
+      if (truth[t].has(h.id)) hit++;
+    }
+    want += truth[t].size;
+  }
+  idx.close();
+  const recall = hit / want;
+
+  // Measured 79.3% here (2,000 gists, 100 queries, k=10). The floor sits a
+  // clear margin below so that ordinary quantisation jitter cannot trip it,
+  // while a real loss — dropping a rotation round that mattered, widening the
+  // code, changing the estimator's arithmetic — moves recall by far more.
+  assert.ok(
+    recall >= 0.74,
+    `quantization recall@${K} fell to ${(recall * 100).toFixed(1)}% ` +
+      `(floor 74.0%, measured baseline 79.3%). The 1-bit code lost ` +
+      `neighbours it used to keep — this is the accuracy half of a ` +
+      `speed/accuracy trade, so a change that speeds up the encoder or the ` +
+      `estimator must NOT land here.`,
+  );
+});
+
+// ── ROUTING: what probing a subset of clusters costs ───────────────────────
+
+test("routing recall degrades monotonically as nprobe shrinks", () => {
+  // 12,000 vectors splits into several clusters (SPLIT_MAX = 4096). Routing is
+  // then exercised by LOWERING ef — nprobe = ceil(ef/4) — rather than by
+  // growing the collection into the tens of thousands, which would cost the
+  // suite seconds to say the same thing.
+  const { vecs, D } = gists(12000);
+  const idx = indexOf(vecs, D);
+  const clusters = idx.clusterCount;
+  assert.ok(clusters >= 4, `expected several clusters, got ${clusters}`);
+
+  const qs = queryIds(vecs.length, 100);
+  const full = 4 * clusters; // nprobe >= clusters: nothing skipped
+  const ref = qs.map((qi) =>
+    new Set(idx.searchKnn(vecs[qi], K, full).map((h) => h.id))
+  );
+
+  const at = (ef) => {
+    let hit = 0, want = 0;
+    for (let t = 0; t < qs.length; t++) {
+      for (const h of idx.searchKnn(vecs[qs[t]], K, ef)) {
+        if (ref[t].has(h.id)) hit++;
+      }
+      want += ref[t].size;
+    }
+    return hit / want;
+  };
+
+  const one = at(4); //  nprobe 1
+  const two = at(8); //  nprobe 2
+  const all = at(16 * clusters);
+  idx.close();
+
+  // Probing every cluster must reproduce the reference exactly — this is the
+  // same scan, so anything below 1.0 means the probe ORDER dropped a cluster
+  // it ranked in, not that the quantizer was imprecise.
+  assert.equal(
+    all,
+    1,
+    "probing every cluster must match the full scan exactly",
+  );
+  // More clusters probed is never worse.
+  assert.ok(
+    two >= one,
+    `routing recall fell when nprobe grew: nprobe=1 ${
+      (one * 100).toFixed(1)
+    }% ` +
+      `-> nprobe=2 ${(two * 100).toFixed(1)}%`,
+  );
+  // Measured 52.9% at nprobe=1 and 76.4% at nprobe=2 of 4 clusters. The floors
+  // guard the PIVOT quality: routing is only worth anything if the nearest
+  // cluster usually holds the nearest vectors, and a pivot chosen badly (a
+  // broken split, a majority-code regression) shows up here first.
+  assert.ok(
+    one >= 0.4,
+    `single-cluster routing recall ${(one * 100).toFixed(1)}% is below the ` +
+      `0.4 floor (measured 52.9%) — cluster pivots no longer predict where ` +
+      `a query's neighbours live.`,
+  );
+});
+
+// ── ESTIMATOR: the arithmetic itself, pinned exactly ───────────────────────
+
+test("the fast estimator is bit-identical to its scalar definition", () => {
+  // The scan's inner loop is the hottest code in inference and invites
+  // micro-optimisation (it currently folds the popcount into 32-bit SWAR
+  // words). Those rewrites are only legitimate while they are EXACT: the
+  // estimator's output ranks every candidate, so a last-bit difference is a
+  // silent reordering, not a rounding detail. This recomputes the definition
+  // straight from the QueryContext and demands equality.
+  const rnd = prng(11);
+  let checked = 0;
+  for (const dim of [8, 64, 100, 256, 1024]) {
+    const qz = new RaBitQuantizer(dim, { seed: SEED });
+    const nb = qz.paddedDim >>> 3;
+    const POP = new Uint8Array(256);
+    for (let i = 1; i < 256; i++) POP[i] = POP[i >> 1] + (i & 1);
+    for (let t = 0; t < 25; t++) {
+      const v = new Float64Array(dim);
+      for (let i = 0; i < dim; i++) v[i] = rnd() * 2 - 1;
+      const q = qz.prepareQuery(v);
+      const code = new Uint8Array(nb * 4);
+      for (let i = 0; i < code.length; i++) code[i] = (rnd() * 256) | 0;
+      for (let c = 0; c < 4; c++) {
+        const off = c * nb;
+        let dot = 0, pc = 0;
+        for (let p = 0; p < q.nbytes; p++) {
+          const b = code[off + p];
+          dot += q.qlut[(p << 8) + b];
+          pc += POP[b];
+        }
+        const A = q.vmin * (2 * pc - qz.paddedDim) +
+          q.delta * (2 * dot - q.sumQInt);
+        const want = q.zero ? 1 : 1 - qz.cosFactor * A;
+        assert.ok(
+          Object.is(qz.estimate(code, off, q), want),
+          `estimate diverged from its definition at dim=${dim}: ` +
+            `${qz.estimate(code, off, q)} vs ${want}`,
+        );
+        checked++;
+      }
+    }
+  }
+  assert.ok(checked >= 500, `expected a broad sweep, checked ${checked}`);
+});
+
+// ── GEOMETRY: rotation rounds are saturated at 1 ───────────────────────────
+
+test("rotation rounds beyond the first buy no recall", () => {
+  // Recorded as an executable fact, because it is the one place in this
+  // sub-library with real headroom: a round is a sign-flip plus a
+  // Walsh-Hadamard transform (the SRHT construction, for which ONE randomised
+  // round already approximates a random rotation), and cost is linear in the
+  // count — encode runs 28.0us at rounds=3 against 16.8us at rounds=1.
+  //
+  // Measured against the trained store — 100,000 real gists, routing removed,
+  // 400 queries, recall@10: rounds=4 70.5%, rounds=3 71.1%, rounds=2 70.6%,
+  // rounds=1 71.1% — indistinguishable across 4,000 ground-truth slots, and
+  // reproduced at N=1,000 and N=4,000. If this assertion ever fails, the
+  // rotation has stopped being saturated and the default is worth revisiting.
+  const { vecs, D } = gists(2000);
+  const norms = vecs.map((v) => {
+    let s = 0;
+    for (let i = 0; i < v.length; i++) s += v[i] * v[i];
+    return Math.sqrt(s);
+  });
+  const qs = queryIds(vecs.length, 100);
+  const truth = qs.map((qi) => exactTopK(vecs, norms, qi, K));
+
+  const recallFor = (rounds) => {
+    const idx = indexOf(vecs, D, rounds);
+    const full = 4 * idx.clusterCount;
+    let hit = 0, want = 0;
+    for (let t = 0; t < qs.length; t++) {
+      for (const h of idx.searchKnn(vecs[qs[t]], K, full)) {
+        if (truth[t].has(h.id)) hit++;
+      }
+      want += truth[t].size;
+    }
+    idx.close();
+    return hit / want;
+  };
+
+  const three = recallFor(3);
+  const one = recallFor(1);
+  assert.ok(
+    Math.abs(three - one) <= 0.03,
+    `one rotation round is no longer equivalent to three: ` +
+      `rounds=3 ${(three * 100).toFixed(1)}% vs rounds=1 ` +
+      `${(one * 100).toFixed(1)}% (tolerance 3 points)`,
+  );
+});

package/test/66-query-edge-whitespace.test.mjs

@@ -0,0 +1,99 @@
+// 66-query-edge-whitespace.test.mjs — a query's leading/trailing whitespace is
+// presentation, not part of the question, and must not decide whether a trained
+// fact is reachable.
+//
+// canon.ts's contract: "a span's leading or trailing separator belongs BETWEEN
+// forms, not to the form".  canon itself PRESERVES edge whitespace, and must,
+// because the hazard it cites is a recognised SUB-span swallowing the boundary
+// byte that separates it from its neighbour ("ice " matching the stored "ice").
+// At the outer edges of a WHOLE input there is no neighbour, so that hazard
+// cannot arise — which is why respond() may trim there and canon may not.
+// test/44 already relies on the same reading for recognise()'s miss path.
+//
+// THE GAP THIS CLOSES (measured on the 15.7M-node trained store): ONE leading
+// space took `Who wrote Romeo and Juliet?` and `What is the chemical symbol for
+// water?` from answered to silent, because a shift re-seats every fold boundary
+// (cos(query, query shifted 1 byte) = 0.68 against a 0.875 reach bar).  That was
+// the whole of analyze_training.ts's K2 phase-robustness gap: 15/18 → 18/18.
+//
+// WHY A RETRY AND NOT A PRE-FILTER — the regression this file pins.  Trimming
+// the query up front is ASYMMETRIC: it normalises the query but not the stored
+// forms, so it breaks byte-exact identity for a form trained WITH edge
+// whitespace.  Verified: pre-filtering broke test/04's ["  ice  ", "cold"] case.
+// The exact bytes are therefore tried FIRST and the trim is reached only when
+// they grounded nothing — which also means the retry costs nothing on any
+// answering path.
+//
+// NOTE ON WHAT IS AND IS NOT TESTABLE HERE.  The padded-query WIN cannot be
+// reproduced in a miniature fixture: a small store answers a padded query on the
+// first pass anyway (an earlier tier catches it), so the retry never fires and
+// an end-to-end assertion passes with or without the fix — verified, an earlier
+// version of this file did exactly that and guarded nothing.  What a fixture CAN
+// pin is the trim's own contract and the asymmetry regression, which is what
+// these tests do; the win itself is evidenced on the real store.
+
+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 { textEdgeTrim } from "../dist/src/canon.js";
+
+const enc = (s) => new TextEncoder().encode(s);
+const dec = new TextDecoder();
+const trim = (s) => dec.decode(textEdgeTrim(enc(s)));
+
+test("1. textEdgeTrim drops only the outer spacing run", () => {
+  assert.equal(trim("  ice  "), "ice");
+  assert.equal(trim("\tice\n"), "ice");
+  assert.equal(trim("ice"), "ice");
+  // INTERIOR whitespace is content and is never touched.
+  assert.equal(trim("  a  b  "), "a  b");
+  // All-separator and empty inputs collapse to empty rather than throwing.
+  assert.equal(trim("   "), "");
+  assert.equal(trim(""), "");
+  // The untouched case must return the SAME object (no copy on the hot path).
+  const b = enc("ice");
+  assert.equal(textEdgeTrim(b), b);
+});
+
+test("2. a form trained WITH edge whitespace still answers when asked exactly", async () => {
+  // The asymmetry regression: trimming the query but not the store would make
+  // this query miss its own deposited form.
+  const m = new Mind({ seed: 7 });
+  await m.ingest([["  ice  ", "cold"]]);
+  assert.equal(await m.respondText("  ice  "), "cold");
+});
+
+test("3. whitespace-only and empty queries are silent, not errors", async () => {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+  await m.ingest([["what is ice?", "ice is frozen water"]]);
+  for (const q of ["", " ", "   ", "\t\n"]) {
+    assert.equal(
+      await m.respondText(q),
+      "",
+      `expected silence for ${JSON.stringify(q)}`,
+    );
+  }
+  await m.store.close();
+});
+
+test("4. a padded query never answers something the unpadded one would not", async () => {
+  // The retry may add REACH, never licence: whatever padding does, it must not
+  // ground a fact for a question the store cannot answer.
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+  await m.ingest([
+    ["what is the capital of France?", "The capital of France is Paris."],
+    ["what is the capital of Spain?", "Madrid is the capital of Spain."],
+  ]);
+  for (const q of ["  Who wrote the Iliad?  ", "  xyzzy plugh quux  "]) {
+    const a = await m.respondText(q);
+    assert.doesNotMatch(
+      a,
+      /Paris|Madrid/,
+      `padding manufactured an answer for ${JSON.stringify(q)}: ${
+        JSON.stringify(a)
+      }`,
+    );
+  }
+  await m.store.close();
+});

package/test/67-climb-anchor-breadth.test.mjs

@@ -0,0 +1,113 @@
+// 67-climb-anchor-breadth.test.mjs — recall's scaffolding-dominated tier
+// trusts a consensus-climb anchor on its SCALE-INVARIANT breadth as well as on
+// its absolute IDF vote, and a breadth-qualified anchor must also be
+// DISCRIMINATIVE.
+//
+// WHY THE ABSOLUTE VOTE IS NOT ENOUGH.  Attention.breadth's own contract
+// (types.ts) already says it: the IDF vote is "an absolute, ln(N)-scaled
+// quantity that means 'strong' on a small store and 'weak' on a large one for
+// the SAME degree of genuine consensus", while breadth is "the fraction of the
+// query's OWN regions whose evidence this point accounts for" and "a point
+// whose breadth clears `dominates` … is real consensus".  Attention.peak's
+// contract makes the same point from the other side: a floor that prices ONE
+// region's evidence may not be compared against a POOLED SUM.
+//
+// Measured on the 15.7M-node trained store (N=325,615, floor = ln N + ½ =
+// 13.19).  The climb picked the RIGHT context and the floor discarded it, while
+// a junk attractor for a query that must stay SILENT outvoted every correct
+// anchor:
+//
+//   anchor the climb picked             vote   breadth  correct?
+//   "What is the chemical formula …"    10.60    0.556   RIGHT
+//   "Qual é a capital de França?"        8.19    0.667   RIGHT
+//   "Who wrote the play Romeo …?"        8.25    0.833   RIGHT
+//   "How do you say "good morning" …"   10.77    0.800   RIGHT
+//   "What is the commercial capital …"  12.69    0.333   Zamunda — MUST be silent
+//   "Menene sunan ginin mafi tsayi …"   12.79    0.214   wrong (Hausa)
+//
+// No vote threshold separates those; breadth > ½ separates them exactly.  On
+// that store the old floor was never cleared at all, so the tier was dead code
+// and 12 probes fell through to silence.
+//
+// WHAT MUST NOT REGRESS, and why the gate is an OR of two guarded readings:
+//
+//   • REPLACING the vote test with the breadth test broke 7 tests.  On a small
+//     store ln(N) is low, so the vote bar is the reading that legitimately
+//     fires there; and Attention.clusters' contract warns that "breadth starves
+//     a genuine, evenly-split multi-topic query, since no root in a real N-way
+//     split can exceed half the vote" — the two-topic fusion tests are exactly
+//     that shape.  Each reading is sufficient on its own evidence.
+//   • BREADTH ALONE fabricates.  On a one-context store every region trivially
+//     corroborates the only anchor there is, so breadth is 1 while the anchor's
+//     IDF is 0 — test/31 A2 answered a lone cat fact for "explain quantum
+//     chromodynamics".  Hence the companion condition: a region's IDF for an
+//     anchor reached through c of N contexts is ln(N/c), so requiring it past
+//     ln 2 requires c·2 < N — the same half-dominance reading in IDF units.
+
+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 = () =>
+  new Mind({ seed: 1, store: new SQliteStore({ path: ":memory:" }) });
+
+test("1. a one-context store never grounds an unrelated query (breadth alone must not decide)", async () => {
+  // Breadth is trivially 1 when there is only one anchor to corroborate, but
+  // that anchor's IDF is 0 — it says nothing.  VERIFIED to bite: dropping the
+  // `peak > ln 2` companion makes this fail (and test/31 A2 with it).  The
+  // fixture matches A2's exactly — `new Mind({ seed: 7 })`, the default store —
+  // because the same shape over a SQliteStore did NOT reproduce it.
+  const m = new Mind({ seed: 7 });
+  await m.ingest([["what is a cat?", "a cat is a small feline"]]);
+  const r = await m.respond("explain quantum chromodynamics");
+  assert.equal(
+    r.v,
+    null,
+    "a lone low-IDF anchor must not ground a foreign query",
+  );
+  assert.equal(r.provenance, undefined);
+});
+
+test("2. an evenly-split multi-topic query still fuses (breadth must not be required)", async () => {
+  // The shape Attention.clusters' contract says breadth starves: no root in a
+  // real N-way split can hold more than half the query's regions, so a
+  // breadth-only gate would refuse both topics.
+  const m = mk();
+  await m.ingest([
+    ["ice", "cold"],
+    ["fire", "hot"],
+    ["what is ice?", "ice is frozen water"],
+    ["what is fire?", "fire is rapid oxidation"],
+  ]);
+  const a = await m.respondText("ice fire");
+  assert.ok(a.length > 0, "a two-topic query must still ground something");
+  await m.store.close();
+});
+
+test("3. honest silence survives on an unrelated corpus", async () => {
+  const m = mk();
+  await m.ingest([
+    ["what is the capital of France?", "The capital of France is Paris."],
+    ["what is the capital of Spain?", "Madrid is the capital of Spain."],
+    ["what is the capital of Italy?", "Rome is the capital of Italy."],
+  ]);
+  for (const q of ["xyzzy plugh quux baz?", "qq8f3kz9 vv2m1x7w?"]) {
+    const a = await m.respondText(q);
+    assert.equal(a, "", `gibberish must stay silent, got ${JSON.stringify(a)}`);
+  }
+  await m.store.close();
+});
+
+test("4. a trained fact still answers (the tier did not displace an earlier one)", async () => {
+  const m = mk();
+  await m.ingest([
+    ["what is the capital of France?", "The capital of France is Paris."],
+    ["what is the capital of Spain?", "Madrid is the capital of Spain."],
+  ]);
+  assert.match(
+    await m.respondText("what is the capital of France?"),
+    /Paris/,
+  );
+  await m.store.close();
+});