@hviana/sema 0.8.1 → 0.8.3

package/test/106-the-join-fires.test.mjs

@@ -0,0 +1,94 @@
+// 106-the-join-fires.test.mjs — DIRECTION: the join reaches the subject the
+// query never wrote.
+//
+// THE GAP THIS CLOSES.  `deriveThrough` derives the answer THROUGH a produced
+// fact: the fact carries the subject the query never named, and the query's
+// remaining tail names the relation to follow FROM that subject.  Measured, the
+// rule never fired — and the report added for it (test/105) named the gate:
+// `leading.length === 0`.  The cause was then measured exactly: the recognition
+// of the fact's bytes returns EXACTLY ONE site — the fact itself — because a
+// STORED WHOLE stops the sweep, so the interior entity the join exists for was
+// never proposed, and the query was answered by gluing the intermediate KEY to
+// the fact (`The director of Eva is Gustaf Molander.gustaf molander country`).
+//
+// WHAT IS PINNED.
+//   1. the join FIRES: the answer is the second fact, reached through the
+//      subject the query never wrote (`The country of Gustaf Molander is
+//      Sweden.`);
+//   2. the rationale says so (`derive-through` is the move that reached it);
+//   3. the intermediate KEY never appears in the answer — the glued reading is
+//      what the query got before, and it is not an answer;
+//   4. a query with no tail is not a join at all: it is answered directly, and
+//      the move must not be claimed.
+//
+// The `canonicalQueryNodes` exclusion (the query's OWN subject, canonically) is
+// what keeps test/99's TRAP refused: its `Eiffel Tower country` is a deposited
+// node in canonical form while the query writes it capitalised, so a raw byte
+// test re-admitted it and the answer came back about Eiffel Tower.
+
+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 F1 = "The director of Eva is Gustaf Molander.";
+const F2 = "The country of Gustaf Molander is Sweden.";
+
+/** The measured chain, filed the way the real store files a fact: under BOTH
+ *  the entity and the key it was learnt with. */
+async function chain() {
+  const store = new SQliteStore({ path: ":memory:" });
+  const mind = new Mind({ seed: 7, store });
+  await mind.ingest([
+    ["eva", F1],
+    ["eva director", F1],
+    ["gustaf molander", F2],
+    ["gustaf molander country", F2],
+  ]);
+  return mind;
+}
+
+const text = (resp) => new TextDecoder().decode(resp.bytes).replace(/\0+/g, "");
+
+test("the join reaches the subject the query never wrote", async () => {
+  const mind = await chain();
+  const moves = [];
+  const out = text(
+    await mind.respond(
+      "eva director country",
+      (s) => moves.push(s.mechanism.at(-1)),
+    ),
+  );
+  assert.equal(out.trim(), F2);
+  assert.ok(
+    moves.includes("derive-through"),
+    `expected the join to be the move that reached it, got ${
+      [...new Set(moves)].join(", ")
+    }`,
+  );
+  await mind.store.close();
+});
+
+test("the intermediate key is never the answer", async () => {
+  const mind = await chain();
+  const out = text(await mind.respond("eva director country"));
+  assert.ok(
+    !out.includes("gustaf molander country"),
+    `the key is not an answer, got ${JSON.stringify(out)}`,
+  );
+  await mind.store.close();
+});
+
+test("a query with no tail is answered directly, not by a join", async () => {
+  const mind = await chain();
+  const moves = [];
+  const out = text(
+    await mind.respond("eva director", (s) => moves.push(s.mechanism.at(-1))),
+  );
+  assert.equal(out.trim(), F1);
+  assert.ok(
+    !moves.includes("derive-through"),
+    "there is nothing to join through when the query ends at the fact",
+  );
+  await mind.store.close();
+});

package/test/107-the-join-is-counted.test.mjs

