@hviana/sema 0.1.7 → 0.1.8

package/dist/src/mind/primitives.js

@@ -3,6 +3,8 @@
 //   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,
@@ -155,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,7 +5,7 @@
 //               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, latin1Key, perceive, resolve, } from "./primitives.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";
@@ -86,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.

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

@@ -105,6 +105,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

package/dist/src/store-sqlite.d.ts

@@ -43,6 +43,10 @@ export declare class SQliteStore extends AbstractStore implements Store {
     private _selPrev;
     private _setMeta;
     private _getMeta;
+    private _insCanon;
+    private _selCanon;
+    private _cntCanon;
+    private _selContentFrom;
     private _delMeta;
     private _insSnapshot;
     private _selSnapshot;
@@ -130,6 +134,10 @@ export declare class SQliteStore extends AbstractStore implements Store {
     protected _dbGetMeta(key: string): string | null;
     protected _dbSetMeta(key: string, val: string): void;
     protected _dbDeleteMeta(key: string): void;
+    canonAdd(h: number, id: number): void;
+    canonFind(h: number): number[];
+    canonCount(): number;
+    eachContent(cb: (id: number, bytes: Uint8Array) => void, fromId?: number): void;
     protected _dbSaveSnapshot(bytes: Uint8Array): void;
     protected _dbLoadSnapshot(): Uint8Array | null;
     protected _vecContentUpsert(entries: Array<{

package/dist/src/store-sqlite.js

@@ -112,6 +112,18 @@ CREATE TABLE IF NOT EXISTS contain (
   id      INTEGER PRIMARY KEY,
   parents BLOB NOT NULL
 );
+-- CANONICAL-FORM index (Store.canonAdd/canonFind): h is the 32-bit hash of a
+-- node's CANONICAL content key (the modality's canonicalizer output — case-
+-- folded, whitespace-collapsed text, etc.; the store never sees the key
+-- itself, only its hash).  Same hash-then-verify discipline as idx_node_h:
+-- the caller re-canonicalizes each candidate's bytes before trusting it, so
+-- a collision costs a read, never a wrong id.  WITHOUT ROWID on (h, id):
+-- the composite key IS the lookup index and gives free dedup.
+CREATE TABLE IF NOT EXISTS canon (
+  h  INTEGER NOT NULL,
+  id INTEGER NOT NULL,
+  PRIMARY KEY (h, id)
+) WITHOUT ROWID;
 CREATE TABLE IF NOT EXISTS snapshot (
   id INTEGER PRIMARY KEY CHECK (id = 1),
   data BLOB NOT NULL
@@ -212,6 +224,10 @@ export class SQliteStore extends AbstractStore {
     _selPrev = null;
     _setMeta = null;
     _getMeta = null;
+    _insCanon = null;
+    _selCanon = null;
+    _cntCanon = null;
+    _selContentFrom = null;
     _delMeta = null;
     _insSnapshot = null;
     _selSnapshot = null;
@@ -797,6 +813,42 @@ export class SQliteStore extends AbstractStore {
         }
         this._delMeta.run(key);
     }
+    // -- Canonical-form index (Store optional capability) --
+    canonAdd(h, id) {
+        if (!this._insCanon) {
+            this._insCanon = this.sqlite.prepare("INSERT OR IGNORE INTO canon (h, id) VALUES (?, ?)");
+        }
+        // Join the deferred write transaction (committed by flush/commit), so a
+        // bulk index build coalesces instead of paying autocommit per row.
+        this._dbBeginTx();
+        this._insCanon.run(h, id);
+    }
+    canonFind(h) {
+        if (!this._selCanon) {
+            this._selCanon = this.sqlite.prepare("SELECT id FROM canon WHERE h = ?");
+        }
+        return this._selCanon.all(h).map((r) => r.id);
+    }
+    canonCount() {
+        if (!this._cntCanon) {
+            this._cntCanon = this.sqlite.prepare("SELECT count(*) AS c FROM canon");
+        }
+        return this._cntCanon.get().c;
+    }
+    eachContent(cb, fromId = 0) {
+        if (!this._selContentFrom) {
+            // Content-bearing nodes are FLAT branches: leaf present, kids an
+            // empty (zero-length) blob — the same population PART 2 of the
+            // diagnostics calls "distinct content spans".
+            this._selContentFrom = this.sqlite.prepare("SELECT id, leaf FROM node " +
+                "WHERE id >= ? AND leaf IS NOT NULL " +
+                "AND (kids IS NULL OR length(kids) = 0)");
+        }
+        for (const row of this._selContentFrom.iterate(fromId)) {
+            const r = row;
+            cb(r.id, new Uint8Array(r.leaf));
+        }
+    }
     // -- Snapshot --
     _dbSaveSnapshot(bytes) {
         if (!this._insSnapshot) {

package/dist/src/store.d.ts

@@ -240,6 +240,18 @@ export interface Store {
      *  repetition, but repetition outranks insertion-order accident.  0 when
      *  the node has no halo row. */
     haloMass(id: NodeId): number;
+    /** Record that node `id`'s canonical key hashes to `h`.  Idempotent. */
+    canonAdd?(h: number, id: NodeId): void;
+    /** All candidate node ids whose canonical key hashes to `h` (collisions
+     *  included — the caller verifies). */
+    canonFind?(h: number): NodeId[];
+    /** Number of (h, id) rows in the canon index — 0 means never built. */
+    canonCount?(): number;
+    /** Visit every content-bearing node (flat branch: `leaf` present, no
+     *  kids) — the population a canonical index is built over.  `fromId`
+     *  restricts the scan to ids ≥ fromId, so an index refresh after further
+     *  training only visits the new rows. */
+    eachContent?(cb: (id: NodeId, bytes: Uint8Array) => void, fromId?: NodeId): void;
     size(): Promise<number>;
     saveSnapshot(bytes: Uint8Array): Promise<void>;
     loadSnapshot(): Promise<Uint8Array | null>;

package/example/train_base.ts

@@ -177,8 +177,11 @@ const LOCAL_PATH = env("LOCAL_PATH", ""); // train from a local dir of *.zip
 const CACHE_DIR = env("CACHE_DIR", join(process.cwd(), "cache"));
 const MAX_CACHE_BYTES = Number(env("MAX_CACHE_GB", "100")) * 1e9;
 const PROGRESS_MS = Number(env("PROGRESS_MS", "250")); // panel refresh cadence
-// Index maintenance at checkpoints: compact (remove garbage) then repair (fill
-// gaps). Both are idempotent batch operations; INDEX_MAINTENANCE=0 disables.
+// Index maintenance at checkpoints: compact (remove garbage), repair (fill
+// gaps), then refresh the canonical-form index (equivalence-class resolution —
+// src/canon.ts). All three are idempotent batch operations (the canon build is
+// additionally incremental via the store's `canon.upto` cursor);
+// INDEX_MAINTENANCE=0 disables.
 const INDEX_MAINTENANCE = env("INDEX_MAINTENANCE", "1") !== "0";
 const DOWNLOAD_TRIES = 5;
 // In-progress downloads are written to a sibling "<dest>.part" and atomically
@@ -1823,8 +1826,9 @@ async function main(): Promise<void> {
 
   const checkpoint = () => mind.save();
 
-  /** Run index maintenance: compact (remove garbage) then repair (fill gaps).
-   *  Both are idempotent — running twice produces the same result as once.
+  /** Run index maintenance: compact (remove garbage), repair (fill gaps),
+   *  then refresh the canonical-form index (see below).  All three are
+   *  idempotent — running twice produces the same result as once.
    *  Compaction frees index space first; repair then adds back every
    *  edge/halo-bearing node whose gist was evicted from the pending cache
    *  before it reached the content index, completing the coverage that
@@ -1877,6 +1881,27 @@ async function main(): Promise<void> {
         }`,
       );
     }
+    // Canonical-form index (src/canon.ts): lets resolution find stored forms
+    // across surface variation (case, width, whitespace).  Incremental and
+    // idempotent by construction — the `canon.upto` meta cursor scans only
+    // nodes newer than the last pass, and the (h, id) primary key ignores
+    // re-inserted rows — so it composes with the resume model exactly like
+    // compact/repair: every checkpoint (and finish) leaves the index
+    // covering all content trained so far.
+    try {
+      const added = await mind.buildCanonIndex();
+      if (added > 0) {
+        progress.log(
+          `  ${GRN}canon index: added ${int(added)} canonical-form entries${R}`,
+        );
+      }
+    } catch (err) {
+      progress.log(
+        `  ${YEL}⚠ canon index build failed${R}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
   };
 
   // The checkpoint recall is a best-effort diagnostic. It is time-bounded so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "type": "module",
   "main": "dist/src/index.js",

package/src/alu/src/parser.ts

@@ -172,10 +172,27 @@ export class QueryParser {
       j,
       bytes: this.evalRun(query.subarray(i, j)),
     }));
-    const spans: ComputedSpan[] = runs.filter(
-      (r): r is ComputedSpan => r.bytes !== null,
-    );
-    let stream = compose(tokens, runs);
+    // BRACKETED runs — "(3 + 4) * (10 - 2)" — extend across grouping
+    // notation the flat alternation cannot cross.  The expression grammar
+    // (expr.ts) already nests and parenthesizes; this only hands it the
+    // WHOLE bracketed span instead of the fragments between brackets.  A
+    // bracketed run that evaluates ABSORBS the flat runs inside it (the
+    // authority law: contained spans are its material); one that does not
+    // evaluate leaves the flat readings untouched.
+    const bracketed = this.bracketedRuns(query, tokens)
+      .map(([i, j]) => ({ i, j, bytes: this.evalRun(query.subarray(i, j)) }))
+      .filter((r): r is ComputedSpan => r.bytes !== null);
+    const absorbed = (r: { i: number; j: number }) =>
+      bracketed.some((b) => b.i <= r.i && r.j <= b.j);
+    const composedRuns = [
+      ...runs.filter((r) => !absorbed(r)),
+      ...bracketed,
+    ].sort((a, b) => a.i - b.i);
+    const spans: ComputedSpan[] = [
+      ...runs.filter((r): r is ComputedSpan => r.bytes !== null),
+      ...bracketed,
+    ];
+    let stream = compose(tokens, composedRuns);
     const readings = new Map<Token, readonly string[]>();
     for (;;) {
       const fired = await this.operations(query, stream, readings);
@@ -302,6 +319,90 @@ export class QueryParser {
     return runs;
   }
 
+  /** The maximal BRACKETED arithmetic runs: like {@link arithmeticRuns} but
+   *  grouping brackets participate — an all-'(' term opens depth where an
+   *  operand is expected, a term beginning with ')' closes it where an
+   *  operator could follow (only its bracket prefix joins the run; anything
+   *  after — a trailing "?" — ends it).  A run is recorded only when it is
+   *  BALANCED, actually crossed a bracket, and contains an operator — the
+   *  bracket-free case is {@link arithmeticRuns}' own.  Evaluation is the
+   *  same registry-derived grammar, whose lexer already reads the brackets. */
+  private bracketedRuns(
+    query: Uint8Array,
+    tokens: Token[],
+  ): Array<[number, number]> {
+    const OPEN = 0x28, CLOSE = 0x29;
+    const bracketPrefix = (t: Token, b: number): number => {
+      if (t.kind !== "term") return 0;
+      let n = 0;
+      while (t.i + n < t.j && query[t.i + n] === b) n++;
+      return n;
+    };
+    const allOf = (t: Token, b: number): boolean =>
+      bracketPrefix(t, b) === t.j - t.i;
+    const bridged = (from: number, to: number): boolean =>
+      from >= to || this.host.segment(query.subarray(from, to)).length <= 1;
+    const runs: Array<[number, number]> = [];
+    let k = 0;
+    while (k < tokens.length) {
+      const first = tokens[k];
+      if (first.kind !== "operand" && !allOf(first, OPEN)) {
+        k++;
+        continue;
+      }
+      let depth = 0;
+      let ops = 0;
+      let brackets = 0;
+      let expectOperand = true;
+      let end = -1; // byte end of the last VALID run state (balanced, after operand/close)
+      let endTok = k; // token index just past the accepted prefix
+      let m = k;
+      let prevJ = -1;
+      while (m < tokens.length) {
+        const t = tokens[m];
+        if (prevJ >= 0 && !bridged(prevJ, t.i)) break;
+        if (expectOperand) {
+          if (allOf(t, OPEN)) {
+            depth += t.j - t.i;
+            brackets++;
+          } else if (t.kind === "operand") {
+            expectOperand = false;
+            if (depth === 0) {
+              end = t.j;
+              endTok = m + 1;
+            }
+          } else break;
+        } else {
+          const c = bracketPrefix(t, CLOSE);
+          if (c > 0 && depth > 0) {
+            const take = Math.min(c, depth);
+            depth -= take;
+            brackets++;
+            if (depth === 0) {
+              end = t.i + take;
+              endTok = m + 1;
+            }
+            // A term with content beyond its usable bracket prefix ("?")
+            // ends the run inside the term.
+            if (take < t.j - t.i) break;
+          } else if (t.kind === "operator") {
+            expectOperand = true;
+            ops++;
+          } else break;
+        }
+        prevJ = t.j;
+        m++;
+      }
+      if (end >= 0 && ops > 0 && brackets > 0) {
+        runs.push([first.i, end]);
+        k = endTok;
+      } else {
+        k++;
+      }
+    }
+    return runs;
+  }
+
   /** Evaluate an infix-arithmetic run to its canonical result bytes, through
    *  the kernel's recursive expression evaluator, or null if it does not
    *  evaluate.  A whole result stays an exact int; otherwise the canonical

package/src/canon.ts

@@ -0,0 +1,65 @@
+// canon.ts — content canonicalization for equivalence-class resolution.
+//
+// The store is content-addressed on RAW bytes: "What", "WHAT" and "what" are
+// three different hashes, so a query whose surface form varies from the
+// trained form resolves to nothing even though the CONTENT is the same.  A
+// CANONICALIZER maps every surface variant of the same content onto one
+// canonical byte string; the store keeps a small hash index from canonical
+// keys to node ids (see Store.canonAdd/canonFind), and resolution falls back
+// to that index when the exact content-addressed lookup misses.
+//
+// The canonicalizer is MODALITY-SPECIFIC and always INJECTED — nothing in the
+// store or the mind's core knows what "case" or "whitespace" is.  The text
+// canonicalizer below is the one `respondText`/`respondTurnText` pass down;
+// a grid or audio modality would supply its own (or none).
+//
+// Canonical keys are equivalence-class LABELS, never content: they are hashed
+// and verified (canon(stored bytes) must equal canon(query bytes) before an
+// id is accepted), so a hash collision costs a read, never a wrong id — the
+// same discipline as the node table's own `h` index.
+
+/** A content canonicalizer: maps a byte span to the canonical representative
+ *  of its equivalence class.  Must be pure and deterministic.  Returning the
+ *  input unchanged is always sound (the class is then {input}). */
+export type Canon = (bytes: Uint8Array) => Uint8Array;
+
+const dec = new TextDecoder("utf-8", { fatal: false });
+const enc = new TextEncoder();
+
+/** The TEXT canonicalizer: Unicode-aware equivalence over every character
+ *  variation that does not change what the text SAYS —
+ *
+ *   • compatibility normalization (NFKC): full-width forms, ligatures,
+ *     composed vs decomposed accents collapse to one representation;
+ *   • case folding (locale-independent lowercase after NFKC — the standard
+ *     simple fold);
+ *   • whitespace: every INTERIOR run of Unicode whitespace becomes one plain
+ *     space.  EDGE whitespace is preserved verbatim: a span's leading or
+ *     trailing separator belongs BETWEEN forms, not to the form — trimming
+ *     it would let a recognised span swallow the boundary byte that
+ *     separates it from its neighbour (observed: "ice fire" composing to
+ *     "coldhot" because the span "ice " matched the stored "ice").
+ *
+ *  "WHAT  IS", "What is" and "ｗｈａｔ is" share one canonical form.  This is
+ *  deliberately conservative: punctuation, digits and word order are content
+ *  and pass through untouched. */
+export function textCanon(bytes: Uint8Array): Uint8Array {
+  const s = dec
+    .decode(bytes)
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/(\S)\s+(?=\S)/g, "$1 ");
+  return enc.encode(s);
+}
+
+/** 32-bit FNV-1a over a canonical key — the integer the store's canon index
+ *  is keyed on.  Same construction as the node table's content hash; a
+ *  collision is resolved by verifying canon(stored) === key, never trusted. */
+export function canonHash(key: Uint8Array): number {
+  let h = 0x811c9dc5 >>> 0;
+  for (let i = 0; i < key.length; i++) {
+    h ^= key[i];
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h >>> 0;
+}

package/src/geometry.ts

@@ -460,6 +460,18 @@ export function bytesToTreePyramid(
       pyramid: { levels: [], bytes: 0 },
     };
   }
+  // ZERO GROWTH: the previous pyramid already covers every byte — its top
+  // level holds the finished, normalized root.  Refolding here would not
+  // only waste the work: when the whole span is one full block, the refold's
+  // top item is a REUSED raw interior of `prev`, and the final normalize
+  // below would mutate that shared raw block in place, corrupting every
+  // later incremental fold built on `prev`.
+  if (prev && prev.bytes === bytes.length && prev.levels.length > 0) {
+    return {
+      tree: prev.levels[prev.levels.length - 1][0].tree,
+      pyramid: prev,
+    };
+  }
   const mg = space.maxGroup;
   const reusable = (L: number): ReadonlyArray<Folded> | null => {
     // prev's TOPMOST level holds its normalized ROOT — reusable blocks must

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./mind/index.js";
 export * from "./store-sqlite.js";
 export * from "./config.js";
 export * from "./extension.js";
+export * from "./canon.js";
 export * from "./ingest-cache.js";
 // rabitq-ivf: the partitioned (IVF) vector index over 1-bit RaBitQ codes.
 export {

package/src/mind/learning.ts

@@ -7,7 +7,12 @@ import { Vec } from "../vec.js";
 import { bindSeat, companySignature, isChunk, Sema } from "../sema.js";
 import type { Input, MindContext } from "./types.js";
 import { changedNodes } from "./types.js";
-import { inputBytes, perceive, perceiveDeposit } from "./primitives.js";
+import {
+  inputBytes,
+  perceive,
+  perceiveDeposit,
+  resolve,
+} from "./primitives.js";
 import { canonicalWindows, leafIdPrefix } from "./canonical.js";
 import { fold as foldVecs } from "../sema.js";
 
@@ -171,6 +176,38 @@ export async function ingestOne(
   return Object.assign(tree, { id: rootId });
 }
 
+/** For each right-edge suffix of the context bytes, resolve it against the
+ *  store.  A suffix whose resolved node is already a known form inherits the
+ *  continuation edge.  Gate: ≥ 2 structural parents (reused across deposits),
+ *  or (halo > 0 ∧ already an edge source).  Pure answers do not qualify. */
+async function propagateSuffixes(
+  ctx: MindContext,
+  src: number,
+  dst: number,
+): Promise<void> {
+  const W = ctx.space.maxGroup;
+  const bytes = ctx.store.bytes(src);
+  const n = bytes.length;
+  if (n < 2 * W) return;
+  // Existence prefilter — the write side of the canonical contract: every
+  // deposit interns its WHOLE byte stream as a flat branch of per-byte leaf
+  // ids (deposit(), canonical.ts).  A suffix is a stored form exactly when
+  // that flat twin exists, so one content-hash probe per offset decides;
+  // only a hit pays for resolve()'s deposit-shaped perception.  This keeps
+  // the scan free of river folds — O(1) probes over cheap byte hashes
+  // instead of O(suffix) vector folds per offset.
+  const leafIds = leafIdPrefix(ctx, bytes);
+  for (let i = 1; i <= n - W; i++) {
+    if (ctx.store.findBranch(leafIds.slice(i)) === null) continue;
+    const id = resolve(ctx, bytes.subarray(i));
+    if (id === null || id === src) continue;
+    const known = ctx.store.parentsFirst(id, 2).length >= 2 ||
+      (ctx.store.haloMass(id) > 0 && ctx.store.hasNext(id));
+    if (!known) continue;
+    await ctx.store.link(id, dst);
+  }
+}
+
 /** Ingest a pair (context, continuation) — learn an edge and pour halos. */
 export async function ingestPair(
   ctx: MindContext,
@@ -182,6 +219,7 @@ export async function ingestPair(
   const ctxId = c.rootId, contId = cont_.rootId;
 
   await ctx.store.link(ctxId, contId);
+  await propagateSuffixes(ctx, ctxId, contId);
 
   // Halos pour company SIGNATURES (identity), not gists (content) — see
   // companySignature in sema.ts.

package/src/mind/match.ts

@@ -446,8 +446,10 @@ export async function follow(
  *  `guide` the context whose gist resonates with the query wins (seat
  *  symmetry) — without one, the most-corroborated context wins (poured halo
  *  MASS, the direct measure of how many episodes established it), falling
- *  back to first-learnt on equal mass.  Callers that HAVE a query gist must
- *  pass it, or they silently change disambiguation regime.
+ *  back to first-learnt on equal mass.  Among many predecessors RECIPROCAL
+ *  ones (mutual edges) are preferred when any exist (RC5).  Callers that
+ *  HAVE a query gist must pass it, or they silently change disambiguation
+ *  regime.
  *
  *  `rev`, when the caller has already materialised prevOf (one read per
  *  relation — a hub's reverse fan-in is corpus-sized), is reused instead of
@@ -466,11 +468,32 @@ export function reverseContext(
   // keeps the single-predecessor shortcut exact.
   const candidates = rev ?? ctx.store.prevFirst(id, hubBound(ctx));
   if (candidates.length === 0) return null;
-  const pick = candidates.length === 1
-    ? candidates[0]
+  // RECIPROCAL PREFERENCE: among many predecessors, one that `id` also
+  // continues TO (cand → id AND id → cand both learnt) is a mutually
+  // established pairing — the strongest structural evidence a predecessor
+  // can carry (bidirectional training deposits both directions of a genuine
+  // pair).  A bare predecessor is one episode's adjacency; guide-resonance
+  // over bare predecessors favours whichever stored document merely
+  // CONTAINS the query's bytes (the linear fold's cosine is byte overlap —
+  // the observed "merci → unrelated French document" failure).  One capped
+  // forward read decides; when no reciprocal exists, behaviour is unchanged
+  // — bare predecessors ARE the honest answer for a shared deposited
+  // continuation (two questions → one answer; audited by 31-audit C1), and
+  // this arm serves every mechanism's reverse projection, so abstaining
+  // here starves far more than the one containment failure it would fix.
+  let pool: readonly number[] = candidates;
+  if (candidates.length > 1) {
+    const fwd = new Set(ctx.store.nextFirst(id, hubBound(ctx)));
+    if (fwd.size > 0) {
+      const mutual = candidates.filter((c) => fwd.has(c));
+      if (mutual.length > 0) pool = mutual;
+    }
+  }
+  const pick = pool.length === 1
+    ? pool[0]
     : guide
-    ? chooseAmong(ctx, candidates, guide).id
-    : pickByMass(ctx, candidates);
+    ? chooseAmong(ctx, pool, guide).id
+    : pickByMass(ctx, pool);
   const g = read(ctx, pick);
   return g.length > 0 ? g : null;
 }