@hviana/sema 0.8.1 → 0.8.3

package/test/114-alignment-budget-is-per-sweep.test.mjs

@@ -0,0 +1,93 @@
+// 114-alignment-budget-is-per-sweep.test.mjs — each alignment sweep owns its
+// budget, so the NEAREST continuation survives either side's exhaustion.
+//
+// THE DEFECT THIS CLOSES (found by an adversarial review of the E3 commit).
+// `alignAround` bounds the work it may spend on (queryGap, contextGap) pairs.
+// The counter was shared between the RIGHT sweep and the LEFT sweep, so once the
+// right side spent the whole budget the left loop's guard was false on entry:
+// zero iterations, and the NEAREST left continuation was lost — the exact
+// opposite of the law the commit states ("an exhausted budget drops the FAR
+// continuations and never the near ones").  It was a regression against the
+// pre-change tree, which bounded each sweep independently.
+//
+// WHAT IS PINNED, structurally and with no magic number: a pair whose two
+// divergent flanks both exceed the work budget still aligns on BOTH sides of the
+// anchor — the left match is present as its own query span, and so is the right.
+// Before the fix the left one is missing, whatever the budget.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { alignAround } from "../dist/src/mind/match.js";
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/** The minimal context `alignAround` reads.  There is no budget to inject any
+ *  more: the sweep's work is proportional to the bytes a run spans. */
+const ctxWith = () => ({ space: { maxGroup: 4 } });
+
+/** A shared head, a shared anchor, and divergent flanks on both sides. */
+function pair(flankLen) {
+  const q = `MATCH${"a".repeat(6)}SEED${"Q".repeat(flankLen)}`;
+  const c = `MATCH${"b".repeat(11)}SEED${"W".repeat(flankLen)}`;
+  return { q, c, at: q.indexOf("SEED") };
+}
+
+const spansOf = (res, text, needle) => {
+  const target = enc.encode(needle);
+  return res.matched.filter(([s, e]) => {
+    const got = enc.encode(text).subarray(s, e);
+    return got.length >= target.length &&
+      dec.decode(got).includes(needle);
+  });
+};
+
+test("both sides of the anchor align even when each flank exceeds the budget", () => {
+  // The budget must be reachable for the NEAR left continuation (its own
+  // 6+11-byte gap costs on the order of a hundred pair-explorations) and must be
+  // EXHAUSTED by the right flank (40x40 divergent bytes cost many hundreds).
+  // 512 sits between the two: it is the range where a shared counter starves the
+  // left sweep and a per-sweep one does not.
+  const { q, c, at } = pair(40);
+  for (const budget of [512, 4096]) {
+    const res = alignAround(
+      ctxWith(budget),
+      enc.encode(q),
+      enc.encode(c),
+      at,
+      at,
+    );
+    assert.ok(
+      spansOf(res, q, "MATCH").length > 0,
+      `the nearest LEFT continuation must survive the right sweep's budget ` +
+        `(budget ${budget}, matched ${JSON.stringify(res.matched)})`,
+    );
+    assert.ok(
+      spansOf(res, q, "SEED").length > 0,
+      "and the anchor itself is of course still matched",
+    );
+  }
+});
+
+test("the run chosen is the one with the smallest total gap", () => {
+  // The criterion the enumeration used to compute, now computed by the walk:
+  // smallest qGap + cGap, ties to the smaller query gap.  Two continuations are
+  // offered at different totals and the NEARER one must win.
+  const enc = new TextEncoder();
+  const head = "common head ";
+  const far = "FAR";
+  const near = "NEAR";
+  const q = enc.encode(
+    head + "x".repeat(4) + near + "q" + "z".repeat(30) + far,
+  );
+  const c = enc.encode(head + "y".repeat(9) + near + "c");
+  const at = head.length - 1;
+  const { matched } = alignAround(ctxWith(), q, c, at, at);
+  const got = matched.map(([a, b]) =>
+    new TextDecoder().decode(q.subarray(a, b))
+  );
+  assert.ok(
+    got.includes("NEAR"),
+    "the nearest continuation must be found: " + JSON.stringify(got),
+  );
+});

package/test/116-the-extension-is-gated-by-the-pipelines-own-remainder.test.mjs

