@hviana/sema 0.4.7 → 0.5.1

package/dist/src/mind/mind.js

@@ -10,16 +10,16 @@
 // Implementation split across src/mind/*.ts — this file assembles the Mind class.
 import { makeKeyring, rng, setVecConfig } from "../vec.js";
 import { Alphabet } from "../alphabet.js";
-import { bytesToTree, reachThreshold, } from "../geometry.js";
+import { contentFoldIncremental, reachThreshold, } from "../geometry.js";
 import { BoundedMap } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
 import { resolveConfig } from "../config.js";
-import { canonHash, textCanon } from "../canon.js";
+import { canonHash, textCanon, textEdgeTrim } from "../canon.js";
 import { bytesEqual, concat2 } from "../bytes.js";
 import { GraphSearch, } from "./graph-search.js";
 import { Alu } from "../alu/src/index.js";
 import { decodeText, Rationale, } from "./rationale.js";
-import { gistOf, inputBytes, latin1Key, perceive as perceiveImpl, resolve as resolveImpl, } from "./primitives.js";
+import { gistOf, inputBytes, perceive as perceiveImpl, perceiveKey, resolve as resolveImpl, } from "./primitives.js";
 import { chooseNext, edgeAncestors as edgeAncestorsFn, invalidateStructuralCaches, } from "./traverse.js";
 import { invalidateJunctionCache } from "./junction.js";
 import { follow } from "./match.js";
@@ -206,8 +206,9 @@ export class Mind {
      *  serves BOTH entry points: `respond` takes fresh per-response memos,
      *  `respondTurn` passes its conversation, whose memos persist across turns
      *  (content-keyed, so the previous turn's results are found by this turn's
-     *  sub-span calls) and whose `resolvedSubtrees` makes foldTree O(suffix)
-     *  instead of O(context).  respondTurn used to inline its own copy of this
+     *  sub-span calls) and whose `resolvedSubtrees` spares foldTree the store
+     *  probes for every prefix subtree — and, for walks that pass no visitor,
+     *  the descent as well.  respondTurn used to inline its own copy of this
      *  and of {@link endResponse}; the two drifted (a memo added to one was
      *  silently absent from the other), so there is exactly one pair now. */
     beginResponse(inspectRationale, canon, conv) {
@@ -322,12 +323,58 @@ export class Mind {
             provenance: thought.provenance,
         };
     }
