@hviana/sema 0.1.7 → 0.1.8

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

@@ -6,8 +6,9 @@
 import { cosine } from "../../vec.js";
 import { consensusFloor, identityBar, reachThreshold, significanceBar, } from "../../geometry.js";
 import { gistOf, read, resolve } from "../primitives.js";
+import { bytesEqual, indexOf } from "../../bytes.js";
 import { corpusN, hubBound } from "../traverse.js";
-import { project, reverseContext } from "../match.js";
+import { follow, project, reverseContext } from "../match.js";
 import { CONCEPT, STEP } from "../graph-search.js";
 import { unexplainedLabel } from "../rationale.js";
 import { rItem, rNode } from "../trace.js";
@@ -43,6 +44,44 @@ export async function recallByResonance(ctx, query, pre) {
                 : "exact self-match — reverse recall to the best-resonating predecessor", nothing, STEP);
         }
     }
+    // 0b. ARGUMENT BINDING (RC8): the query is not itself a stored form, but
+    // it CONTAINS a recognised constituent that is an edge SOURCE — a learnt
+    // pair's left side carried inside a wrapper ("How do you say 'thank you'
+    // in French?").  The wrapper is scaffolding; the argument is the span
+    // that LEADS somewhere, so its continuation — guided by the whole query's
+    // gist — is the answer.  Matching the wrapper while ignoring the argument
+    // (the observed "good morning" template failure) is worse than silence,
+    // so anything short of ONE unambiguous binding falls through: the
+    // constituent bar is the same two-quanta (2W) reading confluence binds
+    // under, nested recognitions collapse to their MAXIMAL span, and two
+    // distinct maximal arguments mean the query asks about neither alone.
+    if (qId === null) {
+        const W2 = 2 * ctx.space.maxGroup;
+        const args = pre.rec.sites.filter((s) => s.end - s.start >= W2 &&
+            s.end - s.start < query.length &&
+            ctx.store.hasNext(s.payload));
+        // Maximal spans by one sorted sweep (starts ascending, ties longest
+        // first): every earlier span starts at or before s, so s is contained
+        // exactly when the running max end already covers it.  O(m log m) — a
+        // long input recognises O(|input|) sites, and a pairwise scan here was
+        // quadratic in the input.
+        args.sort((a, b) => a.start - b.start || b.end - a.end);
+        const maximal = [];
+        let maxEnd = -1;
+        for (const s of args) {
+            if (s.end <= maxEnd)
+                continue;
+            maximal.push(s);
+            maxEnd = s.end;
+        }
+        if (maximal.length === 1) {
+            const arg = maximal[0];
+            const g = await follow(ctx, arg.payload, queryGist);
+            if (g !== null && g.length > 0) {
+                return ground(g, "argument binding — the query's sole edge-source constituent, continuation followed", [[arg.start, arg.end]], STEP);
+            }
+        }
+    }
     const whole = await ctx.store.resonate(queryGist, k);
     if (whole.length === 0) {
         return ground(null, "empty store — nothing to resonate with", [], 0);
@@ -55,9 +94,27 @@ export async function recallByResonance(ctx, query, pre) {
     // into bytes — at most one river window (see {@link identityBar}).  A
     // fixed cosine bar let long queries claim "near-identical" while whole
     // windows — an answer word — differed.
-    if (top.score >= identityBar(ctx.store.D, ctx.space.maxGroup, query.length)) {
+    // A hit RESTATES the query when its bytes are the query's own — exactly,
+    // or under the response's equivalence (a case/width twin).  Restating
+    // hits may only conclude through disciplined reverse recall: voicing
+    // their bytes echoes the query back at itself (never an answer — the
+    // same principle that keeps cast from voicing stored questions), and
+    // projecting them forward is reverse recall's containment failure in the
+    // other direction — "whatever followed these bytes in some document".
+    const qKey = ctx.canon ? ctx.canon(query) : query;
+    const restates = (b) => bytesEqual(b, query) ||
+        (ctx.canon !== null && bytesEqual(ctx.canon(b), qKey));
+    const idBar = identityBar(ctx.store.D, ctx.space.maxGroup, query.length);
+    if (top.score >= idBar) {
         for (const h of whole) {
-            if (h.id === qId || h.score >= 1.0) {
+            // The identity claim is PER HIT, not per tier: hits are ranked
+            // nearest-first, and grounding one below the bar under this tier's
+            // "near-identical" label would launder byte-overlap noise (observed:
+            // "merci" projecting through the unrelated near hit "meraih").
+            if (h.score < idBar)
+                break;
+            const own = read(ctx, h.id);
+            if (h.id === qId || restates(own)) {
                 const rev = ctx.store.prevFirst(h.id, hubBound(ctx));
                 const g = reverseContext(ctx, h.id, queryGist, rev);
                 if (g !== null) {
@@ -65,10 +122,7 @@ export async function recallByResonance(ctx, query, pre) {
                         ? "perfect self-match — reverse recall to the sole predecessor"
                         : "perfect self-match — reverse recall to the best-resonating predecessor", nothing, STEP);
                 }
-                const own = read(ctx, h.id);
-                if (own.length > 0) {
-                    return ground(own, "perfect self-match — the query IS this node", nothing, STEP);
-                }
+                continue;
             }
             const g = await project(ctx, h.id, queryGist);
             if (g) {
@@ -76,25 +130,11 @@ export async function recallByResonance(ctx, query, pre) {
             }
         }
     }
-    // 2. Scaffolding-dominated.
-    if (top.score >= significanceBar(ctx.store.D)) {
-        const N = corpusN(ctx);
-        const minVote = consensusFloor(N);
-        // The committed points of attention ARE the shared climb's roots (same
-        // query, same k, same DF mode) — read them from Precomputed instead of
-        // re-climbing, so even a traced response pays for the climb once.
-        const forest = (await pre.attention()).roots;
-        if (forest.length > 0 && forest[0].vote >= minVote) {
-            const g = await project(ctx, forest[0].anchor, queryGist);
-            if (g) {
-                return ground(g, "scaffolding-dominated query — ground the consensus-climb anchor", [[forest[0].start, forest[0].end]], CONCEPT);
-            }
-        }
-    }
-    // 3. Last resort — gated on the FRACTION OF THE QUERY the grounding
-    // explains, not the raw cosine.  Root gists are unit vectors, but their
-    // magnitudes are recoverable from the byte lengths (‖·‖ = √len under the
-    // linear fold): cos = shared/√(lenQ·lenG), so shared/lenQ = cos·√(lenG/lenQ).
+    // The query-relative grounding fraction, shared by tiers 2–4 — gated on
+    // the FRACTION OF THE QUERY the grounding explains, not the raw cosine.
+    // Root gists are unit vectors, but their magnitudes are recoverable from
+    // the byte lengths (‖·‖ = √len under the linear fold):
+    // cos = shared/√(lenQ·lenG), so shared/lenQ = cos·√(lenG/lenQ).
     // The raw cosine punished honest containment — a query fully inside a
     // longer grounded answer scored √(lenQ/lenG) and was refused — and let a
     // long answer sharing only scaffolding pass; the query-relative fraction
@@ -109,13 +149,38 @@ export async function recallByResonance(ctx, query, pre) {
     // subtract the significance bar (3/√D, §8.3) before converting.  Derived
     // from the existing bars; never tuned.
     const sig = significanceBar(ctx.store.D);
+    const reach = reachThreshold(ctx.space.maxGroup);
     const fracOfQuery = (cos, otherLen) => Math.min(1, Math.max(0, cos - sig) *
         Math.sqrt(otherLen / Math.max(1, query.length)));
+    // 2. Scaffolding-dominated.
+    if (top.score >= sig) {
+        const N = corpusN(ctx);
+        const minVote = consensusFloor(N);
+        // The committed points of attention ARE the shared climb's roots (same
+        // query, same k, same DF mode) — read them from Precomputed instead of
+        // re-climbing, so even a traced response pays for the climb once.
+        const forest = (await pre.attention()).roots;
+        if (forest.length > 0 && forest[0].vote >= minVote) {
+            const g = await project(ctx, forest[0].anchor, queryGist);
+            // The anchor cleared the consensus floor, but the floor prices the
+            // ANCHOR's evidence, not the projection's: a junk attractor can clear
+            // it and project a PIECE OF THE QUERY back at it (the observed
+            // "buenos días in English" → "English" fragment).  A projection that
+            // is a proper byte-subspan of the query restates part of the question
+            // — never an answer (the same principle as `restates` above, extended
+            // to fragments).  Genuine anchor groundings — longer than the query,
+            // or disjoint from it — pass untouched.
+            if (g && !(g.length < query.length && indexOf(query, g, 0) >= 0)) {
+                return ground(g, "scaffolding-dominated query — ground the consensus-climb anchor", [[forest[0].start, forest[0].end]], CONCEPT);
+            }
+        }
+    }
+    // 3. Last resort — the nearest grounded whole-query hit, same gate.
     for (const h of whole) {
         const g = await project(ctx, h.id, queryGist);
         if (g) {
             if (fracOfQuery(cosine(queryGist, gistOf(ctx, g)), g.length) >=
-                reachThreshold(ctx.space.maxGroup)) {
+                reach) {
                 return ground(g, "last resort: the nearest grounded whole-query hit", [], STEP);
             }
         }
@@ -129,7 +194,6 @@ export async function recallByResonance(ctx, query, pre) {
     // anyway to be echoed, so the decision uses their EXACT fold: one river
     // fold of the top hit, measured in the same query-relative,
     // chance-corrected units as the tier above.
-    const reach = reachThreshold(ctx.space.maxGroup);
     const topBytes = read(ctx, top.id);
     const exact = topBytes.length > 0
         ? cosine(queryGist, gistOf(ctx, topBytes))
@@ -137,6 +201,11 @@ export async function recallByResonance(ctx, query, pre) {
     if (fracOfQuery(exact, topBytes.length) < reach) {
         return ground(null, "below reach threshold — nothing in the store relates to this query", [], 0);
     }
+    // Echoing the query's own bytes back at it is not an echo of a RELATED
+    // form — it is the query restated, which answers nothing.
+    if (restates(topBytes)) {
+        return ground(null, "the nearest form IS the query itself — restating it answers nothing", [], 0);
+    }
     // Honest echo.
     return ground(topBytes, "last resort: the nearest resonant form's own bytes (echo, not grounded)", [], 0, true);
 }

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

@@ -4,6 +4,7 @@ import { Alphabet } from "../alphabet.js";
 import { type FoldPyramid, Grid } from "../geometry.js";
 import { BoundedMap, type Store } from "../store.js";
 import { type MindConfig } from "../config.js";
+import { type Canon } from "../canon.js";
 import { GraphSearch, type Leaf, type Site } from "./graph-search.js";
 import type { ComputedSpan, ExtensionHost } from "../extension.js";
 export type { ComputedSpan, ExtensionHost };
@@ -55,6 +56,12 @@ export interface MindOptions {
     mechanisms?: import("./pipeline-mechanism.js").PipelineMechanism[];
     /** Factories that receive the {@link ExtensionHost} and return mechanisms. */
     mechanismFactories?: ((host: import("../extension.js").ExtensionHost) => import("./pipeline-mechanism.js").PipelineMechanism)[];
+    /** Content canonicalizer applied to EVERY response (any modality) for
+     *  equivalence-class resolution — see src/canon.ts.  Text entry points
+     *  ({@link Mind.respondText}, {@link Mind.respondTurnText}) inject the
+     *  Unicode text canonicalizer automatically when this is unset; pass
+     *  `false` to disable canonical resolution everywhere. */
+    canon?: Canon | false;
 }
 export declare class Mind implements MindContext {
     readonly space: Space;
@@ -67,6 +74,16 @@ export declare class Mind implements MindContext {
     readonly mechanisms: import("./pipeline-mechanism.js").PipelineMechanism[];
     /** The live rationale tracer for the inference currently in flight, or null. */
     trace: Rationale | null;
+    /** The content canonicalizer for the response in flight — see
+     *  {@link MindContext.canon}.  Injected per response by the modality entry
+     *  point; null when the response carries no equivalence. */
+    canon: Canon | null;
+    /** Per-response canonical-resolution memo — see {@link MindContext.canonMemo}. */
+    canonMemo: Map<string, number | null> | null;
+    /** The Mind-level canon option: a canonicalizer to use for EVERY response,
+     *  `false` to disable canonical resolution, or null to let each entry
+     *  point decide (text entry points inject {@link textCanon}). */
+    private _canonOpt;
     /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
     climbMemo: Map<string, Map<string, AttentionRead>> | null;
     /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
@@ -130,6 +147,10 @@ export declare class Mind implements MindContext {
      *  memos.  Paired with {@link endResponse}; the ONE place this state is
      *  created, so adding a memo cannot forget its reset. */
     private beginResponse;
+    /** The canonicalizer a response should carry: the Mind-level option when
+     *  set (or none when explicitly disabled), else the entry point's own
+     *  default — text entry points pass {@link textCanon}, binary ones null. */
+    private _canonFor;
     /** Close one response's transient state — every per-response field, incl.
      *  the edge guide/choices `think` sets mid-flight. */
     private endResponse;
@@ -141,7 +162,12 @@ export declare class Mind implements MindContext {
     /** Text view of {@link respond}.  NUL bytes (0x00) are stripped before
      *  decoding — they are structural padding in text answers.  LOSSY for a
      *  binary answer that legitimately contains NULs: use {@link respond} and
-     *  read `bytes` directly for binary/grid modalities. */
+     *  read `bytes` directly for binary/grid modalities.
+     *
+     *  Injects the TEXT canonicalizer (src/canon.ts) so resolution treats
+     *  every character variation of the same text — case, width, whitespace —
+     *  as one form, provided the store's canon index is built
+     *  ({@link buildCanonIndex}). */
     respondText(input: string, inspectRationale?: InspectRationale): Promise<string>;
     /** Begin a new conversation, optionally restoring from a previously-saved
      *  {@link ConversationState}.  The returned handle is required for
@@ -158,6 +184,21 @@ export declare class Mind implements MindContext {
     /** The current serialisable state of an active conversation.  Save this
      *  to resume the conversation later via {@link beginConversation}. */
     conversationState(conv: Conversation): ConversationState | null;
+    /** Append a turn to a conversation's accumulated context WITHOUT
+     *  responding — raw byte append plus a boundary offset, never a
+     *  separator; the fold pyramid advances by O(turn).
+     *
+     *  This is the primitive for turns the Mind should hear but not answer:
+     *  replaying a transcript, feeding the OTHER speaker's line in a
+     *  prediction harness, or restoring context piecewise.  {@link
+     *  respondTurn} = addTurn + think + its own reply appended the same way. */
+    addTurn(conv: Conversation, turn: Input): ConversationState;
+    /** Grow a conversation's accumulated context by one turn's bytes — raw
+     *  append plus a boundary offset, pyramid advanced by O(turn), the grown
+     *  context's tree seeded into the conversation's perceive memo.  The ONE
+     *  place a context grows ({@link addTurn} and {@link respondTurn} both
+     *  come through here), so the append semantics cannot drift. */
+    private _growContext;
     /** Process one turn of a conversation.
      *
      *  `turn` is the raw input for the latest turn — its bytes are appended
@@ -167,7 +208,13 @@ export declare class Mind implements MindContext {
      *
      *  Returns the response AND the updated {@link ConversationState} so the
      *  caller can persist it.  The conversation handle's internal state is
-     *  updated in place — the returned state is a snapshot for storage. */
+     *  updated in place — the returned state is a snapshot for storage.
+     *
+     *  SINGLE FLIGHT: at most one respondTurn may be in flight per Mind.  The
+     *  conversation's memo caches are swapped into the Mind-level per-response
+     *  pointers for the duration of the turn, so a concurrently-running
+     *  respond()/respondTurn() on the SAME Mind would interleave state.
+     *  Different Minds (or sequential awaits, as in every test) are safe. */
     respondTurn(conv: Conversation, turn: Input, inspectRationale?: InspectRationale): Promise<{
         response: Response;
         state: ConversationState;
@@ -205,6 +252,21 @@ export declare class Mind implements MindContext {
      *                     (default 2 — structural bridges)
      *  @returns number of nodes added to the content index */
     repairContentIndex(minParents?: number): Promise<number>;
+    /** Build (or incrementally refresh) the store's canonical-form index: for
+     *  every content-bearing node, record the hash of its CANONICAL key so
+     *  resolution can find stored forms across surface variation (case, width,
+     *  whitespace — whatever `canon` equates; see src/canon.ts).
+     *
+     *  Incremental and idempotent: the last indexed node id is remembered in
+     *  store meta (`canon.upto`), so a refresh after further training scans
+     *  only the new rows.  Run once after training, and again after ingests —
+     *  the same operational shape as {@link repairContentIndex}.
+     *
+     *  @param canon  the canonicalizer to index under — MUST be the same one
+     *                queries will carry (text queries carry {@link textCanon}
+     *                unless the Mind was constructed with its own)
+     *  @returns number of index rows added */
+    buildCanonIndex(canon?: Canon): Promise<number>;
     save(): Promise<Uint8Array>;
     static load(snapshot: Uint8Array, store: Store): Promise<Mind>;
     static loadFromStore(store: Store): Promise<Mind>;

package/dist/src/mind/mind.js

@@ -14,6 +14,7 @@ import { bytesToTreePyramid, reachThreshold, } from "../geometry.js";
 import { BoundedMap } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
 import { resolveConfig } from "../config.js";
+import { canonHash, textCanon } from "../canon.js";
 import { bytesEqual, concat2 } from "../bytes.js";
 import { GraphSearch, } from "./graph-search.js";
 import { Alu } from "../alu/src/index.js";
@@ -42,6 +43,16 @@ export class Mind {
     mechanisms = [];
     /** The live rationale tracer for the inference currently in flight, or null. */
     trace = null;
+    /** The content canonicalizer for the response in flight — see
+     *  {@link MindContext.canon}.  Injected per response by the modality entry
+     *  point; null when the response carries no equivalence. */
+    canon = null;
+    /** Per-response canonical-resolution memo — see {@link MindContext.canonMemo}. */
+    canonMemo = null;
+    /** The Mind-level canon option: a canonicalizer to use for EVERY response,
+     *  `false` to disable canonical resolution, or null to let each entry
+     *  point decide (text entry points inject {@link textCanon}). */
+    _canonOpt = null;
     /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
     climbMemo = null;
     /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
@@ -104,7 +115,8 @@ export class Mind {
             this.store = storeArg;
         }
         else {
-            const { store: optsStore, mechanisms: userMechs, mechanismFactories: userFacts, ...rest } = (optsOrCfg ?? {});
+            const { store: optsStore, mechanisms: userMechs, mechanismFactories: userFacts, canon: optsCanon, ...rest } = (optsOrCfg ?? {});
+            this._canonOpt = optsCanon ?? null;
             this.cfg = resolveConfig(rest);
             this.store = optsStore ?? new SQliteStore({
                 maxGroup: this.cfg.geometry.maxGroup,
@@ -166,11 +178,21 @@ export class Mind {
     /** Open one response's transient state — the tracer and the per-response
      *  memos.  Paired with {@link endResponse}; the ONE place this state is
      *  created, so adding a memo cannot forget its reset. */
-    beginResponse(inspectRationale) {
+    beginResponse(inspectRationale, canon) {
         this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
         this.climbMemo = new Map();
         this.recogniseMemo = new Map();
         this.perceiveMemo = new Map();
+        this.canon = canon ?? null;
+        this.canonMemo = canon ? new Map() : null;
+    }
+    /** The canonicalizer a response should carry: the Mind-level option when
+     *  set (or none when explicitly disabled), else the entry point's own
+     *  default — text entry points pass {@link textCanon}, binary ones null. */
+    _canonFor(entryDefault) {
+        if (this._canonOpt === false)
+            return null;
+        return this._canonOpt ?? entryDefault;
     }
     /** Close one response's transient state — every per-response field, incl.
      *  the edge guide/choices `think` sets mid-flight. */
@@ -179,14 +201,16 @@ export class Mind {
         this.climbMemo = null;
         this.recogniseMemo = null;
         this.perceiveMemo = null;
+        this.canon = null;
+        this.canonMemo = null;
         this._edgeGuide = null;
         this._edgeChoice.clear();
     }
     /** Shared response core — the one path from bytes to voiced answer.
      *  `respond` calls this directly; `respondTurn` has its own path
      *  with conversation-persistent memos and incremental perception. */
-    async _respondImpl(queryBytes, inspectRationale, traceLabel = "respond") {
-        this.beginResponse(inspectRationale);
+    async _respondImpl(queryBytes, inspectRationale, traceLabel = "respond", canon = null) {
+        this.beginResponse(inspectRationale, canon);
         try {
             const top = this.trace?.enter(traceLabel, [
                 rItem(queryBytes, "query"),
@@ -209,12 +233,21 @@ export class Mind {
         }
     }
     async respond(input, inspectRationale) {
-        return this._respondImpl(inputBytes(this, input), inspectRationale);
+        // A STRING input is text by nature: it carries the text equivalence even
+        // through the generic entry point.  Raw bytes / grids carry only the
+        // Mind-level canon option, if any.
+        const canon = this._canonFor(typeof input === "string" ? textCanon : null);
+        return this._respondImpl(inputBytes(this, input), inspectRationale, "respond", canon);
     }
     /** Text view of {@link respond}.  NUL bytes (0x00) are stripped before
      *  decoding — they are structural padding in text answers.  LOSSY for a
      *  binary answer that legitimately contains NULs: use {@link respond} and
-     *  read `bytes` directly for binary/grid modalities. */
+     *  read `bytes` directly for binary/grid modalities.
+     *
+     *  Injects the TEXT canonicalizer (src/canon.ts) so resolution treats
+     *  every character variation of the same text — case, width, whitespace —
+     *  as one form, provided the store's canon index is built
+     *  ({@link buildCanonIndex}). */
     async respondText(input, inspectRationale) {
         const r = await this.respond(input, inspectRationale);
         return decodeText(r.bytes);
@@ -261,6 +294,47 @@ export class Mind {
             boundaries: [...data.boundaries],
         };
     }
+    /** Append a turn to a conversation's accumulated context WITHOUT
+     *  responding — raw byte append plus a boundary offset, never a
+     *  separator; the fold pyramid advances by O(turn).
+     *
+     *  This is the primitive for turns the Mind should hear but not answer:
+     *  replaying a transcript, feeding the OTHER speaker's line in a
+     *  prediction harness, or restoring context piecewise.  {@link
+     *  respondTurn} = addTurn + think + its own reply appended the same way. */
+    addTurn(conv, turn) {
+        const data = this._conversations.get(conv.id);
+        if (!data)
+            throw new Error(`Conversation ${conv.id} not found`);
+        const turnBytes = inputBytes(this, turn);
+        this._growContext(data, turnBytes);
+        return this.conversationState(conv);
+    }
+    /** Grow a conversation's accumulated context by one turn's bytes — raw
+     *  append plus a boundary offset, pyramid advanced by O(turn), the grown
+     *  context's tree seeded into the conversation's perceive memo.  The ONE
+     *  place a context grows ({@link addTurn} and {@link respondTurn} both
+     *  come through here), so the append semantics cannot drift. */
+    _growContext(data, turnBytes) {
+        const prevLen = data.pyramid.bytes;
+        // An empty turn neither grows the context nor marks a boundary —
+        // boundaries are documented strictly increasing, and a zero-length
+        // "turn" is no turn.  The pyramid's zero-growth shortcut makes the
+        // refold below O(1), so the existing tree is returned unchanged.
+        const grow = turnBytes.length > 0;
+        const grown = !grow
+            ? data.bytes
+            : prevLen > 0
+                ? concat2(data.bytes, turnBytes)
+                : turnBytes;
+        if (grow && prevLen > 0)
+            data.boundaries.push(prevLen);
+        const { tree, pyramid } = bytesToTreePyramid(this.space, this.alphabet, grown, data.pyramid);
+        data.pyramid = pyramid;
+        data.bytes = grown;
+        data.perceiveMemo.set(latin1Key(grown), tree);
+        return tree;
+    }
     /** Process one turn of a conversation.
      *
      *  `turn` is the raw input for the latest turn — its bytes are appended
@@ -270,21 +344,21 @@ export class Mind {
      *
      *  Returns the response AND the updated {@link ConversationState} so the
      *  caller can persist it.  The conversation handle's internal state is
-     *  updated in place — the returned state is a snapshot for storage. */
+     *  updated in place — the returned state is a snapshot for storage.
+     *
+     *  SINGLE FLIGHT: at most one respondTurn may be in flight per Mind.  The
+     *  conversation's memo caches are swapped into the Mind-level per-response
+     *  pointers for the duration of the turn, so a concurrently-running
+     *  respond()/respondTurn() on the SAME Mind would interleave state.
+     *  Different Minds (or sequential awaits, as in every test) are safe. */
     async respondTurn(conv, turn, inspectRationale) {
         const data = this._conversations.get(conv.id);
         if (!data)
             throw new Error(`Conversation ${conv.id} not found`);
         const turnBytes = inputBytes(this, turn);
-        const prevLen = data.pyramid.bytes;
-        const prevBytes = data.bytes;
-        const newContext = prevLen > 0 ? concat2(prevBytes, turnBytes) : turnBytes;
-        data.bytes = newContext;
-        if (prevLen > 0)
-            data.boundaries.push(prevLen);
         // Incremental perception — O(turn) instead of O(context).
-        const { tree, pyramid } = bytesToTreePyramid(this.space, this.alphabet, newContext, data.pyramid);
-        data.pyramid = pyramid;
+        const tree = this._growContext(data, turnBytes);
+        const newContext = data.bytes;
         // Swap in the conversation's persistent state so the inference
         // pipeline does not re-process the prefix from scratch.
         //   perceiveMemo / recogniseMemo / climbMemo — content-keyed;
@@ -298,8 +372,11 @@ export class Mind {
         this.climbMemo = data.climbMemo;
         this._resolvedSubtrees = data.resolvedSubtrees;
         this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
+        // A string turn is text by nature — carry the text equivalence, same as
+        // respond() (see _canonFor).
+        this.canon = this._canonFor(typeof turn === "string" ? textCanon : null);
+        this.canonMemo = this.canon ? new Map() : null;
         try {
-            this.perceiveMemo.set(latin1Key(newContext), tree);
             const top = this.trace?.enter("respondTurn", [
                 rItem(newContext, "query"),
             ]);
@@ -313,6 +390,14 @@ export class Mind {
             }
             const voiced = await articulate(this, thought.bytes, newContext);
             top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
+            // The REPLY joins the accumulated context the same way a turn does
+            // ({@link addTurn}): raw byte append plus a boundary offset — never a
+            // separator.  A conversation's context is the full exchange, exactly
+            // the cumulative continuous shape multi-turn training deposits, so a
+            // later turn can refer to what was ANSWERED ("which of those two…"),
+            // not only to what was asked.
+            if (voiced.length > 0)
+                this.addTurn(conv, voiced);
             return {
                 response: {
                     v: gistOf(this, voiced),
@@ -323,17 +408,19 @@ export class Mind {
             };
         }
         finally {
-            // Save back to the conversation for the next turn.
-            data.perceiveMemo = this.perceiveMemo;
-            data.recogniseMemo = this.recogniseMemo;
-            data.climbMemo = this.climbMemo;
-            data.resolvedSubtrees = this._resolvedSubtrees;
-            // Clear Mind references — non-conversation respond() calls get
-            // fresh per-response memos.
+            // No save-back: the conversation's memo MAPS were mutated in place —
+            // `data.*` still points at them.  Re-assigning from the Mind-level
+            // pointers here was a no-op in the single-flight case and, under a
+            // concurrently-started respond() (which swaps its own fresh maps into
+            // those pointers), would inject a FOREIGN response's memos into this
+            // conversation.  Clear Mind references — non-conversation respond()
+            // calls get fresh per-response memos.
             this.trace = null;
             this.perceiveMemo = null;
             this.recogniseMemo = null;
             this.climbMemo = null;
+            this.canon = null;
+            this.canonMemo = null;
             this._resolvedSubtrees = null;
             this._edgeGuide = null;
             this._edgeChoice.clear();
@@ -414,6 +501,48 @@ export class Mind {
             return gistOf(this, bytes);
         }, minParents);
     }
+    // ── Canonical-form index ───────────────────────────────────────────────
+    /** Build (or incrementally refresh) the store's canonical-form index: for
+     *  every content-bearing node, record the hash of its CANONICAL key so
+     *  resolution can find stored forms across surface variation (case, width,
+     *  whitespace — whatever `canon` equates; see src/canon.ts).
+     *
+     *  Incremental and idempotent: the last indexed node id is remembered in
+     *  store meta (`canon.upto`), so a refresh after further training scans
+     *  only the new rows.  Run once after training, and again after ingests —
+     *  the same operational shape as {@link repairContentIndex}.
+     *
+     *  @param canon  the canonicalizer to index under — MUST be the same one
+     *                queries will carry (text queries carry {@link textCanon}
+     *                unless the Mind was constructed with its own)
+     *  @returns number of index rows added */
+    async buildCanonIndex(canon) {
+        const c = canon ?? this._canonFor(textCanon);
+        const store = this.store;
+        if (c === null || !store.canonAdd || !store.eachContent)
+            return 0;
+        const from = Number(await store.getMeta("canon.upto") ?? 0);
+        let added = 0;
+        let maxId = from - 1;
+        store.eachContent((id, bytes) => {
+            if (id > maxId)
+                maxId = id;
+            const key = c(bytes);
+            if (key.length === 0)
+                return;
+            // Only index content whose canonical key DIFFERS from its raw bytes —
+            // an already-canonical span is found by the exact lookup (and by the
+            // fallback's own exact probe of the canonical bytes), so indexing it
+            // would only add rows.
+            if (bytesEqual(key, bytes))
+                return;
+            store.canonAdd(canonHash(key), id);
+            added++;
+        }, from);
+        await store.setMeta("canon.upto", String(maxId + 1));
+        store.commit();
+        return added;
+    }
     // ── Persistence ──────────────────────────────────────────────────────────
     async save() {
         const meta = new TextEncoder().encode(JSON.stringify(this.cfg));

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

@@ -41,6 +41,15 @@ export declare function foldTree(ctx: MindContext, n: Sema, start: number, visit
  *  training did — and recover its root bottom-up.  Returns null if any part is
  *  unknown. */
 export declare function resolve(ctx: MindContext, bytes: Uint8Array): number | null;
+/** Equivalence-class resolution: when the exact content-addressed lookup
+ *  misses, find a stored node whose CANONICAL key equals the span's — the
+ *  store's canon index proposes candidates by key hash, and each is verified
+ *  by re-canonicalizing its bytes (hash-then-verify, like every content
+ *  lookup).  Among verified candidates, one that leads somewhere (has a
+ *  continuation edge) is preferred; ties break to the lowest id — a corpus
+ *  property, not a seed property.  Null when the response carries no
+ *  canonicalizer, the store has no canon index, or nothing verifies. */
+export declare function canonResolve(ctx: MindContext, bytes: Uint8Array): number | null;
 /** Walk a perceived tree in POST-ORDER with byte offsets — children before
  *  their parent, `visit(node, start, end)` for every node including leaves.
  *  Returns the byte end.  The one shared traversal the offset-carrying tree