@@ -0,0 +1,100 @@
+// 116-the-extension-is-gated-by-the-pipelines-own-remainder.test.mjs — EXTENSION
+// judges the question by the pipeline's remainder, with the pipeline's W floor.
+//
+// TWO CORRECTIONS FROM THE ADVERSARIAL REVIEW, in one definition:
+//
+//  M3 — the reasoner's `uncovered` was built from the ladder's `accounted`, a
+//  COST quantity.  The pipeline itself documents that `accounted` can be EMPTY
+//  while nothing is unexplained (a query fully explained by one computed span
+//  plus bridged connectors), and it already builds the genuine remainder as
+//  `[...decided.accounted, ...pre.computed]`.  The reasoner now uses that same
+//  reading — computed once, used by both the extension gate and the fuse gate.
+//
+//  M4 — the boundary.  The pipeline treats a remainder under W as bridging
+//  punctuation, and the reasoner inherits that floor.  The subtlety the review
+//  raised is that a one-word tail CARRIES ITS SEPARATOR: `" why"` is exactly W
+//  bytes, so it IS a remainder and licenses no extension, while `" famous for"`
+//  is well over and does.  Both sides are pinned here, because the boundary is
+//  where the reviewer's own demonstration sat.
+
+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 LINKS = [
+  ["What is the capital of France", "The capital of France is Paris"],
+  ["Paris", "Paris is famous for the Eiffel Tower"],
+];
+
+/** The test/110 chain: the second link is reachable only by hopping. */
+async function chain() {
+  const store = new SQliteStore({ path: ":memory:", D: 1024 });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  await mind.ingest(LINKS);
+  return mind;
+}
+
+const text = (resp) =>
+  new TextDecoder().decode(resp.bytes).replace(/\0+/g, "").trim();
+
+test("a remainder the pipeline calls real licenses the hop", async () => {
+  const mind = await chain();
+  const out = text(
+    await mind.respond("What is the capital of France famous for"),
+  );
+  assert.equal(
+    out,
+    LINKS[1][1],
+    "a remainder well over one window must still reach the next link",
+  );
+  await mind.store.close();
+});
+
+test("a one-word remainder is exactly one window, and licenses nothing", async () => {
+  // `" why"` is W bytes once its separator is counted: per the pipeline's own
+  // floor it is a remainder, and per the extension law a remainder the step
+  // cannot carry licenses no hop — so the grounded fact stands, AND the refusal
+  // is visible: a brake that leaves no trace is the silent cut AGENTS §6
+  // forbids, so the rationale must say the extension was declined for want of
+  // question material.
+  const mind = await chain();
+  const steps = [];
+  const out = text(
+    await mind.respond(
+      "What is the capital of France why",
+      (s) => steps.push(s),
+    ),
+  );
+  assert.equal(
+    out,
+    LINKS[0][1],
+    "a step carrying none of the remainder must not be taken",
+  );
+  const refused = steps.find((s) => s.mechanism.at(-1) === "pivotRefused");
+  assert.ok(refused, "the refusal must be reported, not silent");
+  assert.match(
+    String(refused.note),
+    /carries none of the question material/,
+    "and it must say why it refused",
+  );
+  assert.ok(
+    (refused.outputs ?? []).length > 0,
+    "and name the material it left uncovered",
+  );
+  await mind.store.close();
+});
+
+test("a computed-span query has no phantom remainder (M3)", async () => {
+  // A pure computation: the ladder's `accounted` is not a coverage reading, so
+  // the reasoner must not see a remainder the pipeline says is not there.  The
+  // check is that the answer is the computed one and the engine is not dragged
+  // into an unrelated chain.
+  const mind = await chain();
+  const out = text(await mind.respond("2+2"));
+  assert.ok(
+    out.length > 0,
+    `a computation must still be answered, got ${JSON.stringify(out)}`,
+  );
+  await mind.store.close();
+});

package/test/117-corpus-search.test.mjs