+    /** Answer ONE self-contained input.
+     *
+     *  A MULTI-TURN context is not that, and this is the wrong entry point for
+     *  it.  `respond` folds the bytes it is handed with no boundary set, because
+     *  nothing in a flat byte string says where one turn ended — only the caller
+     *  who assembled it knows, which is the whole reason `boundaries` is a
+     *  parameter of {@link perceiveImpl} and never inferred from content.  A
+     *  conversation deposited through {@link ingest} folds its contexts over
+     *  those turn boundaries, so a hand-concatenated transcript passed here
+     *  folds differently from the way it was learnt and reaches the trained
+     *  context node only by luck (measured on a 7-turn conversation: 5/7 here
+     *  against 7/7 through {@link respondTurn}, same bytes).  Use
+     *  {@link beginConversation} + {@link respondTurn}, or {@link addTurn} to
+     *  replay turns the Mind should hear but not answer. */
     async respond(input, inspectRationale) {
         // A STRING input is text by nature: it carries the text equivalence even
         // through the generic entry point.  Raw bytes / grids carry only the
         // Mind-level canon option, if any.
         const canon = this._canonFor(typeof input === "string" ? textCanon : null);
-        return this._respondImpl(inputBytes(this, input), inspectRationale, "respond", canon);
+        // EDGE WHITESPACE IS NOT PART OF THE QUESTION — trim it once, here, so
+        // every mechanism downstream sees the same question regardless of how the
+        // caller spaced it.  See canon.ts's textEdgeTrim for why the outer edges of a
+        // whole input are exactly where canon.ts's no-trimming hazard cannot arise.
+        // Gated on the SAME modality test as the canonicalizer above: for bytes and
+        // grids 0x20 is content, and nothing is trimmed.
+        //
+        // Measured on the 15.7M-node store: without this, one leading space took
+        // `Who wrote Romeo and Juliet?` and `What is the chemical symbol for
+        // water?` from answered to silent, because a shift re-seats every fold
+        // boundary — the whole of analyze_training.ts's K2 phase-robustness gap.
+        // The caller's EXACT bytes are tried first and the trim is a RETRY, not a
+        // pre-filter.  Trimming up front is asymmetric — it normalises the query but
+        // not the stored forms — so it breaks byte-exact identity for a form trained
+        // WITH edge whitespace: test/04 deposits ["  ice  ", "cold"] and asks
+        // "  ice  ", which must keep answering.  Retrying preserves that (the raw
+        // query resolves on the first pass) while still reaching the padded case
+        // (the raw query grounds nothing, the trimmed one does).
+        //
+        // COST: nothing on any answering path.  The retry needs BOTH silence AND
+        // edge whitespace on the query, the same "only on the already-failed path"
+        // discipline test/44 and the bridge's own trim retry use.  The conversation
+        // entry point (respondTurn) is deliberately NOT trimmed — it tracks
+        // turn-boundary offsets into its accumulated context, and shifting the bytes
+        // under those offsets would desync them.
+        const bytes = inputBytes(this, input);
+        const first = await this._respondImpl(bytes, inspectRationale, "respond", canon);
+        if (first.bytes.length > 0 || typeof input !== "string")
+            return first;
+        const trimmed = textEdgeTrim(bytes);
+        if (trimmed.length === bytes.length || trimmed.length === 0)
+            return first;
+        return this._respondImpl(trimmed, inspectRationale, "respond", canon);
     }
     /** Text view of {@link respond}.  NUL bytes (0x00) are stripped before
      *  decoding — they are structural padding in text answers.  LOSSY for a
@@ -354,15 +401,35 @@ export class Mind {
     beginConversation(state) {
         const id = this._nextConvId++;
         const initBytes = state?.context ?? new Uint8Array(0);
-        const initBoundaries = state?.boundaries ? [...state.boundaries] : [];
+        // NORMALISE CALLER-SUPPLIED BOUNDARIES.  `boundaries` is documented
+        // strictly increasing and every boundary this class produces is (they are
+        // appended as the context grows), but a restored {@link ConversationState}
+        // comes from OUTSIDE — hand-built, migrated, or round-tripped through a
+        // store that did not preserve order.  The folds consume boundaries with a
+        // sequential `b > prev` filter, so an out-of-order entry is silently
+        // DROPPED rather than rejected, and the conversation would then fold over
+        // a different cut set than the one the caller believes it restored.
+        // `bytesToTree` used to sort on the way in and absorbed this; the
+        // incremental fold this now calls does not, so the normalisation belongs
+        // here, at the one public door untrusted boundaries come through.
+        const initBoundaries = state?.boundaries
+            ? [...new Set(state.boundaries)]
+                .filter((b) => b > 0 && b < initBytes.length)
+                .sort((a, b) => a - b)
+            : [];
         const initAnswered = state?.answeredSpans
             ? state.answeredSpans.map(([start, end]) => [start, end])
             : initBoundaries.flatMap((start, i, cuts) => i % 2 === 0 && i + 1 < cuts.length
                 ? [[start, cuts[i + 1]]]
                 : []);
-        const tree = bytesToTree(this.space, this.alphabet, initBytes, undefined, undefined, initBoundaries.length > 0 ? initBoundaries : undefined);
+        // The same incremental fold `_growContext` uses, so a RESTORED
+        // conversation starts with segment state its next turn can reuse — a
+        // resumed conversation is otherwise identical to a live one and must not
+        // pay a full re-fold on every turn for the rest of its life.
+        const restored = contentFoldIncremental(this.space, this.alphabet, initBytes);
         this._conversations.set(id, {
-            tree,
+            tree: restored.tree,
+            content: restored.fold,
             bytes: initBytes,
             boundaries: initBoundaries,
             answeredSpans: initAnswered,
@@ -397,7 +464,41 @@ export class Mind {
      *  This is the primitive for turns the Mind should hear but not answer:
      *  replaying a transcript, feeding the OTHER speaker's line in a
      *  prediction harness, or restoring context piecewise.  {@link
-     *  respondTurn} = addTurn + think + its own reply appended the same way. */
+     *  respondTurn} = addTurn + think + its own reply appended the same way.
+     *
+     *  ── ON SEPARATORS: THERE IS NO SEPARATOR QUESTION ────────────────────
+     *
+     *  "Never a separator" above says what this method DOES — it appends the
+     *  bytes you give it and records an OFFSET — not that separator bytes are
+     *  forbidden, unsupported, or something the engine must be taught about.
+     *  Sema is agnostic to them, and reviewers keep mistaking that agnosticism
+     *  for a constraint.  To be explicit, because the mistake is easy:
+     *
+     *  1. A turn boundary is an OFFSET, held here, in `boundaries`.  It is
+     *     never a character the geometry scans for.  Nothing downstream asks
+     *     "what byte separates two turns?" because nothing downstream finds
+     *     boundaries by looking at content at all.
+     *  2. A separator in a CORPUS is ordinary content.  If a trainer joins
+     *     turns with "\n" (example/train_base.ts does), those newlines are
+     *     simply bytes inside the stream, folded like every other byte.  They
+     *     are a property of that corpus, not of this API and not of the fold.
+     *  3. This API can therefore reproduce ANY corpus exactly, with no
+     *     convention to agree on: replaying a "\n"-joined corpus means passing
+     *     `"\n" + turnText` as the turn.  The separator rides along IN the
+     *     turn bytes, where it belongs.  There is nothing to configure and no
+     *     mode to select.
+     *  4. Inference is not exact-match anyway.  Recognition works over
+     *     sub-spans, canonical equivalence and resonance, so a query that
+     *     differs from the trained bytes by punctuation or whitespace still
+     *     reaches the trained forms; it degrades, it does not fail closed.
+     *
+     *  What follows from 1–4: differing separator bytes between a corpus and a
+     *  query is an ordinary CONTENT difference — the same kind as any other
+     *  wording difference — and it is measured the same way.  It is NOT an
+     *  incompatibility between the trainer and this API, and it does NOT
+     *  require choosing a project-wide separator convention.  A review that
+     *  concludes otherwise (this one did, before being corrected) has mistaken
+     *  its own harness feeding untrained bytes for an architectural defect. */
     addTurn(conv, turn) {
         const data = this._conversations.get(conv.id);
         if (!data)
@@ -422,10 +523,37 @@ export class Mind {
         const grown = prevLen > 0 ? concat2(data.bytes, turnBytes) : turnBytes;
         if (prevLen > 0)
             data.boundaries.push(prevLen);
-        const tree = bytesToTree(this.space, this.alphabet, grown, undefined, undefined, data.boundaries.length > 0 ? data.boundaries : undefined);
+        // THE PLAIN FOLD, INCREMENTALLY.  No boundary set is imposed here: the
+        // tree is exactly the tree `perceive(grown)` builds for these bytes, which
+        // is exactly the tree the DEPOSIT path folded when it learnt them.  That
+        // agreement is the whole point — it is what lets a cumulative context
+        // resolve to its trained node, and when it was absent the alignment family
+        // went quadratic (measured: 5.2M cells on a 476-byte context, against 0
+        // when the two sides agree).
+        //
+        // The optimisation is unaffected by dropping the boundaries, because it
+        // never came from them: content cuts are stable under append, so the
+        // incremental fold reuses every segment left of the new turn as the SAME
+        // object (see contentFoldIncremental).  That object identity is what
+        // `resolvedSubtrees` — a WeakMap keyed by node identity — needs in order
+        // to hit at all.  Measured against the stable-prefix fold it replaces:
+        // ~40 rebuilt nodes per turn either way, flat as the context grows
+        // sevenfold, and ~92% of nodes reused by identity in both.
+        //
+        // `data.boundaries` is still tracked, and is still exact — it is API
+        // metadata (ConversationState, answeredSpans, currentTurnStart), not a
+        // fold instruction.
+        const folded = contentFoldIncremental(this.space, this.alphabet, grown, data.content);
+        const tree = folded.tree;
+        data.content = folded.fold;
         data.tree = tree;
         data.bytes = grown;
-        data.perceiveMemo.set(latin1Key(grown), tree);
+        // Seeded under the PLAIN content key, and that is now the only key there
+        // is: with no boundary set imposed, this tree IS what `perceive(grown)`
+        // computes, so the memo entry is an ordinary cache hit rather than the
+        // deliberate alias it had to be while the two folds differed.  The entry
+        // saves the pipeline re-folding the context it was just handed.
+        data.perceiveMemo.set(perceiveKey(grown), tree);
         return tree;
     }
     /** Process one turn of a conversation.

package/dist/src/mind/pipeline-mechanism.d.ts

@@ -122,6 +122,13 @@ export interface MechanismResult {
     unexplained: string;
     /** Explicit weight override.  When absent, weight = moves + PASS·unaccounted. */
     weight?: number;
+    /** Bytes of `bytes` that came from spans nothing recognised — the asker's
+     *  own words carried through verbatim rather than derived (see
+     *  {@link liftedScaffolding}).  Reported, not priced: the ladder prices what
+     *  a candidate leaves UNACCOUNTED, and this orders candidates that tie on
+     *  exactly that.  Omit when a mechanism composes its answer entirely from
+     *  recognised material, which is the usual case. */
+    scaffolding?: number;
     /** Override the mechanism's default provenance for this result.
      *  When absent, the pipeline uses `mech.provenance`. */
     provenance?: string;

package/dist/src/mind/pipeline.js

@@ -108,7 +108,34 @@ export async function think(ctx, query, mechs) {
         if (ctx.meter)
             ctx.meter.candidates++;
         candidates.push(c);
-        if (best === null || grade(c.weight) < grade(best.weight))
+        if (best === null) {
+            best = c;
+            return;
+        }
+        const g = grade(c.weight), gb = grade(best.weight);
+        if (g < gb) {
+            best = c;
+            return;
+        }
+        // TIE-BREAK: AT EQUAL GRADE, PREFER THE ANSWER THAT INVENTS LESS.
+        //
+        // The ladder prices what a candidate leaves UNACCOUNTED, which is the
+        // right primary question but cannot separate two candidates that leave
+        // the same bytes unaccounted — and then the winner is whichever mechanism
+        // happened to be considered first, which is not a reason.
+        //
+        // What still separates them is what they DID with those bytes.  A
+        // candidate that carries an unexplained span into its answer is passing
+        // the asker's own words back as if they were derived; one that leaves
+        // them out has made a smaller, honest claim.  Measured on test/22's
+        // two-fact chain: cover and recall both graded 11001 over 11 unexplained
+        // bytes, cover answering "The capital of France is Paris famous for" (11
+        // bytes of scaffolding) against recall's crossing of the hop (0).  Order
+        // alone decided it, and the shallower reading won.
+        //
+        // This never overrides the ladder — it only orders within one grade, so
+        // coverage and moves still dominate exactly as before.
+        if (g === gb && (c.scaffolding ?? 0) < (best.scaffolding ?? 0))
             best = c;
     };
     const worthRunning = (floor) => best === null || grade(floor) < grade(best.weight);
@@ -150,6 +177,7 @@ export async function think(ctx, query, mechs) {
                 accounted: r.accounted,
                 unexplained: r.unexplained,
                 complete: r.complete,
+                scaffolding: r.scaffolding,
             });
         }
     }

