@hviana/sema 0.4.7 → 0.5.1

package/test/69-frame-filler.test.mjs

@@ -0,0 +1,115 @@
+// 69-frame-filler.test.mjs — the frame-filler tier must not fire without its
+// evidence, and must refuse an ambiguous subject.
+//
+// WHAT THE MECHANISM DOES (src/mind/frame-filler.ts): when every other tier has
+// declined, take the query's described span, put a corroborated filler from a
+// trained context in its place, and require the STORE to already hold that key
+// byte-exactly.  "We invent a lookup KEY, never an answer" — the answer is the
+// trained continuation of a form the store verifiably has.
+//
+// THE WIN IS REAL-STORE EVIDENCE, NOT A FIXTURE.  On the 15.7M-node trained
+// store, `What is the capital of the country where the Eiffel Tower is?` goes
+// from silence to "The capital of France is Paris." (provenance `recall`), taking
+// analyze_training.ts's section G from 33.3% to 66.7% and the battery from 73.8%
+// to 76.2% with `0 weak` intact.  A/B on warm caches: +50 ms on that query,
+// +16 ms on a refusing query that runs 480 probes, and +0 ms on
+// `What is the capital of Zamunda?` (guard 1 exits before probing) and on every
+// query that answers earlier.
+//
+// WHY NO POSITIVE FIXTURE TEST EXISTS — measured, not assumed.  The mechanism
+// keys on corpus RARITY (container counts, the same reading the bridge's anchor
+// picking uses).  At fixture scale that signal is absent and even inverted: in a
+// 21-deposit store `capital` reports 1 container and `landmark` reports 9, while
+// on the trained store `Eiffel` is 54 against `What` at 1,586.  So a fixture
+// cannot make the query's rarest word land inside the description, which guard 1
+// requires — three fixture shapes were tried (bare, 21-deposit, and one with an
+// attested long word in the description) and none reached the positive path.
+// What a fixture CAN pin is the refusal side, which is what this file does.
+
+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 { frameFillerSubstitution } from "../dist/src/mind/frame-filler.js";
+
+const enc = (s) => new TextEncoder().encode(s);
+const FRAME = [
+  ["What is the capital of France?", "Paris is the capital of France."],
+  ["What is the capital of Spain?", "Madrid is the capital of Spain."],
+  ["What is the capital of Italy?", "Rome is the capital of Italy."],
+  ["What is the capital of Japan?", "Tokyo is the capital of Japan."],
+];
+const LINK = [
+  "What is the most famous landmark in France?",
+  "The most famous landmark in France is the Eiffel Tower.",
+];
+const LINK2 = [
+  "What is the tallest structure in Spain?",
+  "The tallest structure in Spain is the Eiffel Tower.",
+];
+const Q = "What is the capital of the country where the Eiffel Tower is?";
+
+async function fixture(train) {
+  const mind = new Mind({
+    seed: 1,
+    store: new SQliteStore({ path: ":memory:" }),
+  });
+  await mind.ingest(train);
+  return mind;
+}
+/** Call the tier the way recall does: the query plus recall's ranked hit ids. */
+async function tier(mind, q) {
+  const hits = await mind.store.resonate(mind.perceive(q).v, 24);
+  return frameFillerSubstitution(mind, enc(q), hits.map((h) => h.id));
+}
+
+test("1. no linking evidence — the tier does not fire", async () => {
+  // The frame is attested, but nothing in the store ties the description's
+  // content to any filler.  Guard 1 has nothing to qualify.
+  const m = await fixture(FRAME);
+  assert.equal(await tier(m, Q), null);
+  await m.store.close();
+});
+
+test("2. an AMBIGUOUS subject is refused", async () => {
+  // Two trained contexts hold the description's content and each proposes a
+  // different filler.  Guard 4: neither is licensed.
+  const m = await fixture([...FRAME, LINK, LINK2]);
+  assert.equal(await tier(m, Q), null);
+  await m.store.close();
+});
+
+test("3. an unrelated query never grounds a frame neighbour", async () => {
+  // The fabrication shape: a fictional filler in an attested frame.  On the real
+  // store this query resolves 24 keys (Chile, India, Japan, Italy …) once the
+  // guards are weakened, so it is the case that most needs pinning.
+  const m = await fixture([...FRAME, LINK]);
+  for (
+    const q of [
+      "What is the capital of Zamunda?",
+      "xyzzy plugh quux baz?",
+      "qq8f3kz9 vv2m1x7w?",
+    ]
+  ) {
+    assert.equal(await tier(m, q), null, `expected refusal for ${q}`);
+  }
+  await m.store.close();
+});
+
+test("4. the tier is deterministic and side-effect free", async () => {
+  const m = await fixture([...FRAME, LINK]);
+  const a = await tier(m, Q);
+  const b = await tier(m, Q);
+  assert.deepEqual(a, b);
+  // Running it must not disturb the answers of forms that ground normally.
+  assert.match(await m.respondText("What is the capital of France?"), /Paris/);
+  await m.store.close();
+});
+
+test("5. end to end, the fixture's own trained forms still answer", async () => {
+  const m = await fixture([...FRAME, LINK]);
+  assert.match(await m.respondText("What is the capital of Spain?"), /Madrid/);
+  assert.match(await m.respondText("What is the capital of Japan?"), /Tokyo/);
+  assert.equal(await m.respondText("qq8f3kz9 vv2m1x7w?"), "");
+  await m.store.close();
+});

