@hviana/sema 0.3.0 → 0.4.0

package/test/55-cost-meter.test.mjs

@@ -0,0 +1,284 @@
+// 55-cost-meter.test.mjs — the cross-stack computational-usage meter
+// (src/meter.ts).
+//
+// The meter's four contracts, one test each:
+//   1. OFF BY DEFAULT — an unprofiled Mind never attaches one, and the store
+//      is left with no meter after a response either way.
+//   2. NEVER READ BY INFERENCE — profiled and unprofiled answers are
+//      byte-identical, and so is the provenance.
+//   3. COUNTS ARE DETERMINISTIC — the same query on the same store meters
+//      identically (only the millisecond fields may differ).
+//   4. THE WHOLE STACK REPORTS — store reads, perception, recognition,
+//      the mechanism market and the graph search all appear.
+//
+// Plus the two aggregation helpers (sumReports, formatReport) and the
+// multi-turn lifecycle (respondTurn meters through the SAME beginResponse /
+// endResponse pair respond() uses).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { formatReport, Mind, sumReports } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const mk = (opts = {}) =>
+  new Mind({ seed: 1, store: new SQliteStore({ path: ":memory:" }), ...opts });
+
+/** A small store with enough structure that every layer does some work. */
+async function trained(opts) {
+  const mind = mk(opts);
+  await mind.ingest([
+    ["the capital of France is", " Paris"],
+    ["the capital of Japan is", " Tokyo"],
+    ["the capital of Italy is", " Rome"],
+    ["Paris is in", " Europe"],
+    ["Tokyo is in", " Asia"],
+  ]);
+  return mind;
+}
+
+const QUERY = "the capital of France is";
+
+test("1. profiling is off by default and leaves no meter on the store", async () => {
+  const mind = await trained();
+  assert.equal(mind.lastCost, null);
+  await mind.respondText(QUERY);
+  assert.equal(mind.lastCost, null, "no report without { profile: true }");
+  assert.equal(mind.store.meter, null, "store meter never attached");
+  assert.equal(mind.meter, null);
+  await mind.store.close();
+});
+
+test("2. profiling never changes the answer", async () => {
+  const plain = await trained();
+  const profiled = await trained({ profile: true });
+
+  for (const q of [QUERY, "Paris is in", "the capital of Japan is", "zzz"]) {
+    const a = await plain.respond(q);
+    const b = await profiled.respond(q);
+    assert.deepEqual(
+      Array.from(b.bytes),
+      Array.from(a.bytes),
+      `answer changed under profiling for "${q}"`,
+    );
+    assert.equal(b.provenance, a.provenance);
+  }
+  await plain.store.close();
+  await profiled.store.close();
+});
+
+test("3. the meter is detached and the report published after each response", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+
+  assert.equal(mind.meter, null, "meter torn down with the response");
+  assert.equal(mind.store.meter, null, "store detached — no cross-charging");
+
+  const r = mind.lastCost;
+  assert.ok(r, "a report was published");
+  assert.equal(r.version, 1);
+  assert.equal(r.queryBytes, QUERY.length);
+  assert.ok(r.elapsedMs >= 0);
+  await mind.store.close();
+});
+
+test("4. counters are deterministic across identical calls on identical stores", async () => {
+  const a = await trained({ profile: true });
+  const b = await trained({ profile: true });
+  await a.respondText(QUERY);
+  await b.respondText(QUERY);
+  assert.deepEqual(
+    a.lastCost.counters,
+    b.lastCost.counters,
+    "same query + same store ⇒ same work; a diff here is a real regression",
+  );
+  // Phase CALL counts are deterministic too (their millisecond totals are not).
+  const calls = (r) =>
+    Object.fromEntries(
+      Object.entries(r.phases).map(([k, v]) => [k, v.calls]),
+    );
+  assert.deepEqual(calls(a.lastCost), calls(b.lastCost));
+  await a.store.close();
+  await b.store.close();
+});
+
+test("5. every layer of the stack reports", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+  const c = mind.lastCost.counters;
+
+  // Store layer — identity, content, structure.
+  assert.ok(c.leafLookups > 0, "content-addressed leaf lookups counted");
+  assert.ok(c.branchLookups > 0, "content-addressed branch lookups counted");
+  assert.ok(c.byteReads > 0, "node byte reads counted");
+  assert.ok(c.bytesRead > 0, "read VOLUME counted, not just call count");
+
+  // Mind layer — perception and recognition.
+  assert.ok(c.perceptions > 0, "perceptions counted");
+  assert.ok(c.perceivedBytes >= c.perceptions, "perceived volume counted");
+  assert.ok(c.recognitions > 0, "recognitions counted");
+  assert.ok(c.resolves > 0, "identity resolutions counted");
+
+  // The mechanism market — every mechanism was offered the query.
+  assert.ok(
+    c.mechanismFloors + c.mechanismSkips >= 5,
+    "each built-in mechanism's floor() was accounted",
+  );
+  assert.ok(c.mechanismRuns > 0, "at least one mechanism ran");
+  assert.ok(c.candidates > 0, "candidates weighed");
+
+  // Phases are per-mechanism and named after the mechanism itself.
+  const phases = Object.keys(mind.lastCost.phases);
+  assert.ok(phases.includes("think"));
+  assert.ok(phases.includes("articulate"));
+  assert.ok(
+    phases.some((p) => p.endsWith(".floor")),
+    "per-mechanism floor phases present",
+  );
+  await mind.store.close();
+});
+
+test("6. zero-valued counters are omitted, and no bookkeeping leaks in", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+  const c = mind.lastCost.counters;
+  for (const [k, v] of Object.entries(c)) {
+    assert.notEqual(v, 0, `${k} is zero and should have been dropped`);
+    assert.ok(!k.startsWith("_"), `${k} is meter bookkeeping, not work`);
+  }
+  await mind.store.close();
+});
+
+test("7. a bigger query costs more than a smaller one", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText("Paris");
+  const small = mind.lastCost.counters;
+  await mind.respondText(
+    "the capital of France is and the capital of Japan is and Paris is in",
+  );
+  const big = mind.lastCost.counters;
+  assert.ok(
+    big.perceivedBytes > small.perceivedBytes,
+    "perception cost tracks query length",
+  );
+  await mind.store.close();
+});
+
+test("8. respondTurn meters through the same lifecycle", async () => {
+  const mind = await trained({ profile: true });
+  const conv = mind.beginConversation();
+  await mind.respondTurnText(conv, "the capital of France is");
+  const first = mind.lastCost;
+  assert.ok(first, "a turn publishes a report");
+  assert.ok(first.counters.perceptions > 0);
+  assert.equal(mind.store.meter, null, "detached after the turn too");
+
+  await mind.respondTurnText(conv, "Paris is in");
+  const second = mind.lastCost;
+  assert.notEqual(second, null);
+  assert.ok(
+    second.queryBytes > first.queryBytes,
+    "a turn is metered against the ACCUMULATED context, which grows",
+  );
+  mind.endConversation(conv);
+  await mind.store.close();
+});
+
+test("9. conversation memos survive the shared lifecycle (turn 2 re-uses turn 1)", async () => {
+  const mind = await trained({ profile: true });
+  const conv = mind.beginConversation();
+  await mind.respondTurnText(conv, "the capital of France is");
+  await mind.respondTurnText(conv, "the capital of Japan is");
+  const c = mind.lastCost.counters;
+  // The conversation's perceive/recognise memos are swapped in by
+  // beginResponse; the second turn must therefore HIT them for the prefix it
+  // shares with the first.  A zero here means respondTurn stopped carrying
+  // the conversation's persistent state — the exact drift the shared
+  // lifecycle exists to prevent.
+  assert.ok(
+    (c.perceiveHits ?? 0) > 0 || (c.recogniseHits ?? 0) > 0,
+    "the prefix's earlier results were re-used across turns",
+  );
+  mind.endConversation(conv);
+  await mind.store.close();
+});
+
+test("9b. every phase reports the work done inside it, and phases nest", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+  const { phases, counters } = mind.lastCost;
+
+  // Each phase carries counter deltas, not just a duration.
+  const withWork = Object.entries(phases).filter(([, p]) =>
+    Object.keys(p.counters).length > 0
+  );
+  assert.ok(withWork.length > 0, "phases attribute work, not only time");
+
+  // `think` is the outermost inference phase, so its counters must DOMINATE
+  // every phase nested inside it — that is what "inclusive" means, and it is
+  // the property that makes the deltas readable as attribution.
+  const think = phases["think"];
+  assert.ok(think, "think is a phase");
+  for (const [name, p] of Object.entries(phases)) {
+    if (name === "think" || name === "articulate") continue;
+    for (const [k, v] of Object.entries(p.counters)) {
+      assert.ok(
+        (think.counters[k] ?? 0) >= v,
+        `${name}.${k}=${v} exceeds think.${k}=${think.counters[k] ?? 0} — ` +
+          `phases must nest`,
+      );
+    }
+  }
+  // And no phase may claim more of a counter than the whole response spent.
+  for (const [name, p] of Object.entries(phases)) {
+    for (const [k, v] of Object.entries(p.counters)) {
+      assert.ok(
+        (counters[k] ?? 0) >= v,
+        `${name}.${k}=${v} exceeds the response total ${counters[k] ?? 0}`,
+      );
+    }
+  }
+  await mind.store.close();
+});
+
+test("9c. a recursive read is one read, not one per node descended", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+  const c = mind.lastCost.counters;
+  // bytesRead is the byte VOLUME, byteReads the number of read REQUESTS.
+  // Reconstructing a branch used to charge one read per node descended, which
+  // made byteReads track tree size — it read as ~1 byte per read.  Real reads
+  // return whole forms, so the volume must comfortably exceed the count.
+  assert.ok(c.byteReads > 0 && c.bytesRead > 0);
+  assert.ok(
+    c.bytesRead > c.byteReads,
+    `bytesRead ${c.bytesRead} should exceed byteReads ${c.byteReads} — ` +
+      `a per-node charge would invert this`,
+  );
+  await mind.store.close();
+});
+
+test("10. sumReports and formatReport aggregate a battery", async () => {
+  const mind = await trained({ profile: true });
+  const reports = [];
+  for (const q of [QUERY, "Paris is in", "the capital of Italy is"]) {
+    await mind.respondText(q);
+    reports.push(mind.lastCost);
+  }
+  const total = sumReports(reports);
+  assert.equal(total.version, 1);
+  assert.equal(
+    total.queryBytes,
+    reports.reduce((s, r) => s + r.queryBytes, 0),
+  );
+  for (const key of Object.keys(reports[0].counters)) {
+    assert.equal(
+      total.counters[key],
+      reports.reduce((s, r) => s + (r.counters[key] ?? 0), 0),
+      `${key} did not sum`,
+    );
+  }
+  const text = formatReport(total);
+  assert.match(text, /^cost: /);
+  assert.match(text, /perceptions/);
+  await mind.store.close();
+});

