@hviana/sema 0.4.7 → 0.5.0

package/test/71-embedded-canon-equivalence.test.mjs

@@ -0,0 +1,121 @@
+// 71-embedded-canon-equivalence.test.mjs — an EMBEDDED trained form must be
+// recognised under the response's canonical equivalence, not only byte-exactly.
+//
+// The contract: `recognise` decomposes a query into stored forms that lead
+// somewhere.  A trained form sitting at an interior offset of a larger query is
+// found by the scale-gated "exact query-edge forms" tier in recognition.ts.
+// That tier admits candidates with a BYTE-EXACT `store.findBranch` probe over
+// the query's leaf-id run, then calls the canon-capable `resolveSpan`.  The
+// prefilter is therefore strictly narrower than its own resolver: a form whose
+// deposit differs from the query only by the response canonicalizer's
+// equivalence (case, width) can never reach `resolveSpan`, because a
+// differently-cased deposit's branch kid-ids are not the query's leaf-id run
+// under ANY canonicalization of the query.  Measured on a 15.7M-node store:
+// "Hey, What is the process of photosynthesis?" recognises the trained form,
+// "Hey, what is …" recognises nothing, though the lowercased form resolves
+// exactly at offset 0.
+//
+// WHY THE 4.3k-FACT FIXTURE IS NOT OPTIONAL: the tier runs only when
+// `atomIsHub(ctx, corpusN)` is true, i.e. N > ~4096 contexts at maxGroup=4.
+// Every small-store suite exercises the OTHER branch of recognition, so a
+// conventional fixture would pass while the defect is fully present.  The
+// atomIsHub assertion below fails loudly if that crossover ever moves, so this
+// test can never silently stop covering the branch it exists for.
+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 { recognise } from "../dist/src/mind/recognition.js";
+import { resolve } from "../dist/src/mind/primitives.js";
+import { atomIsHub, corpusN } from "../dist/src/mind/traverse.js";
+import { textCanon } from "../dist/src/canon.js";
+
+const enc = (s) => new TextEncoder().encode(s);
+
+// Longer than chainReach(W)=W²=16 bytes, or the tier's own size gate skips it.
+const FORM = "Madam Your Glasses Are Fogged";
+const PREFIX = "Hey, ";
+
+/** Recognise with the canonicalizer a TEXT response would carry.  `ctx.canon`
+ *  is per-response state that `respond()` injects; calling `recognise`
+ *  directly would otherwise run with canon disabled and test nothing. */
+function recogniseAsText(mind, text) {
+  mind.canon = textCanon;
+  mind.canonMemo = new Map();
+  try {
+    return recognise(mind, enc(text));
+  } finally {
+    mind.canon = null;
+    mind.canonMemo = null;
+  }
+}
+
+const sitesFor = (rec, id) => rec.sites.filter((s) => s.payload === id);
+
+test("an embedded trained form is recognised under canonical equivalence", async () => {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+
+  const filler = [];
+  for (let i = 0; i < 4300; i++) filler.push([`filler-${i}`, `f${i}`]);
+  await m.ingest(filler);
+  await m.ingest([[FORM, "a stored continuation for the form"]]);
+  // Canonical resolution reads a store-side index that training builds
+  // explicitly (meta `canon.upto`); without it `canonResolve` has no
+  // candidates and the equivalence under test does not exist at all.
+  await m.buildCanonIndex();
+
+  const N = corpusN(m);
+  assert.ok(
+    atomIsHub(m, N),
+    `fixture must cross atomIsHub (N=${N}); the tier under test is ` +
+      `scale-gated and this suite would otherwise assert nothing`,
+  );
+
+  const formId = resolve(m, enc(FORM));
+  assert.ok(formId !== null, "the trained form must resolve exactly");
+
+  // Control 1 — the form standalone, in its deposited case.
+  assert.ok(
+    sitesFor(recogniseAsText(m, FORM), formId).length > 0,
+    "standalone deposited-case form must be recognised",
+  );
+
+  // Control 2 — the form standalone, lowercased.  This is what proves the
+  // canonical equivalence is REAL and reachable, so the embedded assertion
+  // below is about placement, not about the canonicalizer.
+  assert.ok(
+    sitesFor(recogniseAsText(m, FORM.toLowerCase()), formId).length > 0,
+    "lowercased form must resolve to the same node at offset 0",
+  );
+
+  // Control 3 — embedded, deposited case.  The tier's byte-exact route.
+  assert.ok(
+    sitesFor(recogniseAsText(m, PREFIX + FORM), formId).length > 0,
+    "embedded deposited-case form must be recognised",
+  );
+
+  // THE CONTRACT — embedded AND canonically equivalent.  Controls 2 and 3 each
+  // hold, so anything that fails here is the prefilter being narrower than its
+  // resolver, which is the defect this test exists to prevent.
+  const rec = recogniseAsText(m, PREFIX + FORM.toLowerCase());
+  const hit = sitesFor(rec, formId);
+  assert.ok(
+    hit.length > 0,
+    `embedded lowercased form must be recognised: standalone-lowercased and ` +
+      `embedded-exact both are, so the byte-exact admission gate is the only ` +
+      `thing rejecting it (sites found: ${
+        rec.sites.map((s) => `${s.start}-${s.end}`).join(",") || "none"
+      })`,
+  );
+  // It must be found AT its true offset, not as some other coincidental span.
+  assert.ok(
+    hit.some((s) =>
+      s.start === PREFIX.length && s.end === PREFIX.length + FORM.length
+    ),
+    `the form must be recognised at its own span [${PREFIX.length},${
+      PREFIX.length + FORM.length
+    }], got ${hit.map((s) => `${s.start}-${s.end}`).join(",")}`,
+  );
+
+  await m.store.close();
+});