@@ -0,0 +1,171 @@
+// 117-corpus-search.test.mjs — reading the trained memory back out of the DAG.
+//
+// WHAT IS PINNED.  Two methods and their division of labour:
+//   • `searchCorpus(bytes, limit?)` — MULTIMODAL: bytes in, bytes out, no notion
+//     of text or encoding anywhere in it;
+//   • `searchCorpusText(text, limit?)` — the text case, which encodes, calls the
+//     multimodal one, and decodes.  The search itself exists ONCE (src/mind/
+//     corpus.ts, over the machinery an answer already uses: `recognise` for the
+//     resolved subtrees, `edgeAncestors` for the climb, `nextFirst` for the
+//     continuation).
+//
+// Both are deterministic (same seed, same order, same query ⇒ byte-identical
+// results), both report a miss as a STATE in the byte layer and as prose only in
+// the text layer, and browsing takes the caller's own offset instead of a random
+// draw.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind, SQliteStore } from "../dist/src/index.js";
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/** A small deposited corpus: three experience pairs, no trained store needed. */
+async function fixture() {
+  const mind = new Mind({
+    seed: 7,
+    store: new SQliteStore({ path: ":memory:" }),
+  });
+  await mind.ingest([
+    ["the capital of France", "Paris is the capital of France."],
+    ["the capital of Portugal", "Lisbon is the capital of Portugal."],
+    ["who wrote Hamlet", "Shakespeare wrote Hamlet."],
+  ]);
+  return mind;
+}
+
+const asText = (b) => dec.decode(b).replace(/\0+/g, "").trim();
+
+test("the multimodal search takes bytes and returns bytes", async () => {
+  const mind = await fixture();
+  const result = mind.searchCorpus(enc.encode("the capital of France"));
+  assert.ok(result.pairs.length > 0, "the deposited pair must be found");
+  const pair = result.pairs[0];
+  assert.ok(pair.context instanceof Uint8Array, "context is BYTES, not text");
+  assert.ok(pair.continuation instanceof Uint8Array);
+  assert.ok(typeof pair.contextId === "number");
+  assert.ok(asText(pair.context).includes("capital"));
+  assert.equal(result.browsed, false);
+  assert.equal(result.miss, "matched");
+  assert.ok(result.totalContexts > 0, "the store's own context count is read");
+  await mind.store.close();
+});
+
+test("the text helper is the SAME search, converted", async () => {
+  const mind = await fixture();
+  const bytes = mind.searchCorpus(enc.encode("the capital of France"));
+  const text = mind.searchCorpusText("the capital of France");
+  assert.equal(
+    text.pairs.length,
+    bytes.pairs.length,
+    "one search, two views — the helper must not run a second one",
+  );
+  assert.equal(text.pairs[0].contextId, bytes.pairs[0].contextId);
+  assert.equal(typeof text.pairs[0].context, "string");
+  assert.ok(text.pairs[0].context.includes("capital"));
+  assert.equal(text.note, undefined, "a match needs no note");
+  await mind.store.close();
+});
+
+test("both are deterministic across identical calls", async () => {
+  const mind = await fixture();
+  const a = mind.searchCorpus(enc.encode("the capital of France"));
+  const b = mind.searchCorpus(enc.encode("the capital of France"));
+  assert.deepEqual(
+    a.pairs.map((p) => [p.contextId, p.continuationId, asText(p.context)]),
+    b.pairs.map((p) => [p.contextId, p.continuationId, asText(p.context)]),
+    "same store + same query ⇒ the same pairs in the same order",
+  );
+  assert.deepEqual(
+    mind.searchCorpusText("the capital of France").pairs,
+    mind.searchCorpusText("the capital of France").pairs,
+  );
+  await mind.store.close();
+});
+
+test("a miss is a state in bytes and prose only in text", async () => {
+  const mind = await fixture();
+  const bytes = mind.searchCorpus(enc.encode("zzzq nothing at all"));
+  assert.equal(bytes.pairs.length, 0);
+  assert.ok(
+    bytes.miss === "nothing-resolved" || bytes.miss === "no-continuations",
+    `the byte layer reports a STATE, got ${bytes.miss}`,
+  );
+  assert.equal(bytes.note, undefined, "no prose in the byte layer");
+  const text = mind.searchCorpusText("zzzq nothing at all");
+  assert.equal(text.pairs.length, 0);
+  assert.equal(typeof text.note, "string", "the text layer says it in words");
+  await mind.store.close();
+});
+
+test("determinism holds ACROSS instances, not just across calls", async () => {
+  // The invariant is about the engine, not about one object: the same seed,
+  // the same deposit order and the same query must give byte-identical results
+  // from a FRESH Mind over a fresh store built the same way — both for a search
+  // (whose ids come from the store's intern order) and for a browse.
+  const a = await fixture();
+  const b = await fixture();
+  const shape = (r) =>
+    r.pairs.map((p) => [
+      p.contextId,
+      p.continuationId,
+      p.matchedBytes,
+      Array.from(p.context),
+      Array.from(p.continuation),
+    ]);
+  assert.deepEqual(
+    shape(a.searchCorpus(enc.encode("the capital of France"))),
+    shape(b.searchCorpus(enc.encode("the capital of France"))),
+    "two fresh minds over identically-built stores must agree byte for byte",
+  );
+  assert.deepEqual(
+    shape(a.sampleCorpus(2)),
+    shape(b.sampleCorpus(2)),
+    "and browsing must agree too — no draw from outside the seed",
+  );
+  assert.deepEqual(
+    shape(a.sampleCorpus(2, 0.25)),
+    shape(b.sampleCorpus(2, 0.25)),
+  );
+  await a.store.close();
+  await b.store.close();
+});
+
+test("a browse never shows the same context twice", async () => {
+  // Found by mutating the determinism test: on a store small relative to the
+  // probe budget the id stride revisits ids, so a browse returned the SAME pair
+  // over and over (measured: six copies of context #4 for `limit: 6`).
+  const mind = await fixture();
+  const r = mind.sampleCorpus(6);
+  const ids = r.pairs.map((p) => p.contextId);
+  assert.equal(
+    new Set(ids).size,
+    ids.length,
+    `every browsed pair must be a different context, got ${
+      JSON.stringify(ids)
+    }`,
+  );
+  await mind.store.close();
+});
+
+test("browsing is deterministic, and `from` moves the window", async () => {
+  const mind = await fixture();
+  const a = mind.sampleCorpus(2);
+  const b = mind.sampleCorpus(2);
+  assert.ok(
+    a.pairs.length >= 2,
+    "the fixture must yield at least two DISTINCT samples, or this proves nothing",
+  );
+  assert.deepEqual(
+    a.pairs.map((p) => [p.contextId, p.continuationId]),
+    b.pairs.map((p) => [p.contextId, p.continuationId]),
+    "browsing must not draw randomly",
+  );
+  const other = mind.sampleCorpus(2, 0.5);
+  assert.ok(
+    other.pairs.every((p) => p.matchedBytes === 0),
+    "browse samples carry no query match",
+  );
+  await mind.store.close();
+});