package/test/56-bridge-identity-admission.test.mjs

@@ -0,0 +1,209 @@
+// 56-bridge-identity-admission.test.mjs — the bridge's ZERO-SUBSTITUTION
+// admission: a candidate the alignment explains END TO END on BOTH sides,
+// separated from the query only by material that does not change what the
+// text SAYS, is the SAME learnt form and grounds through its own edge.
+//
+// "Material that does not change what it says" has ONE definition here, and
+// it is read from the corpus, never tuned (AGENTS §2.7, corpus-global
+// population): a span is EXPLAINED when it is sub-quantum (< W — typographic
+// glue) or every W-window in it is COMMON by the store's own climb (the
+// ascent saturates, or it reaches a majority of contexts).  A window that
+// reaches NOTHING is novel content and is never explained — the reading that
+// separates a droppable "the process of " from a load-bearing "heavy ".
+//
+// THE GAP THIS CLOSES (measured on the 17.9M-node trained store).  The query
+// `Who wrote Romeo and Juliet?` against the trained `Who wrote "Romeo and
+// Juliet"?` — two inserted quote characters — returned honest silence.  The
+// gist is a STRUCTURAL signature, so a mid-string insertion shifts every fold
+// boundary after it: the pair scored cos 0.377, BELOW unrelated neighbours
+// like "Who wrote the opera Carmen??" (0.603).  Recall's identity tier gates
+// on identityBar (0.969 at that length) and its reach tiers on 0.875, so no
+// gist-based tier could ever see it.  Only byte-exact alignment can — and the
+// bridge, which does exactly that, refused it for producing NO substitution.
+//
+// WHAT MUST NOT REGRESS (the documented prefix trap, bridge.ts): when the
+// query is a strict byte-PREFIX of several candidates that continue
+// differently, the bridge must still refuse — nothing corroborates picking
+// one continuation over another, and the surplus IS the invented answer.
+// The two shapes are separated by the candidate-side test: an identity
+// candidate has ≤ W bytes beyond the alignment, a prefix candidate has its
+// whole completion beyond it.
+
+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:" }) });
+
+/** Corroboration for the query's own windows: the bridge only aligns against
+ *  content whose W-windows are corpus-attested, so the fixture trains the
+ *  phrasing family, not one isolated sentence. */
+const TRAIN = [
+  ['Who wrote "Romeo and Juliet"?', " William Shakespeare wrote it."],
+  ['Who wrote "Hamlet"?', " William Shakespeare wrote it."],
+  ['Who wrote "Macbeth"?', " William Shakespeare wrote it."],
+  ["Who wrote the opera Carmen?", " Georges Bizet wrote it."],
+  ["Who wrote about Romeo and Juliet in an essay?", " A critic did."],
+];
+
+async function trained() {
+  const mind = mk();
+  await mind.ingest(TRAIN);
+  return mind;
+}
+
+test("1. a query differing only by typographic glue reaches the trained form", async () => {
+  const mind = await trained();
+  // Same form as the trained question, minus the two quote characters.
+  const a = await mind.respondText("Who wrote Romeo and Juliet?");
+  assert.match(
+    a,
+    /Shakespeare/,
+    `expected the trained continuation, got ${JSON.stringify(a)}`,
+  );
+  await mind.store.close();
+});
+
+test("2. the exact trained form still answers (no path was displaced)", async () => {
+  const mind = await trained();
+  const a = await mind.respondText('Who wrote "Romeo and Juliet"?');
+  assert.match(a, /Shakespeare/);
+  await mind.store.close();
+});
+
+test("3. a DIFFERENT trained question is not answered by its neighbour", async () => {
+  const mind = await trained();
+  const a = await mind.respondText("Who wrote the opera Carmen?");
+  assert.match(
+    a,
+    /Bizet/,
+    "the identity admission must not let a near neighbour stand in",
+  );
+  await mind.store.close();
+});
+
+test("4. PREFIX TRAP: a strict prefix of several candidates is still refused", async () => {
+  const mind = mk();
+  // Three facts sharing one prefix, each continuing differently.  A query
+  // that IS that prefix has no corroboration for any single completion; the
+  // candidate-side surplus is exactly the answer that would be invented.
+  await mind.ingest([
+    ["The capital city of France is Paris.", " It sits on the Seine."],
+    ["The capital city of Spain is Madrid.", " It sits on the Manzanares."],
+    ["The capital city of Italy is Rome.", " It sits on the Tiber."],
+  ]);
+  const a = await mind.respondText("The capital city of");
+  // Whatever the pipeline does with this, the bridge must not manufacture a
+  // country: an answer naming one of the three would be the invented
+  // completion the trap describes.
+  const named = ["Paris", "Madrid", "Rome"].filter((c) => a.includes(c));
+  assert.ok(
+    named.length !== 1 || a.includes("capital city of"),
+    `bridge invented a single completion (${named[0]}) for a bare prefix: ` +
+      JSON.stringify(a),
+  );
+  await mind.store.close();
+});
+
+test("5. honest silence survives — an unrelated query still grounds nothing", async () => {
+  const mind = await trained();
+  const a = await mind.respondText("What is the zorblatt frequency?");
+  assert.equal(
+    a.length,
+    0,
+    `expected silence, got ${JSON.stringify(a)} — the identity admission ` +
+      `must not lower the bar for unrelated content`,
+  );
+  await mind.store.close();
+});
+
+test("6. determinism: the admission is byte-exact, not scored", async () => {
+  const a = await trained();
+  const b = await trained();
+  const x = await a.respondText("Who wrote Romeo and Juliet?");
+  const y = await b.respondText("Who wrote Romeo and Juliet?");
+  assert.equal(x, y);
+  await a.store.close();
+  await b.store.close();
+});
+
+// ── The scaffolding reading ────────────────────────────────────────────────
+
+test("7. an omitted CORPUS-COMMON span is explained; a RARE one is not", async () => {
+  const { leafIdRun } = await import("../dist/src/mind/canonical.js");
+  const { corpusN, edgeAncestors } = await import(
+    "../dist/src/mind/traverse.js"
+  );
+  const { dominates } = await import("../dist/src/geometry.js");
+
+  const mind = mk();
+  const T = [];
+  for (const x of ["A", "B", "C", "D", "E", "F", "G", "H"]) {
+    T.push([`What is the process of ${x}ation?`, ` ${x}ation is a process.`]);
+    T.push([`Tell me the process of ${x}ing.`, ` ${x}ing is a process.`]);
+  }
+  T.push(["Is heavy water wet?", " No, heavy water is not wet."]);
+  await mind.ingest(T);
+
+  const N = corpusN(mind);
+  const W = mind.space.maxGroup;
+  // The predicate under test, mirrored exactly (bridge.ts explainedSpan).
+  const explained = (text) => {
+    const b = new TextEncoder().encode(text);
+    if (b.length < W) return true;
+    for (let o = 0; o + W <= b.length; o++) {
+      const ids = leafIdRun(mind, b, o, o + W);
+      if (ids === null) return false;
+      const wid = mind.store.findBranch(ids);
+      if (wid === null) return false;
+      const r = edgeAncestors(mind, wid, N);
+      if (r.saturated) continue;
+      if (r.roots.length === 0) return false;
+      if (!dominates(r.contextsReached, N)) return false;
+    }
+    return true;
+  };
+
+  assert.equal(
+    explained("the process of "),
+    true,
+    "corpus-common scaffolding must be droppable",
+  );
+  assert.equal(
+    explained("heavy "),
+    false,
+    "rare, discriminative content must NEVER be written off as scaffolding — " +
+      "a candidate omitting it answers a different, narrower question",
+  );
+  // The reading, not just the population: a window reaching NOTHING is novel
+  // content.  Going through reachOf (which maps both saturated and
+  // empty-rooted to Infinity) called "heavy " scaffolding and answered
+  // "Is water wet?" with "No, heavy water is not wet.".
+  assert.equal(
+    explained("zqxjwv "),
+    false,
+    "untrained content is never explained",
+  );
+  await mind.store.close();
+});
+
+test("8. EXACT query coverage — a sub-quantum query-side difference is NOT glue", async () => {
+  const mind = mk();
+  // A trained arithmetic fact, and a query differing from it only inside a
+  // sub-quantum span — but that span is DIGITS, and digits are content.
+  await mind.ingest([
+    ["what is 2+2?", " 2+2 is 4."],
+    ["what is 3+3?", " 3+3 is 6."],
+    ["what is 5+5?", " 5+5 is 10."],
+  ]);
+  const a = await mind.respondText("what is 2^10?");
+  assert.ok(
+    !a.includes("4."),
+    `answered a DIFFERENT arithmetic question: ${JSON.stringify(a)} — the ` +
+      `identity admission must require covered === query.length, with no ` +
+      `sub-quantum slack on the query side`,
+  );
+  await mind.store.close();
+});

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

