@hviana/sema 0.5.2 → 0.5.3

package/src/mind/match.ts

@@ -18,19 +18,29 @@
 //                       direct or mutual-sibling)
 //   multi-hop pivot     byte containment               forward       —
 //   articulation        halo sibling                   substitute    conceptThreshold
+//   reference           frameSlots() (the shared       carry into    carriesFillers
+//                       aligner, gaps contracted)      the answer
 //
 // This module holds the shared vocabulary those configurations are built
-// from — the MATCHERS (locate, alignRuns, alignGraded, analogyStrength) and
-// the PROJECTIONS (follow, conceptHop, reverseContext, project) — so each
-// mechanism file states only its configuration, never its own copy of the
-// machinery.  The gates all live in geometry.ts (derived, never tuned).
+// from — the MATCHERS (locate, alignRuns, alignGraded, alignAround/frameSlots,
+// analogyStrength) and the PROJECTIONS (follow, conceptHop, reverseContext,
+// project) — so each mechanism file states only its configuration, never its
+// own copy of the machinery.  Most gates live in geometry.ts (derived, never
+// tuned); the two STRUCTURAL gates that are byte predicates rather than
+// thresholds — isSpanShaped and carriesFillers — live here beside the matchers
+// they gate.
 
 import { addInto, cosine, dot, normalize, Vec, zeros } from "../vec.js";
 import type { Hit } from "../store.js";
-import { conceptThreshold, identityBar, significanceBar } from "../geometry.js";
-import { indexOf } from "../bytes.js";
+import {
+  conceptThreshold,
+  dominates,
+  identityBar,
+  significanceBar,
+} from "../geometry.js";
+import { bytesEqual, indexOf } from "../bytes.js";
 import type { MindContext } from "./types.js";