@@ -0,0 +1,81 @@
+// 107-the-join-is-counted.test.mjs — the join's outcome is observable WITHOUT a
+// rationale.
+//
+// WHY THIS EXISTS.  Everything known about the fact join's refusals came from
+// the rationale, and the rationale PERTURBS the search: appending text to a
+// refusal note changed the answer of a traced response (measured, 386293e), and
+// the "key leads nowhere" refusal chased for four rounds turned out to be a
+// trace artifact — untraced, every refusal is a missing KEY, never a key whose
+// continuation is missing: a key that leads nowhere is not the relation at all,
+// so the scan moves on and there is no counter for it (the branch that reported
+// it was unreachable, and an adversarial review said so).
+// A work counter is the untraced view, and `meter.ts` is its one home
+// (AGENTS §6: a counter name exists in exactly one place).
+//
+// WHAT IS PINNED.  The four outcomes are published in the cost report with no
+// rationale attached.  The assertions stay TRUE when the join is fixed — they
+// check that the counters exist, that a join that fires is counted as fired, and
+// that a query whose join does not fire reports WHY in the counters — never that
+// a particular refusal still happens.
+
+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 F1 = "The director of Eva is Gustaf Molander.";
+const F2 = "The country of Gustaf Molander is Sweden.";
+const F3 = "The capital of Sweden is Stockholm.";
+
+async function chain() {
+  const store = new SQliteStore({ path: ":memory:" });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  await mind.ingest([
+    ["eva", F1],
+    ["eva director", F1],
+    ["gustaf molander", F2],
+    ["gustaf molander country", F2],
+    ["sweden", F3],
+    ["sweden capital", F3],
+  ]);
+  return mind;
+}
+
+const counters = (mind) => mind.lastCost?.counters ?? {};
+
+test("a join that fires is counted, with no rationale attached", async () => {
+  const mind = await chain();
+  await mind.respondText("eva director country"); // no inspectRationale
+  const c = counters(mind);
+  assert.ok(
+    (c.joinFired ?? 0) > 0,
+    "the join reached the second fact, so it must be counted as fired",
+  );
+  await mind.store.close();
+});
+
+test("a query whose join does not fire reports WHY, untraced", async () => {
+  const mind = await chain();
+  await mind.respondText("eva director country capital"); // no rationale
+  const c = counters(mind);
+  const refusals = (c.joinNoKey ?? 0) + (c.joinNoEntity ?? 0);
+  assert.ok(
+    refusals > 0,
+    "a join that did not fire must say so in the counters",
+  );
+  await mind.store.close();
+});
+
+test("the counters are deterministic across identical calls", async () => {
+  const a = await chain();
+  const b = await chain();
+  await a.respondText("eva director country capital");
+  await b.respondText("eva director country capital");
+  assert.deepEqual(
+    counters(a),
+    counters(b),
+    "same query + same store ⇒ same counted work",
+  );
+  await a.store.close();
+  await b.store.close();
+});

package/test/108-the-join-chains.test.mjs

