@hviana/sema 0.8.0 → 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

@@ -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.

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),

package/src/mind/mechanisms/recall.ts

@@ -236,24 +236,22 @@ export async function recallByResonance(
     }
   }
 
-  // The query-relative grounding fraction, shared by tiers 2–4 — gated on
-  // the FRACTION OF THE QUERY the grounding explains, not the raw cosine.
-  // Root gists are unit vectors, but their magnitudes are recoverable from
-  // the byte lengths (‖·‖ = √len under the linear fold):
-  // cos = shared/√(lenQ·lenG), so shared/lenQ = cos·√(lenG/lenQ).
-  // The raw cosine punished honest containment — a query fully inside a
-  // longer grounded answer scored √(lenQ/lenG) and was refused — and let a
-  // long answer sharing only scaffolding pass; the query-relative fraction
-  // measures exactly what the reach bar means: how much of THE QUERY the
-  // store accounts for.
-  // Chance similarity survives the length conversion AMPLIFIED: the same
-  // √(lenG/lenQ) factor that converts an honest shared fraction into a
-  // query-relative one multiplies the estimator/chance floor too, so a long
-  // stored form (√(lenG/lenQ) ≈ 10 at 100×) lifted a noise-level cosine past
-  // the reach bar and grounded pure gibberish (observed).  Only the
-  // ABOVE-CHANCE part of the similarity is evidence of shared content —
-  // subtract the significance bar (3/√D, §8.3) before converting.  Derived
-  // from the existing bars; never tuned.
+  // The query-relative grounding fraction, shared by tiers 2–4 — gated on the
+  // FRACTION OF THE QUERY the grounding explains, not the raw cosine. Root
+  // gists are unit vectors, but their magnitudes are recoverable from the byte
+  // lengths (‖·‖ = √len under the linear fold): cos = shared/√(lenQ·lenG), so
+  // shared/lenQ = cos·√(lenG/lenQ). The raw cosine punished honest containment
+  // — a query fully inside a longer grounded answer scored √(lenQ/lenG) and was
+  // refused — and let a long answer sharing only scaffolding pass; the
+  // query-relative fraction measures exactly what the reach bar means: how much
+  // of THE QUERY the store accounts for. Chance similarity survives the length
+  // conversion AMPLIFIED: the same √(lenG/lenQ) factor that converts an honest
+  // shared fraction into a query-relative one multiplies the estimator/chance
+  // floor too, so a long stored form (√(lenG/lenQ) ≈ 10 at 100×) lifted a
+  // noise-level cosine past the reach bar and grounded pure gibberish
+  // (observed). Only the ABOVE-CHANCE part of the similarity is evidence of
+  // shared content — subtract the significance bar (3/√D, thresholds.md) before
+  // converting. Derived from the existing bars; never tuned.
   const sig = significanceBar(ctx.store.D);
   const reach = reachThreshold(ctx.space.maxGroup);
   const fracOfQuery = (cos: number, otherLen: number): number =>
@@ -411,14 +409,14 @@ export async function recallByResonance(
       }
     }
   }
-  // 3b. Corroborated-substitution bridge — refusal-path only (bridge.ts).
-  // The bridge's proposal source is the response's ONE top-k read — the same
-  // list recall already ranked above — never an exhaustive √N scan.  The
-  // bridge's own candidate cap is 2·recallQueryK, so top-k proposals are
-  // exactly the budget it can consume, and every proposal is byte-verified
-  // downstream (§2.3).  Reuse the memoised `resonance()`; scanning every IVF
-  // cluster here once made every honest refusal cost hundreds of ms regardless
-  // of k.
+  // 3b. Corroborated-substitution bridge — refusal-path only (bridge.ts). The
+  // bridge's proposal source is the response's ONE top-k read — the same list
+  // recall already ranked above — never an exhaustive √N scan. The bridge's own
+  // candidate cap is 2·recallQueryK, so top-k proposals are exactly the budget
+  // it can consume, and every proposal is byte-verified downstream
+  // (exact-vs-approximate.md). Reuse the memoised `resonance()`; scanning every
+  // IVF cluster here once made every honest refusal cost hundreds of ms
+  // regardless of k.
   const wideIds = async () => (await pre.resonance()).map((h) => h.id);
 
   // Every gist-based tier has failed; before refusing, align the query
@@ -471,12 +469,12 @@ export async function recallByResonance(
       // prefixCompletion runs a few lines below and carries the three guards
       // this tier lacks — unreadable-continuation veto, sub-quantum
       // continuation, and UNIQUENESS (distinct continuations ⇒ refuse), which
-      // is exactly what 4,300 competing values must trip.  So this is not a
-      // new rule and not a new threshold: it is deferring a prefix decision to
-      // the tier that owns it (§2.5, one factored machinery).  Byte-strict on
-      // purpose — a candidate differing by case or punctuation ("what is the
-      // capital of france" → "What is the capital of France?") is NOT a byte
-      // prefix, keeps grounding here, and is unaffected.
+      // is exactly what 4,300 competing values must trip. So this is not a new
+      // rule and not a new threshold: it is deferring a prefix decision to the
+      // tier that owns it (match-project.md, one factored machinery).
+      // Byte-strict on purpose — a candidate differing by case or punctuation
+      // ("what is the capital of france" → "What is the capital of France?") is
+      // NOT a byte prefix, keeps grounding here, and is unaffected.
       const strictPrefix = g !== null &&
         cBytes.length > query.length &&
         indexOf(cBytes, query, 0) === 0;
@@ -542,15 +540,15 @@ export async function recallByResonance(
     }
   }
 
-  // The refusal/echo decision.  The echo returns a stored form's bytes AS
-  // the answer — a near-identity claim about the query — and identity-grade
+  // The refusal/echo decision. The echo returns a stored form's bytes AS the
+  // answer — a near-identity claim about the query — and identity-grade
   // decisions are never made on an estimated score ("approximate scores may
-  // rank and propose; they may never decide", §6.2): the RaBitQ estimate
-  // overshooting the reach bar echoed a WRONG-entity neighbour ("capital of
-  // Zamunda?" echoed the Armenia fact, observed).  The bytes are read
-  // anyway to be echoed, so the decision uses their EXACT fold: one river
-  // fold of the top hit, measured in the same query-relative,
-  // chance-corrected units as the tier above.
+  // rank and propose; they may never decide", exact-vs-approximate.md): the
+  // RaBitQ estimate overshooting the reach bar echoed a WRONG-entity neighbour
+  // ("capital of Zamunda?" echoed the Armenia fact, observed). The bytes are
+  // read anyway to be echoed, so the decision uses their EXACT fold: one river
+  // fold of the top hit, measured in the same query-relative, chance-corrected
+  // units as the tier above.
   const topBytes = read(ctx, top.id);
   const exact = topBytes.length > 0
     ? cosine(queryGist, gistOf(ctx, topBytes))