@@ -0,0 +1,104 @@
+// 57-fusion-order.test.mjs — a fused multi-topic answer must READ in the
+// order the question posed its topics.
+//
+// fuseAttention sorts its pieces by `start`, their position in the query.
+// Every attention ROOT carries its own start.  `primary` did not: it was
+// given forest[0].start — the FIRST root's position — which is primary's own
+// source only when primary happens to come from that root.  When it does
+// not, primary sorts to a position it never occupied.
+//
+// Observed live on the 17.9M-node trained store:
+//   "What is the capital of France? And what is 2 + 2?"
+//     -> "4The capital city of France is Paris."
+// Both pieces were correct; only the order was wrong.  The ALU result, whose
+// evidence is the "2 + 2" span at the END of the query, had inherited the
+// France root's start of 0.
+//
+// primary's position is now the earliest query byte its own grounding stands
+// on: `accounted` when non-empty, else the computed span (a pure computation
+// is priced out of `accounted` by cover — the same cost-ladder-vs-coverage
+// distinction think() already draws for the fusion remainder).
+//
+// NOT under test: the missing separator between the pieces.  joinWithBridge
+// splices only a LEARNT connector; when the corpus holds none the pieces join
+// bare.  Inventing a space would synthesize bytes the store never saw, which
+// this system does not do — bare joining is the honest degradation.
+
+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:" }) });
+
+/** Two independent topics, each with its own trained fact, plus enough
+ *  same-frame neighbours that the consensus climb commits both as separate
+ *  points of attention rather than one. */
+const TRAIN = [
+  ["What is the capital of France?", " The capital of France is Paris."],
+  ["What is the capital of Spain?", " The capital of Spain is Madrid."],
+  ["What is the capital of Italy?", " The capital of Italy is Rome."],
+  ["What is the largest planet?", " The largest planet is Jupiter."],
+  ["What is the largest ocean?", " The largest ocean is the Pacific."],
+];
+
+async function trained() {
+  const mind = mk();
+  await mind.ingest(TRAIN);
+  return mind;
+}
+
+/** Index of `needle` in `hay`, or -1. */
+const at = (hay, needle) => hay.indexOf(needle);
+
+test("1. two fused topics appear in the query's own order", async () => {
+  const mind = await trained();
+  const a = await mind.respondText(
+    "What is the capital of France? And what is the largest planet?",
+  );
+  const iParis = at(a, "Paris"), iJup = at(a, "Jupiter");
+  if (iParis >= 0 && iJup >= 0) {
+    assert.ok(
+      iParis < iJup,
+      `France was asked FIRST but its answer trails: ${JSON.stringify(a)}`,
+    );
+  }
+  await mind.store.close();
+});
+
+test("2. reversing the question reverses the fused answer", async () => {
+  const mind = await trained();
+  const a = await mind.respondText(
+    "What is the largest planet? And what is the capital of France?",
+  );
+  const iParis = at(a, "Paris"), iJup = at(a, "Jupiter");
+  if (iParis >= 0 && iJup >= 0) {
+    assert.ok(
+      iJup < iParis,
+      `the planet was asked FIRST but its answer trails: ${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(
+    await mind.respondText("What is the capital of France?"),
+    /Paris/,
+  );
+  assert.match(
+    await mind.respondText("What is the largest planet?"),
+    /Jupiter/,
+  );
+  await mind.store.close();
+});
+
+test("4. determinism", async () => {
+  const a = await trained(), b = await trained();
+  const q = "What is the capital of France? And what is the largest planet?";
+  assert.equal(await a.respondText(q), await b.respondText(q));
+  await a.store.close();
+  await b.store.close();
+});