package/dist/src/mind/prefix-completion.d.ts

@@ -0,0 +1,59 @@
+import type { MindContext } from "./types.js";
+/** Trained forms the query may OPEN, proposed from the write side's own
+ *  leaf-id window index — the supply of last resort for {@link
+ *  prefixCompletion}.
+ *
+ *  WHY A SECOND SUPPLY EXISTS.  The ranked list this mechanism normally reads
+ *  is a resonance list, and resonance cannot rank a proper prefix: measured on
+ *  the trained 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.
+ *  Three bytes of truncation put the answer out of reach on GEOMETRY, not on a
+ *  bug, so no k and no re-ranking recovers it.
+ *
+ *  WHY THIS ROUTE WORKS WHERE THE FOLD DOES NOT.  A query's own fold is
+ *  useless here: content addressing is not phrase-position-invariant, so a
+ *  standalone prefix folds to a DIFFERENT node than the same bytes sitting
+ *  inside a longer deposit, and neither the prefix's own node nor its
+ *  ancestors lead to the deposit (measured: the 22-byte prefix of the
+ *  photosynthesis form resolves, is shared by 6 contexts, and does not have
+ *  the form among its ancestors).  Leaf ids ARE position-invariant — they are
+ *  content-addressed on single bytes — and `indexSubSpans` already interns a
+ *  flat branch over every canonical WINDOW of a deposit's leaf-id stream, with
+ *  containment edges to the chunks that window spans.  A query that is a
+ *  prefix therefore shares those window nodes exactly, and reaches the deposit
+ *  by climbing containment then parents.  Nothing is added to the write side;
+ *  this reads an index training already built.
+ *
+ *  BOUNDED (§2.8), AND WITH NO NEW THRESHOLD.  The window whose containment is
+ *  SMALLEST carries the most evidence, and one saturated at `hubBound` carries
+ *  none — that is the same √N reading of "hub" the rest of the mind uses, not
+ *  a tuned knob.  The upward walk spends a budget of `hubBound` nodes and
+ *  fans out by W, so a hub query enumerates nothing and the caller stays
+ *  silent rather than guessing (§2.13).  Measured on the trained store: the
+ *  photosynthesis form at a one-byte truncation picks a window with 52
+ *  containers, visits 446 nodes, and yields exactly ONE candidate that
+ *  survives the caller's byte compare — the form itself.
+ *
+ *  These are PROPOSALS only.  Every candidate still faces the byte-exact
+ *  prefix compare and all three guards below, so a wrong proposal costs one
+ *  bounded read and can never be voiced (§2.3). */
+export declare function prefixCandidates(ctx: MindContext, query: Uint8Array): number[];
+/** A trained form the query opens, and the bytes by which it continues. */
+export interface PrefixCompletion {
+    /** The trained form whose opening the query is — the answer, voiced whole. */
+    id: number;
+    /** The form's own bytes.  The mechanism grounds a FORM, never a slice of
+     *  one: slicing at the query's end would cut at an offset the geometry has
+     *  no reason to treat as a boundary. */
+    form: Uint8Array;
+    /** The bytes past the query — carried for the rationale and for the
+     *  uniqueness comparison, not voiced on its own. */
+    continuation: Uint8Array;
+}
+/** The sole trained form the query opens — or null when no candidate opens with
+ *  it, when the continuation is sub-quantum, when a candidate's continuation
+ *  cannot be read through, or when the candidates disagree.
+ *
+ *  `ranked` must be a list the caller has ALREADY fetched; this mechanism never
+ *  resonates on its own (see the header's cost note). */
+export declare function prefixCompletion(ctx: MindContext, query: Uint8Array, ranked: ReadonlyArray<number>): PrefixCompletion | null;

