@hviana/sema 0.1.0

package/test/33-multi-candidate.test.mjs

@@ -0,0 +1,222 @@
+// 33-multi-candidate.test.mjs — the grounding decider's extended surface.
+//
+// Pins five refinements to think()'s grounding decider (pipeline.ts), each
+// verified through the public respond()/inspectRationale API rather than by
+// reaching into internals:
+//
+//   1. CAST's three internal schemas (substitution, redirection, comparison)
+//      each contribute their OWN candidate to the decider, instead of the
+//      first-fired schema shadowing the rest.
+//   2. Every mechanism's candidate carries a diagnostic `unexplained` label —
+//      never priced, only explanatory — surfaced in decideGrounding's trace.
+//   3. A near-tie between the winner and the runner-up is surfaced as a
+//      `narrowDecision` trace step.
+//   4. A winning candidate that explains only a sliver of the query is
+//      flagged `thinGrounding` — diagnostic, never suppressing the answer.
+//   5. CAST and extraction are skipped outright (`skipMechanism`) when a
+//      dynamic floor read from the (memoised) consensus climb shows the
+//      mechanism cannot structurally fire.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const mk = (seed = 7) =>
+  new Mind({ seed, store: new SQliteStore({ path: ":memory:" }) });
+
+async function trace(m, q) {
+  const steps = [];
+  const r = await m.respond(q, (s) => steps.push(s));
+  return { r, steps };
+}
+
+const stepsNamed = (steps, name) =>
+  steps.filter((s) => s.mechanism.at(-1) === name);
+
+test("1 — CAST's schemas each contribute their own candidate to the decider", async () => {
+  const m = mk(7);
+  await m.ingest([
+    ["Ice is cold", "cold"],
+    ["Fire is hot", "hot"],
+    ["Steel is hard", "hard"],
+    ["Water is wet", "wet"],
+  ]);
+  const { r, steps } = await trace(m, "What if steel were cold?");
+  assert.equal(r.provenance, "cast");
+
+  const schemas = stepsNamed(steps, "castSchema");
+  assert.ok(
+    schemas.length >= 2,
+    `expected at least two CAST schemas to fire, got ${schemas.length}`,
+  );
+
+  const decide = steps.find((s) => s.mechanism.at(-1) === "decideGrounding");
+  assert.ok(
+    decide,
+    "decideGrounding must be traced when multiple candidates compete",
+  );
+  const castCandidates = decide.inputs.filter((i) => i.role.startsWith("cast"));
+  assert.ok(
+    castCandidates.length >= 2,
+    `decideGrounding must show multiple CAST candidates, got ${castCandidates.length}`,
+  );
+  await m.store.close();
+});
+
+test("1b — different CAST schemas are weighed by their OWN explanatory power, not a shared span", async () => {
+  // A 3-point weave: redirection transfers between the DOMINANT ("The Mona
+  // Lisa..." exemplar) and the named substitute ("Pablo Picasso"), while
+  // comparison pairs the dominant with a DIFFERENT analog reached through
+  // the halo gate — two genuinely different point-pairs, so their accounted
+  // spans (and hence weights) may legitimately differ by far more than any
+  // fixed move-cost offset (at most CONCEPT + STEP ≈ 12). Before the fix,
+  // every fired CAST schema shared ONE weave-wide `accounted` array
+  // regardless of which points it actually used, so this spread was
+  // impossible — schemas could only ever differ by move cost.
+  const m = mk(2);
+  await m.ingest([
+    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
+    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
+    [
+      "The Night Watch was painted by Rembrandt van Rijn.",
+      "Rembrandt van Rijn",
+    ],
+    ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
+    ["Michelangelo", "Il Divino painted the Sistine Chapel ceiling"],
+    ["a nickname meaning the divine one", "Michelangelo"],
+    ["a nickname meaning the divine one", "Il Divino"],
+    ["also called", "Michelangelo"],
+    ["also called", "Il Divino"],
+    ["known as", "Michelangelo"],
+    ["known as", "Il Divino"],
+    ["Il Divino", "Il Divino was a nickname coined by his contemporaries"],
+  ]);
+  const { r, steps } = await trace(
+    m,
+    "The Weeping Woman was painted by Pablo Picasso.",
+  );
+  // The correct answer is still reachable — the fix must not cost accuracy.
+  const got = new TextDecoder().decode(r.bytes).replace(/\0/g, "");
+  assert.ok(got.includes("Cubist"), `expected the Picasso fact, got "${got}"`);
+
+  const decide = steps.find((s) => s.mechanism.at(-1) === "decideGrounding");
+  const castWeights = decide.inputs
+    .filter((i) => i.role.startsWith("cast"))
+    .map((i) => Number(i.role.match(/weight ([\d.]+)/)[1]));
+  assert.ok(
+    castWeights.length >= 2,
+    `expected at least two CAST candidates, got ${castWeights.length}`,
+  );
+  const spread = Math.max(...castWeights) - Math.min(...castWeights);
+  assert.ok(
+    spread > 100,
+    `CAST candidates' weights must diverge by more than a fixed move-cost ` +
+      `offset (≤ ~12) when their accounted spans genuinely differ — got ` +
+      `weights ${castWeights} (spread ${spread})`,
+  );
+  await m.store.close();
+});
+
+test("2 — decideGrounding surfaces each candidate's unexplained label", async () => {
+  const m = mk(7);
+  await m.ingest([
+    ["ice is cold so ice is brittle", "brittle"],
+    ["steel is hard so steel is strong", "strong"],
+    ["water is frigid so water is freezing", "freezing"],
+  ]);
+  const { steps } = await trace(m, "steel is frigid so steel is ???");
+  const decide = steps.find((s) => s.mechanism.at(-1) === "decideGrounding");
+  assert.ok(decide, "no decideGrounding step");
+  assert.ok(
+    decide.inputs.some((i) => i.role.includes("unexplained:")),
+    "at least one candidate must carry a diagnostic unexplained label",
+  );
+  await m.store.close();
+});
+
+test("3 — a near-tie between the winner and runner-up emits narrowDecision", async () => {
+  const m = mk(7);
+  await m.ingest([
+    ["ice is cold so ice is brittle", "brittle"],
+    ["steel is hard so steel is strong", "strong"],
+    ["water is frigid so water is freezing", "freezing"],
+  ]);
+  const { steps } = await trace(m, "steel is frigid so steel is ???");
+  const narrow = stepsNamed(steps, "narrowDecision");
+  assert.equal(narrow.length, 1, "expected exactly one narrowDecision step");
+  assert.ok(/margin \d+ grade-unit/.test(narrow[0].note), narrow[0].note);
+  assert.equal(narrow[0].inputs.length, 1);
+  assert.equal(narrow[0].outputs.length, 1);
+  await m.store.close();
+});
+
+test("3b — a clean, well-separated decision does NOT emit narrowDecision", async () => {
+  const m = mk(7);
+  await m.ingest([["ice", "cold"], ["fire", "hot"]]);
+  const { steps } = await trace(m, "ice");
+  assert.equal(
+    stepsNamed(steps, "narrowDecision").length,
+    0,
+    "a single, uncontested grounding must not be flagged narrow",
+  );
+  await m.store.close();
+});
+
+test("4 — a thin winning candidate is flagged thinGrounding", async () => {
+  const m = mk(42);
+  const SYS = "You are a helpful and harmless assistant.\n\n" +
+    "You are not allowed to use any tools.\n";
+  await m.ingest([
+    [
+      SYS + "Describe the importance of gender equality in the workplace.",
+      "Gender equality means equal chances to be hired and promoted.",
+    ],
+    [
+      SYS + "Provide a summary of the 1992 Dream Team basketball squad.",
+      "The Dream Team won gold in Barcelona in 1992.",
+    ],
+    [
+      SYS + "Explain how photosynthesis converts sunlight into energy.",
+      "Photosynthesis binds carbon dioxide and water into sugar.",
+    ],
+    [
+      SYS + "Summarize the causes of the fall of the Western Roman Empire.",
+      "The Western Roman Empire fell from overreach and migration.",
+    ],
+  ]);
+  const { r, steps } = await trace(
+    m,
+    SYS +
+      "Tell me about gender equality at work, and also the 1992 Dream Team.",
+  );
+  assert.ok(r.v !== null, "the query must still ground an answer");
+  const thin = stepsNamed(steps, "thinGrounding");
+  assert.equal(thin.length, 1, "a low-density grounding must be flagged thin");
+  assert.ok(/density [\d.]+ is below 1\/W/.test(thin[0].note));
+  await m.store.close();
+});
+
+test("4b — a fully-covered answer is NOT flagged thinGrounding", async () => {
+  const m = mk(7);
+  await m.ingest([["what is ice?", "ice is frozen water"]]);
+  const { r, steps } = await trace(m, "what is ice?");
+  assert.ok(r.v !== null);
+  assert.equal(stepsNamed(steps, "thinGrounding").length, 0);
+  await m.store.close();
+});
+
+test("5 — CAST is skipped by a dynamic floor when the climb can't support a weave", async () => {
+  const m = mk(7);
+  await m.ingest([["ice", "cold"], ["fire", "hot"]]);
+  const { steps } = await trace(m, "ice");
+  const skip = stepsNamed(steps, "skipMechanism");
+  assert.ok(
+    skip.some((s) => /cast skipped/.test(s.note)),
+    `expected a cast skipMechanism step, got: ${skip.map((s) => s.note)}`,
+  );
+  // And no CAST schema should have run at all — the floor pruned it
+  // BEFORE counterfactualTransfer's own alignment work.
+  assert.equal(stepsNamed(steps, "castSchema").length, 0);
+  await m.store.close();
+});