package/test/72-prefix-candidate-supply.test.mjs

@@ -0,0 +1,114 @@
+// 72-prefix-candidate-supply.test.mjs — a query that is a proper PREFIX of a
+// trained form must be able to reach that form even when resonance cannot rank
+// it.
+//
+// THE GAP THIS PINS.  `prefixCompletion` consumes a ranked list the caller
+// already fetched, and that list comes from resonance.  Resonance cannot rank a
+// proper prefix: measured on a 15.7M-node store, cos(prefix, form) falls from
+// 0.9629 at a one-byte truncation to 0.6206 at three bytes, against a
+// reachThreshold of 0.8750.  The mechanism's guards were therefore never
+// reached — the trace read `candidates: 24, opened: 0` — and the query answered
+// nothing.  `prefixCandidates` is the second SUPPLY that closes it, reading the
+// leaf-id WINDOW index `indexSubSpans` already writes at deposit time.  No
+// ingestion, storage or fold change is involved: this test would pass on a
+// store trained before the supply existed.
+//
+// WHY THE ASSERTIONS ARE SHAPED THIS WAY.  On a small fixture resonance may
+// well return the form by luck, and then an end-to-end "does it answer?" test
+// would pass with the supply deleted — pinning nothing.  So the contract is
+// asserted on `prefixCandidates` DIRECTLY, and the resonance list is asserted
+// to lack the form, which is what makes the supply load-bearing rather than
+// redundant.
+//
+// The 4.3k-fact fixture is not decoration: window containment is judged against
+// `hubBound` = √N, so a toy store makes every window look saturated and the
+// supply would correctly return nothing, testing nothing.
+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 {
+  prefixCandidates,
+  prefixCompletion,
+} from "../dist/src/mind/prefix-completion.js";
+import { gistOf, resolve } from "../dist/src/mind/primitives.js";
+
+const enc = (s) => new TextEncoder().encode(s);
+const dec = new TextDecoder();
+
+const FORM = "The chief export of the northern province is powdered basalt.";
+
+test("a proper prefix reaches its trained form through the window supply", async () => {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+
+  const filler = [];
+  for (let i = 0; i < 4300; i++) filler.push([`filler-${i}`, `f${i}`]);
+  await m.ingest(filler);
+  await m.ingest([[FORM, "acknowledged"]]);
+
+  const formId = resolve(m, enc(FORM));
+  assert.ok(formId !== null, "the trained form must resolve exactly");
+
+  // Truncate by more than one grouping window, so the continuation clears
+  // prefixCompletion's sub-quantum guard and the tier can actually fire.
+  const W = m.space.maxGroup;
+  const query = enc(FORM.slice(0, FORM.length - 3 * W));
+
+  // Premise 1 — the exact tiers genuinely cannot serve this query.
+  assert.equal(
+    resolve(m, query),
+    null,
+    "a proper prefix must have no branch of its own, or the gap is not real",
+  );
+
+  // Premise 2 — resonance does not supply the form, so anything that works
+  // below is the new supply and not the ranked list in disguise.
+  // Premise 2 — the ranked list is NOT what is under test.  At fixture scale
+  // resonance does rank the form (it is the only content among 4,300 fillers
+  // that resembles the query), and that is measured, not assumed: the
+  // assertion below records it, so if fixture geometry ever changes the reader
+  // is told rather than misled.  Resonance's real-world inability to rank a
+  // prefix is a LARGE-CORPUS property — cos falls to 0.6206 at a three-byte
+  // truncation against a 0.8750 bar, on a 15.7M-node store — and cannot be
+  // reproduced at this scale.  That is why the contract below is asserted on
+  // `prefixCandidates` DIRECTLY: deleting or emptying the supply fails this
+  // test regardless of what resonance happens to return.
+  const ranked = (await m.store.resonate(gistOf(m, query), 64)).map((h) =>
+    h.id
+  );
+  assert.ok(
+    ranked.includes(formId),
+    "fixture note: at this scale resonance is expected to rank the form; " +
+      "if it no longer does, the end-to-end path below became the load-" +
+      "bearing assertion and this comment must be revisited",
+  );
+
+  // THE CONTRACT — the write side's own window index proposes the form.
+  const proposed = prefixCandidates(m, query);
+  assert.ok(
+    proposed.includes(formId),
+    `the window supply must propose the trained form the query opens ` +
+      `(proposed ${proposed.length} candidate(s))`,
+  );
+
+  // …and the mechanism, unchanged, grounds it whole through that supply.
+  const completed = prefixCompletion(m, query, proposed);
+  assert.ok(completed !== null, "the supplied form must complete the query");
+  assert.equal(
+    dec.decode(completed.form),
+    FORM,
+    "a FORM is grounded whole, never a slice cut at the query's end",
+  );
+
+  // HONEST DEGRADATION (§2.13).  A query with no discriminative window must
+  // propose nothing rather than guess — silence is the correct answer, and a
+  // supply that widened until it found something would be the real defect.
+  const hub = enc("The ");
+  assert.equal(
+    prefixCompletion(m, hub, prefixCandidates(m, hub)),
+    null,
+    "a query carrying no discriminative window must stay silent",
+  );
+
+  await m.store.close();
+});

