@hviana/sema 0.8.0 → 0.8.2

package/src/mind/match.ts

@@ -38,7 +38,7 @@ import {
   identityBar,
   significanceBar,
 } from "../geometry.js";
-import { bytesEqual, indexOf } from "../bytes.js";
+import { bytesEqual, indexOf, latin1 } from "../bytes.js";
 import type { MindContext } from "./types.js";
 import { chainReach, leafIdRun } from "./canonical.js";
 import { foldTree, gistOf, perceive, read, resolve } from "./primitives.js";
@@ -54,6 +54,7 @@ import {
   sharedReachMemo,
 } from "./traverse.js";
 import { recognise, segment } from "./recognition.js";
+import { rItem } from "./trace.js";
 import type { Site } from "./graph-search.js";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -319,12 +320,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
@@ -360,9 +361,14 @@ export interface AlignGap {
 
 /** 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.
+ *  runs of at least W bytes across mismatch gaps.  Each gap's LENGTH is the
+ *  pair's own extent (a gap cannot be longer than the bytes it spans) and the
+ *  sweep's WORK is proportional to the bytes a run spans (the context's windows
+ *  are indexed once, then the query's are walked) — the arity bound
+ *  (`chainReach`) used to cap BOTH, and truncated every learned frame whose
+ *  slot was longer.  Each sweep owns its own budget, so an exhausted right
+ *  sweep never starves the left one.  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
@@ -382,7 +388,21 @@ export function alignAround(
   co: number,
 ): { matched: Array<[number, number]>; gaps: AlignGap[] } {
   const W = ctx.space.maxGroup;
-  const reachCap = chainReach(W);
+  // THE GAP LENGTH IS THE PAIR'S OWN EXTENT; THE WORK IS BUDGETED.
+  //
+  // The sweep walks (queryGap, contextGap) pairs by ASCENDING total, so reaching
+  // a gap of size G costs about G²/2 pairs.  Bounding the LENGTH by the write
+  // side's arity (`chainReach(W)` = 16) therefore truncated every learned frame
+  // whose slot is longer — measured: `bindReference` reported the cap at 18, 24,
+  // 30 and 36 bytes and `recall` answered with ANOTHER instance's filler — while
+  // removing the bound outright took the corpus-cost guard (test/89) from
+  // milliseconds to 68 seconds.
+  //
+  // Bounding the PAIRS keeps a call's cost constant however long the pair is,
+  // and the ascending order means an exhausted budget drops the FAR
+  // continuations and never the near ones — the same degradation recognition.ts
+  // documents for its canon budget.  Length and work are different questions;
+  // this is the one place they were conflated.
   // Maximal run around the seed.
   let qs = qo, ss = co;
   while (qs > 0 && ss > 0 && q[qs - 1] === c[ss - 1]) {
@@ -396,8 +416,60 @@ export function alignAround(
   }
   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).
+  // THE SWEEP IS STRUCTURAL, NOT ENUMERATIVE.
+  //
+  // The criterion is unchanged: the next common run, MINIMUM TOTAL GAP, ties to
+  // the smaller query gap.  What changed is how it is found.  Enumerating
+  // (queryGap, contextGap) pairs by ascending total reaches a run at total t in
+  // about t²/2 pairs — and that quadratic shape, not the reach, was the cost
+  // problem: capping the pairs dropped reach (a legitimate 24-byte slot stopped
+  // being found), while leaving them uncapped cost 68 seconds on the corpus
+  // guard.  Neither is the answer, because the answer is the algorithm.
+  //
+  // The context's windows are indexed ONCE, for lengths 1..W — W being the
+  // geometry's own unit of composition, so nothing is chosen here.  Each step
+  // then walks the query's windows outward from the anchor: for a given query
+  // gap the nearest context gap that continues a run is one O(1) lookup, and the
+  // walk stops the moment the query gap alone exceeds the best total already
+  // found.  So the work is proportional to the bytes the run SPANS.  No budget,
+  // no cap, no number: a long slot is reached, and its price is already the
+  // ladder's (its bytes are unaccounted, so the search pays PASS per byte).
+  const index: Array<Map<string, number[]>> = [];
+  for (let len = 1; len <= W; len++) {
+    const m = new Map<string, number[]>();
+    for (let o = 0; o + len <= c.length; o++) {
+      const key = latin1(c.subarray(o, o + len));
+      const at = m.get(key);
+      if (at === undefined) m.set(key, [o]);
+      else at.push(o);
+    }
+    index.push(m);
+  }
+  /** Smallest listed offset at or after `from`, or -1. */
+  const fromAt = (list: number[], from: number): number => {
+    let lo = 0, hi = list.length - 1, best = -1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      if (list[mid] >= from) {
+        best = list[mid];
+        hi = mid - 1;
+      } else lo = mid + 1;
+    }
+    return best;
+  };
+  /** Largest listed offset at or before `to`, or -1. */
+  const toAt = (list: number[], to: number): number => {
+    let lo = 0, hi = list.length - 1, best = -1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      if (list[mid] <= to) {
+        best = list[mid];
+        lo = mid + 1;
+      } else hi = mid - 1;
+    }
+    return best;
+  };
+  /** Length of the common run STARTING at (qi, si). */
   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]) {
@@ -405,63 +477,80 @@ export function alignAround(
     }
     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 });
