@hviana/sema 0.4.7 → 0.5.0

package/src/mind/mind.ts

@@ -14,16 +14,18 @@ import { bindSeat, fold, Sema, Space } from "../sema.js";
 import { Alphabet } from "../alphabet.js";
 import {
   bytesToTree,
+  contentFoldIncremental,
   Grid,
   gridToTree,
   hilbertBytes,
   reachThreshold,
   stackGrids,
 } from "../geometry.js";
+import type { ContentFold } from "../geometry.js";
 import { BoundedMap, type Store } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
 import { type MindConfig, resolveConfig } from "../config.js";
-import { type Canon, canonHash, textCanon } from "../canon.js";
+import { type Canon, canonHash, textCanon, textEdgeTrim } from "../canon.js";
 import {
   type CandidateSpan,
   coverSequence,
@@ -114,6 +116,18 @@ interface ConversationData {
   tree: Sema;
   bytes: Uint8Array;
   boundaries: number[];
+  /** The plain fold's reusable segment state (see {@link ContentFold}).  A
+   *  grown context reuses every content segment it already folded and folds
+   *  only the new turn — O(turn) instead of O(context) — and, because the
+   *  reused segments are the SAME Sema objects, `resolvedSubtrees` (keyed by
+   *  node identity) hits across turns, which is what makes recognition
+   *  O(suffix).  Undefined until the first grow.
+   *
+   *  No turn boundaries are involved: reuse comes from content cuts being
+   *  stable under append, and imposing boundaries would only change the tree
+   *  away from what the deposit path folded.  `boundaries` beside this field
+   *  is API metadata, not an input to the fold. */
+  content?: ContentFold;
   answeredSpans: Array<[number, number]>;
   perceiveMemo: Map<string, Sema>;
   recogniseMemo: Map<string, Recognition>;
@@ -130,6 +144,7 @@ import {
   inputBytes,
   latin1Key,
   perceive as perceiveImpl,
+  perceiveKey,
   read,
   resolve as resolveImpl,
 } from "./primitives.js";
@@ -605,6 +620,20 @@ export class Mind implements MindContext {
     };
   }
 
+  /** 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: Input,
     inspectRationale?: InspectRationale,
@@ -613,8 +642,43 @@ export class Mind implements MindContext {
     // 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);
+    // 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(
-      inputBytes(this, input),
+      trimmed,
       inspectRationale,
       "respond",
       canon,
@@ -651,7 +715,22 @@ export class Mind implements MindContext {
   beginConversation(state?: ConversationState): Conversation {
     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] as [number, number]
@@ -661,16 +740,18 @@ export class Mind implements MindContext {
           ? [[start, cuts[i + 1]] as [number, number]]
           : []
       );
-    const tree = bytesToTree(
+    // 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,
-      undefined,
-      undefined,
-      initBoundaries.length > 0 ? initBoundaries : undefined,
     );
     this._conversations.set(id, {
-      tree,
+      tree: restored.tree,
+      content: restored.fold,
       bytes: initBytes,
       boundaries: initBoundaries,
       answeredSpans: initAnswered,
@@ -707,7 +788,41 @@ export class Mind implements MindContext {
    *  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: Conversation, turn: Input): ConversationState {
     const data = this._conversations.get(conv.id);
     if (!data) throw new Error(`Conversation ${conv.id} not found`);
@@ -730,17 +845,42 @@ export class Mind implements MindContext {
     if (!grow) return data.tree;
     const grown = prevLen > 0 ? concat2(data.bytes, turnBytes) : turnBytes;
     if (prevLen > 0) data.boundaries.push(prevLen);
-    const tree = bytesToTree(
+    // 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,
-      undefined,
-      undefined,
-      data.boundaries.length > 0 ? data.boundaries : undefined,
+      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;
   }
 

package/src/mind/pipeline-mechanism.ts

@@ -587,6 +587,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/src/mind/pipeline.ts

@@ -189,6 +189,10 @@ export async function think(
     accounted: ReadonlyArray<[number, number]>;
     unexplained: string;
     complete?: boolean;
+    /** Bytes of this candidate's ANSWER that came from spans nothing
+     *  recognised — query words carried through verbatim (see
+     *  {@link liftedScaffolding}).  Absent means none/unreported. */
+    scaffolding?: number;
   }
   const grade = (w: number) => Math.floor(w / STEP);
   const unaccounted = (spans: ReadonlyArray<[number, number]>): number =>
@@ -205,7 +209,34 @@ export async function think(
     if (c.bytes.length === 0) return;
     if (ctx.meter) ctx.meter.candidates++;
     candidates.push(c);
-    if (best === null || grade(c.weight) < grade(best.weight)) best = c;
+    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: number) =>
     best === null || grade(floor) < grade(best.weight);
@@ -260,6 +291,7 @@ export async function think(
         accounted: r.accounted,
         unexplained: r.unexplained,
         complete: r.complete,
+        scaffolding: r.scaffolding,
       });
     }
   }

package/src/mind/prefix-completion.ts

@@ -0,0 +1,314 @@
+// 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 type { MindContext } from "./types.js";
+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: MindContext,
+  query: Uint8Array,
+): number[] {
+  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: number | null = 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<number>(frontier);
+  let budget = bound;
+  while (frontier.length > 0 && budget > 0) {
+    const next: number[] = [];
+    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];
+}
+
+/** 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 function prefixCompletion(
+  ctx: MindContext,
+  query: Uint8Array,
+  ranked: ReadonlyArray<number>,
+): PrefixCompletion | null {
+  const W = ctx.space.maxGroup;
+  const t = ctx.trace?.enter("prefixCompletion", [rItem(query, "query")]);
+  const done = (
+    hit: PrefixCompletion | null,
+    note: string,
+    data?: unknown,
+  ): PrefixCompletion | null => {
+    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: PrefixCompletion[] = [];
+  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,
+  );
+}