@hviana/sema 0.8.1 → 0.8.3

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 };
 }
@@ -634,7 +723,7 @@ export function frameSlots(
  *  ANCHOR that the query displaced.  Neither implies the other, and the
  *  observed failures pass the restatement guard cleanly.
  *
- *  Three conditions, all byte-exact and all necessary:
+ *  Four conditions, all byte-exact and all necessary:
  *
  *  1. the query and the anchor must be ONE STRUCTURE — what they share has to
  *     dominate the query, or the query is not a variant of the anchor at all
@@ -722,8 +811,10 @@ export function substituteAll(
   const usable = pairs.filter((p) => p.needle.length > 0);
   if (usable.length === 0) return hay;
   // Longest needle first, so a needle that is a prefix of another can never
-  // pre-empt it.  Ties cannot arise: an instance whose fillers are not
-  // pairwise distinct is refused by frameSlots.
+  // pre-empt it.  Ties cannot arise: a consumer that VOICES checks the
+  // fillers pairwise with `distinct` and refuses such an instance itself —
+  // `frameSlots` reports and does not judge (see its own doc), so the refusal
+  // lives with the mechanism that needs it, not here.
   const order = [...usable].sort((a, b) => b.needle.length - a.needle.length);
   const out: number[] = [];
   let i = 0;

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",
@@ -851,7 +867,9 @@ export async function counterfactualTransfer(
   // grounds") — fine for ORIENTING mechanisms, not for voicing learnt
   // content the query never asked about.  Computed once here; both the
   // hub fallback below and the comparison gate consume it.
-  const rootTrusted = roots.some((r) => r.vote >= consensusFloor(corpusN(ctx)));
+  const rootTrusted = roots.some((r) =>
+    r.idfVote >= consensusFloor(corpusN(ctx))
+  ); // the IDF sum: the bar's own quantity
   // The context that ESTABLISHES a filler — the same reverse context, under
   // the same naming test, `seatOfNode` uses to VOICE an analog (a predecessor
   // whose bytes CONTAIN the node's: it names or describes it, rather than

package/src/mind/mechanisms/confluence.ts

@@ -146,6 +146,30 @@ export async function confluenceJoin(
   const bindsAConstituent = (cover: Array<[number, number]>): boolean =>
     cover.some(([cs, ce]) => ce - cs >= 2 * W);
 
+  // THE VOTE ENTERS AS ORDER, NEVER AS A BAR.  This is the only one of the
+  // climb's four consumers (recall, fuseAttention, cast, here) that uses the
+  // evidence's MAGNITUDE without a floor, and it is legitimate by construction:
+  // `ranked` answers "which anchor is stronger" — a question about votes, so the
+  // comparison stays within one dimension — and the vote is otherwise only
+  // REPORTED (Stream.vote travels to the rationale's constraint nodes).  What
+  // actually SELECTS a constraint is byte-structural and never the magnitude: a
+  // run of at least 2W (`bindsAConstituent`, with its accidental-sharing
+  // counter-examples above), disjoint covers (`disjoint`), and scaffolding never
+  // binds at all (`dominates(reachOf(…), N)`).  The MEET such a stream may
+  // produce is selected the same way: a span shorter than 2W is rejected, and
+  // the winner is the one with the smallest `reach` (ties broken by the longer
+  // span) — a corpus quantity and bytes, never the vote, which appears only in
+  // the trace item.
+  // binds at all (`dominates(reachOf(…), N)`).  The only cut in this loop is a
+  // BUDGET, and it is measured: stopping the scan at 2W anchors saves 50-70% of
+  // confluence's cost on non-conjunctive queries while preserving every genuinely
+  // conjunctive case, whose top anchors ARE its constraints.
+  // MEASURED (this goal, on THIS file's own conjunctive fixture): the two
+  // streams appear at ranks 1 and 4 against a budget of 2W = 8, on a query whose
+  // `ranked` is 9 — so the cut IS live (it would have returned null at the 8th
+  // anchor) and it does NOT prune the case it exists to protect.  The other
+  // conjunctive fixture (the Leonardo one) finds them at ranks 0 and 1.  Scope:
+  // these are the repo's conjunctive fixtures, and no more.
   const streams: Stream[] = [];
   const rankedCapped = ranked.length > pre.k ? ranked.slice(0, pre.k) : ranked;
   // CONJUNCTIVITY EARLY-EXIT: a conjunctive query's top-ranked anchors

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/mechanisms/recall.ts

@@ -276,9 +276,36 @@ export async function recallByResonance(
     // consensus", while breadth is the SCALE-INVARIANT reading — "a point whose
     // breadth clears `dominates` (> half the query's regions corroborate it) is
     // real consensus; one that does not is a coincidental single-region echo".
-    // Attention.peak's contract makes the same point from the other side:
-    // comparing a POOLED SUM against a floor that prices ONE region's evidence
-    // is a dimensional error.
+    // THIS USED TO CLAIM A DIMENSIONAL ERROR, AND THAT CLAIM WAS FALSE.
+    // It read: "comparing a POOLED SUM against a floor that prices ONE region's
+    // evidence is a dimensional error."  `consensusFloor` is not priced for one
+    // region: thresholds.md §2 derives it as the POOLED-vote significance floor —
+    // "each region contributes at most ln(N/c) <= ln(N); ln(N)+1/2 demands ..." —
+    // and attention.ts says the same where it builds the vote ("the scale
+    // consensusFloor is derived for").  The comparison is in ONE dimension, and
+    // it is so because the climb WEIGHTS BY IDF: `wf` in voteRegions is
+    // `direct ? df : combined ? idf + df : idf`, and the engine only ever runs the
+    // last one (DFMode's default "inverse", the mode every non-test caller uses —
+    // `direct` and `combined` are exercised by test/24 and test/27 only, and
+    // test/24 pins that their votes DO differ).  In those two the sum would leave
+    // the floor's dimension and the floor would need re-deriving.
+    //
+    // What the OR below is really for is SCALE, not dimension (the paragraph
+    // above says it): a vote that clears ln(N)+1/2 means "strong" on a small store
+    // and "weak" on a large one for the same genuine consensus, so the
+    // scale-invariant breadth reading is added beside it.
+    //
+    // AND THE PREMISE IS IDF.  The deviation in the other two weighting modes is
+    // TWO-SIDED and DERIVED: `direct` DEFLATES a region (ln(1+c) < ln(N/c) for
+    // small c) and `combined` INFLATES it (ln N + ln(1+1/c)), both by at most
+    // `ln 2` — see `geometry.ts`'s `consensusFloor`, where the bound lives.
+    // MEASURED on 8 anchors across 5 queries, running the same climb in all
+    // three modes: ZERO gate inversions — every anchor's `vote >= floor` verdict
+    // is the same in `inverse`, `direct` and `combined`, even where the readings
+    // straddle the floor on opposite sides (#148: inverse 3.39, combined 4.71
+    // above it, direct 1.31 below).  Pinned by test/55's test 20.  The bar is not
+    // re-derived for those modes because nothing reachable needs it; the premise
+    // is IDF, and that is now written where the gate reads it.
     //
     // Measured on the 15.7M-node store (N=325,615, so the old floor was 13.19).
     // The absolute vote cannot separate right from wrong at this scale, and the
@@ -348,7 +375,7 @@ export async function recallByResonance(
     if (
       forest.length > 0 &&
       !allWindowsAreScaffolding(ctx, query) &&
-      (forest[0].vote >= minVote ||
+      (forest[0].idfVote >= minVote || // the IDF sum: the bar's own quantity
         (dominates(forest[0].breadth, 1) && forest[0].peak > Math.LN2))
     ) {
       const g = await project(ctx, forest[0].anchor, queryGist);
@@ -602,6 +629,7 @@ export const recallMechanism: PipelineMechanism = {
       moves: r.moves,
       unexplained: r.unexplained,
       provenance: r.echoed ? "recall-echo" : "recall",
+      used: new Set<number>(),
       ...(r.complete ? { complete: true } : {}),
     }];
   },

package/src/mind/mind.ts

@@ -11,6 +11,8 @@
 
 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,
@@ -21,6 +23,7 @@ import {
   reachThreshold,
   stackGrids,
 } from "../geometry.js";
+import { keyEnds } from "./canonical.js";
 import type { ContentFold } from "../geometry.js";
 import { BoundedMap, type Store } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
@@ -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,63 @@ 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;
+  /** Branch nodes the pivot sweep may probe — see {@link MindConfig}. */
+  pivotProbeK?: 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 +404,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 +445,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.contentKeyEnds}. */
+  contentKeyEnds(prefix: Uint8Array, tail: Uint8Array): readonly number[] {
+    return keyEnds(this, prefix, tail);
+  }
+
   chooseNext(node: number): number | undefined {
     return chooseNext(this, node, this._edgeGuide);
   }
@@ -737,6 +813,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-mechanism.ts

@@ -675,6 +675,13 @@ export interface MechanismResult {
   bytes: Uint8Array;
   accounted: Array<[number, number]>;
   moves: number;
+  /** WHAT THIS ANSWER SPEAKS FOR — the anchors it voices, and therefore the
+   *  content the reasoner must not pivot back through.  Declared by the
+   *  mechanism about its OWN result, exactly like `accounted`/`unexplained`/
+   *  `complete`: post-grounding honours the property and NEVER ASKS WHICH
+   *  MECHANISM SET IT, so the market stays uniform.  An EMPTY set is a real
+   *  declaration — "this answer voices nothing" (recall) — and withholds
+   *  nothing; omit the field and the pipeline re-recognises the answer. */
   used?: ReadonlySet<number>;
   unexplained: string;
   /** Explicit weight override.  When absent, weight = moves + PASS·unaccounted. */