@hviana/sema 0.8.1 → 0.8.3

package/dist/src/mind/match.js

@@ -31,8 +31,8 @@
 // they gate.
 import { addInto, cosine, dot, normalize, zeros } from "../vec.js";
 import { conceptThreshold, dominates, identityBar, significanceBar, } from "../geometry.js";
-import { bytesEqual, indexOf } from "../bytes.js";
-import { chainReach, leafIdRun } from "./canonical.js";
+import { bytesEqual, indexOf, latin1 } from "../bytes.js";
+import { leafIdRun } from "./canonical.js";
 import { foldTree, gistOf, perceive, read, resolve } from "./primitives.js";
 import { argmaxCosine, chooseAmong, chooseNext, corpusN, edgeAncestors, guidedFirst, hubBound, hubCap, sharedReachMemo, } from "./traverse.js";
 import { recognise, segment } from "./recognition.js";
@@ -237,9 +237,14 @@ export function alignGraded(ctx, query, contextBytes, querySites) {
 }
 /** 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
@@ -253,7 +258,21 @@ export function alignGraded(ctx, query, contextBytes, querySites) {
  *  window test); {@link frameSlots} takes the other reading. */
 export function alignAround(ctx, q, c, qo, co) {
     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]) {
@@ -267,8 +286,66 @@ export function alignAround(ctx, q, c, qo, co) {
     }
     const matched = [[qs, qe]];
     const gaps = [];
-    // 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 = [];
+    for (let len = 1; len <= W; len++) {
+        const m = new Map();
+        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, from) => {
+        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, to) => {
+        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, si) => {
         let n = 0;
         while (qi + n < q.length && si + n < c.length && q[qi + n] === c[si + n]) {
@@ -276,69 +353,76 @@ export function alignAround(ctx, q, c, qo, co) {
         }
         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)
+    /** Length of the common run ENDING at (qi, si). */
+    const runLenBefore = (qi, si) => {
+        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, si, forward) => {
+        const qLim = forward ? q.length - qi : qi;
+        let best = 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;
-                if (qi + gq >= q.length || si + gs >= c.length)
+                const o = forward ? fromAt(list, si) : toAt(list, si - len);
+                if (o < 0)
                     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 });
+                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)
+        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;
-                }
-            }
-        }
-        if (!found)
+        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 });
+        }
+        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 };
 }