@@ -0,0 +1,78 @@
+// 108-the-join-chains.test.mjs — DIRECTION, the other half: the result of one
+// join feeds the next.
+//
+// THE GAP THIS CLOSES.  The join's conclusion covered the WHOLE remaining tail
+// (`j = queryLen`), so it consumed everything and could only ever conclude: a
+// three-relation query got one join and stopped.  The whole-tail key was the
+// same defect seen from the key side — a two-relation tail names no learnt key
+// at all.
+//
+// THE FIX, and the measurement that found the last piece of it.  The key is the
+// SHORTEST tail prefix that BOTH resolves and leads somewhere, and the
+// conclusion covers only that prefix, leaving the rest of the tail for the next
+// step.  Resolving is not enough: a dry run of these very primitives showed the
+// first prefix that resolves for the candidate `Sweden` is the key `Sweden `
+// (trailing space) — which leads NOWHERE — while the key that names the fact
+// (`sweden capital`) sat one prefix further; accepting the first resolving key
+// refused the join.
+//
+// WHAT IS PINNED, untraced (a rationale perturbs the search — test/107):
+//   1. the answer is the THIRD fact, reached through two joins;
+//   2. `joinFired` counts exactly two — the counters are the untraced view;
+//   3. the two-relation query still counts exactly one, so chaining did not
+//      turn every join into a chain.
+
+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 F1 = "The director of Eva is Gustaf Molander.";
+const F2 = "The country of Gustaf Molander is Sweden.";
+const F3 = "The capital of Sweden is Stockholm.";
+
+async function chain() {
+  const store = new SQliteStore({ path: ":memory:" });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  await mind.ingest([
+    ["eva", F1],
+    ["eva director", F1],
+    ["gustaf molander", F2],
+    ["gustaf molander country", F2],
+    ["sweden", F3],
+    ["sweden capital", F3],
+  ]);
+  return mind;
+}
+
+const text = (resp) => new TextDecoder().decode(resp.bytes).replace(/\0+/g, "");
+
+test("a three-relation query reaches the third fact, through two joins", async () => {
+  const mind = await chain();
+  const out = text(await mind.respond("eva director country capital"));
+  assert.equal(out.trim(), F3, "the chain must reach the capital fact");
+  await mind.store.close();
+});
+
+test("the counters agree, with no rationale attached", async () => {
+  const mind = await chain();
+  await mind.respond("eva director country capital");
+  assert.equal(
+    mind.lastCost?.counters.joinFired ?? 0,
+    2,
+    "two joins reached it — the untraced view must agree with the answer",
+  );
+  await mind.store.close();
+});
+
+test("a two-relation query still joins exactly once", async () => {
+  const mind = await chain();
+  const out = text(await mind.respond("eva director country"));
+  assert.equal(out.trim(), F2);
+  assert.equal(
+    mind.lastCost?.counters.joinFired ?? 0,
+    1,
+    "chaining must not turn a single join into a chain",
+  );
+  await mind.store.close();
+});

package/test/109-the-pivot-is-counted.test.mjs

@@ -0,0 +1,60 @@
+// 109-the-pivot-is-counted.test.mjs — how far the reasoner hopped is a
+// BEHAVIOUR, so it is observable without a rationale.
+//
+// WHY THIS EXISTS.  EXTENSION (the study's gap 3): the pivot does not stop when
+// the question is already satisfied — it hops on while the answer still contains
+// an unconsumed learnt context (`reasoning.ts`: the loop breaks only on a null
+// pivot, a null forward step, an unchanged answer, or a restatement).  That is a
+// property of how far the chain went, and until now it was visible only through
+// `pivotStep` in the rationale — which PERTURBS the search (measured: appending
+// text to a refusal note changed a traced answer).  `meter.ts` is the untraced
+// view and the one home for a counter name (AGENTS §6).
+//
+// WHAT IS PINNED.  The pivot is counted on the fixture where the multi-hop
+// genuinely needs it (test/23's two-fact chain), untraced.  The assertion is
+// "at least one", so it stays true whether or not the EXTENSION fix changes how
+// many hops a satisfied question takes — the drift itself gets its own test
+// once the criterion for "satisfied" is measured.
+
+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";
+
+/** test/23's two-fact chain: the pivot is what crosses the hop. */
+async function pivotFixture() {
+  const store = new SQliteStore({ path: ":memory:" });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  await mind.ingest([
+    ["What is the capital of France", "The capital of France is Paris"],
+    ["Paris", "Paris is famous for the Eiffel Tower"],
+  ]);
+  return mind;
+}
+
+test("the pivot is counted, with no rationale attached", async () => {
+  const mind = await pivotFixture();
+  const out = await mind.respondText(
+    "What is the capital of France famous for",
+  );
+  assert.ok(
+    out.includes("Eiffel"),
+    `the multi-hop must still chain, got ${JSON.stringify(out)}`,
+  );
+  assert.ok(
+    (mind.lastCost?.counters.pivotSteps ?? 0) > 0,
+    "the hop was taken, so it must be counted",
+  );
+  await mind.store.close();
+});
+
+test("a query that needs no hop counts none", async () => {
+  const mind = await pivotFixture();
+  await mind.respondText("What is the capital of France");
+  assert.equal(
+    mind.lastCost?.counters.pivotSteps ?? 0,
+    0,
+    "a directly answered question pivots nowhere",
+  );
+  await mind.store.close();
+});

