@hviana/sema 0.7.9 → 0.8.1

package/src/mind/bridge.ts

@@ -148,23 +148,23 @@ export function dismissedKnownContent(
   return false;
 }
 
-// The seeded aligner this file used to own now lives in the shared match
-// family as {@link alignAround} — the frame reading (match.ts) reads the same
-// gaps and asks the OPPOSITE question of them (see AlignGap's own doc).  Two
-// consumers, one definition (AGENTS §2.5); the bridge's reading is unchanged.
+// The seeded aligner this file used to own now lives in the shared match family
+// as {@link alignAround} — the frame reading (match.ts) reads the same gaps and
+// asks the OPPOSITE question of them (see AlignGap's own doc). Two consumers,
+// one definition (factored-machinery.md); the bridge's reading is unchanged.
 const align = alignAround;
 
 /** Recall's corroborated-substitution bridge — see the module comment.
  *  Returns the best bridged grounding proposal, or null. */
 /** `proposed` is a THUNK, not a list: the bridge's own cheap gates (the
- *  two-quantum query floor and the O(|query|) stored-window anchor scan)
- *  decide whether ANY candidate can be aligned, and they need no proposals
- *  to do it.  Resolving the caller's proposals eagerly meant recall paid its
- *  exhaustive whole-index resonance — the most expensive single act on the
- *  refusal path — for every query, including the ones whose windows the
- *  store has never seen and which the anchor scan rejects outright.  Same
- *  investment discipline the mechanism floors follow (AGENTS §2.6): never
- *  compute a shared analysis just to discard it. */
+ *  two-quantum query floor and the O(|query|) stored-window anchor scan) decide
+ * whether ANY candidate can be aligned, and they need no proposals to do it.
+ * Resolving the caller's proposals eagerly meant recall paid its exhaustive
+ * whole-index resonance — the most expensive single act on the refusal path —
+ * for every query, including the ones whose windows the store has never seen
+ * and which the anchor scan rejects outright. Same investment discipline the
+ * mechanism floors follow (mechanism-market.md): never compute a shared
+ * analysis just to discard it. */
 export async function substitutionBridge(
   ctx: MindContext,
   query: Uint8Array,
@@ -290,12 +290,12 @@ async function bridgeImpl(
     );
     return null;
   }
-  // NO DISCRIMINATING LITERAL EVIDENCE — abstain (§2.13).  A bridge grounds
-  // through the literal spans it did NOT substitute; those anchors are the
-  // whole of its evidence.  When every one of them is SATURATED — containment
-  // clamped at the √N hub bound, i.e. the window is corpus-global scaffolding
-  // — the query's unsubstituted part discriminates nothing, and the single
-  // substituted span is carrying the entire semantic load.  That is not a
+  // NO DISCRIMINATING LITERAL EVIDENCE — abstain (INVARIANTS.md). A bridge
+  // grounds through the literal spans it did NOT substitute; those anchors are
+  // the whole of its evidence. When every one of them is SATURATED —
+  // containment clamped at the √N hub bound, i.e. the window is corpus-global
+  // scaffolding — the query's unsubstituted part discriminates nothing, and the
+  // single substituted span is carrying the entire semantic load. That is not a
   // corroborated bridge; it is a template match, and it FABRICATES.
   //
   // Measured on the trained store (hubBound 571).  "What is the capital of"