@@ -462,7 +546,7 @@ export function frameSlots(ctx, query, cand, id) {
  *  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
@@ -547,8 +631,10 @@ export function substituteAll(hay, pairs) {
     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 = [];
     let i = 0;

package/dist/src/mind/mechanisms/cast.js

@@ -16,7 +16,7 @@ import { analogyStrength, follow, project, reverseContext, sharedFrameStrengthOf
 import { joinWithBridge } from "../resonance.js";
 import { restatesQuery } from "../reasoning.js";
 import { CONCEPT, STEP } from "../graph-search.js";
-import { concat2, indexOf } from "../../bytes.js";
+import { indexOf } from "../../bytes.js";
 import { consensusFloor, dominates } from "../../geometry.js";
 import { unexplainedLabel, unexplainedSpans, } from "../rationale.js";
 import { rItem, rNode } from "../trace.js";
@@ -523,7 +523,23 @@ export async function counterfactualTransfer(ctx, query, pre) {
         const fwd = await follow(ctx, proj.anchor, qv);
         if (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", [
             rItem(filler, "filler", subj.point.anchor),
@@ -715,7 +731,7 @@ export async function counterfactualTransfer(ctx, query, pre) {
     // 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/dist/src/mind/mechanisms/confluence.js

@@ -98,6 +98,30 @@ export async function confluenceJoin(ctx, query, pre) {
     // constraints).  Shard-bound streams are no constraints, and their meets
     // are connective debris (". Sure,", "ngul" — observed).
     const bindsAConstituent = (cover) => 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 = [];
     const rankedCapped = ranked.length > pre.k ? ranked.slice(0, pre.k) : ranked;
     // CONJUNCTIVITY EARLY-EXIT: a conjunctive query's top-ranked anchors

package/dist/src/mind/mechanisms/cover.js

@@ -83,6 +83,8 @@ export async function resolveConnectors(ctx, sites, query) {
     const bridgePair = async (l, r) => {
         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);
@@ -122,6 +124,10 @@ export async function resolveConnectors(ctx, sites, query) {
             // 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, orderedNodes[m].bytes, allowance);
             if (interior !== null)
                 links.set(key, interior);

package/dist/src/mind/mechanisms/recall.js

@@ -194,9 +194,36 @@ export async function recallByResonance(ctx, query, pre) {
         // 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
@@ -265,7 +292,7 @@ export async function recallByResonance(ctx, query, pre) {
         const minVote = consensusFloor(corpusN(ctx));
         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);
             // THE ANCHOR'S OCCUPANT IS NOT THE ASKER'S.  This tier grounds an anchor
@@ -468,6 +495,7 @@ export const recallMechanism = {
                 moves: r.moves,
                 unexplained: r.unexplained,
                 provenance: r.echoed ? "recall-echo" : "recall",
+                used: new Set(),
                 ...(r.complete ? { complete: true } : {}),
             }];
     },

package/dist/src/mind/mind.d.ts

@@ -1,5 +1,6 @@
 import { Vec } from "../vec.js";
 import { Sema, Space } from "../sema.js";
+import type { CorpusResult } from "./corpus.js";
 import { Alphabet } from "../alphabet.js";
 import { Grid } from "../geometry.js";
 import { BoundedMap, type Store } from "../store.js";
@@ -49,10 +50,42 @@ import type { AttentionRead, MindContext, Recognition } from "./types.js";
 export type { AnchorRejectionReason, ClimbConsensusData, ConsensusAnchorTrace, ConsensusReachTrace, ConsensusRegionTrace, CrossRegionTier, JunctionVoteTrace, RegionOutcome, } from "./attention.js";
 export type { AncestorReach, SaturationReason, SaturationStop, } from "./types.js";
 import { type CostReport, Meter } from "../meter.js";
+/** 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;
+}
 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>;
@@ -153,6 +186,10 @@ export declare 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;
+    /** Feed a search refusal into the rationale (see GraphSearchHost). */
+    reportSearch(name: string, parts: ReadonlyArray<Uint8Array>, note: string): void;
     leadsSomewhere(id: number): boolean;
     recogniseSpan(bytes: Uint8Array): {
         sites: ReadonlyArray<Site>;
@@ -167,6 +204,8 @@ export declare 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[];
     chooseNext(node: number): number | undefined;
     constructor(opts?: MindOptions);
     constructor(cfg: MindConfig, store: Store, _fromStore: true);
@@ -249,6 +288,24 @@ export declare class Mind implements MindContext {
      *  as one form, provided the store's canon index is built
      *  ({@link buildCanonIndex}). */
     respondText(input: string, inspectRationale?: InspectRationale): Promise<string>;
+    /** 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;
+    /** 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;
+    /** 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;
     /** Begin a new conversation, optionally restoring from a previously-saved
      *  {@link ConversationState}.  The returned handle is required for
      *  {@link respondTurn} and {@link endConversation}.

package/dist/src/mind/mind.js

@@ -9,8 +9,10 @@
 // Architecture: 4 primitives × 2 patterns = all inference.
 // Implementation split across src/mind/*.ts — this file assembles the Mind class.
 import { makeKeyring, rng, setVecConfig } from "../vec.js";
+import { sampleCorpus, searchCorpus } from "./corpus.js";
 import { Alphabet } from "../alphabet.js";
 import { contentFoldIncremental, reachThreshold, } from "../geometry.js";
+import { keyEnds } from "./canonical.js";
 import { BoundedMap } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
 import { resolveConfig } from "../config.js";
@@ -19,7 +21,7 @@ import { bytesEqual, concat2 } from "../bytes.js";
 import { GraphSearch, } from "./graph-search.js";
 import { Alu } from "../alu/src/index.js";
 import { decodeText, Rationale, } from "./rationale.js";
-import { gistOf, inputBytes, perceive as perceiveImpl, perceiveKey, resolve as resolveImpl, } from "./primitives.js";
+import { canonResolve as canonResolveImpl, gistOf, inputBytes, perceive as perceiveImpl, perceiveKey, resolve as resolveImpl, } from "./primitives.js";
 import { chooseNext, edgeAncestors as edgeAncestorsFn, invalidateStructuralCaches, leadsSomewhere, } from "./traverse.js";
 import { invalidateJunctionCache } from "./junction.js";
 import { follow } from "./match.js";
@@ -33,6 +35,21 @@ import { rItem } from "./trace.js";
 // The work meter is exported from src/index.ts (via src/meter.ts) — the one
 // definition; the Mind only consumes it.
 import { Meter } from "../meter.js";
+/** What the text helper says when the byte layer reports a miss. */
+const CORPUS_NOTE = {
+    "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) {
+    return decodeText(bytes).replace(/\uFFFD+$/, "").replace(/\s+/g, " ").trim();
+}
 // ═══════════════════════════════════════════════════════════════════════════
 // THE MIND
 // ═══════════════════════════════════════════════════════════════════════════
@@ -116,6 +133,14 @@ export class Mind {
      *  `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) {
+        return canonResolveImpl(this, bytes);
+    }
+    /** Feed a search refusal into the rationale (see GraphSearchHost). */
+    reportSearch(name, parts, note) {
+        this.trace?.step(name, parts.map((b) => rItem(b)), [], note);
+    }
     leadsSomewhere(id) {
         return leadsSomewhere(this, id);
     }
@@ -136,6 +161,10 @@ export class Mind {
      *  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, tail) {
+        return keyEnds(this, prefix, tail);
+    }
     chooseNext(node) {
         return chooseNext(this, node, this._edgeGuide);
     }
@@ -411,6 +440,48 @@ export class Mind {
         const r = await this.respond(input, inspectRationale);
         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, limit) {
+        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, from) {
+        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, limit) {
+        const result = this.searchCorpus(new TextEncoder().encode(query), limit);
+        return {
+            query,
+            pairs: result.pairs.map((p) => ({
+                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
      *  {@link ConversationState}.  The returned handle is required for

package/dist/src/mind/pipeline-mechanism.d.ts

@@ -151,6 +151,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. */