@hviana/sema 0.1.6 → 0.1.8

package/dist/src/mind/mind.js

@@ -10,15 +10,16 @@
 // Implementation split across src/mind/*.ts — this file assembles the Mind class.
 import { makeKeyring, rng, setVecConfig } from "../vec.js";
 import { Alphabet } from "../alphabet.js";
-import { reachThreshold, } from "../geometry.js";
+import { bytesToTreePyramid, reachThreshold, } from "../geometry.js";
 import { BoundedMap } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
 import { resolveConfig } from "../config.js";
-import { bytesEqual } from "../bytes.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";
 import { decodeText, Rationale, } from "./rationale.js";
-import { gistOf, inputBytes, perceive as perceiveImpl, resolve as resolveImpl, } from "./primitives.js";
+import { gistOf, inputBytes, latin1Key, perceive as perceiveImpl, resolve as resolveImpl, } from "./primitives.js";
 import { chooseNext, edgeAncestors as edgeAncestorsFn } from "./traverse.js";
 import { follow } from "./match.js";
 import { recognise, segment } from "./recognition.js";
@@ -42,16 +43,24 @@ export class Mind {
     mechanisms = [];
     /** The live rationale tracer for the inference currently in flight, or null. */
     trace = null;
-    /** Per-response memo of the consensus climb.  NOTE: this memo and
-     *  {@link recogniseMemo} are BYPASSED while a rationale trace is attached
-     *  (every mechanism must emit its own steps), so a traced respond re-pays
-     *  up to four consensus climbs plus repeat recognitions — that is where the
-     *  traced-vs-untraced latency multiple comes from, by design. */
+    /** 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;
-    /** Per-response memo of recognise() — see {@link MindContext.recogniseMemo}. */
+    /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
     recogniseMemo = null;
-    /** Per-response memo of perceive() — see {@link MindContext.perceiveMemo}. */
+    /** Memo of perceive() — content-keyed.  See {@link MindContext.perceiveMemo}. */
     perceiveMemo = null;
+    /** Subtree-resolution cache.  See {@link MindContext._resolvedSubtrees}. */
+    _resolvedSubtrees = null;
     /** The perceived gist of the query currently being answered.  Set by `think`
      *  before the graph search runs; `chooseNext` consults it as a gate (a null
      *  guide means no query is in flight, so structural walkers keep plain
@@ -75,6 +84,9 @@ export class Mind {
     _depositTrees = new BoundedMap(8);
     _depositLens = new Set();
     _internIds = new WeakMap();
+    // ── Conversation state ──────────────────────────────────────────────────
+    _nextConvId = 1;
+    _conversations = new Map();
     // ── GraphSearchHost implementation ─────────────────────────────────────
     /** Canonical node id of a byte span.  Required by GraphSearchHost & MindContext. */
     resolve(bytes) {
@@ -103,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,
@@ -165,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 WeakMap();
-        this.recogniseMemo = new WeakMap();
+        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. */
@@ -178,22 +201,26 @@ export class Mind {
         this.climbMemo = null;
         this.recogniseMemo = null;
         this.perceiveMemo = null;
+        this.canon = null;
+        this.canonMemo = null;
         this._edgeGuide = null;
         this._edgeChoice.clear();
     }
-    async respond(input, inspectRationale) {
-        this.beginResponse(inspectRationale);
+    /** 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", canon = null) {
+        this.beginResponse(inspectRationale, canon);
         try {
-            const inBytes = inputBytes(this, input);
-            const top = this.trace?.enter("respond", [
-                rItem(inBytes, "query"),
+            const top = this.trace?.enter(traceLabel, [
+                rItem(queryBytes, "query"),
             ]);
-            const thought = await think(this, inBytes, this.mechanisms);
+            const thought = await think(this, queryBytes, this.mechanisms);
             if (thought === null) {
                 top?.done([], "nothing to perceive or an empty store — no answer");
                 return { v: null, bytes: new Uint8Array(0) };
             }
-            const voiced = await articulate(this, thought.bytes, inBytes);
+            const voiced = await articulate(this, thought.bytes, queryBytes);
             top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
             return {
                 v: gistOf(this, voiced),
@@ -205,14 +232,207 @@ export class Mind {
             this.endResponse();
         }
     }
+    async respond(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);
     }
+    // ── Conversation API ────────────────────────────────────────────────────
+    /** Begin a new conversation, optionally restoring from a previously-saved
+     *  {@link ConversationState}.  The returned handle is required for
+     *  {@link respondTurn} and {@link endConversation}.
+     *
+     *  Conversations are independent — a Mind can manage several concurrently.
+     *  Each tracks the fold pyramid (accumulated internal processing) and
+     *  turn-boundary offsets; the geometry never inspects content to guess
+     *  where one turn ends and the next begins. */
+    beginConversation(state) {
+        const id = this._nextConvId++;
+        // Build the initial pyramid: from scratch for a new conversation,
+        // or from the saved context bytes when restoring.
+        const initBytes = state?.context ?? new Uint8Array(0);
+        const { pyramid } = bytesToTreePyramid(this.space, this.alphabet, initBytes);
+        this._conversations.set(id, {
+            pyramid,
+            bytes: initBytes,
+            boundaries: state?.boundaries ? [...state.boundaries] : [],
+            perceiveMemo: new Map(),
+            recogniseMemo: new Map(),
+            climbMemo: new Map(),
+            resolvedSubtrees: new WeakMap(),
+        });
+        return { id };
+    }
+    /** End a conversation, releasing its internal resources (accumulated
+     *  context, boundary offsets, and the fold-pyramid cache).  Idempotent. */
+    endConversation(conv) {
+        this._conversations.delete(conv.id);
+    }
+    /** The current serialisable state of an active conversation.  Save this
+     *  to resume the conversation later via {@link beginConversation}. */
+    conversationState(conv) {
+        const data = this._conversations.get(conv.id);
+        if (!data)
+            return null;
+        return {
+            context: data.bytes,
+            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
+     *  to the accumulated context directly (raw concatenation).  The Mind
+     *  tracks the byte offset where each turn ends; no separator is ever
+     *  inserted or inspected.
+     *
+     *  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.
+     *
+     *  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);
+        // Incremental perception — O(turn) instead of O(context).
+        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;
+        //     the prefix's results from the previous turn are found by
+        //     the current turn's sub-span calls.
+        //   _resolvedSubtrees — Sema-node-keyed; when the pyramid reuses
+        //     prefix subtrees (identical objects), foldTree returns their
+        //     ids immediately — O(suffix) instead of O(context).
+        this.perceiveMemo = data.perceiveMemo;
+        this.recogniseMemo = data.recogniseMemo;
+        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 {
+            const top = this.trace?.enter("respondTurn", [
+                rItem(newContext, "query"),
+            ]);
+            const thought = await think(this, newContext, this.mechanisms);
+            if (thought === null) {
+                top?.done([], "nothing to perceive or an empty store — no answer");
+                return {
+                    response: { v: null, bytes: new Uint8Array(0) },
+                    state: this.conversationState(conv),
+                };
+            }
+            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),
+                    bytes: voiced,
+                    provenance: thought.provenance,
+                },
+                state: this.conversationState(conv),
+            };
+        }
+        finally {
+            // 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();
+        }
+    }
+    /** Text view of {@link respondTurn}.  See {@link respondText} for the
+     *  NUL-stripping caveat.  For binary or grid turns use {@link respondTurn}
+     *  directly — this is a text-only convenience, like {@link respondText}. */
+    async respondTurnText(conv, turn, inspectRationale) {
+        const { response, state } = await this.respondTurn(conv, turn, inspectRationale);
+        return { response: decodeText(response.bytes), state };
+    }
     async embedding(input) {
         return (await this.respond(input)).v;
     }