package/test/34-cross-region.test.mjs

@@ -0,0 +1,252 @@
+// 34-cross-region.test.mjs — DIRECT REGION-TO-REGION INTERACTION (binding).
+//
+// Sema's attention lets each region of the query vote INDEPENDENTLY for the
+// context it climbs to, then POOLS the votes additively (poolVotes).  Additive
+// pooling is a soft conjunction: when two regions each cast a vote that
+// includes a shared context, that context accumulates and wins.  But pooling
+// can only ever surface a context that at least ONE region already votes for.
+//
+// The gap this exercises — the "binding problem": a context that NO single
+// region votes for, reachable only by letting two regions interact DIRECTLY.
+// With cross-cutting attributes (colour × shape → answer), each attribute
+// alone is ambiguous across two contexts, and — crucially — each region's own
+// resonance climbs to a DIFFERENT context than the joint one.  So the joint
+// context receives zero independent votes and additive pooling can never
+// reach it; only composing the two regions can.
+//
+//   red circle → alpha     red square → beta
+//   blue circle → gamma    blue square → delta
+//
+// "red" alone attends to `red square`; "circle" alone attends to `circle`.
+// Neither reaches `red circle`.  A query naming both, non-adjacently
+// ("red then circle"), MUST attend to `red circle` — and that requires the
+// two regions to interact.
+//
+// ── Why these assertions are on climbAttention, not respondText ────────────
+// The mechanism lives IN attention: its contract is the set of contexts the
+// query attends to.  Asserting there tests the mechanism itself, and — unlike
+// an end-to-end respondText assertion — the assertion FLIPS with the
+// mechanism: without region interaction the query provably attends to the
+// wrong context (`red square`), with it to the joint one (`red circle`).
+// (End-to-end voicing of a scattered-attribute query is a separate
+// articulation concern and is deliberately not conflated here.)
+
+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 enc = (s) => new TextEncoder().encode(s);
+const dec = (b) =>
+  new TextDecoder().decode(b.filter((x) => x !== 0)).replace(/\s+/g, " ")
+    .trim();
+
+// Attributes are trained as standalone forms too, so each is RECOGNISED as a
+// whole-form region (a site) in the query — otherwise a 6-byte word like
+// "circle" fragments across the 4-byte chunk grid and never forms one clean
+// region to compose with.
+const CORPUS = [
+  ["red", "is a color"],
+  ["blue", "is a color"],
+  ["circle", "is a shape"],
+  ["square", "is a shape"],
+  ["red circle", "answer alpha"],
+  ["red square", "answer beta"],
+  ["blue circle", "answer gamma"],
+  ["blue square", "answer delta"],
+];
+
+const mk = (seed) =>
+  new Mind({ seed, store: new SQliteStore({ path: ":memory:" }) });
+
+/** The contexts the query attends to, most-dominant first, as text. */
+async function attends(m, q) {
+  const roots = await m.climbAttention(enc(q), 24);
+  return roots.map((r) => dec(m.store.bytesPrefix(r.anchor, 1e9)));
+}
+
+// The mechanism is content-addressed and therefore seed-independent; running
+// several seeds guards against a fragile (seed-sensitive) approximation
+// passing by luck.
+const SEEDS = [1, 2, 3, 7, 11];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// THE NEED — no single region reaches the joint context.
+//
+// If either attribute alone already attended to `red circle`, additive pooling
+// would suffice and no interaction would be needed.  It does not: each single
+// attribute climbs elsewhere.  This is what makes the binding query below
+// UNREACHABLE without direct region interaction.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("need: neither attribute alone attends to the joint context", async () => {
+  for (const seed of SEEDS) {
+    const m = mk(seed);
+    await m.ingest(CORPUS);
+    const red = await attends(m, "red");
+    const circle = await attends(m, "circle");
+    assert.ok(
+      !red.includes("red circle"),
+      `seed ${seed}: "red" alone must not reach the joint context, got [${red}]`,
+    );
+    assert.ok(
+      !circle.includes("red circle"),
+      `seed ${seed}: "circle" alone must not reach the joint context, got [${circle}]`,
+    );
+    await m.store.close();
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// THE REQUIREMENT — the binding query attends to the joint context.
+//
+// "red" and "circle" fall into non-adjacent regions; each individually climbs
+// to a different context (`red square`, `circle`).  Only by composing the two
+// regions does the JOINT context `red circle` become a point of attention.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("binding: two non-adjacent attributes attend to their JOINT context", async () => {
+  for (const seed of SEEDS) {
+    const m = mk(seed);
+    await m.ingest(CORPUS);
+    const got = await attends(m, "red then circle");
+    assert.equal(
+      got[0],
+      "red circle",
+      `seed ${seed}: "red then circle" must attend to the JOINT context ` +
+        `"red circle" (the only fact with BOTH attributes), got [${got}]`,
+    );
+    await m.store.close();
+  }
+});
+
+test("binding is symmetric: the other cross-cut also composes", async () => {
+  for (const seed of SEEDS) {
+    const m = mk(seed);
+    await m.ingest(CORPUS);
+    const got = await attends(m, "blue then square");
+    assert.equal(
+      got[0],
+      "blue square",
+      `seed ${seed}: "blue then square" must attend to "blue square", got [${got}]`,
+    );
+    await m.store.close();
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// WRONG-WORLD GUARD — composition must not manufacture a context the two
+// attributes do NOT jointly evidence.  "red then circle" shares "circle" with
+// the blue world, but nothing red-and-blue was ever learnt together: the joint
+// evidence is for the RED circle, never a blue one.
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ORDER-FREEDOM — a junction evidences that two forms were LEARNT TOGETHER;
+// which one the query happens to mention first is a fact about the query, not
+// about the learnt whole.  "circle then red" reverses the stored order of
+// `red circle` and must still compose to it.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("binding is order-free: reversed mention still composes", async () => {
+  for (const seed of SEEDS) {
+    const m = mk(seed);
+    await m.ingest(CORPUS);
+    const got = await attends(m, "circle then red");
+    assert.equal(
+      got[0],
+      "red circle",
+      `seed ${seed}: "circle then red" must attend to "red circle" even ` +
+        `though the query reverses the stored order, got [${got}]`,
+    );
+    await m.store.close();
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// N-ARY BINDING — binding is not intrinsically pairwise.  With THREE
+// cross-cutting attributes every PAIR is still ambiguous (each pair appears in
+// two contexts); only the triple picks out one.  A pairwise-only mechanism
+// tops out at the two-context pair container; n-ary selection must reach the
+// unique triple.
+// ═══════════════════════════════════════════════════════════════════════════
+
+const CORPUS3 = [
+  ["red", "is a color"],
+  ["blue", "is a color"],
+  ["big", "is a size"],
+  ["small", "is a size"],
+  ["circle", "is a shape"],
+  ["square", "is a shape"],
+  ["red big circle", "answer a"],
+  ["red big square", "answer b"],
+  ["red small circle", "answer c"],
+  ["red small square", "answer d"],
+  ["blue big circle", "answer e"],
+  ["blue big square", "answer f"],
+  ["blue small circle", "answer g"],
+  ["blue small square", "answer h"],
+];
+
+test("binding is n-ary: three cross-cutting attributes reach their unique triple", async () => {
+  for (const seed of SEEDS) {
+    const m = mk(seed);
+    await m.ingest(CORPUS3);
+    const got = await attends(m, "red then big then circle");
+    assert.equal(
+      got[0],
+      "red big circle",
+      `seed ${seed}: "red then big then circle" must attend to the unique ` +
+        `TRIPLE context "red big circle" (every pair is ambiguous), got [${got}]`,
+    );
+    await m.store.close();
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CORPUS INDEPENDENCE — binding must not require attributes to have been
+// TRAINED STANDALONE.  Without the standalone rows no attribute is a
+// recognised site: "circle" fragments across the 4-byte chunk grid.  But the
+// fragments are stored chunks that vote, and their BYTES still compose — the
+// junction ascent matches byte containment, so the fragment pair evidences
+// the same joint container the whole word would.  (This also exercises
+// explaining-away: the grid shard " cir" exists verbatim only in `blue
+// circle` — pure alignment accident — and its aliased vote must be
+// superseded by the exact joint evidence, not left to outvote it.)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const CORPUS_FACTS_ONLY = [
+  ["red circle", "answer alpha"],
+  ["red square", "answer beta"],
+  ["blue circle", "answer gamma"],
+  ["blue square", "answer delta"],
+];
+
+test("corpus independence: binding composes from grid fragments, no standalone training", async () => {
+  for (const seed of SEEDS) {
+    const m = mk(seed);
+    await m.ingest(CORPUS_FACTS_ONLY);
+    const got = await attends(m, "red then circle");
+    assert.equal(
+      got[0],
+      "red circle",
+      `seed ${seed}: without standalone attribute rows, "red then circle" ` +
+        `must still attend to "red circle" via fragment composition, got [${got}]`,
+    );
+    await m.store.close();
+  }
+});
+
+test("guard: binding does not leak into a non-jointly-evidenced world", async () => {
+  for (const seed of SEEDS) {
+    const m = mk(seed);
+    await m.ingest(CORPUS);
+    const got = await attends(m, "red then circle");
+    assert.ok(
+      !got.some((c) => c.startsWith("blue")),
+      `seed ${seed}: "red then circle" must not attend to any blue-world ` +
+        `context, got [${got}]`,
+    );
+    await m.store.close();
+  }
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "rootDir": ".",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts", "example/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}