package/test/118-the-join-reaches-a-key-off-the-cut.test.mjs

@@ -0,0 +1,74 @@
+// 118-the-join-reaches-a-key-off-the-cut.test.mjs — a deposited, CONTINUING key
+// must be reachable even when its boundary is not a fold cut of the tail.
+//
+// WHY THIS EXISTS.  The join builds `key = fact.bytes ‖ tail[0..len]` and used to
+// try only the tail's own fold boundaries (plus its end).  A boundary is not a
+// proxy for a stored key's end: a deposited member's end is the end of ITS OWN
+// stream, and the fold never emits a cut at a stream's end (geometry's `emit`
+// guards `at >= n`) — so the boundary that names a real stored key can sit
+// between cuts, or beyond every one of them.  Measured on the five-fact chain
+// below: the fourth hop's key "stockholm mayor" exists (resolve() finds it), its
+// continuation is the mayor fact, and its boundary (p = 6) is NOT among the
+// tail's cuts ([4,7]) — so the join could not try it and the answer stopped at
+// the third fact.
+//
+// The candidate ends are now the prefixes that ARE stored nodes, ascending, from
+// the host's `contentKeyEnds` — so the shortest name still wins, and every
+// deposited key is reachable.
+//
+// WHAT IS PINNED.  The chain reaches the FIFTH fact, and the join fires at least
+// four times.  The counters are the untraced view (AGENTS §6: profile without a
+// trace attached).
+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.";
+const F4 = "The mayor of Stockholm is Karin Wanngard.";
+const F5 = "The party of Karin Wanngard is the Social Democrats.";
+
+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],
+    ["stockholm", F4],
+    ["stockholm mayor", F4],
+    ["karin wanngard", F5],
+    ["karin wanngard party", F5],
+  ]);
+  return { mind, store };
+}
+
+const text = (resp) => new TextDecoder().decode(resp.bytes).replace(/\0+/g, "");
+
+test("a five-fact chain reaches the fifth fact, through four joins", async () => {
+  const { mind, store } = await chain();
+  const out = text(
+    await mind.respond("eva director country capital mayor party"),
+  ).trim();
+  const fired = mind.lastCost?.counters.joinFired ?? 0;
+  await store.close();
+
+  assert.equal(
+    out,
+    F5,
+    `the chain must reach the fifth fact. A key that EXISTS and LEADS ON ` +
+      `("stockholm mayor" → the mayor fact) was not tried because its boundary ` +
+      `is not a cut of the tail alone — the join was asked to extend from the ` +
+      `third fact and stopped (joinFired=${fired})`,
+  );
+  assert.ok(
+    fired >= 4,
+    `the join must fire once per licensed hop (measured ${fired}); four hops ` +
+      `were available: eva→gustaf molander→sweden→stockholm→karin wanngard`,
+  );
+});

package/test/119-the-work-does-not-grow-with-the-corpus.test.mjs