package/test/73-scaffolding-only-bridge-abstains.test.mjs

@@ -0,0 +1,178 @@
+// 73-scaffolding-only-bridge-abstains.test.mjs — the substitution bridge must
+// ABSTAIN when every literal span it did not substitute is corpus-global
+// scaffolding.
+//
+// THE DEFECT THIS PINS.  A bridge grounds through the literal spans it did NOT
+// substitute; those anchors are the whole of its evidence.  The anchor scan
+// ranked them by containment but rejected only the ones with ZERO containers,
+// so a query made entirely of scaffolding still bridged — the single
+// substituted span carried the whole semantic load, and the answer was voiced
+// with confidence.  Measured on the trained store (hubBound 571): "What is the
+// capital of" has 19 anchors, ALL saturated ("What":572, "hat ":572, "at i":572
+// …), and answered with an unrelated trained context about an integral.  That
+// breaks honest silence (§2.13), which is worse than a gap: a gap is visible, a
+// fabrication is not.
+//
+// WHY THIS IS NOT A PROBE-SHAPED PATCH.  The gate was falsified against the
+// queries the bridge answers CORRECTLY before it was written, and every one of
+// them has an unsaturated anchor with no near miss: "Who is the author of
+// Hamlet?" → "let?":12, "How do you say 'thank you' in French?" → "y 't":3,
+// "…largest planet…" → "tem?":31, "What is the capital of France?" →
+// "f Fr":114.  The honest-silence probes sit on the same side as the correct
+// ones ("Zamu":3), so this gate is not what makes them silent and cannot be
+// credited for them.  The separation is categorical, not marginal.
+//
+// WHY A TEST DOUBLE AND NOT A CORPUS.  Saturation is a LARGE-CORPUS
+// phenomenon and cannot be manufactured at fixture scale — this was measured,
+// not assumed, across three fixture designs:
+//   • one repeated template  → content addressing dedups the identical chunks,
+//     so its windows have 1–5 containers, not thousands;
+//   • template with varied surroundings → the leading windows saturate (67 at
+//     bound 66) but interior ones stay at 1, because "is the " is always the
+//     same deduped chunk whatever surrounds it;
+//   • randomised small vocabulary → most windows saturate, but cross-boundary
+//     windows ("fa b":13) cannot, since they touch only the two adjacent chunk
+//     types.
+// Every window saturating at once needs the real store's scale AND lexical
+// diversity.  So the CONDITION is supplied by a store double and the BEHAVIOUR
+// under it is asserted — the honest way to pin a rule whose trigger a fixture
+// cannot reach.  The double inflates containment only; it invents no node, and
+// the padding is a real container id, so nothing downstream reads a fiction.
+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 { substitutionBridge } from "../dist/src/mind/bridge.js";
+import { gistOf } from "../dist/src/mind/primitives.js";
+import {
+  allWindowsAreScaffolding,
+  hubBound,
+} from "../dist/src/mind/traverse.js";
+
+const enc = (s) => new TextEncoder().encode(s);
+
+/** Report every window as corpus-global: the real containers, padded with an
+ *  id that is genuinely among them, up to past the hub bound.  Only `.length`
+ *  drives the gate, and padding with a real container keeps every other reader
+ *  truthful. */
+function saturateContainment(mind) {
+  const store = mind.store;
+  const real = store.containersSlice.bind(store);
+  const bound = hubBound(mind);
+  store.containersSlice = (child, off, limit) => {
+    const got = real(child, off, limit);
+    if (got.length === 0) return got;
+    const out = got.slice();
+    while (out.length < Math.min(limit, bound + 1)) out.push(got[0]);
+    return out;
+  };
+  return () => {
+    store.containersSlice = real;
+  };
+}
+
+test("a bridge with only scaffolding anchors stays silent", async () => {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+
+  const facts = [];
+  for (let i = 0; i < 600; i++) {
+    facts.push([
+      `case ${i}: what is the qty${i} of item${i}?`,
+      `it is ${i * 2}`,
+    ]);
+  }
+  await m.ingest(facts);
+
+  const query = enc("case 7: what is the qty7 of item7?");
+  const proposed = async () =>
+    (await m.store.resonate(gistOf(m, query), 256)).map((h) => h.id);
+
+  // CONTROL — with real containment the query HAS discriminating anchors, so
+  // the gate must not apply.  Establishing this first is what makes the
+  // assertion below about saturation rather than about this query being
+  // unbridgeable for some unrelated reason.
+  const ordinary = await substitutionBridge(m, query, proposed);
+
+  // THE CONTRACT — the identical query, with every anchor now corpus-global.
+  // Nothing corroborates a substitution, so the only honest result is none.
+  const restore = saturateContainment(m);
+  try {
+    const bridged = await substitutionBridge(m, query, proposed);
+    assert.equal(
+      bridged,
+      null,
+      "a bridge whose every anchor is corpus-global scaffolding must abstain",
+    );
+  } finally {
+    restore();
+  }
+
+  // …and the gate is SELECTIVE: it changed the outcome only because of
+  // saturation.  If the bridge declined this query anyway, the assertion above
+  // would be vacuous, and this is what says it is not.
+  assert.notEqual(
+    ordinary,
+    null,
+    "fixture invalid: the bridge declines this query even with real " +
+      "containment, so the saturated assertion above pins nothing",
+  );
+
+  await m.store.close();
+});
+
+// The predicate itself, and its SECOND consumer.  The scaffolding-dominated
+// tier in mechanisms/recall.ts grounds the consensus-climb anchor, and it
+// fabricated for the same reason the bridge did: measured on the trained
+// store, "What is the capital " answered "Colombo is the commercial capital of
+// Sri Lanka…" on breadth 0.667 / clusters 1, every window a hub ("What":572).
+//
+// DISPERSION WAS TRIED THERE FIRST AND FALSIFIED — recorded here because the
+// falsification is the reason this predicate is shared rather than local: the
+// fabrication and the no-punctuation robustness probe "what is the capital of
+// france" have the IDENTICAL profile (breadth 0.667, clusters 1), so requiring
+// clusters >= 2 silenced the good probe too and cost the battery a probe.
+// Window saturation separates them cleanly where dispersion cannot
+// ("f fr":248 vs all-saturated).
+test("scaffolding-only is a property of the query, not of one mechanism", async () => {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+
+  const facts = [];
+  for (let i = 0; i < 600; i++) {
+    facts.push([
+      `case ${i}: what is the qty${i} of item${i}?`,
+      `it is ${i * 2}`,
+    ]);
+  }
+  await m.ingest(facts);
+
+  const query = enc("case 7: what is the qty7 of item7?");
+
+  // With real containment the query HAS discriminating windows.
+  assert.equal(
+    allWindowsAreScaffolding(m, query),
+    false,
+    "a query with a discriminating window must not read as scaffolding-only",
+  );
+
+  // With every window corpus-global it does not.
+  const restore = saturateContainment(m);
+  try {
+    assert.equal(
+      allWindowsAreScaffolding(m, query),
+      true,
+      "a query whose every stored window is a hub must read as scaffolding-only",
+    );
+  } finally {
+    restore();
+  }
+
+  // A query the store has never seen has no evidence EITHER WAY, and must not
+  // be mistaken for scaffolding — its callers refuse it on their own terms.
+  assert.equal(
+    allWindowsAreScaffolding(m, enc("zzqx vvwy jjkl")),
+    false,
+    "a query with no stored window at all is not scaffolding-only",
+  );
+
+  await m.store.close();
+});