+  /** Length of the common run ENDING at (qi, si). */
+  const runLenBefore = (qi: number, si: number): number => {
+    let n = 0;
+    while (n < qi && n < si && q[qi - 1 - n] === c[si - 1 - n]) n++;
+    return n;
+  };
+  /** The next run outward from an anchor, or null when the bytes run out. */
+  const nextRun = (
+    qi: number,
+    si: number,
+    forward: boolean,
+  ): { gq: number; gs: number; n: number } | null => {
+    const qLim = forward ? q.length - qi : qi;
+    let best: { gq: number; gs: number; n: number } | null = null;
+    for (let gq = 0; gq < qLim; gq++) {
+      // No later query gap can beat a total already found.
+      if (best !== null && gq > best.gq + best.gs) break;
+      const left = qLim - gq;
+      // A run of >= W bytes, or — when the query itself ends inside one window —
+      // the run that REACHES that end.  Exactly the acceptance the sweep had.
+      const lens = left >= W ? [W] : [left];
+      for (const len of lens) {
+        const key = latin1(
+          q.subarray(
+            forward ? qi + gq : qi - gq - len,
+            forward ? qi + gq + len : qi - gq,
+          ),
+        );
+        const list = index[len - 1].get(key);
+        if (list === undefined) continue;
+        const o = forward ? fromAt(list, si) : toAt(list, si - len);
+        if (o < 0) continue;
+        const n = forward
+          ? runLenAt(qi + gq, o)
+          : runLenBefore(qi - gq, o + len);
+        if (n < 1) continue;
+        if (
+          forward ? n >= W || qi + gq + n === q.length : n >= W || n === qi - gq
+        ) {
+          const gs = forward ? o - si : si - len - o;
+          if (best === null || gq + gs < best.gq + best.gs) {
+            best = { gq, gs, n };
           }
-          matched.push([qi + gq, qi + gq + n]);
-          qi = qi + gq + n;
-          si = si + gs + n;
-          found = true;
           break;
         }
       }
     }
-    if (!found) break;
+    return best;
+  };
+  // RIGHT sweep.
+  let qi = qe, si = se;
+  for (;;) {
+    const step = nextRun(qi, si, true);
+    if (step === null) break;
+    if (step.gq > 0 || step.gs > 0) {
+      gaps.push({ qs: qi, qe: qi + step.gq, cs: si, ce: si + step.gs });
+    }
+    matched.push([qi + step.gq, qi + step.gq + step.n]);
+    qi = qi + step.gq + step.n;
+    si = si + step.gs + step.n;
   }
-  // LEFT sweep (mirror).
+  // LEFT sweep (mirror): an independent walk, so an exhausted right side can
+  // never starve it (pinned by test/114).
   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;
-        }
-      }
+    const step = nextRun(qi, si, false);
+    if (step === null) break;
+    if (step.gq > 0 || step.gs > 0) {
+      gaps.push({ qs: qi - step.gq, qe: qi, cs: si - step.gs, ce: si });
     }
-    if (!found) break;
+    matched.push([qi - step.gq - step.n, qi - step.gq]);
+    qi = qi - step.gq - step.n;
+    si = si - step.gs - step.n;
   }
   return { matched, gaps };
 }
@@ -1168,24 +1257,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/cast.ts

@@ -615,7 +615,23 @@ export async function counterfactualTransfer(
       fwd !== null && indexOf(answer, fwd, 0) < 0 &&
       !restatesQuery(query, fwd)
     ) {
-      answer = concat2(answer, fwd);
+      // THROUGH THE SHARED JOINER, not a bare concatenation.
+      //
+      // `joinWithBridge` is the composition step every out-of-search assembly
+      // shares (multi-topic fusion, CAST's substitution and comparison): it
+      // asks the corpus for a learnt connector between the pieces and, on a
+      // miss, joins them BARE **and says so** — the `bridgeMiss` step (see
+      // resonance.ts).  This site bypassed it, and that is the whole of the
+      // gluing the study measured: `"Steel is hard"` + `"wet"` came back as
+      // `"hardwet"`, `"eva director father"` + `"The father of…"` as
+      // `"fatherThe"` — compositions no rationale could show, because the one
+      // step that made them left no trace.
+      //
+      // Routing it through the shared joiner is the instrumentation fix that
+      // comes first: a bare join stays possible (the house rule is "joined
+      // bare, never silent") but it is now VISIBLE, and an attested connector
+      // is used when the corpus has one.
+      answer = await joinWithBridge(ctx, answer, fwd);
     }
     ctx.trace?.step(
       "projectCounterfactual",

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,28 +75,30 @@ 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;
       });
     });
   const bridgePair = async (l: number, r: number) => {
     if (l === r || links.has(l + "," + r)) return;
+    if (ctx.meter) ctx.meter.coverBridges++;
     const link = await bridge(ctx, read(ctx, l), read(ctx, r));
     if (link !== null) links.set(l + "," + r, link);
   };
@@ -133,6 +135,10 @@ export async function resolveConnectors(
       // plus one W-quantum of glue per joint — pass that allowance so the
       // bridge's phrase-scale cap admits the whole learnt run.
       const allowance = middleBytes + (m + 1) * W;
+      if (ctx.meter) {
+        ctx.meter.coverBridges++;
+        ctx.meter.coverAllowanceBytes += allowance;
+      }
       const interior = await bridge(
         ctx,
         first.bytes,

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