@@ -281,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

@@ -1,9 +1,20 @@
 import { Vec } from "../vec.js";
 import { Sema } from "../sema.js";
 import type { Input, MindContext } from "./types.js";
+/** The content key of a byte span — one latin1 char per byte, an exact,
+ *  collision-free encoding.  Spans on the perception path are query-scale
+ *  (windows, regions, candidate spans), so key construction is far cheaper
+ *  than the river fold it deduplicates. */
+export declare function latin1Key(bytes: Uint8Array): string;
 /** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree. */
-export declare function perceive(ctx: MindContext, input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null): Sema;
+ *  Deterministic — identical bytes always produce an identical tree.
+ *
+ *  `boundaries` is an optional sorted list of proper byte offsets where the
+ *  fold must split so that each prefix segment folds identically to how it
+ *  folded when it was learned (§10.3 stable-prefix contract).  Only the
+ *  CALLER — who assembled the multi-turn context — knows where those
+ *  boundaries are; the geometry never guesses them from the bytes. */
+export declare function perceive(ctx: MindContext, input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null, boundaries?: readonly number[]): Sema;
 /** The DEPOSIT-shaped perceive: the PLAIN fold (bit-identical to inference
  *  perception — that structural train/inference agreement is load-bearing
  *  for exact recall), computed INCREMENTALLY via the fold's level pyramid
@@ -30,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

package/dist/src/mind/primitives.js

@@ -3,13 +3,15 @@
 //   Address  — bytes → node   (perceive, foldTree, resolve)
 //   Read     — node → bytes   (read)
 import { bytesToTree, bytesToTreePyramid, gridToTree, hilbertBytes, stackGrids, } from "../geometry.js";
+import { canonHash } from "../canon.js";
+import { bytesEqual } from "../bytes.js";
 import { ALL } from "./types.js";
 // ── Address: bytes → node ──────────────────────────────────────────────
 /** The content key of a byte span — one latin1 char per byte, an exact,
  *  collision-free encoding.  Spans on the perception path are query-scale
  *  (windows, regions, candidate spans), so key construction is far cheaper
  *  than the river fold it deduplicates. */