package/test/70-prefix-completion.test.mjs

@@ -0,0 +1,170 @@
+// 70-prefix-completion.test.mjs — a query that IS the opening of one trained
+// form is completed by that form's remainder; anything less is refused.
+//
+// WHAT THE MECHANISM DOES (src/mind/prefix-completion.ts): when every other
+// tier has declined, scan the candidate list recall's refusal path has ALREADY
+// fetched and look for a trained form whose bytes literally BEGIN with the whole
+// query.  The answer is that form's own remainder — never an invention.
+//
+// WHY IT IS NEEDED, measured on the 15.7M-node trained store:
+// `The capital of France is` grounded nothing, while
+// `The capital of France is Paris.` is trained and reads back byte-exact.  Two
+// independent reasons the earlier tiers cannot reach it:
+//   * `resolve(prefix)` is null — a proper prefix has no branch of its own.
+//   * the form is absent from `resonate(k)` at k = 24, 256 AND 2048, while forms
+//     scoring LOWER are returned (cos 0.5752 for the target against Germany
+//     0.5670, Yemen 0.5591).  `k` only reorders within the IVF clusters already
+//     probed, so no k recovers it; with `exhaustive` it ranks 8.
+// It is a RETRIEVABILITY gap, not a semantic one.
+//
+// COST — A/B on the trained store, counting resonate calls directly: the tier
+// adds ZERO exhaustive calls.  F-prefix already made exactly one (for the
+// substitution bridge) and returned silence; with the tier it makes the same one
+// and answers.  Battery: F 0% → 25%, overall 76.2% → 78.6%, `0 weak`, all three
+// honest-silence probes still silent, median latency 0.63s → 0.57s.
+//
+// Unlike test/69, a POSITIVE fixture IS constructible here: the mechanism keys
+// on literal byte containment, not on corpus rarity, and rarity is the signal
+// that collapses at fixture scale.
+//
+// The mechanism has NO notion of text: no separator, no character class, no
+// "word".  Its only structural quantity is W, the river's grouping window.  So
+// these fixtures are readable prose only for the reader's benefit -- every
+// assertion below is about bytes and geometry.
+
+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";
+
+const enc = (s) => new TextEncoder().encode(s);
+const dec = new TextDecoder();
+
+async function fixture(train) {
+  const mind = new Mind({
+    seed: 1,
+    store: new SQliteStore({ path: ":memory:" }),
+  });
+  await mind.ingest(train);
+  return mind;
+}
+/** Call the tier the way recall does: the query plus a ranked hit list. */
+async function tier(mind, q, k = 64) {
+  const hits = await mind.store.resonate(mind.perceive(q).v, k);
+  return prefixCompletion(mind, enc(q), hits.map((h) => h.id));
+}
+
+const FACTS = [
+  "The capital of France is Paris.",
+  "The capital of Japan is Tokyo.",
+  "The capital of Germany is Berlin.",
+];
+
+test("1. the sole form opening with the query is completed by its remainder", async () => {
+  const m = await fixture(FACTS);
+  const hit = await tier(m, "The capital of France is");
+  assert.notEqual(hit, null, "the trained form opens with the query");
+  assert.equal(dec.decode(hit.form), "The capital of France is Paris.");
+  await m.store.close();
+});
+
+test("2. AMBIGUITY is refused — the prefix trap", async () => {
+  // Two trained forms open with the same words and continue differently.  The
+  // corpus does not say which completion the asker means, so neither is
+  // licensed.  This is the documented prefix trap, and it is real — it simply
+  // does not hold for EVERY prefix, which is what test 1 pins.
+  const m = await fixture([
+    "The capital city is Paris.",
+    "The capital city is Berlin.",
+  ]);
+  assert.equal(await tier(m, "The capital city is"), null);
+  await m.store.close();
+});
+
+test("3. the same completion via two forms is ONE answer, not an ambiguity", async () => {
+  // Uniqueness is judged on the remainder BYTES, not on the candidate id.
+  const m = await fixture([
+    "The capital of France is Paris.",
+    "The capital of France is Paris.",
+  ]);
+  const hit = await tier(m, "The capital of France is");
+  assert.notEqual(hit, null);
+  assert.equal(dec.decode(hit.form), "The capital of France is Paris.");
+  await m.store.close();
+});
+
+test("4. a SUB-QUANTUM continuation is refused", async () => {
+  // Observed on the trained store: `What is the capital of France?` opens a
+  // trained `What is the capital of France??`, which continues by ONE byte.
+  // Below W the continuation is sub-quantum -- the fold groups nothing from it
+  // -- and voicing it is the degenerate reply of the battery's section M.
+  // The bar is the grouping window, not a punctuation class.
+  const m = await fixture(["What is the capital of France??"]);
+  assert.equal(await tier(m, "What is the capital of France?"), null);
+  await m.store.close();
+});
+
+test("5. a query no trained form opens with is refused", async () => {
+  const m = await fixture(FACTS);
+  for (
+    const q of [
+      "The capital of Zamunda is",
+      "xyzzy plugh quux",
+      "Paris is the capital of",
+    ]
+  ) {
+    assert.equal(await tier(m, q), null, q);
+  }
+  await m.store.close();
+});
+
+test("6. a query that is a whole trained form is not 'completed' by itself", async () => {
+  // An exact form has an EMPTY remainder, which no guard should let through —
+  // and the exact tiers own that query anyway.
+  const m = await fixture(FACTS);
+  assert.equal(await tier(m, "The capital of France is Paris."), null);
+  await m.store.close();
+});
+
+test("7. the tier is deterministic and side-effect free", async () => {
+  const m = await fixture(FACTS);
+  const q = "The capital of France is";
+  const before = m.store.nodeCount();
+  const a = await tier(m, q);
+  const b = await tier(m, q);
+  assert.equal(dec.decode(a.form), dec.decode(b.form));
+  assert.equal(a.id, b.id);
+  assert.equal(
+    m.store.nodeCount(),
+    before,
+    "the tier must not intern anything",
+  );
+  await m.store.close();
+});
+
+test("9. a form that continues past the read bound vetoes", async () => {
+  // Reads are bounded (query.length * W).  A candidate that opens with the
+  // query but SATURATES the read continues out of sight, so it is a standing
+  // disagreement -- NOT something to skip.  Skipping it is what manufactures a
+  // fragment: it removes the only evidence contradicting an interior fold node
+  // that happens to fit under the cap.
+  const q = "The capital of France is";
+  const long = q + " Paris, and the country's largest city by a wide margin, " +
+    "a global centre for art, fashion, gastronomy and culture.";
+  assert.ok(long.length > q.length * 4, "the fixture must exceed the cap");
+  const m = await fixture([long]);
+  assert.equal(await tier(m, q), null);
+  await m.store.close();
+});
+
+test("8. end to end, the fixture's own trained forms still answer", async () => {
+  // The tier sits on the refusal path; it must not disturb normal grounding.
+  const m = await fixture([
+    "What is the capital of France?",
+    "The capital of France is Paris.",
+  ]);
+  const r = await m.respond("What is the capital of France?");
+  assert.ok(r.bytes.length > 0, "a trained question still answers");
+  await m.store.close();
+});

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();
+});