@@ -0,0 +1,122 @@
+// 119-the-work-does-not-grow-with-the-corpus.test.mjs — the derivation's work
+// must be FLAT in the corpus for a byte-identical answer.
+//
+// THE LAW.  bounded-reads.md forbids per-query work that grows with N: a bigger
+// store may answer differently (a better derivation can exist), but it must not
+// buy arbitrary COMPUTATION for the same answer.  test/89 measures this for the
+// completion recursion against real prose, test/14 for recall reads; this closes
+// the loop for the derivation as a whole after the F3/F4 migrations, where the
+// hop allowance stopped deciding depth and the pivot's probe sweep got its own
+// capacity.
+//
+// THE BARS ARE THE REPO'S OWN, not new numbers (trap 4).  test/89 asserts
+// `k < 0.6` for its `searches` (nested solve() calls — the recursion, which its
+// fix governs end to end; measured 1.28 unfixed → 0.38 fixed) and `k < 1` for
+// agenda pops — "only outright linear growth is the forbidden case … so this
+// asserts the law itself", measured 1.40 unfixed → 0.54 fixed.  Same helper as
+// test/14 (`logLogSlope`), copied because suites here are standalone.
+//
+// MEASURED BEFORE THIS TEST EXISTED, on the fixture below, one call per size:
+// pops 338 / 338 / 338 / 338 (k = 0.000), searches 2 everywhere, one pivot, and
+// a byte-identical answer — flat, and flat by a wide margin.
+
+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";
+
+/** Power-law exponent k in t ≈ c·n^k, by log–log least squares.
+ *  k≈0 flat · k≈1 linear · k≈2 quadratic.  (test/14's helper.) */
+function logLogSlope(sizes, times) {
+  const n = sizes.length;
+  const xs = sizes.map(Math.log), ys = times.map(Math.log);
+  const mx = xs.reduce((a, b) => a + b, 0) / n;
+  const my = ys.reduce((a, b) => a + b, 0) / n;
+  let num = 0, den = 0;
+  for (let i = 0; i < n; i++) {
+    num += (xs[i] - mx) * (ys[i] - my);
+    den += (xs[i] - mx) ** 2;
+  }
+  return num / den;
+}
+
+const WORDS =
+  ("alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima " +
+    "mike november oscar papa").split(" ");
+
+/** A three-fact chain the query closes through (test/110's LINKS), plus `n`
+ *  unrelated pairs so the corpus grows without touching the derivation. */
+const QUERY = "What is the capital of France famous for";
+
+async function measure(n) {
+  const store = new SQliteStore({ path: ":memory:" });
+  const mind = new Mind({ seed: 7, store, profile: true });
+  const pairs = [
+    ["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"],
+  ];
+  for (let i = 0; i < n; i++) {
+    pairs.push([
+      `note ${i} about ${WORDS[i % 16]} ${WORDS[(i * 3) % 16]}`,
+      `the ${WORDS[i % 16]} of ${WORDS[(i * 5) % 16]} is ${
+        WORDS[(i * 7) % 16]
+      } ${i}`,
+    ]);
+  }
+  await mind.ingest(pairs);
+  const answer = String(await mind.respondText(QUERY)).trim();
+  const c = mind.lastCost.counters;
+  await store.close();
+  return { answer, pops: c.searchPops ?? 0, searches: c.searches ?? 0 };
+}
+
+test("a bigger corpus does not buy more work for the same answer", async () => {
+  const base = 250;
+  const sizes = [];
+  const pops = [];
+  const searches = [];
+  const answers = [];
+  for (const mult of [1, 2, 4, 8]) {
+    const n = base * mult;
+    const r = await measure(n);
+    sizes.push(n);
+    pops.push(r.pops);
+    searches.push(r.searches);
+    answers.push(r.answer);
+    console.log(
+      `    N=${n} → pops ${r.pops}, searches ${r.searches}, ` +
+        `answer "${r.answer.slice(0, 32)}"`,
+    );
+  }
+
+  // The answer is the CONTROL: same answer, eight times the corpus.  Without
+  // this the exponents below could be flat because the query stopped being
+  // answered at all.
+  assert.equal(
+    new Set(answers).size,
+    1,
+    `the answer must not move with the corpus (got ${JSON.stringify(answers)})`,
+  );
+
+  const kSearches = logLogSlope(sizes, searches);
+  const kPops = logLogSlope(sizes, pops);
+  console.log(
+    `    growth exponents over N→8N: searches k=${kSearches.toFixed(2)}, ` +
+      `pops k=${kPops.toFixed(2)}`,
+  );
+
+  assert.ok(
+    kSearches < 0.6,
+    `nested searches grew with exponent k=${kSearches.toFixed(2)} in corpus ` +
+      `size (${searches.join(" → ")}) for a byte-identical answer`,
+  );
+  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 bounded-reads.md forbids outright`,
+  );
+});