-function latin1Key(bytes) {
+export function latin1Key(bytes) {
     // Batched String.fromCharCode — avoids the O(n²) cost of repeated += on
     // potentially-large query spans, and stays well under the ~65536 arg limit.
     const n = bytes.length;
@@ -20,8 +22,14 @@ function latin1Key(bytes) {
     return s;
 }
 /** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree. */
-export function perceive(ctx, input, leafAt, lookup) {
+ *  Deterministic — identical bytes always produce an identical tree.
+ *
+ *  `boundaries` is an optional sorted list of proper byte offsets where the
+ *  fold must split so that each prefix segment folds identically to how it
+ *  folded when it was learned (§10.3 stable-prefix contract).  Only the
+ *  CALLER — who assembled the multi-turn context — knows where those
+ *  boundaries are; the geometry never guesses them from the bytes. */
+export function perceive(ctx, input, leafAt, lookup, boundaries) {
     if (typeof input === "string" || input instanceof Uint8Array) {
         const bytes = typeof input === "string"
             ? new TextEncoder().encode(input)
@@ -37,11 +45,11 @@ export function perceive(ctx, input, leafAt, lookup) {
                 const hit = memo.get(key);
                 if (hit !== undefined)
                     return hit;
-                const tree = bytesToTree(ctx.space, ctx.alphabet, bytes);
+                const tree = bytesToTree(ctx.space, ctx.alphabet, bytes, undefined, undefined, boundaries);
                 memo.set(key, tree);
                 return tree;
             }
-            return bytesToTree(ctx.space, ctx.alphabet, bytes);
+            return bytesToTree(ctx.space, ctx.alphabet, bytes, undefined, undefined, boundaries);
         }
         return bytesToTree(ctx.space, ctx.alphabet, bytes, leafAt, lookup);
     }
@@ -105,11 +113,24 @@ export function gistOf(ctx, bytes) {
  *  node with its byte span and resolved id.  Returns the node's byte end and
  *  resolved id. */
 export function foldTree(ctx, n, start, visit) {
+    // Fast path: subtree already resolved (from a previous conversation turn
+    // or an earlier recognition pass).  The pyramid reuses prefix subtrees as
+    // identical Sema objects, so this cache turns foldTree into O(suffix)
+    // instead of O(context) for multi-turn recognition.
+    const cached = ctx._resolvedSubtrees?.get(n);
+    if (cached !== undefined) {
+        const end = start + cached.len;
+        visit?.(n, start, end, cached.id);
+        return { end, node: cached.id };
+    }
     if (n.kids === null) {
         const b = n.leaf ?? new Uint8Array(0);
         const end = start + b.length;
         const node = ctx.store.findLeaf(b);
         visit?.(n, start, end, node);
+        if (node !== null && ctx._resolvedSubtrees) {
+            ctx._resolvedSubtrees.set(n, { id: node, len: b.length });
+        }
         return { end, node };
     }
     let pos = start;
@@ -125,6 +146,9 @@ export function foldTree(ctx, n, start, visit) {
     }
     const node = known ? ctx.store.findBranch(kids) : null;
     visit?.(n, start, pos, node);
+    if (node !== null && ctx._resolvedSubtrees) {
+        ctx._resolvedSubtrees.set(n, { id: node, len: pos - start });
+    }
     return { end: pos, node };
 }
 /** The canonical node id of a byte span: perceive it in isolation — the way
@@ -133,7 +157,72 @@ export function foldTree(ctx, n, start, visit) {
 export function resolve(ctx, bytes) {
     if (bytes.length === 0)
         return null;
-    return foldTree(ctx, perceive(ctx, bytes), 0).node;
+    const exact = foldTree(ctx, perceive(ctx, bytes), 0).node;
+    if (exact !== null)
+        return exact;
+    return canonResolve(ctx, bytes);
+}
+/** 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 function canonResolve(ctx, bytes) {
+    const canon = ctx.canon;
+    const store = ctx.store;
+    if (canon === null || !store.canonFind)
+        return null;
+    if (bytes.length < 2)
+        return null;
+    const memo = ctx.canonMemo;
+    const memoKey = memo ? latin1Key(bytes) : "";
+    if (memo) {
+        const hit = memo.get(memoKey);
+        if (hit !== undefined)
+            return hit;
+    }
+    const set = (v) => {
+        memo?.set(memoKey, v);
+        return v;
+    };
+    const key = canon(bytes);
+    if (key.length === 0)
+        return set(null);
+    // A stored form that IS canonical is not in the index (buildCanonIndex
+    // skips identity rows) — the exact content-addressed lookup of the
+    // canonical bytes finds it directly.
+    if (key.length !== bytes.length || !bytesEqual(key, bytes)) {
+        const direct = foldTree(ctx, perceive(ctx, key), 0).node;
+        if (direct !== null)
+            return set(direct);
+    }
+    const candidates = store.canonFind(canonHash(key));
+    if (candidates.length === 0)
+        return set(null);
+    let best = null;
+    let bestLeads = false;
+    for (const id of candidates) {
+        const bytesOf = read(ctx, id);
+        const stored = canon(bytesOf);
+        if (stored.length !== key.length || !bytesEqual(stored, key))
+            continue;
+        // The index stores FLAT content twins; the id the exact path would have
+        // resolved for these bytes is their FOLD — the deposit-shaped node that
+        // carries the edges and halos.  Re-folding the candidate's bytes lands
+        // on exactly the node the canonical-case query would have found.
+        const folded = foldTree(ctx, perceive(ctx, bytesOf), 0).node;
+        const use = folded ?? id;
+        const leads = store.hasNext(use) || store.haloMass(use) > 0;
+        if (best === null || (leads && !bestLeads) ||
+            (leads === bestLeads && use < best)) {
+            best = use;
+            bestLeads = leads;
+        }
+    }
+    return set(best);
 }
 /** Walk a perceived tree in POST-ORDER with byte offsets — children before
  *  their parent, `visit(node, start, end)` for every node including leaves.

package/dist/src/mind/recognition.js

@@ -5,8 +5,8 @@
 //               that leads somewhere (has a continuation edge or a halo).
 //   segment   — leaf-parent segmentation using the geometry's own groupings.
 import { rItem } from "./trace.js";
-import { foldTree, gistOf, perceive, resolve } from "./primitives.js";
-import { leadsSomewhere } from "./traverse.js";
+import { canonResolve, foldTree, gistOf, latin1Key, perceive, resolve, } from "./primitives.js";
+import { atomIsHub, corpusN, leadsSomewhere } from "./traverse.js";
 import { chainReach, leafIdAt } from "./canonical.js";
 import { isChunk } from "../sema.js";
 /** Decompose a byte stream into every stored form that leads somewhere
@@ -22,16 +22,16 @@ import { isChunk } from "../sema.js";
  *
  *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus. */
 export function recognise(ctx, bytes) {
-    // Per-response memo (see MindContext.recogniseMemo): think, articulate and
-    // the pre-consume pass all recognise the same byte objects; each repeat is
-    // O(n·maxGroup²) store probes.  Skipped while tracing so every call still
-    // emits its rationale step.
+    // Content-keyed memo — works for both single-turn respond() and multi-turn
+    // respondTurn() (where the map persists across calls).  Skipped while
+    // tracing so every call still emits its rationale step.
     if (ctx.recogniseMemo && !ctx.trace) {
-        const hit = ctx.recogniseMemo.get(bytes);
+        const key = latin1Key(bytes);
+        const hit = ctx.recogniseMemo.get(key);
         if (hit !== undefined)
             return hit;
         const fresh = recogniseImpl(ctx, bytes);
-        ctx.recogniseMemo.set(bytes, fresh);
+        ctx.recogniseMemo.set(key, fresh);
         return fresh;
     }
     return recogniseImpl(ctx, bytes);
@@ -59,7 +59,20 @@ function recogniseImpl(ctx, bytes) {
         }
         return id;
     };
+    // Byte atoms (implicit negative-id single-byte leaves) are admitted as
+    // recognised sites only while atoms can still DISCRIMINATE at this corpus
+    // scale (see {@link atomIsHub}).  On a small store a single-letter fact
+    // ("a" → "A") is genuine learnt content and its site is essential; on a
+    // large one every letter of every query would otherwise become a
+    // "recognised form" — the bridge then finds junction connectors between
+    // bare letters, cover follows edges hanging off them, and pure noise
+    // ("qq8f3kz9…") grounds to an arbitrary learnt sentence instead of
+    // silence.  Atoms stay available as leaves (PASS-carried literals) and
+    // through exact tier-0 resolution regardless.
+    const atomsAreHubs = atomIsHub(ctx, corpusN(ctx));
     const emit = (start, end, id) => {
+        if (id < 0 && atomsAreHubs)
+            return;
         if (leadsSomewhere(ctx, id)) {
             sites.push({ start, end, payload: id });
         }
@@ -73,6 +86,16 @@ function recogniseImpl(ctx, bytes) {
         }
         if (node !== null)
             emit(start, end, node);
+        // Canonical fallback: a subtree whose exact content-addressed lookup
+        // missed may still be a stored form under the response's equivalence
+        // (case, width, whitespace — whatever the injected canonicalizer says).
+        // O(subtree bytes) per miss, memoised per response; a no-op when no
+        // canonicalizer was injected or the store has no canon index.
+        else if (end - start >= 2) {
+            const cid = canonResolve(ctx, bytes.subarray(start, end));
+            if (cid !== null)
+                emit(start, end, cid);
+        }
         if (isChunk(n)) {
             starts.add(start);
             // Try every sub-span within this leaf-parent.