package/test/110-the-reasoner-stops-when-the-question-is-answered.test.mjs

@@ -0,0 +1,91 @@
+// 110-the-reasoner-stops-when-the-question-is-answered.test.mjs — EXTENSION: a
+// further chain link must not change the answer to a question already answered.
+//
+// THE GAP THIS CLOSES.  Every stopping condition in the pivot loop judged the
+// ANSWER; none asked whether the QUESTION was satisfied (reasoning.ts says so
+// in its own words).  Measured on a three-link chain, the reasoner took ONE hop
+// MORE than the question needed and REPLACED the satisfying answer:
+//
+//   elos=2  pivots=1 → "Paris is famous for the Eiffel Tower"   (the answer)
+//   elos=3  pivots=2 → "the Eiffel Tower is in Paris"           (one hop past it)
+//
+// THE INVARIANT (and the acceptance test, relational — no magic string):
+//
+//   adding a link to the corpus must NOT change the answer to a question the
+//   shorter corpus already answered.
+//
+// WHAT MAKES IT PRINCIPLED, and what each candidate cost.  Eight formulations
+// were measured and refuted before this one — including a count of extensions,
+// which is not a reason.  This one uses two data the mind already has:
+//   • the cost ladder's own `unaccounted` spans (what the grounding left
+//     uncovered) — passed to the reasoner by the pipeline;
+//   • the mind's own line between chance and evidence — one W-byte window —
+//     so an extension counts as progress only if it carries a window of the
+//     uncovered material;
+//   • and the pipeline's EXISTING condition for who owns a shape: "only a
+//     mechanism carrying its own `used` set (cast/join) gets this" — which is
+//     exactly `voiced.length > 0`, since `voiced` is what the mechanism
+//     withheld.  A producer owns its answer (test/29 C3's hop inside the
+//     comparison's seat fires); the reasoner's own extensions do not.
+//
+// It terminates by a real argument — the uncovered material is finite and each
+// taken extension must carry some of it — never by a depth limit.
+
+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 QUERY = "What is the capital of France famous for";
+
+/** The chain with `n` links: each fact's subject continues into the next. */
+const LINKS = [
+  ["What is the capital of France", "The capital of France is Paris"],
+  ["Paris", "Paris is famous for the Eiffel Tower"],
+  ["the Eiffel Tower", "the Eiffel Tower is in Paris"],
+];
+
+async function chain(n) {
+  const store = new SQliteStore({ path: ":memory:" });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  await mind.ingest(LINKS.slice(0, n));
+  return mind;
+}
+
+const text = (resp) => new TextDecoder().decode(resp.bytes).replace(/\0+/g, "");
+
+test("a longer corpus does not change an answer already given", async () => {
+  const short = await chain(2);
+  const long = await chain(3);
+  const answered = text(await short.respond(QUERY)).trim();
+  const extended = text(await long.respond(QUERY)).trim();
+  assert.equal(
+    extended,
+    answered,
+    "adding a link must not push the chain past the answer",
+  );
+  // The expected answer is the fixture's OWN second link — the relation the
+  // question asked for — not a string copied into the test.
+  assert.equal(answered, LINKS[1][1]);
+  await short.store.close();
+  await long.store.close();
+});
+
+test("the counters agree: one hop, not two — with no rationale attached", async () => {
+  const mind = await chain(3);
+  await mind.respond(QUERY);
+  assert.equal(
+    mind.lastCost?.counters.pivotSteps ?? 0,
+    1,
+    "the satisfying hop is taken and the drift is not",
+  );
+  await mind.store.close();
+});
+
+test("a question the first link already answers still takes no hop", async () => {
+  const mind = await chain(3);
+  const out = text(await mind.respond("What is the capital of France"));
+  assert.equal(out.trim(), "The capital of France is Paris");
+  assert.equal(mind.lastCost?.counters.pivotSteps ?? 0, 0);
+  await mind.store.close();
+});