package/dist/src/mind/prefix-completion.js

@@ -0,0 +1,270 @@
+// prefix-completion.ts — Grounding a query that IS the opening of a trained
+// form.
+//
+// THE SHAPE.  `The capital of France is` grounds nothing, while
+// `The capital of France is Paris.` is trained and reads back byte-exact.  The
+// query is not SIMILAR to that form, it is a PROPER PREFIX of it: every query
+// byte is a literal match, in order, from offset zero.  That is the strongest
+// grounding relation in the store — stronger than the bridge's corroborated
+// substitution, which pays a CONCEPT per substituted span, and stronger than
+// resonance, which only claims an angle.  Nothing is invented: the answer IS a
+// trained form, voiced whole.
+//
+// NO NOTION OF TEXT.  This mechanism reads bytes and geometry only.  It has no
+// separator, no character class, no "word": the only structural quantity it
+// uses is W, the river's grouping window, which is the same capacity the
+// perception tree groups by and the same bar the argument-binding tier holds
+// its constituents to.  A completion shorter than one grouping window carries
+// no structure the geometry can perceive, whatever the modality — that is a
+// statement about the fold, not about punctuation.  Presentation (what is
+// "spacing", what is "case") belongs to the injected canon and to the modality
+// entry point, never here; see src/canon.ts.
+//
+// WHY THE EARLIER TIERS CANNOT DO IT.  Two independent reasons, both measured:
+//
+//   1. `resolve(prefix)` is null.  A proper prefix of a deposited stream has no
+//      branch of its own unless it was itself deposited, so the exact tiers
+//      have nothing to find.
+//   2. The form is not among the resonance candidates AT ALL.  Measured on the
+//      trained store: cos(query, that form) = 0.5752, yet the form is absent
+//      from `resonate(k)` at k = 24, 256 AND 2048 — while forms scoring LOWER
+//      (Germany 0.5670, Yemen 0.5591) are returned.  `k` only reorders WITHIN
+//      the IVF clusters already probed, exactly as Store.resonate's doc warns,
+//      so no k recovers it.  With `exhaustive` it ranks 8.
+//
+// So this is a RETRIEVABILITY gap, not a semantic one, and it is repaired by
+// reading the candidate list recall's refusal path has ALREADY fetched
+// exhaustively for the substitution bridge — never by resonating on its own.
+// Measured cost of the scan over those 570 candidates: 2.9 ms warm, 20.4 ms
+// cold, against a ~700 ms refusal path.  Issuing a FRESH exhaustive call would
+// cost 490 ms median against 13 ms non-exhaustive (36×), which is why this tier
+// takes the candidate list as an argument and adds nothing to it.
+//
+// THREE GUARDS, each falsified into existence by measurement — do not drop any:
+//
+//   1. AN UNREADABLE CONTINUATION VETOES.  Reads are bounded (a stored span can
+//      run to hundreds of kilobytes), so a candidate that opens with the query
+//      but SATURATES the read continues in a way nobody can see.  It is a
+//      standing disagreement: if any such candidate exists, nothing is grounded.
+//      It must NOT be quietly skipped, and that is not a stylistic point — the
+//      skip is what MANUFACTURES a fragment.  Measured on a one-deposit fixture
+//      whose form exceeds the cap: the query matched BOTH the whole 138-byte
+//      form (saturating) AND an interior fold node of 34 bytes (unsaturated,
+//      continuing `" Paris, an"`).  Skipping the saturated candidate removed the
+//      only evidence that disagreed, uniqueness then passed on the interior
+//      node, and a mid-form slice was voiced as an answer.  Suppressing the
+//      disagreement is what created the fabrication.
+//      (Testing instead whether a candidate is a "complete form" via the fold
+//      does NOT work and was measured: content addressing makes an interior
+//      node resolve to ITSELF, so self-resolution says nothing about
+//      completeness.)
+//   2. THE CONTINUATION MUST REACH ONE GROUPING WINDOW.  A trained
+//      `What is the capital of France??` opens with `What is the capital of
+//      France?` and continues by a single byte.  Below W the continuation is
+//      sub-quantum — the fold groups nothing from it — and voicing it produces
+//      the degenerate reply that is a known failure smell.
+//   3. UNIQUENESS.  Several trained forms may open with the query and continue
+//      differently, and then the corpus does not say which continuation the
+//      asker means.  Distinct continuations ⇒ refuse.  This is the documented
+//      PREFIX TRAP, and it is real — just not for every prefix.  Measured: of
+//      15 battery probes exactly ONE yields a unique continuation, and all
+//      three honest-silence probes yield none (including `What is the capital
+//      of Zamunda?`, whose top hit scores 0.83).
+//
+// Uniqueness is judged on the continuation BYTES, not on the candidate id: the
+// same continuation reached through two trained forms is one answer, not an
+// ambiguity.
+import { bytesEqual } from "../bytes.js";
+import { rItem } from "./trace.js";
+import { canonicalWindows, leafIdPrefix } from "./canonical.js";
+import { hubBound } from "./traverse.js";
+/** Trained forms the query may OPEN, proposed from the write side's own
+ *  leaf-id window index — the supply of last resort for {@link
+ *  prefixCompletion}.
+ *
+ *  WHY A SECOND SUPPLY EXISTS.  The ranked list this mechanism normally reads
+ *  is a resonance list, and resonance cannot rank a proper prefix: measured on
+ *  the trained 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.
+ *  Three bytes of truncation put the answer out of reach on GEOMETRY, not on a
+ *  bug, so no k and no re-ranking recovers it.
+ *
+ *  WHY THIS ROUTE WORKS WHERE THE FOLD DOES NOT.  A query's own fold is
+ *  useless here: content addressing is not phrase-position-invariant, so a
+ *  standalone prefix folds to a DIFFERENT node than the same bytes sitting
+ *  inside a longer deposit, and neither the prefix's own node nor its
+ *  ancestors lead to the deposit (measured: the 22-byte prefix of the
+ *  photosynthesis form resolves, is shared by 6 contexts, and does not have
+ *  the form among its ancestors).  Leaf ids ARE position-invariant — they are
+ *  content-addressed on single bytes — and `indexSubSpans` already interns a
+ *  flat branch over every canonical WINDOW of a deposit's leaf-id stream, with
+ *  containment edges to the chunks that window spans.  A query that is a
+ *  prefix therefore shares those window nodes exactly, and reaches the deposit
+ *  by climbing containment then parents.  Nothing is added to the write side;
+ *  this reads an index training already built.
+ *
+ *  BOUNDED (§2.8), AND WITH NO NEW THRESHOLD.  The window whose containment is
+ *  SMALLEST carries the most evidence, and one saturated at `hubBound` carries
+ *  none — that is the same √N reading of "hub" the rest of the mind uses, not
+ *  a tuned knob.  The upward walk spends a budget of `hubBound` nodes and
+ *  fans out by W, so a hub query enumerates nothing and the caller stays
+ *  silent rather than guessing (§2.13).  Measured on the trained store: the
+ *  photosynthesis form at a one-byte truncation picks a window with 52
+ *  containers, visits 446 nodes, and yields exactly ONE candidate that
+ *  survives the caller's byte compare — the form itself.
+ *
+ *  These are PROPOSALS only.  Every candidate still faces the byte-exact
+ *  prefix compare and all three guards below, so a wrong proposal costs one
+ *  bounded read and can never be voiced (§2.3). */
+export function prefixCandidates(ctx, query) {
+    const store = ctx.store;
+    const W = ctx.space.maxGroup;
+    const run = leafIdPrefix(ctx, query);
+    // The widest canonical window is the most discriminative one the write side
+    // ever interned; a query too short to spell one carries no window evidence.
+    const len = canonicalWindows(W)[1];
+    if (run.length < len)
+        return [];
+    const bound = hubBound(ctx);
+    let best = null;
+    let bestN = 0;
+    for (let off = 0; off + len <= run.length; off++) {
+        const wid = store.findBranch(run.slice(off, off + len));
+        if (wid === null)
+            continue;
+        const n = store.containersSlice(wid, 0, bound).length;
+        // Empty says the window spans no chunk; saturated says it is a hub, whose
+        // containment discriminates nothing.  Neither is evidence.
+        if (n === 0 || n >= bound)
+            continue;
+        if (best === null || n < bestN) {
+            best = wid;
+            bestN = n;
+        }
+    }
+    if (best === null)
+        return [];
+    let frontier = store.containersSlice(best, 0, bound);
+    const seen = new Set(frontier);
+    let budget = bound;
+    while (frontier.length > 0 && budget > 0) {
+        const next = [];
+        for (const f of frontier) {
+            if (budget-- <= 0)
+                break;
+            for (const p of store.parentsFirst(f, W)) {
+                if (seen.has(p))
+                    continue;
+                seen.add(p);
+                next.push(p);
+            }
+        }
+        frontier = next;
+    }
+    return [...seen];
+}
+/** The sole trained form the query opens — or null when no candidate opens with
+ *  it, when the continuation is sub-quantum, when a candidate's continuation
+ *  cannot be read through, or when the candidates disagree.
+ *
+ *  `ranked` must be a list the caller has ALREADY fetched; this mechanism never
+ *  resonates on its own (see the header's cost note). */
+export function prefixCompletion(ctx, query, ranked) {
+    const W = ctx.space.maxGroup;
+    const t = ctx.trace?.enter("prefixCompletion", [rItem(query, "query")]);
+    const done = (hit, note, data) => {
+        t?.done(hit === null ? [] : [rItem(hit.continuation, "continuation", hit.id)], note, data);
+        return hit;
+    };
+    // Reads are bounded to phrase scale, the same bound the frame filler uses.
+    // A query with no room for a whole grouping window past its own length
+    // cannot clear guard 2, so it is not worth a single read.
+    const cap = query.length * W;
+    if (query.length === 0 || cap < query.length + W) {
+        return done(null, "no room for a perceivable continuation within the cap");
+    }
+    // Distinct continuations, each with the first form that offered it.  Held as
+    // a list, not a byte-keyed map: candidates that open with the query are few
+    // (measured: 1 on the trained store's winning query), and a linear byte
+    // compare needs no string encoding of content.  Uniqueness (guard 3) is
+    // decided over this list, so the scan cannot stop early — a second
+    // continuation IS the refusal, and finding it is the point.
+    const found = [];
+    let opened = 0;
+    let unreadable = 0;
+    let subQuantum = 0;
+    for (const id of ranked) {
+        const form = ctx.store.bytesPrefix(id, cap);
+        if (form.length <= query.length)
+            continue;
+        let opens = true;
+        for (let i = 0; i < query.length; i++) {
+            if (form[i] !== query[i]) {
+                opens = false;
+                break;
+            }
+        }
+        if (!opens)
+            continue;
+        opened++;
+        // Guard 1: a saturated read continues out of sight — a disagreement that
+        // cannot be resolved, so it ends the search rather than being skipped.
+        if (form.length >= cap) {
+            unreadable++;
+            continue;
+        }
+        const rest = form.subarray(query.length);
+        // Guard 2: below one grouping window there is no structure to voice.
+        if (rest.length < W) {
+            subQuantum++;
+            continue;
+        }
+        if (!found.some((f) => bytesEqual(f.continuation, rest))) {
+            found.push({ id, form, continuation: rest });
+        }
+    }
+    const data = {
+        candidates: ranked.length,
+        opened,
+        unreadable,
+        subQuantum,
+        distinctContinuations: found.length,
+    };
+    if (unreadable > 0 && found.length > 0) {
+        return done(null, "a form opens with this query but continues past the read bound — " +
+            "its continuation cannot be read, so none is licensed", data);
+    }
+    // Guard 2b: A SUB-QUANTUM CONTINUATION IS STILL A DISAGREEMENT.  Guard 2
+    // refuses to VOICE a below-window continuation, and rightly — there is no
+    // structure there to speak.  But dropping such a candidate from the
+    // uniqueness tally silently converts "the corpus offers many continuations,
+    // most of them unvoiceable" into "the corpus offers exactly one", and
+    // guard 3 then passes VACUOUSLY on the sole survivor.  That is precisely
+    // the failure guard 1 documents for unreadable continuations — suppressing
+    // the disagreement is what manufactures the answer — so it is answered the
+    // same way, and for the same reason.
+    //
+    // Measured on a 4,300-fact fixture of "what is the value of <i>?": the
+    // query "what is the value of" drew candidates continuing " 0?", " 4?",
+    // " 8?" (3 bytes, sub-quantum at W=4) and " 10?" (4 bytes).  The first
+    // three were dropped, leaving one survivor, and the mechanism reported
+    // "exactly one trained form" and voiced "the value of 10 is 20" — an
+    // arbitrary pick from thousands of equally-good readings, with the
+    // evidence of ambiguity discarded on the way.
+    //
+    // Note this can only ever cause SILENCE, never a different answer: it
+    // withholds a completion the corpus does not uniquely license.
+    if (subQuantum > 0 && found.length > 0) {
+        return done(null, "other trained forms open with this query but continue below one " +
+            "grouping window — the corpus offers competing readings, so no " +
+            "single completion is licensed", data);
+    }
+    // Guard 3: the corpus must agree on ONE continuation.
+    if (found.length !== 1) {
+        return done(null, found.length === 0
+            ? "no trained form opens with this query and continues perceivably"
+            : "trained forms open with this query but continue differently — " +
+                "the corpus does not say which continuation is meant", data);
+    }
+    return done(found[0], "one trained form opens with this query, and continues perceivably", data);
+}