@hviana/sema 0.1.9 → 0.2.0

package/dist/src/mind/mind.js

@@ -0,0 +1,562 @@
+// mind/mind.ts — perceive, deposit, recall, think, express.
+//
+// Memory is a content-addressed node graph (see store.ts). Learning is
+// DEPOSITION: perceive a stream into a tree and intern every node, so equal —
+// and, by resonance, similar — subtrees collapse to one shared node. A fact is
+// an EDGE between node ids; recall traverses edges; thinking completes the
+// query's OWN tree, node by node, to a fixed point. No whole, no weights.
+//
+// Architecture: 4 primitives × 2 patterns = all inference.
+// Implementation split across src/mind/*.ts — this file assembles the Mind class.
+import { makeKeyring, rng, setVecConfig } from "../vec.js";
+import { Alphabet } from "../alphabet.js";
+import { bytesToTreePyramid, reachThreshold, } from "../geometry.js";
+import { BoundedMap } from "../store.js";
+import { SQliteStore } from "../store-sqlite.js";
+import { resolveConfig } from "../config.js";
+import { canonHash, textCanon } from "../canon.js";
+import { bytesEqual, concat2 } from "../bytes.js";
+import { GraphSearch, } from "./graph-search.js";
+import { Alu } from "../alu/src/index.js";
+import { decodeText, Rationale, } from "./rationale.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";
+import { meaningOf } from "./resonance.js";
+import { climbAttention as climbAttentionFn, naturalBreak as naturalBreakFn, } from "./attention.js";
+import { aluToMechanism, defaultMechanisms, think } from "./pipeline.js";
+import { articulate } from "./articulation.js";
+import { ingest } from "./learning.js";
+import { rItem } from "./trace.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// THE MIND
+// ═══════════════════════════════════════════════════════════════════════════
+export class Mind {
+    space;
+    alphabet;
+    store;
+    cfg;
+    /** The lightest-derivation engine over the Sema graph. */
+    search;
+    /** The grounding mechanisms iterated by {@link think}. */
+    mechanisms = [];
+    /** The live rationale tracer for the inference currently in flight, or null. */
+    trace = null;
+    /** The content canonicalizer for the response in flight — see
+     *  {@link MindContext.canon}.  Injected per response by the modality entry
+     *  point; null when the response carries no equivalence. */
+    canon = null;
+    /** Per-response canonical-resolution memo — see {@link MindContext.canonMemo}. */
+    canonMemo = null;
+    /** The Mind-level canon option: a canonicalizer to use for EVERY response,
+     *  `false` to disable canonical resolution, or null to let each entry
+     *  point decide (text entry points inject {@link textCanon}). */
+    _canonOpt = null;
+    /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
+    climbMemo = null;
+    /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
+    recogniseMemo = null;
+    /** 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
+     *  first-edge behaviour) and the reverse projection uses it for
+     *  reverse-recall disambiguation via `chooseAmong`. */
+    _edgeGuide = null;
+    /** Per-response memo of {@link chooseNext} picks — ensures every mechanism
+     *  of a single response follows the SAME continuation for each ambiguous
+     *  context node. */
+    _edgeChoice = new Map();
+    /** Previous deposit's seen node ids for incremental change detection. */
+    _prevSeen = null;
+    /** Session cache of node-id → perceived gist for candidate scoring — see
+     *  {@link MindContext._gistCache}.  32 MB ≈ 8K gists at D=1024; hub
+     *  candidate sets (√N at most) fit comfortably and recur across queries. */
+    _gistCache = new BoundedMap(32_000_000, (v) => v.byteLength);
+    // Deposit-path fold-pyramid cache (see MindContext) — ENTRY-count
+    // bounded: a pyramid costs ~KB per content byte (one D-float gist per
+    // interior node), and only the few live conversation chains need to stay
+    // warm, so 8 entries is the honest budget.
+    _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) {
+        return resolveImpl(this, bytes);
+    }
+    // recogniseSpan wraps recognise
+    recogniseSpan(bytes) {
+        const r = recognise(this, bytes);
+        return { sites: r.sites, leaves: r.leaves, splits: r.splits };
+    }
+    /** Disambiguate among multiple learnt continuations of the same context node.
+     *  Required by {@link GraphSearchHost} — the graph search calls this through the
+     *  host interface when a recognised form has more than one outgoing edge.
+     *  Delegates to the standalone {@link chooseNext} which picks the candidate
+     *  with the most distributional evidence (highest `prevOf` count — the
+     *  structural manifestation of its halo).  When evidence is equal the
+     *  first-inserted edge wins. */
+    chooseNext(node) {
+        return chooseNext(this, node, this._edgeGuide);
+    }
+    constructor(optsOrCfg, storeArg, _fromStore) {
+        let userMechanisms = [];
+        let userFactories = [];
+        if (_fromStore !== undefined) {
+            this.cfg = resolveConfig(optsOrCfg);
+            this.store = storeArg;
+        }
+        else {
+            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,
+            });
+            userMechanisms = userMechs ?? [];
+            userFactories = userFacts ?? [];
+        }
+        setVecConfig({
+            normalizeEpsilon: this.cfg.normalizeEpsilon,
+            cosineEpsilon: this.cfg.cosineEpsilon,
+        });
+        const seedRand = rng((this.cfg.seed ^ 0x9e3779) >>> 0);
+        const seats = makeKeyring(this.store.D, Math.max(8, this.cfg.geometry.maxGroup), seedRand);
+        this.space = {
+            D: this.store.D,
+            seats,
+            rand: rng((this.cfg.seed ^ 0x51f15e) >>> 0),
+            maxGroup: this.cfg.geometry.maxGroup,
+        };
+        this.alphabet = new Alphabet(this.cfg.seed, this.store.D, this.cfg.alphabet);
+        this.search = new GraphSearch(this.store, this.space.maxGroup, this);
+        // Build the mechanism list: default grounding + ALU + user mechanisms.
+        for (const m of defaultMechanisms)
+            this.mechanisms.push(m);
+        const host = this.extensionHost();
+        if (this.cfg.alu.enabled) {
+            const alu = new Alu({
+                tol: this.cfg.alu.tol,
+                maxIter: this.cfg.alu.maxIter,
+                precision: this.cfg.alu.precision,
+            }, host);
+            this.mechanisms.push(aluToMechanism(alu));
+        }
+        for (const m of userMechanisms)
+            this.mechanisms.push(m);
+        for (const f of userFactories)
+            this.mechanisms.push(f(host));
+    }
+    // ── Public API ───────────────────────────────────────────────────────────
+    /** Exposed for tests: the consensus climb over query sub-regions. */
+    climbAttention(query, k, mode = "inverse") {
+        return climbAttentionFn(this, query, k, mode);
+    }
+    /** Exposed for tests: climb the structural DAG from a node to its
+     *  edge-bearing ancestor contexts. */
+    edgeAncestors(id, contextCount) {
+        return edgeAncestorsFn(this, id, contextCount);
+    }
+    /** Exposed for tests: find the natural break point in a sorted vote list. */
+    naturalBreak(votes) {
+        return naturalBreakFn(votes);
+    }
+    // ── respond ───────────────────────────────────────────────────────────
+    /** Perceive input into a content-defined tree.  Deterministic — identical
+     *  bytes always produce an identical tree.  Public for ingest-cache. */
+    perceive(input, leafAt, lookup) {
+        return perceiveImpl(this, input, leafAt, lookup);
+    }
+    /** 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, canon) {
+        this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
+        this.climbMemo = new Map();
+        this.recogniseMemo = new Map();
+        this.perceiveMemo = new Map();
+        this.canon = canon ?? null;
+        this.canonMemo = canon ? new Map() : null;
+    }
+    /** The canonicalizer a response should carry: the Mind-level option when
+     *  set (or none when explicitly disabled), else the entry point's own
+     *  default — text entry points pass {@link textCanon}, binary ones null. */
+    _canonFor(entryDefault) {
+        if (this._canonOpt === false)
+            return null;
+        return this._canonOpt ?? entryDefault;
+    }
+    /** Close one response's transient state — every per-response field, incl.
+     *  the edge guide/choices `think` sets mid-flight. */
+    endResponse() {
+        this.trace = null;
+        this.climbMemo = null;
+        this.recogniseMemo = null;
+        this.perceiveMemo = null;
+        this.canon = null;
+        this.canonMemo = null;
+        this._edgeGuide = null;
+        this._edgeChoice.clear();
+    }
+    /** Shared response core — the one path from bytes to voiced answer.
+     *  `respond` calls this directly; `respondTurn` has its own path
+     *  with conversation-persistent memos and incremental perception. */
+    async _respondImpl(queryBytes, inspectRationale, traceLabel = "respond", canon = null) {
+        this.beginResponse(inspectRationale, canon);
+        try {
+            const top = this.trace?.enter(traceLabel, [
+                rItem(queryBytes, "query"),
+            ]);
+            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, queryBytes);
+            top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
+            return {
+                v: gistOf(this, voiced),
+                bytes: voiced,
+                provenance: thought.provenance,
+            };
+        }
+        finally {
+            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.
+     *
+     *  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;
+    }
+    /** Kinship note: the vector arm below is a miniature of recall's tier 3
+     *  (resonate → reach gate → read out the nearest form's bytes) — the
+     *  read-out direction of the same operation, without recall's grounding
+     *  ladder.  If either side's acceptance rule changes, revisit the other. */
+    async express(idOrV) {
+        if (typeof idOrV === "number")
+            return this.store.bytes(idOrV);
+        const [hit] = await this.store.resonate(idOrV, 1);
+        // The same confidence floor recall uses: a vector whose nearest stored
+        // form sits below the reach threshold relates to NOTHING in the store —
+        // returning that form's bytes anyway would fabricate an answer from an
+        // unrelated neighbour.  Silence is the honest read-out.
+        if (hit && hit.score >= reachThreshold(this.space.maxGroup)) {
+            return this.store.bytes(hit.id);
+        }
+        return new Uint8Array(0);
+    }
+    // ── Learning ─────────────────────────────────────────────────────────────
+    async ingest(input, second) {
+        return ingest(this, input, second);
+    }
+    // ── Extension Surface ────────────────────────────────────────────────────
+    extensionHost() {
+        const mind = this;
+        return {
+            meaningOf: (bytes, anchors) => meaningOf(this, bytes, anchors),
+            continuation: (bytes) => this.groundedContinuation(bytes),
+            segment: (bytes) => segment(this, bytes).map((s) => ({ i: s.start, j: s.end })),
+            get reach() {
+                return mind.space.maxGroup;
+            },
+        };
+    }
+    async groundedContinuation(bytes) {
+        const id = resolveImpl(this, bytes);
+        if (id === null)
+            return null;
+        const grounded = await follow(this, id);
+        if (grounded !== null && !bytesEqual(grounded, bytes))
+            return grounded;
+        return null;
+    }
+    // ── Content-index repair ───────────────────────────────────────────────
+    /** Re-index structurally-important nodes whose gists were evicted from the
+     *  pending cache before they reached the content index.  See {@link
+     *  Store.repairContentIndex} for the contract; this method wires the
+     *  Mind's perception into the store's repair walk.
+     *
+     *  Run this after training or at checkpoints to restore recall reach for
+     *  nodes that bridge experiences but were never indexed.  A pure interior
+     *  node (no edges, no halo) is deliberately skipped — it is scaffolding,
+     *  not an experience root or bridge, and regenerating its gist would waste
+     *  I/O and index space for no recall benefit.
+     *
+     *  @param minParents  only repair nodes with ≥ this many structural parents
+     *                     (default 2 — structural bridges)
+     *  @returns number of nodes added to the content index */
+    async repairContentIndex(minParents = 2) {
+        return this.store.repairContentIndex(async (id) => {
+            const bytes = this.store.bytes(id);
+            if (bytes.length === 0)
+                return null;
+            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));
+        await this.store.saveSnapshot(meta);
+        return meta;
+    }
+    static async load(snapshot, store) {
+        const cfg = JSON.parse(new TextDecoder().decode(snapshot));
+        return new Mind(cfg, store, true);
+    }
+    static async loadFromStore(store) {
+        const meta = await store.loadSnapshot();
+        if (!meta)
+            throw new Error("no snapshot in store");
+        return Mind.load(meta, store);
+    }
+}