@hviana/sema 0.1.7 → 0.1.9

package/src/mind/mechanisms/recall.ts

@@ -13,8 +13,9 @@ import {
 } from "../../geometry.js";
 import type { MindContext } from "../types.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 type { PipelineMechanism, Precomputed } from "../pipeline-mechanism.js";
@@ -81,6 +82,51 @@ export async function recallByResonance(
     }
   }
 
+  // 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: typeof args = [];
+    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);
@@ -99,11 +145,27 @@ export async function recallByResonance(
   // 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: Uint8Array): boolean =>
+    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) {
@@ -116,15 +178,7 @@ export async function recallByResonance(
             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) {
@@ -138,31 +192,11 @@ export async function recallByResonance(
     }
   }
 
-  // 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
@@ -177,18 +211,50 @@ export async function recallByResonance(
   // 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: number, otherLen: number): number =>
     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,
@@ -208,7 +274,6 @@ export async function recallByResonance(
   // 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))
@@ -221,6 +286,16 @@ export async function recallByResonance(
       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,

package/src/mind/mind.ts

@@ -25,6 +25,7 @@ import {
 import { BoundedMap, type Store } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
 import { type MindConfig, resolveConfig } from "../config.js";
+import { type Canon, canonHash, textCanon } from "../canon.js";
 import {
   type CandidateSpan,
   coverSequence,
@@ -160,6 +161,12 @@ export interface MindOptions {
   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;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -182,6 +189,19 @@ export class Mind implements MindContext {
   /** The live rationale tracer for the inference currently in flight, or null. */
   trace: Rationale | null = 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 = null;
+
+  /** Per-response canonical-resolution memo — see {@link MindContext.canonMemo}. */
+  canonMemo: Map<string, number | null> | 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: Canon | false | null = null;
+
   /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
   climbMemo: Map<string, Map<string, AttentionRead>> | null = null;
 
@@ -285,8 +305,10 @@ export class Mind implements MindContext {
         store: optsStore,
         mechanisms: userMechs,
         mechanismFactories: userFacts,
+        canon: optsCanon,
         ...rest
       } = (optsOrCfg ?? {}) as MindOptions;
+      this._canonOpt = optsCanon ?? null;
       this.cfg = resolveConfig(rest as Partial<MindConfig>);
       this.store = optsStore ?? new SQliteStore({
         maxGroup: this.cfg.geometry.maxGroup,
@@ -378,11 +400,24 @@ export class Mind implements MindContext {
   /** 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. */
-  private beginResponse(inspectRationale?: InspectRationale): void {
+  private beginResponse(
+    inspectRationale?: InspectRationale,
+    canon?: Canon | null,
+  ): void {
     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. */
+  private _canonFor(entryDefault: Canon | null): Canon | null {
+    if (this._canonOpt === false) return null;
+    return this._canonOpt ?? entryDefault;
   }
 
   /** Close one response's transient state — every per-response field, incl.
@@ -392,6 +427,8 @@ export class Mind implements MindContext {
     this.climbMemo = null;
     this.recogniseMemo = null;
     this.perceiveMemo = null;
+    this.canon = null;
+    this.canonMemo = null;
     this._edgeGuide = null;
     this._edgeChoice.clear();
   }
@@ -403,8 +440,9 @@ export class Mind implements MindContext {
     queryBytes: Uint8Array,
     inspectRationale?: InspectRationale,
     traceLabel = "respond",
+    canon: Canon | null = null,
   ): Promise<Response> {
-    this.beginResponse(inspectRationale);
+    this.beginResponse(inspectRationale, canon);
     try {
       const top = this.trace?.enter(traceLabel, [
         rItem(queryBytes, "query"),
@@ -434,13 +472,27 @@ export class Mind implements MindContext {
     input: Input,
     inspectRationale?: InspectRationale,
   ): Promise<Response> {
-    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: string,
     inspectRationale?: InspectRationale,
@@ -498,6 +550,52 @@ export class Mind implements MindContext {
     };
   }
 
+  /** 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 {
+    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. */
+  private _growContext(data: ConversationData, turnBytes: Uint8Array): Sema {
+    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
@@ -507,7 +605,13 @@ export 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. */
   async respondTurn(
     conv: Conversation,
     turn: Input,
@@ -517,22 +621,9 @@ export class Mind implements MindContext {
     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.
@@ -547,10 +638,12 @@ export class Mind implements MindContext {
     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"),
       ]);
@@ -570,6 +663,14 @@ export class Mind implements MindContext {
         "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),
@@ -579,17 +680,19 @@ export class Mind implements MindContext {
         state: this.conversationState(conv)!,
       };
     } 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();
@@ -694,6 +797,46 @@ export class Mind implements MindContext {
     );
   }
 
+  // ── 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?: Canon): Promise<number> {
+    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(): Promise<Uint8Array> {

package/src/mind/primitives.ts

@@ -14,6 +14,8 @@ import {
   hilbertBytes,
   stackGrids,
 } from "../geometry.js";
+import { canonHash } from "../canon.js";
+import { bytesEqual } from "../bytes.js";
 import { ALL } from "./types.js";
 import type { Input, MindContext } from "./types.js";
 
@@ -199,7 +201,70 @@ export function foldTree(
  *  unknown. */
 export function resolve(ctx: MindContext, bytes: Uint8Array): number | null {
   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: MindContext,
+  bytes: Uint8Array,
+): number | null {
+  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: number | null): number | null => {
+    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: number | null = 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

package/src/mind/recognition.ts

@@ -8,6 +8,7 @@ import { rItem } from "./trace.js";
 
 import type { MindContext, Recognition, Segment } from "./types.js";
 import {
+  canonResolve,
   foldTree,
   gistOf,
   latin1Key,
@@ -96,6 +97,15 @@ function recogniseImpl(ctx: MindContext, bytes: Uint8Array): Recognition {
       leaves.push({ start, end, bytes: n.leaf ?? new Uint8Array(0), node });
     }
     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.

package/src/mind/types.ts

@@ -144,6 +144,16 @@ export interface MindContext extends GraphSearchHost {
   cfg: MindConfig;
   search: GraphSearch;
   trace: Rationale | null;
+  /** The content canonicalizer for THIS response, or null — injected by the
+   *  modality entry point (respondText passes the text canonicalizer; a
+   *  binary respond passes none).  Resolution uses it as a fallback: when
+   *  the exact content-addressed lookup misses, the span's canonical key is
+   *  probed against the store's canon index (see src/canon.ts).  The core
+   *  never inspects what the equivalence IS. */
+  canon: ((bytes: Uint8Array) => Uint8Array) | null;
+  /** Per-response memo of canonical-fallback resolutions, keyed by the
+   *  span's latin1 content key.  Null outside respond(). */
+  canonMemo: Map<string, number | null> | null;
   /** Memo of the consensus climb — content-keyed (latin1) so results
    *  persist across conversation turns where the same byte spans recur.
    *  Null outside respond(); during respondTurn() the conversation's