package/test/111-the-cover-assembly-is-counted.test.mjs

@@ -0,0 +1,74 @@
+// 111-the-cover-assembly-is-counted.test.mjs — the connector assembly is
+// countable without a rationale.
+//
+// WHY THIS EXISTS.  LIMIT (the study's gap 4): a hub query's `cover.run` is 91%
+// of its time (`"Hello."`: 2.7 s of 3.0 s) and holds its ~270 MB peak, and none
+// of it was countable — `searchPushes` (3130) and `candidates` (2) do not see
+// the connector assembly, and the rationale perturbs the search.  `meter.ts` is
+// the untraced view and the one home for a counter name (AGENTS §6).
+//
+// WHAT THE COUNTERS IMMEDIATELY SETTLED, and it is why they exist: `"Hello."`
+// makes TWO bridge calls with 59 bytes of allowance — three orders of magnitude
+// below its ~270 MB peak — so the connector assembly is NOT that peak.  A
+// hypothesis dies to a counter instead of to an afternoon of profiling.
+//
+// WHAT IS PINNED.  Both counters are published, exercised by a fixture small
+// enough to be a fixture (two touching contexts), and deterministic across
+// identical calls.  They stay true whatever the LIMIT fix turns out to be.
+
+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";
+
+async function fixture(pairs) {
+  const store = new SQliteStore({ path: ":memory:" });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  await mind.ingest(pairs);
+  return mind;
+}
+
+test("the pairwise assembly is counted, with no rationale attached", async () => {
+  // Two contexts that TOUCH in the query (`ab`|`cd`), so the cover must bridge
+  // them pairwise.
+  const mind = await fixture([
+    ["ab", "x"],
+    ["cd", "y"],
+  ]);
+  const out = await mind.respondText("abcd");
+  const c = mind.lastCost?.counters ?? {};
+  assert.ok(
+    (c.coverBridges ?? 0) > 0,
+    "the cover bridged touching sites, so the calls must be counted",
+  );
+  assert.ok(out.length > 0, "and the answer still composes");
+  await mind.store.close();
+});
+
+test("the n-ary interior's allowance is counted", async () => {
+  // Three sites in one query: the n-ary path passes an allowance that grows
+  // with the intermediate answers' bytes — the quantity that would grow with a
+  // hub query's answers.
+  const mind = await fixture([
+    ["ab", "x"],
+    ["cd", "y"],
+    ["ab cd", "z"],
+  ]);
+  await mind.respondText("ab cd");
+  const c = mind.lastCost?.counters ?? {};
+  assert.ok(
+    (c.coverAllowanceBytes ?? 0) > 0,
+    "the n-ary interior ran, so its allowance must be counted",
+  );
+  await mind.store.close();
+});
+
+test("the counters are deterministic across identical calls", async () => {
+  const a = await fixture([["ab", "x"], ["cd", "y"]]);
+  const b = await fixture([["ab", "x"], ["cd", "y"]]);
+  await a.respondText("abcd");
+  await b.respondText("abcd");
+  assert.deepEqual(a.lastCost?.counters, b.lastCost?.counters);
+  await a.store.close();
+  await b.store.close();
+});

package/test/112-the-exploration-does-not-grow-with-the-hub.test.mjs