@@ -310,7 +310,8 @@ async function bridgeImpl(
   // them silent and cannot be credited for them.
   //
   // This introduces NO new threshold: `bound` is the same √N reading of "hub"
-  // the anchor scan already clamps its own containment read to (§2.2, §2.7).
+  // the anchor scan already clamps its own containment read to (thresholds.md,
+  // commonality.md).
   if (allWindowsAreScaffolding(ctx, query)) {
     ctx.trace?.step(
       "substitutionBridge",
@@ -353,8 +354,8 @@ async function bridgeImpl(
   //
   // The question every gap poses is "may the two forms differ HERE without
   // differing in what they SAY?", and that is the discriminative-vs-
-  // scaffolding question AGENTS §2.7 names, over the CORPUS-GLOBAL
-  // population.  It already has one definition — `dominates(reachOf(...), N)`,
+  // scaffolding question commonality.md names, over the CORPUS-GLOBAL
+  // population. It already has one definition — `dominates(reachOf(...), N)`,
   // the same gate confluence's filler test uses ("scaffolding never binds").
   // Nothing new is derived here; the bar is read, not invented.
   //
@@ -366,17 +367,17 @@ async function bridgeImpl(
   //     climb's own definition of non-discriminative), or it resolves to a
   //     majority of the corpus's contexts.  "the process of ", " is the ".
   //
-  // THE READING MATTERS, not just the population (AGENTS §2.7).  This
-  // deliberately does NOT go through `reachOf`, which maps BOTH "saturated"
-  // and "reaches nothing" to Infinity.  For IDF weighting those are the same
-  // thing (no usable identity evidence); for THIS question they are
-  // opposites — a window reaching nothing is novel content, the most
-  // discriminative material there is, and reading it as Infinity would call
-  // it scaffolding.  Measured: with `reachOf`, "Is water wet?" was answered
-  // with "No, heavy water is not wet." — "heav"/"eavy" occur once, reach no
-  // edge-bearing ancestor, and were written off as filler.  So an
-  // empty-rooted window is NEVER explained, and neither is an untrained one
-  // (the same principle attestedQ applies to the query side).
+  // THE READING MATTERS, not just the population — see commonality.md. This
+  // deliberately does NOT go through `reachOf`, which maps BOTH "saturated" and
+  // "reaches nothing" to Infinity. For IDF weighting those are the same thing
+  // (no usable identity evidence); for THIS question they are opposites — a
+  // window reaching nothing is novel content, the most discriminative material
+  // there is, and reading it as Infinity would call it scaffolding. Measured:
+  // with `reachOf`, "Is water wet?" was answered with "No, heavy water is not
+  // wet." — "heav"/"eavy" occur once, reach no edge-bearing ancestor, and were
+  // written off as filler. So an empty-rooted window is NEVER explained, and
+  // neither is an untrained one (the same principle attestedQ applies to the
+  // query side).
   const reachMemo = sharedReachMemo(ctx);
   const explainedSpan = (
     bytes: Uint8Array,

package/src/mind/graph-search.ts

@@ -23,7 +23,7 @@ import {
   type Rule,
 } from "../derive/src/index.js";
 import type { Store } from "../store.js";
-import { bytesEqual, concat2, concatBytes, latin1 } from "../bytes.js";
+import { bytesEqual, concat2, concatBytes, indexOf, latin1 } from "../bytes.js";
 import type { GraphSearchHost } from "./types.js";
 
 import { ALL } from "./types.js";
@@ -375,9 +375,10 @@ export class GraphSearch {
     private readonly host: GraphSearchHost,
   ) {}
 
-  /** The hub bound √N (AGENTS §2.8) — the ONE fan-out cap, stated here
-   *  rather than imported from `traverse.ts` because this module is
-   *  deliberately host-based (it holds a bare Store, never a MindContext).
+  /* * The hub bound √N (bounded-reads.md) — the ONE
+   *  fan-out cap, stated here rather than imported from `traverse.ts` because
+   *  this module is deliberately host-based (it holds a bare Store, never a
+   *  MindContext).
    *  That is the same write/read-side duplication convention canonical.ts's
    *  header documents: if the formula changes it must change in BOTH places.
    *  It is stated ONCE per side, though — the expression used to be spelled
@@ -1038,12 +1039,12 @@ export class GraphSearch {
     const memo = this.recompleteMemo;
     if (memo.has(node)) return memo.get(node) ?? null;
     // Re-covering is how a PRODUCED node's bytes enter the search at all: the
-    // cover machinery otherwise only ever sees the QUERY's spans.  The recursion
+    // cover machinery otherwise only ever sees the QUERY's spans. The recursion
     // is allowed to nest — a chain IS nested completions — but it is bounded so
-    // the work stays the ANSWER's (AGENTS §2.8): the stack below is the cycle
-    // guard, only ACCEPTED completions recurse, and the nested solve decomposes
-    // the form by its own shape instead of re-recognising the corpus's hub forms
-    // inside it.
+    // the work stays the ANSWER's (bounded-reads.md): the stack below is the
+    // cycle guard, only ACCEPTED completions recurse, and the nested solve
+    // decomposes the form by its own shape instead of re-recognising the
+    // corpus's hub forms inside it.
     //
     // `recompleteOpen` IS the stack of the chain being built, so MEMBERSHIP is
     // the cycle guard: a node already open on this chain cannot re-enter it.
@@ -1165,22 +1166,40 @@ export class GraphSearch {
     // The entity candidates are the forms the fact's own bytes CONTAIN — the
     // same recogniser the query went through, so the evidence standard is the
     // query's.  A byte atom is never a subject; the fact's own node is the span
-    // itself, not an entity inside it.
-    for (const site of this.host.recogniseSpan(fact.bytes).sites) {
-      if (site.payload < 0 || site.payload === fact.node) continue;
-      // The admission predicate has ONE definition — `traverse.ts`'s
-      // `leadsSomewhere` (edge or halo).  The host LENDS it when it can (Mind
-      // does, with the response-scoped struct cache); a bare host falls back to
-      // the raw-store probe, so the search stays host-based.  Same semantics
-      // either way; the hook spares the repeated probe and keeps the predicate
-      // from being redefined here.
-      const leads = this.host.leadsSomewhere !== undefined
-        ? this.host.leadsSomewhere(site.payload)
-        : this.store.hasNext(site.payload) || this.store.hasHalo(site.payload);
-      if (!leads) continue;
-      const key = this.host.resolve(
-        concat2(this.store.bytesPrefix(site.payload, ALL), tail),
+    // itself, not an entity inside it.  The admission predicate has ONE
+    // definition — `traverse.ts`'s `leadsSomewhere` (edge or halo); the host
+    // LENDS it when it can (Mind does, with the response-scoped struct cache),
+    // and a bare host falls back to the raw-store probe, so the search stays
+    // host-based.
+    const leading = this.host.recogniseSpan(fact.bytes).sites.filter((s) =>
+      s.payload >= 0 && s.payload !== fact.node &&
+      (this.host.leadsSomewhere !== undefined
+        ? this.host.leadsSomewhere(s.payload)
+        : this.store.hasNext(s.payload) || this.store.hasHalo(s.payload))
+    );
+    // …then prefer the entity the query did NOT name, and the MAXIMAL one.  The
+    // join exists to reach the subject the query never wrote, so:
+    //   • a candidate the query already contains is the query's OWN subject, and
+    //     following its fact answers about that subject instead of the inferred
+    //     one (measured: "Gustaf Molander spouse date of death" gave Gustaf's
+    //     date of death, not his spouse's);
+    //   • a candidate contained in a longer one is not the entity the fact
+    //     introduces ("Timur" must not win over "Timur Bekmambetov").
+    // Byte work over bytes already read, and the pruning REMOVES the
+    // resolve()/nextFirst() probes these candidates would have paid.
+    const candidates = leading
+      .map((s) => ({
+        payload: s.payload,
+        bytes: this.store.bytesPrefix(s.payload, ALL),
+      }))
+      .filter((c) => indexOf(queryBytes, c.bytes, 0) < 0)
+      .filter((c, _i, all) =>
+        !all.some((o) =>
+          o.bytes.length > c.bytes.length && indexOf(o.bytes, c.bytes, 0) >= 0
+        )
       );
+    for (const c of candidates) {
+      const key = this.host.resolve(concat2(c.bytes, tail));
       if (key === null) continue;
       const nx = this.store.nextFirst(key, 1);
       if (nx.length === 0) continue;

package/src/mind/junction.ts

@@ -208,7 +208,7 @@ function cachedContainers(
  *     is legitimately reached across many containing structures.  Half the
  *     successful junctions would be lost.
  *
- *     REFUTED EARLY-STOP (side-cone exhaustion, §2.17's "real saturation"):
+ * REFUTED EARLY-STOP (side-cone exhaustion, saturation.md's "real saturation"):
  *     stopping the walk the moment ONE side's upward cone is emptied is wrong,
  *     in both a hub-guarded form and a hub-flagged form.  The junction test is
  *     a BYTE containment over the UNION of the two cones, and a junction can be
@@ -265,13 +265,13 @@ export function junctionContainersFrom(
     d: 0,
   }));
   while (stack.length > 0 && out.length < bound) {
-    // BUDGET EXHAUSTION IS AN ABSTENTION, AND IT MUST BE VISIBLE (§2.13).  The
-    // walk stops with work still on the stack, the caller reads "no container"
-    // and falls through to a lower ladder rung — indistinguishable, from the
-    // outside, from a walk that looked everywhere and found nothing.  With a
-    // SHARED budget (cross-region's one k·W allowance per tier) an EARLIER
-    // pair can drain it, so a later pair's exact tier may never run at all;
-    // this counter is the only thing that says so.
+    // BUDGET EXHAUSTION IS AN ABSTENTION, AND IT MUST BE VISIBLE
+    // (INVARIANTS.md). The walk stops with work still on the stack, the caller
+    // reads "no container" and falls through to a lower ladder rung —
+    // indistinguishable, from the outside, from a walk that looked everywhere
+    // and found nothing. With a SHARED budget (cross-region's one k·W allowance
+    // per tier) an EARLIER pair can drain it, so a later pair's exact tier may
+    // never run at all; this counter is the only thing that says so.
     if (b.n-- <= 0) {
       if (ctx.meter) ctx.meter.junctionBudgetExhausted++;
       break;

package/src/mind/learning.ts

@@ -306,7 +306,8 @@ function constituentSketch(ctx: MindContext, id: number, k: number): number[] {
         for (const g of constituentSketch(ctx, kid, k)) pool.push(g);
       }
     }
-    // Bottom-k by identity, then by id so ties are corpus-determined (§2.1).
+    // Bottom-k by identity, then by id so ties are corpus-determined
+    // (determinism.md).
     pool.sort((a, b) => (unitPriority(a) - unitPriority(b)) || (a - b));
     const seen = new Set<number>();
     out = [];
@@ -368,15 +369,15 @@ function constituentSketch(ctx: MindContext, id: number, k: number): number[] {
  *  terms unique to that partner, which dilute but never mislead; the shared
  *  units contribute the signal.
  *
- *  HUBS ARE THE ONE EXCLUSION, read LIMITed as `parentsFirst(n, bound+1)` —
- *  the store's own exact hub-or-not probe (a result longer than the bound
- *  means MORE than the bound), never a fan-in-sized read.  A constituent with
- *  more than √N structural parents is scaffolding by §8.8's bound: " is ",
- *  "the ".  Superposing it would put a term shared by every deposit into every
- *  profile, ALL halos would correlate, and the concept threshold's null model
- *  (unrelated halos at 0 ± 1/√D) that §4.1's hygiene note protects would
- *  collapse.  It is still DESCENDED into — a hub chunk can contain a rare
- *  unit — but contributes nothing itself.
+ *  HUBS ARE THE ONE EXCLUSION, read LIMITed as `parentsFirst(n, bound+1)` — the
+ * store's own exact hub-or-not probe (a result longer than the bound means MORE
+ * than the bound), never a fan-in-sized read. A constituent with more than √N
+ * structural parents is scaffolding by bounded-reads.md's bound: " is ", "the
+ * ". Superposing it would put a term shared by every deposit into every
+ * profile, ALL halos would correlate, and the concept threshold's null model
+ * (unrelated halos at 0 ± 1/√D) that halo-sketch.md's hygiene note protects
+ * would collapse. It is still DESCENDED into — a hub chunk can contain a rare
+ * unit — but contributes nothing itself.
  *
  *  Byte atoms are skipped in BOTH representations (a negative id and a stored
  *  kid-less node): an atom's fan-in is the alphabet's, so it can only ever
@@ -386,32 +387,32 @@ function constituentSketch(ctx: MindContext, id: number, k: number): number[] {
  *  analogy strength 0.3636 -> 0.2004, "no halo-tier company evidence",
  *  test/29 C1).
  *
- *  A FUNCTION OF THE NODE AND THE CORPUS STATE — stated precisely, because
- *  the weaker claim is the true one.  The constituents are read from the
- *  STORE, never from the depositing tree's id map: that map holds only the
- *  nodes THIS deposit newly interned, so a partner met a second time yielded a
- *  profile missing exactly those constituents, the exact-partner case fell
- *  from cosine 1 to 1/√(1+k), and the geometry stopped meaning anything.
- *  Reading the store fixes that.  It does NOT make the profile permanent: the
- *  hub test reads fan-in against √N and both grow with training, so a partner
- *  poured early and again late can profile differently.  That residue is
- *  confined to the hub EXCLUSION — which terms are dropped as scaffolding —
- *  and never to which units are found, because the descent itself is now
- *  order-independent.  The drift is one-directional and benign: a term can
- *  only ever go from contributing to being excluded as scaffolding.  Replay of
- *  a fixed training order is bit-identical, so §2.1 holds.  What must not be
- *  claimed is that a node's profile is fixed for all time; it is fixed given
- *  the corpus that has been seen.
+ *  A FUNCTION OF THE NODE AND THE CORPUS STATE — stated precisely, because the
+ * weaker claim is the true one. The constituents are read from the STORE, never
+ * from the depositing tree's id map: that map holds only the nodes THIS deposit
+ * newly interned, so a partner met a second time yielded a profile missing
+ * exactly those constituents, the exact-partner case fell from cosine 1 to
+ * 1/√(1+k), and the geometry stopped meaning anything. Reading the store fixes
+ * that. It does NOT make the profile permanent: the hub test reads fan-in
+ * against √N and both grow with training, so a partner poured early and again
+ * late can profile differently. That residue is confined to the hub EXCLUSION —
+ * which terms are dropped as scaffolding — and never to which units are found,
+ * because the descent itself is now order-independent. The drift is
+ * one-directional and benign: a term can only ever go from contributing to
+ * being excluded as scaffolding. Replay of a fixed training order is
+ * bit-identical, so determinism.md holds. What must not be claimed is that a
+ * node's profile is fixed for all time; it is fixed given the corpus that has
+ * been seen.
  *
- *  THE NULL MODEL IS OTHERWISE UNTOUCHED (§4.1).  Every term is still a seeded
- *  function of a NODE IDENTITY, never a gist, so no byte-similarity between
- *  partners can leak content similarity into distributional similarity.  The
- *  result is normalized, so ONE episode still pours ONE unit of mass:
- *  {@link Store.haloMass} keeps counting episodes and every mass-based
- *  reading is unchanged.  Two partners sharing j of k discriminating
- *  constituents meet at j/(1+k) — graded evidence, above the 1/√D noise floor
- *  and below conceptThreshold until the overlap is most of the content, which
- *  is the semantics "same company" should have.
+ * THE NULL MODEL IS OTHERWISE UNTOUCHED (halo-sketch.md). Every term is still a
+ * seeded function of a NODE IDENTITY, never a gist, so no byte-similarity
+ * between partners can leak content similarity into distributional similarity.
+ * The result is normalized, so ONE episode still pours ONE unit of mass: {@link
+ * Store.haloMass} keeps counting episodes and every mass-based reading is
+ * unchanged. Two partners sharing j of k discriminating constituents meet at
+ * j/(1+k) — graded evidence, above the 1/√D noise floor and below
+ * conceptThreshold until the overlap is most of the content, which is the
+ * semantics "same company" should have.
  *
  *  Bounded: at most {@link PROFILE_VISITS} constituents are classified, each
  *  by ONE LIMITed structural-parent read, so a pour costs O(1) reads in the

package/src/mind/match.ts

@@ -319,12 +319,12 @@ export function alignGraded(
 //
 //     "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:
+// 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
+// match-project.md with its three parts in their proper places:
 //
 //   matcher     alignAround + contractGap + frameSlots — bytes only, no
 //               projection, no licence.  SAFE FOR EVERY CONSUMER: knowing a
@@ -1168,24 +1168,25 @@ export async function project(
 
 // ── The span-shape family ───────────────────────────────────────────────────
 //
-// "Is this answer drawn from this context?" has TWO formally distinct
-// readings, and the pair plus the anchor classifier built on them are SHARED
-// machinery — extraction proposes span-shaped exemplars with them, the
-// shared `Precomputed.spanShapedOf` container computes them, and fusion
-// (reasoning.ts) gates on the strict one.  They lived inside
-// mechanisms/extraction.ts, so `pipeline-mechanism.ts` and `reasoning.ts`
-// both had to import back OUT of a specific mechanism — an inversion the
-// mechanism market forbids (AGENTS §2.6: the shared contract may not depend
-// on any one mechanism; §2.5: a shared matcher belongs to this family, never
-// to a mechanism's private helpers).  Deleting extraction must not break the
-// shared container, so they live here.
+// "Is this answer drawn from this context?" has TWO formally distinct readings,
+// and the pair plus the anchor classifier built on them are SHARED machinery —
+// extraction proposes span-shaped exemplars with them, the shared
+// `Precomputed.spanShapedOf` container computes them, and fusion (reasoning.ts)
+// gates on the strict one. They lived inside mechanisms/extraction.ts, so
+// `pipeline-mechanism.ts` and `reasoning.ts` both had to import back OUT of a
+// specific mechanism — an inversion the mechanism market forbids: the shared
+// contract may not depend on any one mechanism (mechanism-market.md), and a
+// shared matcher belongs to this family (match-project.md), never to a
+// mechanism's private helpers. Deleting extraction must not break the shared
+// container, so they live here.
 //
 //   • isSpanShaped  — the OPEN reading (sparse in-order embedding).
 //   • containsSpan  — the STRICT reading (contiguous run or resolved node).
 //   • skillExemplar — classify one anchor into (context, answer) using them.
 //
-// The two readings are NOT interchangeable; AGENTS §2.5 pins the distinction
-// and each function's own doc states what breaks if it is substituted.
+// The two readings are NOT interchangeable; match-project.md pins the
+// distinction and each function's own doc states what breaks if it is
+// substituted.
 
 /** Check whether an anchor is a span-shaped skill exemplar: it represents a
  *  fact whose context and answer together form a span-in-context pattern.

package/src/mind/mechanisms/cover.ts

@@ -4,7 +4,7 @@
 // Cover consumes recognition directly (its axioms are the query's own
 // decomposition) plus the computed spans any parse()-bearing mechanism
 // contributed: computed spans MASK colliding recognised sites and enter the
-// search at zero cost ("computation always wins", §16.3) — which is also why
+// search at zero cost ("computation always wins", alu.md) — which is also why
 // cover runs FIRST in defaultMechanisms: a computed-backed cover becomes a
 // near-zero-cost incumbent that prunes the other mechanisms through the
 // ordinary admissible-floor check, with no extension special-case anywhere.
@@ -75,22 +75,23 @@ export async function resolveConnectors(
       if (query === undefined || ctx.answeredSpans.length === 0) return true;
       const continuations = ctx.store.nextFirst(s.payload, hubBound(ctx));
       return !continuations.some((answer) => {
-        // PREFIX-CAPPED (AGENTS §2.8): a candidate longer than the query cannot
-        // occur INSIDE it, so read one byte past the query's length — enough to
-        // detect the overflow — and reject without reconstructing the rest.
-        // The `+ 1` is what makes the test exact rather than a truncation: a
-        // result of exactly `query.length + 1` bytes is known to be too long,
-        // and anything shorter is the candidate's COMPLETE content, so the
-        // substring test below is the same test as before.  (The same overflow
-        // probe bridge.ts:256 already uses.)
+        // PREFIX-CAPPED (bounded-reads.md): a candidate longer than the query
+        // cannot occur INSIDE it, so read one byte past the query's length —
+        // enough to detect the overflow — and reject without reconstructing the
+        // rest. The `+ 1` is what makes the test exact rather than a
+        // truncation: a result of exactly `query.length + 1` bytes is known to
+        // be too long, and anything shorter is the candidate's COMPLETE
+        // content, so the substring test below is the same test as before. (The
+        // same overflow probe bridge.ts:256 already uses.)
         //
         // This loop runs up to hubBound(ctx) = √N reads PER SITE, and only on a
         // multi-turn response — `answeredSpans` is empty for a plain respond(),
-        // so the probe does not execute there.  The cap cannot reduce the read
+        // so the probe does not execute there. The cap cannot reduce the read
         // COUNT — only a semantic change to the "already answered" test could —
         // but it bounds each read by the query instead of by the corpus, which
-        // is what §2.8 asks for and what rescues a SHORT query: at 3 bytes this
-        // reads 4 bytes per candidate instead of the ~231 it averaged before.
+        // is what bounded-reads.md asks for and what rescues a SHORT query: at
+        // 3 bytes this reads 4 bytes per candidate instead of the ~231 it
+        // averaged before.
         const bytes = read(ctx, answer, query.length + 1);
         return bytes.length <= query.length && indexOf(query, bytes, 0) >= 0;
       });

package/src/mind/mechanisms/prefix-completion.ts

@@ -1,15 +1,15 @@
 // 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
+// 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
+// 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.
+// CONTAINMENT one, and on an exact grade tie the identity claim is the stronger
+// evidence — the same ordering exact-vs-approximate.md'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?" —
@@ -49,12 +49,12 @@
 //
 // So this is a RETRIEVABILITY gap, not a semantic one, and the ANN is the wrong
 // instrument for it: a proper prefix's gist cannot rank its own continuation.
-// The repair is CONTENT-ADDRESSED (§2.3) — `formsOpenedBy` (traverse.ts) reads
-// the leaf-id WINDOW index the write side already maintains and answers "which
-// trained forms does this byte run open?" in a bounded √N walk.  That is this
-// mechanism's first supply.  The response's memoised top-k `resonance()` is the
-// second, for prefixes long enough that the gist still ranks the form; it is
-// read, never re-issued.
+// The repair is CONTENT-ADDRESSED (exact-vs-approximate.md) — `formsOpenedBy`
+// (traverse.ts) reads the leaf-id WINDOW index the write side already maintains
+// and answers "which trained forms does this byte run open?" in a bounded √N
+// walk. That is this mechanism's first supply. The response's memoised top-k
+// `resonance()` is the second, for prefixes long enough that the gist still
+// ranks the form; it is read, never re-issued.
 //
 // AN EXHAUSTIVE ANN LIST IS NOT A SUPPLY HERE, AND WAS REMOVED.  This tier once
 // read `Precomputed.wideResonance()` — a full-index `resonate(guide, √N,
@@ -273,20 +273,20 @@ export const prefixMechanism: PipelineMechanism = {
     return STEP;
   },
   async run(ctx, query, pre) {
-    // ONE SUPPLY PASS, not a two-tier `??`.  The window index (exact,
+    // ONE SUPPLY PASS, not a two-tier `??`. The window index (exact,
     // content-addressed) and the response's memoised top-k (approximate) are
-    // concatenated and the three guards decide ONCE over the union.  A
+    // concatenated and the three guards decide ONCE over the union. A
     // first-then-fallback chain would let the APPROXIMATE tier override the
-    // EXACT one (§2.3): when formsOpenedBy finds two continuations, guard 3
-    // returns null and the fallback re-runs the guards on resonance's top-k
-    // alone — which, seeing only one of the two forms, would voice it.  That is
-    // precisely the disagreement-suppression guard 3 exists to prevent, and it
-    // is the exact tier's ambiguity being washed away by the approximate tier.
-    // Evaluating the union means a disagreement the window index saw can never
-    // be hidden by what the ANN happens to rank.  The ANN read is the
-    // response's ONE memoised top-k (§2.11), already paid by recall's refusal
-    // path on the queries where this mechanism fires, so reading it here is not
-    // a second index scan.
+    // EXACT one (exact-vs-approximate.md): when formsOpenedBy finds two
+    // continuations, guard 3 returns null and the fallback re-runs the guards
+    // on resonance's top-k alone — which, seeing only one of the two forms,
+    // would voice it. That is precisely the disagreement-suppression guard 3
+    // exists to prevent, and it is the exact tier's ambiguity being washed away
+    // by the approximate tier. Evaluating the union means a disagreement the
+    // window index saw can never be hidden by what the ANN happens to rank. The
+    // ANN read is the response's ONE memoised top-k (memoization.md), already
+    // paid by recall's refusal path on the queries where this mechanism fires,
+    // so reading it here is not a second index scan.
     const ids = [
       ...formsOpenedBy(ctx, query),
       ...(await pre.resonance()).map((h) => h.id),