@hviana/sema 0.8.1 → 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";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -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 };
 }

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

@@ -98,6 +98,7 @@ export async function resolveConnectors(
     });
   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);
   };
@@ -134,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/mind.ts

@@ -11,9 +11,12 @@
 
 import { cosine, makeKeyring, rng, setVecConfig, Vec } from "../vec.js";
 import { bindSeat, fold, Sema, Space } from "../sema.js";
+import { sampleCorpus, searchCorpus } from "./corpus.js";
+import type { CorpusPair, CorpusResult } from "./corpus.js";
 import { Alphabet } from "../alphabet.js";
 import {
   bytesToTree,
+  contentBoundaries,
   contentFoldIncremental,
   Grid,
   gridToTree,
@@ -146,6 +149,7 @@ interface ConversationData {
 import type { AttentionRead, MindContext, Recognition } from "./types.js";
 import { changedNodes, liftAnswer, spliceAll } from "./types.js";
 import {
+  canonResolve as canonResolveImpl,
   foldTree,
   gistOf,
   inputBytes,
@@ -194,10 +198,61 @@ import { type CostReport, Meter } from "../meter.js";
 
 // ── MindOptions ───────────────────────────────────────────────────────────
 
+/** A stored pair as TEXT — the text helper's view of {@link CorpusPair}. */
+export interface CorpusTextPair {
+  context: string;
+  continuation: string;
+  contextId: number;
+  continuationId: number;
+  matchedBytes: number;
+  contextTruncated: boolean;
+  continuationTruncated: boolean;
+}
+
+/** {@link CorpusResult} as text, plus the prose for why nothing matched.  The
+ *  byte layer reports a STATE; saying it in words belongs to the text layer. */
+export interface CorpusTextResult {
+  query: string;
+  pairs: CorpusTextPair[];
+  resolved: number;
+  reached: number;
+  totalContexts: number;
+  browsed: boolean;
+  note?: string;
+}
+
+/** What the text helper says when the byte layer reports a miss. */
+const CORPUS_NOTE: Record<string, string> = {
+  "nothing-resolved":
+    "No trained note sits above the parts of that text the mind recognised. " +
+    "It addresses content exactly, so try wording closer to something it was " +
+    "actually given — or browse the examples instead.",
+  "no-continuations":
+    "That text reaches stored nodes, but none of them carries a learnt " +
+    "continuation.",
+};
+
+/** UTF-8 of bytes for display: reuse {@link decodeText} (the mind's own text
+ *  conversion), then drop the replacement character a byte-boundary cut leaves
+ *  behind.  Much of a real corpus is non-Latin, so that trailing U+FFFD is the
+ *  common case, not an exotic one — and it is the ONLY thing added here. */
+function previewCorpusText(bytes: Uint8Array): string {
+  return decodeText(bytes).replace(/\uFFFD+$/, "").replace(/\s+/g, " ").trim();
+}
+
 export interface MindOptions {
   seed?: number;
   recallQueryK?: number;
   haloQueryK?: number;
+  /** Items one rationale step may itemise — see {@link MindConfig}. */
+  rationaleSampleK?: number;
+  /** Corpus-reading capacities and budgets — see {@link MindConfig}. */
+  corpusLimitMax?: number;
+  corpusClimbs?: number;
+  corpusContextsPerClimb?: number;
+  corpusSampleProbes?: number;
+  corpusPreviewBytes?: number;
+  corpusSampleFloorBytes?: number;
   normalizeEpsilon?: number;
   cosineEpsilon?: number;
   geometry?: Partial<import("../config.js").GeometryConfig>;
@@ -347,6 +402,20 @@ export class Mind implements MindContext {
    *  `traverse.ts`'s ONE definition (edge or halo, with its response-scoped
    *  cache).  The search holds a bare Store and cannot reach that cache itself,
    *  so it asks through this hook; a bare host keeps its raw-store fallback. */
+  /** The canonical identity for the search (see GraphSearchHost). */
+  canonResolve(bytes: Uint8Array): number | null {
+    return canonResolveImpl(this, bytes);
+  }
+
+  /** Feed a search refusal into the rationale (see GraphSearchHost). */
+  reportSearch(
+    name: string,
+    parts: ReadonlyArray<Uint8Array>,
+    note: string,
+  ): void {
+    this.trace?.step(name, parts.map((b) => rItem(b)), [], note);
+  }
+
   leadsSomewhere(id: number): boolean {
     return leadsSomewhere(this, id);
   }
@@ -374,6 +443,11 @@ export class Mind implements MindContext {
    *  with the most distributional evidence (highest `prevOf` count — the
    *  structural manifestation of its halo).  When evidence is equal the
    *  first-inserted edge wins. */
+  /** See {@link GraphSearchHost.contentCuts}. */
+  contentCuts(bytes: Uint8Array): readonly number[] {
+    return contentBoundaries(this.space, bytes);
+  }
+
   chooseNext(node: number): number | undefined {
     return chooseNext(this, node, this._edgeGuide);
   }
@@ -737,6 +811,55 @@ export class Mind implements MindContext {
     return decodeText(r.bytes);
   }
 
+  // ── Reading the trained memory back ─────────────────────────────────────
+
+  /** Which stored notes does this query REACH?  BYTES in, BYTES out — this
+   *  method has no notion of text or encoding; the text case is
+   *  {@link searchCorpusText}, which is one caller of this.
+   *
+   *  Exact content addressing through the machinery an answer already uses
+   *  (see src/mind/corpus.ts): the query's recognised sites are the resolved
+   *  subtrees, the climb goes up from the biggest, and a result is a context
+   *  that carries a learnt continuation.  Nothing is written and nothing is
+   *  indexed. */
+  searchCorpus(queryBytes: Uint8Array, limit?: number): CorpusResult {
+    return searchCorpus(this, queryBytes, limit);
+  }
+
+  /** Browse real pairs.  Deterministic: `from` is the caller's own offset in
+   *  [0,1), so browsing twice with different offsets shows different notes
+   *  without a random draw. */
+  sampleCorpus(limit?: number, from?: number): CorpusResult {
+    return sampleCorpus(this, limit, from);
+  }
+
+  /** The TEXT case of {@link searchCorpus}: encode, search, decode.  The search
+   *  itself exists once, in the byte layer above; only the rendering lives
+   *  here, with the rest of this class's text modality. */
+  searchCorpusText(query: string, limit?: number): CorpusTextResult {
+    const result = this.searchCorpus(
+      new TextEncoder().encode(query),
+      limit,
+    );
+    return {
+      query,
+      pairs: result.pairs.map((p: CorpusPair): CorpusTextPair => ({
+        context: previewCorpusText(p.context),
+        continuation: previewCorpusText(p.continuation),
+        contextId: p.contextId,
+        continuationId: p.continuationId,
+        matchedBytes: p.matchedBytes,
+        contextTruncated: p.contextTruncated,
+        continuationTruncated: p.continuationTruncated,
+      })),
+      resolved: result.resolved,
+      reached: result.reached,
+      totalContexts: result.totalContexts,
+      browsed: result.browsed,
+      note: result.miss === "matched" ? undefined : CORPUS_NOTE[result.miss],
+    };
+  }
+
   // ── Conversation API ────────────────────────────────────────────────────
 
   /** Begin a new conversation, optionally restoring from a previously-saved

package/src/mind/pipeline.ts

@@ -545,12 +545,40 @@ export async function think(
       ctx.store.nextFirst(id, hubBound(ctx)).map((n) => read(ctx, n))
     )
     : [];
+  // REPORTABLE, NOT SILENT.  A declared-complete grounding ends the derivation
+  // here, and that decision is part of the derivation's shape: the reader of a
+  // rationale must be able to see that the chain stopped because the mechanism
+  // claimed the query WAS the context, not because nothing followed.  The step
+  // carries the claim, not a re-description of the answer — the extension is
+  // skipped, so there is no output item to show.
+  if (decided.complete) {
+    ctx.trace?.step(
+      "completeGrounding",
+      [rItem(answer, provenance)],
+      [],
+      "grounding declared complete — the query IS the context, so " +
+        "post-grounding extension is skipped",
+    );
+  }
+  // THE REASONER JUDGES ITS OWN EXTENSIONS BY THE PIPELINE'S REMAINDER, not by
+  // the ladder's `accounted` — and by the SAME reading the fuse gate below uses,
+  // with the same W floor.  `accounted` is a COST quantity (measured: a query
+  // fully explained by one computed span plus bridged connectors reports
+  // `accounted: []` while nothing is unexplained), and a remainder under one
+  // river-fold quantum is bridging punctuation, never a second topic — so it
+  // licenses no extension and blocks none.
+  const explained: Array<[number, number]> = [
+    ...decided.accounted,
+    ...pre.computed.map((u): [number, number] => [u.i, u.j]),
+  ];
+  const uncovered = unexplainedSpans(query.length, explained)
+    .filter(([a, b]) => b - a >= ctx.space.maxGroup);
   const reasoned = decided.complete ? answer : meter
     ? await meter.time(
       "reason",
-      () => reason(ctx, query, answer, preConsumed, pre, voiced),
+      () => reason(ctx, query, answer, preConsumed, pre, voiced, uncovered),
     )
-    : await reason(ctx, query, answer, preConsumed, pre, voiced);
+    : await reason(ctx, query, answer, preConsumed, pre, voiced, uncovered);
 
   // Fuse only when the query has a genuine REMAINDER no mechanism's
   // structural evidence touched at all.  `decided.accounted` alone
@@ -568,10 +596,6 @@ export async function think(
   // observed: a single space between two fully-computed arithmetic spans
   // ("2+2 3+3") registered as "unaccounted" and pulled in an unrelated
   // corpus fact, corrupting "4 6" into "4 63".
-  const explained: Array<[number, number]> = [
-    ...decided.accounted,
-    ...pre.computed.map((u): [number, number] => [u.i, u.j]),
-  ];
   const remainder = unaccounted(explained);
   // Whether the winning candidate's entire recognised substance is
   // COMPUTED — every accounted span exactly a pre.computed span, nothing

package/src/mind/reasoning.ts

@@ -43,6 +43,10 @@ export async function reason(
   preConsumed: ReadonlySet<number>,
   pre: Precomputed,
   voiced: readonly Uint8Array[] = [],
+  /** The query material the GROUNDING left uncovered — the cost ladder's own
+   *  `unaccounted` spans.  Only the reasoner's OWN extensions are judged
+   *  against it; a mechanism carrying its own `used` set owns its shape. */
+  uncovered: readonly (readonly [number, number])[] = [],
 ): Promise<Uint8Array> {
   // Echo guard: a query that is ITSELF a learnt continuation (some context's
   // answer) is being asked back at the system — hopping forward from it would
@@ -200,6 +204,57 @@ export async function reason(
     const fc = await follow(ctx, pivot, qv);
     consumeAll(pivot);
     if (fc === null || bytesEqual(fc, cur) || restatesQuery(query, fc)) break;
+    // WHOSE EXTENSION IS THIS?
+    //
+    // `voiced` is what the mechanism WITHHELD (the pipeline sends the used
+    // anchors' CONTINUATIONS, not their bytes — see pipeline's own note), so a
+    // non-empty `voiced` means exactly what that note says: the grounding came
+    // from a mechanism that carries its own short `used` set (cast/join) and
+    // therefore owns the shape of its answer.  The further terms inside such a
+    // seat are legitimately followable — test/29 C3's `Mona Lisa` lives inside
+    // the voiced seat and leads on to a fact about neither analog.
+    //
+    // Every other grounding is ordinary, and an extension of it is the
+    // reasoner's own inference: it is taken only while question material the
+    // grounding left uncovered remains AND the step carries some of it, judged
+    // by the mind's own line between chance and evidence — one W-byte window,
+    // no word notion, no character class, no threshold.  Measured: the drift's
+    // second step (`the Eiffel Tower is in Paris` after `Paris is famous for
+    // the Eiffel Tower`) carries no window of `" famous for"` and is refused,
+    // while the first carries it.  Terminates by a real argument: the uncovered
+    // material is finite and each taken extension must carry some of it.
+    const producerOwnsShape = voiced.length > 0;
+    if (!producerOwnsShape && uncovered.length > 0) {
+      const W = ctx.space.maxGroup;
+      let progress = false;
+      for (const [a, b] of uncovered) {
+        for (let i = a; i + W <= b && !progress; i++) {
+          if (indexOf(fc, query.subarray(i, i + W), 0) >= 0) progress = true;
+        }
+        if (progress) break;
+      }
+      if (!progress) {
+        // THE BRAKE, MADE VISIBLE.  The reasoner declines a step that carries
+        // none of the material the grounding left uncovered — the drift the
+        // extension tests pin.  A refusal that leaves no trace is the kind of
+        // silent cut AGENTS §6 forbids: the rationale is where a reader learns
+        // that an extension was declined for want of question material, and
+        // where the next person sees why the chain stopped here.  Measured with
+        // the check disabled, test/110 and test/116 fail — so this brake is the
+        // only thing keeping the extension honest until the pivot reports its
+        // own accounted spans and the ladder can judge it instead.
+        const left = uncovered.reduce((n, [a, b]) => n + (b - a), 0);
+        ctx.trace?.step(
+          "pivotRefused",
+          [rItem(cur, "answer"), rItem(query, "query")],
+          uncovered.map(([a, b]) => rItem(query.subarray(a, b), "uncovered")),
+          `the step carries none of the question material the grounding left ` +
+            `uncovered (${left} byte(s) in ${uncovered.length} span(s)) — refused`,
+        );
+        break;
+      }
+    }
+    if (ctx.meter) ctx.meter.pivotSteps++;
     t ??= ctx.trace?.enter("reason", [rItem(startedFrom, "grounded")]);
     ctx.trace?.step(
       "pivotStep",

package/src/mind/traverse.ts

@@ -765,7 +765,15 @@ export function chooseNext(
   // for the prevCount calls in the loop above, never for extra rItemShort
   // byte-reads.
   if (ctx.trace) {
-    const others = capped.filter((c) => c !== best);
+    // A BOUNDED SAMPLE, AND THE COUNT.  The step used to carry EVERY candidate
+    // it weighed — measured on the trained store, 1559 out-items in one step
+    // (hubBound's own size) and 1082 in another (the hub's degree).  The
+    // rationale's job is to explain the CHOICE, and the count is what says how
+    // wide the field was; the declared candidate budget (`recallQueryK`) is what
+    // bounds the sample, so no number is invented here.
+    const others = capped
+      .filter((c) => c !== best)
+      .slice(0, ctx.cfg.rationaleSampleK);
     ctx.trace.step(
       "disambiguate",
       [rItemShort(ctx, best, "halo-evidence", bestSupport)],

package/src/mind/types.ts

@@ -65,12 +65,38 @@ export interface GraphSearchHost {
     starts: ReadonlySet<number>;
   };
   chooseNext?(node: number): number | undefined;
+  /** The boundary positions of `bytes` under the engine's ONE boundary rule
+   *  (geometry.ts's `contentBoundaries`), or undefined when the host has no
+   *  space to ask.  The join's key is an entity plus a prefix of the tail, and
+   *  the prefix that names a stored relation ENDS on one of these boundaries —
+   *  measured, 5 of 5 accepted keys over four join-firing queries, where the
+   *  byte-by-byte scan spent 153 probes for 14 boundaries.  Boundaries are
+   *  content-defined and STABLE under prefix extension, which is why a corpus
+   *  key's end is a boundary of the query's own fold of the same bytes. */
+  contentCuts?(bytes: Uint8Array): readonly number[];
   /** The admission predicate — `traverse.ts`'s `leadsSomewhere`, its ONE
    *  definition: does this node bear an edge or a halo?  Optional, so a bare
    *  host (a raw Store and nothing else) still works; when present, the search
    *  uses it rather than re-probing the store, which keeps the predicate
    *  single-defined AND memoised on the response-scoped struct cache. */
   leadsSomewhere?(id: number): boolean;
+  /** Report a SEARCH REFUSAL into the rationale — the channel AGENTS §6
+   *  requires: a callback threaded through a call chain must FEED the
+   *  rationale, the way `GraphSearch`'s `onDerivation` feeds `traceDerivation`,
+   *  never a channel of its own.  Optional, so a bare host stays silent rather
+   *  than crashing. */
+  reportSearch?(
+    name: string,
+    parts: ReadonlyArray<Uint8Array>,
+    note: string,
+  ): void;
+  /** The CANONICAL resolver ({@link canonResolve}), optional like
+   *  {@link leadsSomewhere}.  The store's keys were written through the
+   *  canonical fold, so a fact's `Gustaf Molander` and the deposited
+   *  `gustaf molander` are the SAME node (measured inside a response: the
+   *  canonical resolver maps the surface form to the deposited node while a raw
+   *  resolve returns null).  A bare host falls back to the plain probe. */
+  canonResolve?(bytes: Uint8Array): number | null;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════