@@ -0,0 +1,89 @@
+// 112-the-exploration-does-not-grow-with-the-hub.test.mjs
+//
+// THE OFFER IS THE CORPUS'S STRUCTURE.  A chain hop offers the continuations the
+// corpus holds, and the search pays for exploring them on the ladder (every hop
+// costs STEP).  What must NOT happen is a combinatorial explosion: the work must
+// not grow with the SQUARE of the hub's degree.
+//
+// This file used to pin an offer CAP (`exploreCap`, with its invented
+// `PLURALITY` floor).  That cap is gone: it was a short-circuit — it bounded what
+// a hop could OFFER instead of charging for it — and it was not needed.  In the
+// regime where it used to bite (`hubBound = ceil(√N)` greater than the hub's
+// degree, reached here by choosing the degree below √N, so no trained store is
+// needed) the measured shape without it is LINEAR: degrees 35/70/120 gave offers
+// 52/84/120, pushes 262/296/332, perceptions 530/592/757 — while the peak was
+// identical with and without the cap (218/415/689 MB against 215/410/662),
+// because the peak is set by the store, not by the fan-out.  What made that hop
+// expensive was never the breadth of the offer: it was per-offer work, two
+// duplicate/oversized computations since removed.
+//
+// The residual, stated: the trained store's hub (degree 1 083) is an
+// EXTRAPOLATION from this linear shape, not a measurement.
+
+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 QUERY = "alpha beta";
+
+/** `alpha` leads to `beta`, and `beta` is a hub of `degree` continuations.
+ *
+ *  The filler keeps `edgeSourceCount()` above the square of the degree, so the
+ *  READ bound (`hubBound = ceil(√N)`) exceeds the hub's degree — the regime in
+ *  which the removed cap used to change the offer. */
+async function hub(degree) {
+  const store = new SQliteStore({ path: ":memory:", D: 1024 });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  const pairs = [
+    ["alpha", "beta"],
+    ["beta", "gamma"],
+  ];
+  for (let i = 0; i < degree; i++) {
+    pairs.push(["beta", `continuation number ${i} of this hub`]);
+  }
+  const filler = Math.ceil(degree * degree * 1.4);
+  for (let i = 0; i < filler; i++) {
+    pairs.push([`filler ${i} note`, `unrelated filler body ${i} here`]);
+  }
+  await mind.ingest(pairs);
+  return mind;
+}
+
+const pushes = (mind) => mind.lastCost?.counters.searchPushes ?? 0;
+const offers = (mind) => mind.lastCost?.counters.chainOffers ?? 0;
+
+test("the work does not explode with the hub's degree", async () => {
+  const small = await hub(20);
+  const big = await hub(80);
+  await small.respond(QUERY);
+  await big.respond(QUERY);
+  const a = pushes(small);
+  const b = pushes(big);
+  // The degree grows 4x.  An explosion multiplies the work by the SQUARE of
+  // that ratio — 16x — so the bound needs no invented number: it is the ratio's
+  // own square, and the measured shape is linear (about 4x).
+  assert.ok(
+    offers(big) > offers(small),
+    "the offer must follow the corpus's continuations: " +
+      `${offers(small)} → ${offers(big)}`,
+  );
+  assert.ok(
+    b < a * 16,
+    "work must not explode with the degree (4x degree would be 16x work): " +
+      `${a} → ${b}`,
+  );
+  await small.store.close();
+  await big.store.close();
+});
+
+test("and the hub still leads somewhere the chain can use", async () => {
+  const mind = await hub(40);
+  const out = (await mind.respondText(QUERY)).replace(/\0+/g, "").trim();
+  assert.ok(
+    out.length > 0,
+    `the hub must still be reachable, got ${JSON.stringify(out)}`,
+  );
+  assert.ok(offers(mind) > 0, "and the chain hop must have been taken");
+  await mind.store.close();
+});

package/test/113-the-rationale-payload-is-bounded.test.mjs