-import { leafIdRun } from "./canonical.js";
+import { chainReach, leafIdRun } from "./canonical.js";
 import { foldTree, gistOf, perceive, read, resolve } from "./primitives.js";
 import {
   argmaxCosine,
@@ -294,6 +304,405 @@ export function alignGraded(
   return out;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// THE FRAME READING — variable positions, and the licence to voice through one
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// Sema is otherwise a fully GROUND system: every item of the deduction system,
+// every matcher and every gate compares ground bytes.  Nothing anywhere
+// represents a POSITION whose occupant comes from the context rather than the
+// corpus, and so no mechanism can tell
+//
+//     "the corpus does not explain these bytes"   (PASS — refuse)
+//
+// apart from
+//
+//     "these bytes occupy a place the corpus keeps open"   (bind).
+//
+// Both arrive as unaligned residue.  That single missing distinction is why
+// the substitution bridge refuses on `attestedQ`, why the cover charges PASS
+// over a slot, and why CAST reads a filler as noise rather than as the
+// variable it is.  The family below supplies it, and it lives HERE — not in
+// any mechanism — because it is the ordinary (matcher, projection, gate)
+// triple of §2.5 with its three parts in their proper places:
+//
+//   matcher     alignAround + contractGap + frameSlots — bytes only, no
+//               projection, no licence.  SAFE FOR EVERY CONSUMER: knowing a
+//               span is variable can only improve an alignment.
+//   projection  follow / project — unchanged, already here.
+//   gate        carriesFillers — the licence to VOICE through a slot.  Needed
+//               only by a mechanism that voices, so it is deliberately NOT
+//               folded into the matcher.
+//
+// The split matters.  Slot detection is universal; the licence is not, and a
+// consumer that took the matcher's answer as permission to voice would be
+// making exactly the claim the licence exists to withhold.
+
+/** One place two byte streams DISAGREE, between runs where they agree: the
+ *  query span `[qs,qe)` standing where the candidate's `[cs,ce)` stands.
+ *
+ *  Two mechanisms read the same gap and ask OPPOSITE questions of it, which is
+ *  why the shape lives here rather than in either of them:
+ *
+ *    • the substitution bridge asks whether the two sides MEAN THE SAME, and
+ *      so EXPANDS the gap (absorbing flanking matched bytes) until the query
+ *      side is corpus-attested and the pair clears the concept bar;
+ *    • the frame reading asks WHERE THE SLOT IS, and so CONTRACTS it
+ *      ({@link contractGap}) until the two sides share nothing at all.
+ *
+ *  Neither reading is derivable from the other, and both need the same gap. */
+export interface AlignGap {
+  qs: number;
+  qe: number;
+  cs: number;
+  ce: number;
+}
+
+/** Extend a seed match (query offset qo ↔ candidate offset co) to its maximal
+ *  common run, then walk outward in both directions collecting further common
+ *  runs of at least W bytes across bounded mismatch gaps (each side ≤
+ *  chainReach).  Returns the matched query spans and the mismatch pairs
+ *  between consecutive runs.
+ *
+ *  This is the SEEDED aligner, distinct from {@link alignRuns}: that one finds
+ *  every run two structures share anywhere (a weave), this one reads two
+ *  streams as ONE structure that diverges in bounded places (a frame with
+ *  slots).
+ *
+ *  Gaps come back in SWEEP order (right sweep, then left), not query order,
+ *  and only the INTERIOR ones are reported — a consumer that needs the query's
+ *  unmatched head or tail derives it from `matched`.  Both are the bridge's
+ *  contract, which prices its edges separately (see its matchStart/matchEnd
+ *  window test); {@link frameSlots} takes the other reading. */
+export function alignAround(
+  ctx: MindContext,
+  q: Uint8Array,
+  c: Uint8Array,
+  qo: number,
+  co: number,
+): { matched: Array<[number, number]>; gaps: AlignGap[] } {
+  const W = ctx.space.maxGroup;
+  const reachCap = chainReach(W);
+  // Maximal run around the seed.
+  let qs = qo, ss = co;
+  while (qs > 0 && ss > 0 && q[qs - 1] === c[ss - 1]) {
+    qs--;
+    ss--;
+  }
+  let qe = qo, se = co;
+  while (qe < q.length && se < c.length && q[qe] === c[se]) {
+    qe++;
+    se++;
+  }
+  const matched: Array<[number, number]> = [[qs, qe]];
+  const gaps: AlignGap[] = [];
+  // The next common run of ≥ W bytes past (qi, si), with each side's gap
+  // bounded by chainReach; smallest total gap wins (nearest continuation).
+  const runLenAt = (qi: number, si: number): number => {
+    let n = 0;
+    while (qi + n < q.length && si + n < c.length && q[qi + n] === c[si + n]) {
+      n++;
+    }
+    return n;
+  };
+  // RIGHT sweep.
+  let qi = qe, si = se;
+  for (;;) {
+    let found = false;
+    for (let total = 1; total <= 2 * reachCap && !found; total++) {
+      for (let gq = 0; gq <= Math.min(total, reachCap); gq++) {
+        const gs = total - gq;
+        if (gs > reachCap) continue;
+        if (qi + gq >= q.length || si + gs >= c.length) continue;
+        const n = runLenAt(qi + gq, si + gs);
+        if (n >= W || qi + gq + n === q.length) {
+          if (n === 0) continue;
+          if (gq > 0 || gs > 0) {
+            gaps.push({ qs: qi, qe: qi + gq, cs: si, ce: si + gs });
+          }
+          matched.push([qi + gq, qi + gq + n]);
+          qi = qi + gq + n;
+          si = si + gs + n;
+          found = true;
+          break;
+        }
+      }
+    }
+    if (!found) break;
+  }
+  // LEFT sweep (mirror).
+  qi = qs;
+  si = ss;
+  for (;;) {
+    let found = false;
+    for (let total = 1; total <= 2 * reachCap && !found; total++) {
+      for (let gq = 0; gq <= Math.min(total, reachCap); gq++) {
+        const gs = total - gq;
+        if (gs > reachCap) continue;
+        if (qi - gq <= 0 || si - gs <= 0) continue;
+        // Run ENDING at (qi - gq, si - gs).
+        let n = 0;
+        while (
+          n < qi - gq && n < si - gs &&
+          q[qi - gq - 1 - n] === c[si - gs - 1 - n]
+        ) {
+          n++;
+        }
+        if (n >= W || n === qi - gq) {
+          if (n === 0) continue;
+          if (gq > 0 || gs > 0) {
+            gaps.push({ qs: qi - gq, qe: qi, cs: si - gs, ce: si });
+          }
+          matched.push([qi - gq - n, qi - gq]);
+          qi = qi - gq - n;
+          si = si - gs - n;
+          found = true;
+          break;
+        }
+      }
+    }
+    if (!found) break;
+  }
+  return { matched, gaps };
+}
+
+/** Contract a gap to its VARYING CORE: strip the prefix and suffix the two
+ *  sides share.  {@link alignAround} cannot match a shared affix shorter than
+ *  W, so that affix lands INSIDE the gap — measured, the slot of
+ *  `How do I compile main.c?` against `…hello.c?` comes back as
+ *  `main.c?`/`hello.c?`, three bytes of which (`.c?`) both sides hold.
+ *
+ *  Splicing the uncontracted gap carries the query's own punctuation into the
+ *  answer; worse, it hides what actually VARIES, which is the only thing a
+ *  cohort can agree about.  Returns null when nothing is left on either side —
+ *  a pure insertion or deletion, which names no slot. */
+export function contractGap(
+  q: Uint8Array,
+  c: Uint8Array,
+  g: AlignGap,
+): AlignGap | null {
+  let { qs, qe, cs, ce } = g;
+  while (qs < qe && cs < ce && q[qs] === c[cs]) {
+    qs++;
+    cs++;
+  }
+  while (qe > qs && ce > cs && q[qe - 1] === c[ce - 1]) {
+    qe--;
+    ce--;
+  }
+  return qe > qs && ce > cs ? { qs, qe, cs, ce } : null;
+}
+
+/** What one place two streams disagree IS, once contracted to its varying
+ *  core.  A consumer decides which kinds it can use; the matcher only reports.
+ *
+ *    substitution  both sides carry bytes — one thing stands where another does
+ *    insertion     the query carries bytes the candidate does not
+ *    deletion      the candidate carries bytes the query does not */
+export type SlotKind = "substitution" | "insertion" | "deletion";
+
+/** One VARIABLE POSITION of a pairing: where the query and a candidate differ,
+ *  contracted to the bytes that actually vary. */
+export interface FrameSlot {
+  /** Query span (empty for a deletion). */
+  qs: number;
+  qe: number;
+  /** Candidate span (empty for an insertion). */
+  cs: number;
+  ce: number;
+  kind: SlotKind;
+  /** The candidate's own bytes here — empty for an insertion. */
+  filler: Uint8Array;
+}
+
+/** One trained context read against the query as ONE structure with variable
+ *  positions.
+ *
+ *  EVERYTHING THE ALIGNER SAW, NOTHING JUDGED.  `slots` holds every place the
+ *  pairing varies, in query order, whatever its kind or size, and `covered`
+ *  says how much of the query the two hold in common.  No gate is applied
+ *  here — see {@link frameSlots}. */
+export interface FrameInstance {
+  /** The trained context this reading is against. */
+  id: number;
+  /** Every variable position, in query order. */
+  slots: FrameSlot[];
+  /** Query spans the pairing literally matched — the frame itself. */
+  matched: Array<[number, number]>;
+  /** Query bytes the frame accounts for: the size of what is shared. */
+  covered: number;
+}
+
+/** THE SLOT MATCHER: read one query ↔ context pairing as one structure with
+ *  variable positions.
+ *
+ *  IT REPORTS; IT DOES NOT JUDGE.  This returns every gap the aligner found,
+ *  contracted to its varying core and tagged with its kind, plus the shared
+ *  coverage — and rejects nothing.  That is the whole point of the split, and
+ *  it was got WRONG first: four VOICING gates (the frame must dominate the
+ *  query, each slot must reach one window on both sides, an insertion or
+ *  deletion disqualifies the pairing, fillers must be pairwise distinct) were
+ *  applied here, and every one of them is a requirement for SUBSTITUTING AND
+ *  SPEAKING, not for knowing where a pairing varies.  With them in place the
+ *  shared reading was reference-shaped: measured over four real pairings, three
+ *  were hidden from every consumer —
+ *
+ *    `What is the capital of the country where the Eiffel Tower is?`
+ *        against `What is the capital of France?`  (covered 23/61)  HIDDEN
+ *    `What is the capital of France, really?`      (an insertion)   HIDDEN
+ *    `What is the capital of Fran?`                (sub-window)     HIDDEN
+ *
+ *  — including the case of the one consumer that most obviously needed it.  A
+ *  shared layer with one usable consumer is private code at a public address.
+ *  Each gate now lives with the mechanism that needs it (see reference.ts).
+ *
+ *  Seeded at the origin, because a frame is shared structure the query and its
+ *  instances both OPEN with: the maximal run around (0,0) is the frame's head
+ *  and the sweeps find the rest.
+ *
+ *  Null only for a degenerate pairing (either side empty). */
+export function frameSlots(
+  ctx: MindContext,
+  query: Uint8Array,
+  cand: Uint8Array,
+  id: number,
+): FrameInstance | null {
+  if (query.length === 0 || cand.length === 0) return null;
+  const { matched, gaps } = alignAround(ctx, query, cand, 0, 0);
+  const spans = [...matched].sort((a, b) => a[0] - b[0]);
+  // Where the alignment RAN OUT on each side.  Seeded at the origin there is
+  // no leading gap, so both cursors are everything consumed so far: the
+  // matched runs (equal length on both sides by construction) plus what each
+  // interior gap ate of its own side.  Counting only the runs reads the
+  // candidate cursor short by exactly the fillers already seen, and invents a
+  // trailing gap on every well-aligned instance.
+  const all: AlignGap[] = [...gaps];
+  let qEnd = 0, cEnd = 0;
+  for (const [s, e] of spans) {
+    cEnd += e - s;
+    qEnd = Math.max(qEnd, e);
+  }
+  for (const g of gaps) cEnd += g.ce - g.cs;
+  if (qEnd < query.length || cEnd < cand.length) {
+    all.push({ qs: qEnd, qe: query.length, cs: cEnd, ce: cand.length });
+  }
+  const slots: FrameSlot[] = [];
+  for (const gap of all.sort((a, b) => a.qs - b.qs)) {
+    if (gap.qe <= gap.qs && gap.ce <= gap.cs) continue;
+    // Contract to the varying core.  contractGap returns null when one side is
+    // wholly shared with the other — a pure insertion or deletion, which is a
+    // real variation and is reported AS ONE, not discarded.
+    const core = contractGap(query, cand, gap);
+    const g = core ?? gap;
+    const kind: SlotKind = g.qe > g.qs && g.ce > g.cs
+      ? "substitution"
+      : g.qe > g.qs
+      ? "insertion"
+      : "deletion";
+    slots.push({
+      qs: g.qs,
+      qe: g.qe,
+      cs: g.cs,
+      ce: g.ce,
+      kind,
+      filler: cand.slice(g.cs, g.ce),
+    });
+  }
+  const covered = spans.reduce((n, [s, e]) => n + e - s, 0);
+  return { id, slots, matched: spans, covered };
+}
+
+/** Whether every member is byte-distinct from the others. */
+export function distinct(items: readonly Uint8Array[]): boolean {
+  for (let i = 0; i < items.length; i++) {
+    for (let j = i + 1; j < items.length; j++) {
+      if (bytesEqual(items[i], items[j])) return false;
+    }
+  }
+  return true;
+}
+
+/** Substitute every `needle -> repl` pair SIMULTANEOUSLY: one left-to-right
+ *  pass, longest needle first at each position, and a replacement is never
+ *  re-examined.
+ *
+ *  SIMULTANEOUS IS NOT A DETAIL.  Applying the pairs in sequence lets one
+ *  substitution's OUTPUT be another's input: with slots `gcc -> zig` and
+ *  `hello.c -> zig.c` a sequential pass rewrites bytes it had just written,
+ *  and the result depends on the order the slots happened to be found in.
+ *  Longest-first at each position makes the pass independent of pair order,
+ *  which is what keeps {@link carriesFillers} and the binding it licenses the
+ *  SAME operation — if they could disagree, the licence would not be testing
+ *  what is voiced. */
+export function substituteAll(
+  hay: Uint8Array,
+  pairs: ReadonlyArray<{ needle: Uint8Array; repl: Uint8Array }>,
+): Uint8Array {
+  const usable = pairs.filter((p) => p.needle.length > 0);
+  if (usable.length === 0) return hay;
+  // Longest needle first, so a needle that is a prefix of another can never
+  // pre-empt it.  Ties cannot arise: an instance whose fillers are not
+  // pairwise distinct is refused by frameSlots.
+  const order = [...usable].sort((a, b) => b.needle.length - a.needle.length);
+  const out: number[] = [];
+  let i = 0;
+  let hit = false;
+  outer:
+  while (i < hay.length) {
+    for (const p of order) {
+      if (i + p.needle.length > hay.length) continue;
+      let k = 0;
+      while (k < p.needle.length && hay[i + k] === p.needle[k]) k++;
+      if (k < p.needle.length) continue;
+      for (const b of p.repl) out.push(b);
+      i += p.needle.length;
+      hit = true;
+      continue outer;
+    }
+    out.push(hay[i]);
+    i++;
+  }
+  return hit ? Uint8Array.from(out) : hay;
+}
+
+/** THE CARRIAGE LICENCE — the gate that decides whether a slot may be VOICED
+ *  through.  Given two instances of one frame and what each one continues to,
+ *  it asks one byte question:
+ *
+ *      substituteAll(contA, fillersA -> fillersB) == contB
+ *
+ *  When it holds, the corpus attests byte-exactly that the continuation is a
+ *  function of the fillers and nothing else, so putting a NEW occupant through
+ *  the same carriage is derivation rather than invention.  No threshold, no
+ *  similarity, no new constant: the store's own instances decide, exactly as
+ *  the bridge's `unanimous` decides whether a frame is a value slot.
+ *
+ *  Its FAILURE is what this is really for.  A frame whose continuation carries
+ *  filler-DEPENDENT content — `What is the capital of X?` answering a different
+ *  city per X — fails it, and that failure is the only thing between a slot
+ *  and an invented fact.  Measured on the trained 15.7M-node store (325,615
+ *  contexts): `What is the capital of Zamunda?` resonates to a PURE cohort,
+ *  every one of the top 14 hits an instance of that frame, with an unambiguous
+ *  slot; every structural gate passes and only this one refuses, on
+ *  `replace("Tokyo", "Japan" -> "France") != "Paris"`.
+ *
+ *  With SEVERAL slots the test is unchanged, which is the point of testing the
+ *  whole substitution at once: a frame whose answer tracks one slot but
+ *  invents around another fails exactly as a single-slot value slot does. */
+export function carriesFillers(
+  contA: Uint8Array,
+  fillersA: readonly Uint8Array[],
+  contB: Uint8Array,
+  fillersB: readonly Uint8Array[],
+): boolean {
+  if (fillersA.length !== fillersB.length) return false;
+  const projected = substituteAll(
+    contA,
+    fillersA.map((needle, s) => ({ needle, repl: fillersB[s] })),
+  );
+  return bytesEqual(projected, contB);
+}
+
 /** The IN-LIST halo matcher: the best halo-mate for `halo` among EXPLICIT
  *  candidates, above the concept threshold — the list counterpart of
  *  {@link haloSiblings}, which asks the halo INDEX for candidates instead.

package/src/mind/{prefix-completion.ts → mechanisms/prefix-completion.ts}

@@ -1,5 +1,20 @@
-// prefix-completion.ts — Grounding a query that IS the opening of a trained
-// form.
+// mechanisms/prefix-completion.ts — Grounding a query that IS the opening of a
+// trained form (Grounding V).
+//
+// A MECHANISM, NOT A TIER.  This used to run inside recall's refusal path, in
+// a fixed if-chain that first-match-wins — the shape CAST was refactored away
+// from, where placement rather than the cost ladder decided.  Its claim is
+// maximal (every query byte literally matched, from offset zero, against a
+// trained form) at one STEP, so as a market candidate it competes honestly and
+// the decider weighs it like everything else.  It is registered LAST: recall's
+// exact self-match makes an IDENTITY claim about the query while this makes a
+// CONTAINMENT one, and on an exact grade tie the identity claim is the
+// stronger evidence — the same ordering §2.3's ladders use.
+//
+// Its SUPPLY moved too, and further: `formsOpenedBy` (traverse.ts) answers a
+// question about the STORE — "which trained forms does this byte run open?" —
+// so it is retrieval machinery any mechanism may ask, not this one's private
+// helper.
 //
 // THE SHAPE.  `The capital of France is` grounds nothing, while
 // `The capital of France is Paris.` is trained and reads back byte-exact.  The
@@ -75,96 +90,12 @@
 // 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];
-}
+import type { MindContext } from "../types.js";
+import { bytesEqual } from "../../bytes.js";
+import { rItem } from "../trace.js";
+import { formsOpenedBy } from "../traverse.js";
+import { STEP } from "../graph-search.js";
+import type { PipelineMechanism, Precomputed } from "../pipeline-mechanism.js";
 
 /** A trained form the query opens, and the bytes by which it continues. */
 export interface PrefixCompletion {
@@ -312,3 +243,46 @@ export function prefixCompletion(
     data,
   );
 }
+
+// ── Pipeline mechanism ──────────────────────────────────────────────────────
+
+export const prefixMechanism: PipelineMechanism = {
+  name: "prefix",
+  provenance: "prefix",
+  async floor(ctx, query, _pre, worthRunning) {
+    // One projection: the form is voiced whole, nothing is substituted.
+    // INVESTMENT DISCIPLINE — the supplies below are the response's wide
+    // candidate list and a bounded √N walk, so neither is touched until the
+    // bound can still beat the incumbent.
+    if (!worthRunning(STEP)) return STEP;
+    // A query with no room for a perceivable continuation inside the phrase
+    // cap cannot clear guard 2, so it is not worth a single read.
+    const cap = query.length * ctx.space.maxGroup;
+    if (query.length === 0 || cap < query.length + ctx.space.maxGroup) {
+      return null;
+    }
+    return STEP;
+  },
+  async run(ctx, query, pre) {
+    // The response's shared wide list first; only when it supplies nothing does
+    // the write side's window index propose.  That ordering is the whole cost
+    // story: a query the ranked list can already explain pays not one extra
+    // read, and the bounded walk is spent only where the alternative is an
+    // empty answer.  A second SUPPLY, not a second mechanism — the same three
+    // guards decide either way.
+    const completed = prefixCompletion(ctx, query, await pre.wideResonance()) ??
+      prefixCompletion(ctx, query, formsOpenedBy(ctx, query));
+    if (completed === null) return [];
+    return [{
+      bytes: completed.form,
+      // Every query byte is literally matched against the form, so there is
+      // nothing to be humble about in the accounting — the same reading the
+      // IDENTITY bridge takes.
+      accounted: [[0, query.length]],
+      moves: STEP,
+      unexplained: "",
+      // NOT complete: the query is a proper PREFIX, so the form may carry more
+      // past the remainder this voiced.
+    }];
+  },
+};