package/test/74-prefix-trap-not-sprung-early.test.mjs

@@ -0,0 +1,114 @@
+// 74-prefix-trap-not-sprung-early.test.mjs — a query that is the OPENING of
+// many trained forms must stay silent, at BOTH points where that decision can
+// be made wrongly.
+//
+// THE SHAPE.  A corpus of templated facts ("what is the value of <i>?") holds
+// thousands of forms sharing one long opening.  Asked the opening alone, the
+// corpus does not say which one is meant, so the only honest answer is none.
+// Two independent defects each voiced one anyway, and each is pinned here by a
+// fixture the OTHER fix cannot rescue.
+//
+// 1. THE IDENTITY BRIDGE SPRANG THE PREFIX TRAP ITSELF.  With zero
+//    substitutions the bridge claims "a trained context IS this query, up to
+//    filler".  When the query is a strict byte PREFIX of that context, the
+//    dismissed tail is exactly the discriminating part, and grounding through
+//    it asserts a specification the asker never made.  It also PREEMPTED
+//    prefixCompletion, which runs later and owns this decision.  Fixture 1
+//    keeps every continuation at or above one grouping window, so guard 2b
+//    below cannot fire and only the deferral can produce silence.
+//
+// 2. A SUB-QUANTUM CONTINUATION WAS DROPPED FROM THE UNIQUENESS TALLY.
+//    prefixCompletion refuses to VOICE a below-window continuation, but it
+//    also removed those candidates before counting, turning "many readings,
+//    most unvoiceable" into "exactly one" — guard 3 then passed vacuously.
+//    Fixture 2 makes the competing continuations sub-quantum and the survivor
+//    voiceable, so ONLY guard 2b can produce silence.
+//
+// Both fixtures were measured before the fixes: fixture 1 answered "the value
+// of 0 is 0", fixture 2 answered "the value of 10 is 20" — each an arbitrary
+// pick from thousands of equally-good readings.
+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 { prefixCompletion } from "../dist/src/mind/prefix-completion.js";
+import { resolve } from "../dist/src/mind/primitives.js";
+
+const enc = (s) => new TextEncoder().encode(s);
+
+const dec = new TextDecoder();
+const say = async (m, q) => {
+  const r = await m.respond(q);
+  return dec.decode((r?.bytes ?? new Uint8Array()).filter((b) => b !== 0));
+};
+
+test("sub-quantum continuations still count as competing readings", async () => {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+
+  // Continuations are " 0?", " 4?", " 8?" (3 bytes, sub-quantum at W=4) and
+  // " 10?" (4 bytes, voiceable).  Dropping the short ones leaves exactly one
+  // survivor — the vacuous uniqueness this test exists to prevent.
+  const facts = [];
+  for (let i = 0; i < 4300; i++) {
+    facts.push([`what is the value of ${i}?`, `the value of ${i} is ${i * 2}`]);
+  }
+  await m.ingest(facts);
+
+  const answer = await say(m, "what is the value of");
+  assert.equal(
+    answer,
+    "",
+    `forms opening with this query continue below one grouping window — ` +
+      `they are competing readings, not absent ones; got ${
+        JSON.stringify(answer.slice(0, 60))
+      }`,
+  );
+
+  await m.store.close();
+});
+
+// GUARD 2b IN ISOLATION.  The end-to-end test above needs BOTH fixes (with the
+// identity-bridge deferral disabled it fabricates before prefixCompletion is
+// ever consulted), so it cannot attribute the silence to guard 2b alone.  This
+// one calls the mechanism directly with a candidate list of exactly the shape
+// that fooled it: several forms continuing below one grouping window and ONE
+// continuing above it.  Dropping the short ones leaves a lone survivor and
+// guard 3 passes vacuously — the defect — so a mechanism that answers here is
+// counting evidence it discarded.
+//
+// Isolating the DEFERRAL the same way was attempted and is not achievable
+// end-to-end: in every fixture whose continuations are all voiceable the
+// bridge does not ground at all, so the deferral is unreachable and such a
+// test asserts nothing.  It is pinned by the test above instead.
+test("prefixCompletion refuses when dropped candidates were the disagreement", async () => {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+
+  // W = 4.  " 0?"/" 4?"/" 8?" are 3 bytes — sub-quantum; " 10?" is 4.
+  await m.ingest([
+    ["what is the value of 0?", "zero"],
+    ["what is the value of 4?", "four"],
+    ["what is the value of 8?", "eight"],
+    ["what is the value of 10?", "ten"],
+  ]);
+
+  const query = enc("what is the value of");
+  const ranked = ["0?", "4?", "8?", "10?"].map((v) =>
+    m.store.findLeaf(enc(`what is the value of ${v}`)) ??
+      resolveForm(m, `what is the value of ${v}`)
+  );
+
+  const hit = prefixCompletion(m, query, ranked.filter((x) => x !== null));
+  assert.equal(
+    hit,
+    null,
+    `three forms open with this query and continue sub-quantum while one ` +
+      `continues perceivably; the corpus offers competing readings, so no ` +
+      `completion is licensed`,
+  );
+
+  await m.store.close();
+});
+
+function resolveForm(mind, text) {
+  return resolve(mind, enc(text));
+}