@@ -0,0 +1,84 @@
+// 113-the-rationale-payload-is-bounded.test.mjs — a step reports a BOUNDED
+// sample and the COUNT, never the whole field.
+//
+// THE GAP THIS CLOSES.  The study measured a rationale step carrying 1082 items
+// and another 1559 — the hub's degree and `hubBound`'s own size, both on the
+// trained store.  The step that does it is `disambiguate`: it weighed a hub's
+// continuations and emitted EVERY candidate it considered as an output item.
+// A rationale that carries the entire field is not an explanation, it is a dump:
+// what explains the choice is the pick, the count that says how wide the field
+// was, and a bounded sample of what it was chosen from.
+//
+// WHAT IS PINNED, and neither number is invented here:
+//   1. the sample is bounded by the DECLARED candidate budget (`recallQueryK`,
+//      config.ts — a capacity/budget, which is all that file holds);
+//   2. the note still carries the TOTAL, so nothing is lost — measured in the
+//      fixture below: 27 continuations weighed, 12 itemised;
+//   3. the choice itself is untouched (the inputs still name the pick).
+
+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 { DEFAULT_CONFIG } from "../dist/src/config.js";
+
+// The DECLARED capacity, read from the config — no number is copied here.
+const BUDGET = DEFAULT_CONFIG.rationaleSampleK;
+
+const WORDS =
+  ("alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima " +
+    "mike november oscar papa quebec romeo sierra tango uniform victor whiskey " +
+    "xray yankee zulu amber bronze copper dahlia ember fjord gossamer harbour " +
+    "indigo jasmine kestrel lantern marigold nectar opal pewter quartz ripple " +
+    "saffron thistle umber violet willow xenon yarrow").split(" ");
+
+/** A hub of 40 continuations, plus filler so `hubBound` exceeds the budget. */
+async function hub() {
+  const store = new SQliteStore({ path: ":memory:", D: 1024 });
+  // RECALL's budget is deliberately enormous: the rationale's sample must not
+  // follow it (found by an adversarial review — sharing `recallQueryK` meant
+  // this very setting un-bounded the payload).
+  const mind = new Mind({
+    seed: 7,
+    store,
+    profile: true,
+    recallQueryK: 100000,
+  });
+  const w = (i, n) => WORDS[(i * 7 + n * 13) % WORDS.length];
+  const pairs = [];
+  for (let i = 0; i < 40; i++) {
+    pairs.push(["beta", `continuation number ${i} of this hub`]);
+  }
+  for (let i = 0; i < 900; i++) {
+    pairs.push([
+      `${w(i, 1)} ${w(i, 2)} ${w(i, 3)} ${i}`,
+      `${w(i, 4)} ${w(i, 5)} ${w(i, 6)} ${w(i, 7)} ${i}`,
+    ]);
+  }
+  await mind.ingest(pairs);
+  return mind;
+}
+
+test("a step reports a bounded sample, and the count of the whole field", async () => {
+  const mind = await hub();
+  const steps = [];
+  await mind.respondText("beta", (s) => steps.push(s));
+  const dis = steps.filter((s) => s.mechanism.at(-1) === "disambiguate");
+  assert.ok(dis.length > 0, "the fixture must make the decider weigh a hub");
+  const step = dis[0];
+  const outs = step.outputs ?? [];
+  assert.ok(
+    outs.length <= BUDGET,
+    `the sample must fit the declared budget, got ${outs.length}`,
+  );
+  const total = Number(
+    /(\d+)\s+continuations/.exec(String(step.note))?.[1] ?? 0,
+  );
+  assert.ok(total > 0, "the note must say how wide the field was");
+  assert.ok(
+    total >= outs.length,
+    "the count is the WHOLE field, not the sample",
+  );
+  assert.equal((step.inputs ?? []).length, 1, "the pick is still named");
+  await mind.store.close();
+});