@hviana/sema 0.2.9 → 0.4.0

package/src/mind/match.ts

@@ -31,7 +31,7 @@ import { conceptThreshold, identityBar, significanceBar } from "../geometry.js";
 import { indexOf } from "../bytes.js";
 import type { MindContext } from "./types.js";
 import { leafIdRun } from "./canonical.js";
-import { gistOf, read, resolve } from "./primitives.js";
+import { foldTree, gistOf, perceive, read, resolve } from "./primitives.js";
 import {
   argmaxCosine,
   chooseAmong,
@@ -119,6 +119,25 @@ export function alignRuns(
   query: Uint8Array,
   ct: Uint8Array,
 ): Array<{ qs: number; qe: number; cs: number }> {
+  if (ctx.meter) {
+    ctx.meter.alignments++;
+    // The alignment family's honest unit: the seed index is O(|query|) but
+    // the run extension is O(|query|·|ct|) in the worst case, and a weave
+    // that starts scanning conversation-length contexts shows up HERE long
+    // before it shows up in a call count.
+    ctx.meter.alignCells += query.length * ct.length;
+  }
+  // MEASURED AND REFUTED — seeding at the write side's unit floor W−1 instead
+  // of W.  `canonicalWindows` interns both lengths precisely so a form
+  // straddling a group boundary is reachable from either cut, and the runs
+  // found here are exactly such remnants: test/29 C1's query shares only `ce `
+  // with `Ice is cold` — three bytes, never seeded at W, so that structure
+  // enters the weave carrying nothing but the scaffolding run every exemplar
+  // shares.  But this is a byte MATCHER between two streams, not an index, and
+  // at W−1 the corpus is dense with spurious 3-byte agreements: the extra runs
+  // reshuffle which point claims which span, and test/29 A2 loses its analog.
+  // C1 does not pass either way.  The store's unit floor does not transfer to
+  // the aligner's seed length.
   const quantum = Math.min(ctx.space.maxGroup, ct.length);
   if (quantum < 1 || query.length < quantum) return [];
   const gram = (b: Uint8Array, at: number): string => {
@@ -167,6 +186,13 @@ export function alignRuns(
  *  kind, so the substitution/redirection schemas work unchanged on conceptual
  *  alignment. */
 export interface GradedRun {
+  /** True for a run the CLIMB proposed rather than the byte matcher found — see
+   *  {@link computeWeave}'s phase 2.  Provenance only: a proposed run reaches
+   *  CAST already gated (dominant literal agreement, not frame, and over bytes
+   *  no literal run claimed), so every consumer reads it exactly like any other
+   *  run.  Filtering seat-shaped reads by this flag was tried and is NOT
+   *  needed — the gates, not the flag, are what make it safe. */
+  proposed?: boolean;
   qs: number;
   qe: number;
   cs: number;
@@ -542,3 +568,122 @@ export async function project(
   if (fc) return fc;
   return reverseContext(ctx, id, guide);
 }
+
+// ── 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.
+//
+//   • 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.
+
+/** 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.
+ *  If the anchor has a nextOf continuation, that is the answer and the anchor
+ *  itself is the context.  Otherwise the anchor's prevOf parents provide
+ *  candidate contexts, and the longest one whose span is span-shaped wins. */
+export async function skillExemplar(
+  ctx: MindContext,
+  anchor: number,
+  guide?: Vec | null,
+): Promise<{ contextBytes: Uint8Array; answerBytes: Uint8Array } | null> {
+  if (ctx.store.hasNext(anchor)) {
+    const contextBytes = read(ctx, anchor);
+    const answerBytes = await follow(ctx, anchor, guide);
+    if (
+      answerBytes !== null && isSpanShaped(ctx, contextBytes, answerBytes)
+    ) {
+      return { contextBytes, answerBytes };
+    }
+    return null;
+  }
+  const answerBytes = read(ctx, anchor);
+  // Candidate contexts, capped at the hub bound (a common answer's reverse
+  // fan-in is corpus-sized).
+  const capped = ctx.store.prevFirst(anchor, hubBound(ctx));
+  const spanShaped: Array<{ id: number; bytes: Uint8Array }> = [];
+  for (const p of capped) {
+    const ctxB = read(ctx, p);
+    if (ctxB.length > 0 && isSpanShaped(ctx, ctxB, answerBytes)) {
+      spanShaped.push({ id: p, bytes: ctxB });
+    }
+  }
+  if (spanShaped.length === 0) return null;
+  // Among span-shaped contexts, the longest wins (the smallest spanning frame
+  // heuristic's dual: more frame to locate in the query); the query gist,
+  // when given, breaks LENGTH TIES via chooseAmong — the same reverse-regime
+  // disambiguator every context pick uses, whose gist cache spares the
+  // re-fold this block once paid per tied candidate.  Same strict first-seen
+  // tie-break as the hand loop it replaces.
+  const maxLen = Math.max(...spanShaped.map((s) => s.bytes.length));
+  const longest = spanShaped.filter((s) => s.bytes.length === maxLen);
+  let contextBytes = longest[0].bytes;
+  if (guide && longest.length > 1) {
+    const pick = chooseAmong(ctx, longest.map((s) => s.id), guide).id;
+    contextBytes = longest.find((s) => s.id === pick)!.bytes;
+  }
+  return { contextBytes, answerBytes };
+}
+
+/** Whether the answer is a SPARSE subsequence of the context (bytes in
+ *  order, arbitrary gaps) — the OPEN span-shape reading (see the section
+ *  note above).  This is what lets extraction validate a MULTI-PIECE
+ *  exemplar whose answer is stitched from several context runs — but it is
+ *  deliberately permissive, so it must never be used as evidence that one
+ *  span was "drawn from" another (see {@link containsSpan} for that).
+ *
+ *  There is deliberately NO containsSpan pre-check here: strict containment
+ *  IMPLIES the subsequence embedding (a contiguous run, or a resolved node —
+ *  whose content-addressed identity means its bytes occur contiguously — is
+ *  an in-order embedding with zero gaps), so the scan below decides alone,
+ *  with the same truth value.  The old pre-check re-perceived the context
+ *  (a full river fold) per CANDIDATE in skillExemplar's √N-capped loop —
+ *  pure cost, no discrimination. */
+export function isSpanShaped(
+  _ctx: MindContext,
+  context: Uint8Array,
+  answer: Uint8Array,
+): boolean {
+  let ai = 0;
+  for (let ci = 0; ci < context.length && ai < answer.length; ci++) {
+    if (context[ci] === answer[ai]) ai++;
+  }
+  return ai === answer.length;
+}
+
+/** STRICT containment: the answer's resolved node appears in the context's
+ *  folded tree, or the answer occurs as one CONTIGUOUS byte run of the
+ *  context.  This is real evidence the answer was drawn from the context.
+ *  Fusion gates on this — the sparse-subsequence reading of
+ *  {@link isSpanShaped} is trivially satisfied by short answers over long
+ *  queries ("cold" is a gap-tolerant subsequence of most sentences holding
+ *  c…o…l…d in order), and gating fusion on it silently starved multi-topic
+ *  queries of their further points of attention. */
+export function containsSpan(
+  ctx: MindContext,
+  context: Uint8Array,
+  answer: Uint8Array,
+): boolean {
+  const ansId = resolve(ctx, answer);
+  if (ansId !== null) {
+    let found = false;
+    foldTree(ctx, perceive(ctx, context), 0, (_n, _s, _e, node) => {
+      if (node === ansId) found = true;
+    });
+    if (found) return true;
+  }
+  return indexOf(context, answer, 0) >= 0;
+}

package/src/mind/mechanisms/cast.ts

@@ -351,14 +351,27 @@ export async function counterfactualTransfer(
       ? s.ctx.subarray(0, r.cs + (r.qe - r.qs))
       : query.subarray(r.qs, r.qe);
   };
+  // The subject is the closest structure whose FILLER RUN precedes the seat.
+  // The gate is on `runs[0]` — the run `fillerOf` actually reads — not on the
+  // point's LAST run: requiring the subject's whole alignment to end before
+  // the seat disqualifies any structure the query mentions on BOTH sides of
+  // it, which is the shape CAST exists for.  Measured on
+  // `steel is frigid so steel is ???` against `steel is hard so steel is
+  // strong` (runs "steel is " at 0-9 and "d so steel is " at 14-28) and
+  // `water is frigid so water is freezing` (seat "frigi" at 9-14): the
+  // subject's filler run sits squarely before the seat, but its second run —
+  // the recurrence AFTER it, the very thing that makes the sentence an
+  // analogy — pushed lastRun past the seat and no substitution fired at all.
+  // The ordering key follows the gate to the same run, so "closest preceding"
+  // still means closest by the evidence actually used.
   const beforeOf = (p: Point, r: GradedRun): Point | undefined =>
     argmaxBy(
       points.filter((s) =>
-        s !== p && lastRun(s).qe <= r.qs &&
+        s !== p && s.runs[0].qe <= r.qs &&
         s.runs[0].cs < quantum &&
         usable(s.runs[0].qs, s.runs[0].qe)
       ),
-      (s) => lastRun(s).qs,
+      (s) => s.runs[0].qs,
       -Infinity,
       true,
     )?.item;
@@ -371,6 +384,18 @@ export async function counterfactualTransfer(
       const before = beforeOf(p, r);
       if (before === undefined) return null;
       if (r.cs > fillerOf(before).length + quantum) return null;
+      // SUBSTITUTION MUST ACTUALLY DISPLACE.  The schema's premise is that the
+      // displaced structure's seat is held by something ELSE, which the
+      // subject then replaces.  When the subject's filler already occurs in
+      // that structure, there is nothing to displace — the "transfer" restates
+      // the structure with its own occupant put back, and the answer is a
+      // tautology.  Measured on `Michelangelo is to sculpture as who is to
+      // literature?`: the weave aligned the concept `Michelangelo` and the
+      // exemplar `The David was sculpted by Michelangelo.`, and substitution
+      // produced `Michelangelo sculpted by Michelangelo.` — then outbid every
+      // honest candidate with it (test/29 A2).  Byte containment, the same
+      // primitive the self-evidence and contradiction guards use.
+      if (indexOf(p.ctx, fillerOf(before), 0) >= 0) return null;
       return { p, before, depth: p.ctx.length - r.cs };
     })
     .filter((c): c is NonNullable<typeof c> => c !== null);
@@ -479,13 +504,27 @@ export async function counterfactualTransfer(
      *  schema accounts them. */
     src: Point;
   }
+  // QUERY-SCALE — "this learnt context is the same size as the question", the
+  // bound comparison holds its dominant and its analogs to.  A byte-exact
+  // `<= query.length` made that judgement turn on a difference the
+  // architecture cannot perceive: on `The Weeping Woman was painted by Pablo
+  // Picasso.` (47 bytes) the weave's dominant was `The Night Watch was painted
+  // by Rembrandt van Rijn.` (50) — three bytes over, so comparison refused
+  // outright, while the interchangeable `The Mona Lisa was painted by Leonardo
+  // da Vinci.` (47) would have passed.  WHICH exemplar becomes dominant is
+  // settled by run-claiming order among equals, so a 3-byte difference was
+  // deciding whether the schema fires at all (test/33 1b).  W is the smallest
+  // distinction perception can make — the same quantum countClusters separates
+  // neighbourhoods by — so a context within one quantum of the query's length
+  // carries no independently perceivable unit beyond it and is the same scale.
+  const queryScale = (n: number): boolean => n - query.length < quantum;
   const analogs: AnalogCandidate[] = [];
   for (const p of points) {
     if (p === dominant) continue;
     // Push the point's own anchor only when its context fits within
     // the query (the seat sentence must not dominate the comparison).
     if (
-      p.ctx.length <= query.length &&
+      queryScale(p.ctx.length) &&
       indexOf(dominant.ctx, p.ctx, 0) < 0 &&
       indexOf(p.ctx, dominant.ctx, 0) < 0 &&
       indexOf(query, p.ctx, 0) < 0
@@ -504,7 +543,7 @@ export async function counterfactualTransfer(
     for (const nid of ctx.store.nextFirst(p.anchor, hubBound(ctx))) {
       const nctx = read(ctx, nid);
       if (
-        nctx.length > query.length ||
+        !queryScale(nctx.length) ||
         indexOf(dominant.ctx, nctx, 0) >= 0 ||
         indexOf(nctx, dominant.ctx, 0) >= 0 ||
         indexOf(query, nctx, 0) >= 0
@@ -512,6 +551,23 @@ export async function counterfactualTransfer(
       analogs.push({ anchor: nid, point: null, src: p });
     }
   }
+  // MEASURED AND REFUTED — proposing analogs from the dominant's halo when the
+  // query-local generator finds none.  Both loops above are query-local (an
+  // aligned point, or one forward hop off one), while the gate that judges
+  // candidates — analogyStrength's halo tier — is cross-domain by construction
+  // and is licence enough on its own (`bestHalo` exempts it from the naming and
+  // trusted-root bars).  So the gate reads as strictly more capable than the
+  // generator, and closing that asymmetry looks like the fix for test/29 A2
+  // (`Michelangelo is to sculpture as who is to literature?`, whose only stored
+  // content is `Michelangelo`: the weave aligns the concept and its own
+  // exemplar, each contains the other, so every candidate is excluded and
+  // comparison checks zero).
+  //
+  // It proposes nothing.  Measured on A2's own 13-pair corpus: `Michelangelo`
+  // HAS a halo, and `haloSiblings` returns not one sibling above
+  // significanceBar — the distributional company that would make Shakespeare a
+  // cross-domain analog was never trained.  The asymmetry is real but it is not
+  // what stops A2; the corpus is.
   let bestAnalog: AnalogCandidate | null = null;
   let bestSim = 0;
   let bestHalo = false;
@@ -756,7 +812,7 @@ export async function counterfactualTransfer(
     bestAnalog !== null &&
     (bestHalo || analogNamed || rootTrusted) &&
     !cmpDismisses &&
-    dominant.ctx.length <= query.length &&
+    queryScale(dominant.ctx.length) &&
     roots.length <= 1 &&
     !dominates(cmpMaxGap, query.length) &&
     cmpMaxGap < dominant.ctx.length
@@ -802,7 +858,7 @@ export async function counterfactualTransfer(
     );
   } else if (
     bestAnalog !== null &&
-    dominant.ctx.length <= query.length &&
+    queryScale(dominant.ctx.length) &&
     roots.length <= 1
   ) {
     ctx.trace?.step(

package/src/mind/mechanisms/extraction.ts

@@ -7,12 +7,9 @@
 // (or one of its pieces is), and the context is the smallest spanning frame
 // that contains it.
 
-import type { Vec } from "../../vec.js";
 import type { MindContext } from "../types.js";
-import type { Site } from "../graph-search.js";
-import { foldTree, gistOf, perceive, read, resolve } from "../primitives.js";
-import { follow, locate } from "../match.js";
-import { chooseAmong, hubBound } from "../traverse.js";
+import { read } from "../primitives.js";
+import { follow, isSpanShaped, locate, skillExemplar } from "../match.js";
 import { concatBytes, indexOf } from "../../bytes.js";
 import { decodeText, unexplainedLabel } from "../rationale.js";
 import type {
@@ -358,104 +355,6 @@ export function answerRunsInContext(
   return merged.length > 0 ? merged : null;
 }
 
-/** 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.
- *  If the anchor has a nextOf continuation, that is the answer and the anchor
- *  itself is the context.  Otherwise the anchor's prevOf parents provide
- *  candidate contexts, and the longest one whose span is span-shaped wins. */
-export async function skillExemplar(
-  ctx: MindContext,
-  anchor: number,
-  guide?: Vec | null,
-): Promise<{ contextBytes: Uint8Array; answerBytes: Uint8Array } | null> {
-  if (ctx.store.hasNext(anchor)) {
-    const contextBytes = read(ctx, anchor);
-    const answerBytes = await follow(ctx, anchor, guide);
-    if (
-      answerBytes !== null && isSpanShaped(ctx, contextBytes, answerBytes)
-    ) {
-      return { contextBytes, answerBytes };
-    }
-    return null;
-  }
-  const answerBytes = read(ctx, anchor);
-  // Candidate contexts, capped at the hub bound (a common answer's reverse
-  // fan-in is corpus-sized).
-  const capped = ctx.store.prevFirst(anchor, hubBound(ctx));
-  const spanShaped: Array<{ id: number; bytes: Uint8Array }> = [];
-  for (const p of capped) {
-    const ctxB = read(ctx, p);
-    if (ctxB.length > 0 && isSpanShaped(ctx, ctxB, answerBytes)) {
-      spanShaped.push({ id: p, bytes: ctxB });
-    }
-  }
-  if (spanShaped.length === 0) return null;
-  // Among span-shaped contexts, the longest wins (the smallest spanning frame
-  // heuristic's dual: more frame to locate in the query); the query gist,
-  // when given, breaks LENGTH TIES via chooseAmong — the same reverse-regime
-  // disambiguator every context pick uses, whose gist cache spares the
-  // re-fold this block once paid per tied candidate.  Same strict first-seen
-  // tie-break as the hand loop it replaces.
-  const maxLen = Math.max(...spanShaped.map((s) => s.bytes.length));
-  const longest = spanShaped.filter((s) => s.bytes.length === maxLen);
-  let contextBytes = longest[0].bytes;
-  if (guide && longest.length > 1) {
-    const pick = chooseAmong(ctx, longest.map((s) => s.id), guide).id;
-    contextBytes = longest.find((s) => s.id === pick)!.bytes;
-  }
-  return { contextBytes, answerBytes };
-}
-
-/** Whether the answer is a SPARSE subsequence of the context (bytes in
- *  order, arbitrary gaps) — the OPEN span-shape reading (see the section
- *  note above).  This is what lets extraction validate a MULTI-PIECE
- *  exemplar whose answer is stitched from several context runs — but it is
- *  deliberately permissive, so it must never be used as evidence that one
- *  span was "drawn from" another (see {@link containsSpan} for that).
- *
- *  There is deliberately NO containsSpan pre-check here: strict containment
- *  IMPLIES the subsequence embedding (a contiguous run, or a resolved node —
- *  whose content-addressed identity means its bytes occur contiguously — is
- *  an in-order embedding with zero gaps), so the scan below decides alone,
- *  with the same truth value.  The old pre-check re-perceived the context
- *  (a full river fold) per CANDIDATE in skillExemplar's √N-capped loop —
- *  pure cost, no discrimination. */
-export function isSpanShaped(
-  _ctx: MindContext,
-  context: Uint8Array,
-  answer: Uint8Array,
-): boolean {
-  let ai = 0;
-  for (let ci = 0; ci < context.length && ai < answer.length; ci++) {
-    if (context[ci] === answer[ai]) ai++;
-  }
-  return ai === answer.length;
-}
-
-/** STRICT containment: the answer's resolved node appears in the context's
- *  folded tree, or the answer occurs as one CONTIGUOUS byte run of the
- *  context.  This is real evidence the answer was drawn from the context.
- *  Fusion gates on this — the sparse-subsequence reading of
- *  {@link isSpanShaped} is trivially satisfied by short answers over long
- *  queries ("cold" is a gap-tolerant subsequence of most sentences holding
- *  c…o…l…d in order), and gating fusion on it silently starved multi-topic
- *  queries of their further points of attention. */
-export function containsSpan(
-  ctx: MindContext,
-  context: Uint8Array,
-  answer: Uint8Array,
-): boolean {
-  const ansId = resolve(ctx, answer);
-  if (ansId !== null) {
-    let found = false;
-    foldTree(ctx, perceive(ctx, context), 0, (_n, _s, _e, node) => {
-      if (node === ansId) found = true;
-    });
-    if (found) return true;
-  }
-  return indexOf(context, answer, 0) >= 0;
-}
-
 // ── Pipeline mechanism ──────────────────────────────────────────────────────
 
 export const extractionMechanism: PipelineMechanism = {

package/src/mind/mechanisms/recall.ts

@@ -29,6 +29,9 @@ export interface RecallResult {
   accounted: Array<[number, number]>;
   moves: number;
   unexplained: string;
+  /** See {@link import("../pipeline-mechanism.js").MechanismResult.complete}
+   *  — set by the IDENTITY-bridge tier alone. */
+  complete?: boolean;
 }
 
 /** Recall the answer by resonating the whole query against the content index. */
@@ -48,6 +51,7 @@ export async function recallByResonance(
     accounted: Array<[number, number]>,
     moves: number,
     echoed = false,
+    complete = false,
   ): RecallResult | null => {
     t?.done(
       bytes === null
@@ -61,6 +65,7 @@ export async function recallByResonance(
       accounted,
       moves,
       unexplained: unexplainedLabel(query, accounted),
+      ...(complete ? { complete } : {}),
     };
   };
   const k = pre.k;
@@ -329,14 +334,35 @@ export async function recallByResonance(
     // natural, tuning-free ceiling (probe every cluster) for a call that
     // is ALREADY refusal-path-only and must not miss a candidate hiding
     // behind an unlucky structural distance.
-    const wide = k < hubBound(ctx)
-      ? await ctx.store.resonate(queryGist, hubBound(ctx), true)
-      : whole;
-    const bridged = await substitutionBridge(
-      ctx,
-      query,
-      wide.map((h) => h.id),
-    );
+    //
+    // MEASURED COST, AND WHY IT STAYS (17.9M vectors / 325K contexts):
+    // this one call is ~570 ms and ~45% of all inference time on a refusing
+    // query.  The cost is entirely `exhaustive` (nprobe = every cluster),
+    // NOT the widened k — timed on that store: k=571 exhaustive 632 ms,
+    // k=24 exhaustive 536 ms, k=571 NON-exhaustive 12 ms.  So narrowing k
+    // buys nothing and the 50x is the whole-index scan itself.
+    // It is load-bearing: over an 18-query battery the bridge produced a
+    // winner 4 times, and ALL FOUR winners came from this proposal channel
+    // — the anchor-climb channel won nothing on its own.  Reordering the
+    // channels (climb first, resonate only on failure) would therefore pay
+    // the climb, fail, and pay this anyway.  Do not weaken it without
+    // re-running that measurement.
+    // Handed to the bridge as a THUNK: this exhaustive whole-index probe is
+    // the most expensive single act on the refusal path, and the bridge's
+    // own cheap gates (query length, the O(|query|) stored-window anchor
+    // scan) can refuse without any proposal at all.  See substitutionBridge.
+    const wideIds = async (): Promise<ReadonlyArray<number>> => {
+      const wide = k >= hubBound(ctx)
+        ? whole
+        : ctx.meter
+        ? await ctx.meter.time(
+          "recall.exhaustiveResonate",
+          () => ctx.store.resonate(queryGist, hubBound(ctx), true),
+        )
+        : await ctx.store.resonate(queryGist, hubBound(ctx), true);
+      return wide.map((h) => h.id);
+    };
+    const bridged = await substitutionBridge(ctx, query, wideIds);
     if (bridged !== null) {
       const g = await project(ctx, bridged.id, queryGist);
       // A projection contained in a substituted candidate-side span is the
@@ -357,16 +383,56 @@ export async function recallByResonance(
       ) {
         return ground(
           g,
-          `substitution bridge — a trained context accounts for the query ` +
-            `up to ${bridged.subs.length} corroborated substitution(s)`,
-          // Accounted NOTHING — the same epistemic humility as the echo
-          // tier below: a substitution-bridged grounding is a last resort
-          // that must lose to ANY mechanism that actually explained the
-          // query (observed: pricing the aligned spans here outweighed
-          // extraction's correct answer in the grounding decider), while
-          // still beating silence when everything else refused.
-          [],
+          bridged.subs.length === 0
+            ? `identity bridge — a trained context IS this query, up to ` +
+              `scaffolding the corpus itself treats as filler`
+            : `substitution bridge — a trained context accounts for the ` +
+              `query up to ${bridged.subs.length} corroborated ` +
+              `substitution(s)`,
+          // WHAT THIS GROUNDING EXPLAINS — the spans its alignment covers,
+          // matched AND substituted, for BOTH tiers.
+          //
+          // A corroborated substitution is not a gap in the explanation; it is
+          // an explanation the mechanism PAID for, one CONCEPT each in `moves`
+          // just below.  Leaving its span unaccounted charges the same act
+          // twice — once as a move, once as PASS-per-unexplained-byte — and the
+          // second charge is far the larger, so a bridge that matched 28 of 29
+          // bytes declared the whole query unexplained and lost to any
+          // mechanism with a smaller honest claim.  Measured on test/49's
+          // paraphrase: it FOUND the trained fact through two corroborated case
+          // substitutions and was outbid 29011 to 1012 by a CAST comparison
+          // that voiced the wrong country.
+          //
+          // This tier DID once report `[]` for the substituted case, against
+          // the observation that "pricing the aligned spans outweighed
+          // extraction's correct answer in the grounding decider".  That is no
+          // longer so and the suite is the witness: with the fold's regions
+          // content-defined and the junction tiers no longer consuming each
+          // other's candidates, full accounting here passes every test that
+          // refutation was recorded for.  Reporting only the LITERALLY matched
+          // spans (accounted minus the substituted ones) was also implemented
+          // and is a strictly worse reading of the same ladder — it still
+          // double-charges, just less.
+          //
+          // An IDENTITY bridge (zero substitutions) substituted nothing, so
+          // there is nothing to be humble about: every accounted byte is a
+          // LITERAL match against a trained form, and the query is that form
+          // up to scaffolding.  Reporting `[]` for it was actively wrong in
+          // two ways — it priced a full explanation at PASS-per-byte so junk
+          // outweighed it, and, because the honest-remainder test in think()
+          // reads the same spans, it left the whole query "unaccounted" and
+          // forced the multi-topic fusion gate open.  Observed live: the
+          // correct "What is the process of photosynthesis?" grounding was
+          // fused away into an unrelated "Hello! How can I assist you
+          // today?" point of attention.
+          [...bridged.accounted],
           CONCEPT * bridged.subs.length + STEP,
+          false,
+          // COMPLETE only for the identity tier: the query IS this trained
+          // context, so `g` is that context's own continuation — the whole
+          // read-out.  A SUBSTITUTED bridge makes no such claim (it stood a
+          // different word in the query's place), so it stays extendable.
+          bridged.subs.length === 0,
         );
       }
     }
@@ -434,6 +500,7 @@ export const recallMechanism: PipelineMechanism = {
       moves: r.moves,
       unexplained: r.unexplained,
       provenance: r.echoed ? "recall-echo" : "recall",
+      ...(r.complete ? { complete: true } : {}),
     }];
   },
 };