@hviana/sema 0.7.3 → 0.7.6

package/README.md

@@ -41,7 +41,7 @@ No weights. No gradients. No training loop. No neural network. No GPU.
 > Vector Symbolic Architecture (Plate 1995; Kanerva 2009) over a
 > content-addressable memory, with inference by weighted automated deduction
 > (Knuth 1977; Felzenszwalb & McAllester 2007). Each term is grounded in
-> [HOW_IT_WORKS.md](HOW_IT_WORKS.md).
+> [docs/INDEX.md](docs/INDEX.md).
 
 ---
 
@@ -314,16 +314,16 @@ start talking — no install, no runtime, no API key.
 
 ## ✦ Learn more
 
-| Document                                                                             | What's inside                                                                                                                                            |
-| :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 📘 **[HOW_IT_WORKS.md](HOW_IT_WORKS.md)**                                            | The full theory: vector symbolic architectures, the Merkle DAG, distributional halos, weighted deduction — concepts, diagrams, and extensive pseudocode. |
-| 🛠️ **[AGENTS.md](AGENTS.md)**                                                        | The development manual: repo layout, build/test, internals, invariants, and recipes for extending the system.                                            |
-| 🎓 **[CITATION.cff](CITATION.cff)**                                                  | How to cite Sema in academic work.                                                                                                                       |
-| ⚖️ **[LICENSE.md](LICENSE.md)**                                                      | PolyForm Noncommercial License 1.0.0.                                                                                                                    |
-| 📚 **[DATASETS.md](DATASETS.md)**                                                    | Training corpora: provenance, per-corpus attribution, and how a trained memory file is licensed.                                                         |
-| 💼 **[COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)**                                | Commercial licensing terms and contact.                                                                                                                  |
-| 🤗 **[Trained examples](https://huggingface.co/buckets/hviana/sema-trained-v1)**     | Pre-trained memory files you can download and use directly.                                                                                              |
-| 💿 **[Binary examples](https://huggingface.co/buckets/hviana/sema-binary-examples)** | Ready-to-run web chat apps for Windows, Mac, and Linux — one file, no install.                                                                           |
+| Document                                                                             | What's inside                                                                                                                                          |
+| :----------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 📘 **[docs/INDEX.md](docs/INDEX.md)**                                                | Architecture docs: single-system laws (docs/architecture/), mechanisms, invariants, and harness gates — the entry point for theory and implementation. |
+| 🛠️ **[AGENTS.md](AGENTS.md)**                                                        | The development manual: repo layout, build/test, internals, invariants, and recipes for extending the system.                                          |
+| 🎓 **[CITATION.cff](CITATION.cff)**                                                  | How to cite Sema in academic work.                                                                                                                     |
+| ⚖️ **[LICENSE.md](LICENSE.md)**                                                      | PolyForm Noncommercial License 1.0.0.                                                                                                                  |
+| 📚 **[DATASETS.md](DATASETS.md)**                                                    | Training corpora: provenance, per-corpus attribution, and how a trained memory file is licensed.                                                       |
+| 💼 **[COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)**                                | Commercial licensing terms and contact.                                                                                                                |
+| 🤗 **[Trained examples](https://huggingface.co/buckets/hviana/sema-trained-v1)**     | Pre-trained memory files you can download and use directly.                                                                                            |
+| 💿 **[Binary examples](https://huggingface.co/buckets/hviana/sema-binary-examples)** | Ready-to-run web chat apps for Windows, Mac, and Linux — one file, no install.                                                                         |
 
 ---
 

package/dist/src/mind/graph-search.d.ts

@@ -270,37 +270,47 @@ export declare class GraphSearch {
      *  and recompose into a deeper learnt form (→ FINAL).  This is why a single
      *  edge-target needs no bespoke logic — it routes back through {@link solve}.
      *
-     *  Re-recognition (not the node's tree children) is what surfaces the learnt
-     *  parts: content-defined chunking may cut "p1 p2" as "p1 p"|"2", so only
-     *  recognising the bytes recovers p1 and p2 as the forms the graph knows.
+     *  The produced bytes are decomposed by the machinery that owns their shape:
+     *  the span's LEAVES and SPLITS drive the split rule, which resolves each half
+     *  through findLeaf — so a part that straddles a content-defined cut is still
+     *  recovered even though the node's tree children need not align with the
+     *  learnt parts (the fold cuts "p1 p2" as "p1 p"|"2").  Recognised SITES are
+     *  filtered to the node's own kids: a produced form is completed out of what
+     *  it was built from, never by re-recognising arbitrary forms inside it.  That
+     *  filter is load-bearing — a 37-byte dialogue sentence carries seven hub
+     *  openers, and re-covering them chained through the corpus's whole
+     *  continuation population: 2.5 GB and OOM for `respond("hi.")`.
      *
      *  The recovered answer is accepted only when it MOVED and names a LEARNT node
      *  ({@link resolve}) — the graph itself gates against re-expanding a contained
-     *  form ("ice is cold" ⊅→ "ice is cold is cold").
+     *  form ("ice is cold" ⊅→ "ice is cold is cold").  An ACCEPTED completion is
+     *  then re-covered in turn, so a chain runs as deep as the graph licenses; a
+     *  rejected one ends its branch, so no work is spent past it.
      *
-     *  Termination is STRUCTURAL: a produced node is re-covered once, never inside
-     *  another re-cover (see the guard below), so one cover pays at most one
-     *  nested {@link solve} per distinct produced node it actually reaches, and
-     *  {@link recompleteMemo} collapses a repeat to nothing.
-     *
-     *  This comment used to argue termination from "distinct node ids are finite
-     *  and each finished completion is memoised".  That is a bound of N — the one
-     *  AGENTS §2.8 forbids — and it was load-bearing, not pedantic: nested, the
-     *  recursion reached depth 331 and 9.1 GB on an 18.9M-node store for a 2-byte
-     *  query and did not terminate, which is what killed a 5 h training run at its
-     *  checkpoint recall.  Guard: test/89-completion-recursion.test.mjs. */
+     *  Termination and cost are STRUCTURAL: {@link recompleteOpen} is the chain's
+     *  stack (membership is the cycle guard), {@link recompleteMemo} re-covers each
+     *  node at most once, only accepted completions recurse, and every level
+     *  deepens only the top derivation — so a cover pays for the chain it finds,
+     *  not for how densely the corpus interconnects the forms it passes through.
+     *  Guard: test/89-completion-recursion.test.mjs. */
     private recompleteNode;
     /** Per-cover memo of each produced node's completion (so the many terminal
      *  outs of a long query re-cover each distinct node at most once); reset at the
      *  top of {@link cover}. */
     private recompleteMemo;
-    /** The node currently being re-completed — the recursion stack, and so also
-     *  the nesting depth.  {@link recompleteNode} refuses to start while it is
-     *  non-empty (one re-cover per produced node, never one inside another), which
-     *  is what keeps a query's cost proportional to its answer rather than to the
-     *  corpus; it therefore holds at most one id.  A Set, not a flag, because it
-     *  states WHICH node is open — the invariant a reader needs to check the
-     *  guard, and what makes the old cycle-guard reading still hold. */
+    /** The derivation sink of the TOP cover, threaded into every nested
+     *  completion so a produced form's own recompositions are reported in the
+     *  same trace instead of vanishing after the first layer.  Undefined when
+     *  nothing is inspecting, so an uninspected response pays nothing. */
+    private derivationSink?;
+    /** The chain of nodes currently being re-completed — the recursion STACK.
+     *  MEMBERSHIP is the cycle guard ({@link recompleteNode} refuses a node
+     *  already open on this chain), which is what lets a completion recurse as
+     *  deep as the graph licenses while the work stays the answer's: the
+     *  recursion only advances through an ACCEPTED completion, every produced
+     *  form is decomposed into its own kids, and the memo re-covers each node at
+     *  most once per cover.  A Set, not a flag, because it states WHICH node is
+     *  open — the invariant a reader needs to check the guard. */
     private recompleteOpen;
     /** out(i,j,bytes,…): index it for the binary rules, then offer splicing a
      *  learnt connector (the in-search bridge), splitting (at a sub-leaf form

package/dist/src/mind/graph-search.js

@@ -230,12 +230,26 @@ export class GraphSearch {
         // through (completion is cover, recursively — see {@link recompleteNode}).
         this.recompleteOpen.clear();
         this.recompleteMemo = new Map();
-        return this.solve(queryLen, {
+        // The top cover's derivation sink is threaded into every nested completion
+        // so the recompositions a produced form needs are reported in the same
+        // trace instead of vanishing after the first layer.
+        this.derivationSink = onDerivation;
+        const solved = this.solve(queryLen, {
             sites,
             leaves,
             splits,
             starts,
         }, conceptTarget, substitutions, connectors, computedResults, onDerivation);
+        // Deepening runs HERE, once, on the derivation the top cover CHOSE — never
+        // inside the nested solve a completion runs.  Nesting the deepening is what
+        // made per-query cost track how densely the corpus interconnects the forms
+        // passed through: every re-cover fanned out into the whole corpus's
+        // continuations instead of following the chain the answer itself licensed.
+        // With deepening only at the top, `recompleteNode` walks the accepted chain
+        // one link at a time (its own memo and stack), so the work is the answer's.
+        return solved === null
+            ? null
+            : { segs: this.deepen(solved.segs), cost: solved.cost };
     }
     /** Build the deduction system for one span and return its lightest cover's
      *  chosen spans — the SINGLE routine the query and every produced composite
@@ -270,7 +284,7 @@ export class GraphSearch {
             onDerivation(readDerivation(derivation, substitutions !== undefined));
         }
         return derivation
-            ? { segs: this.deepen(readCover(derivation)), cost: derivation.cost }
+            ? { segs: readCover(derivation), cost: derivation.cost }
             : null;
     }
     /** Re-cover the CHOSEN fixpoint spans, in place.
@@ -722,55 +736,51 @@ export class GraphSearch {
      *  and recompose into a deeper learnt form (→ FINAL).  This is why a single
      *  edge-target needs no bespoke logic — it routes back through {@link solve}.
      *
-     *  Re-recognition (not the node's tree children) is what surfaces the learnt
-     *  parts: content-defined chunking may cut "p1 p2" as "p1 p"|"2", so only
-     *  recognising the bytes recovers p1 and p2 as the forms the graph knows.
+     *  The produced bytes are decomposed by the machinery that owns their shape:
+     *  the span's LEAVES and SPLITS drive the split rule, which resolves each half
+     *  through findLeaf — so a part that straddles a content-defined cut is still
+     *  recovered even though the node's tree children need not align with the
+     *  learnt parts (the fold cuts "p1 p2" as "p1 p"|"2").  Recognised SITES are
+     *  filtered to the node's own kids: a produced form is completed out of what
+     *  it was built from, never by re-recognising arbitrary forms inside it.  That
+     *  filter is load-bearing — a 37-byte dialogue sentence carries seven hub
+     *  openers, and re-covering them chained through the corpus's whole
+     *  continuation population: 2.5 GB and OOM for `respond("hi.")`.
      *
      *  The recovered answer is accepted only when it MOVED and names a LEARNT node
      *  ({@link resolve}) — the graph itself gates against re-expanding a contained
-     *  form ("ice is cold" ⊅→ "ice is cold is cold").
+     *  form ("ice is cold" ⊅→ "ice is cold is cold").  An ACCEPTED completion is
+     *  then re-covered in turn, so a chain runs as deep as the graph licenses; a
+     *  rejected one ends its branch, so no work is spent past it.
      *
-     *  Termination is STRUCTURAL: a produced node is re-covered once, never inside
-     *  another re-cover (see the guard below), so one cover pays at most one
-     *  nested {@link solve} per distinct produced node it actually reaches, and
-     *  {@link recompleteMemo} collapses a repeat to nothing.
-     *
-     *  This comment used to argue termination from "distinct node ids are finite
-     *  and each finished completion is memoised".  That is a bound of N — the one
-     *  AGENTS §2.8 forbids — and it was load-bearing, not pedantic: nested, the
-     *  recursion reached depth 331 and 9.1 GB on an 18.9M-node store for a 2-byte
-     *  query and did not terminate, which is what killed a 5 h training run at its
-     *  checkpoint recall.  Guard: test/89-completion-recursion.test.mjs. */
+     *  Termination and cost are STRUCTURAL: {@link recompleteOpen} is the chain's
+     *  stack (membership is the cycle guard), {@link recompleteMemo} re-covers each
+     *  node at most once, only accepted completions recurse, and every level
+     *  deepens only the top derivation — so a cover pays for the chain it finds,
+     *  not for how densely the corpus interconnects the forms it passes through.
+     *  Guard: test/89-completion-recursion.test.mjs. */
     recompleteNode(node) {
         if (!this.host.recogniseSpan)
             return null;
         const memo = this.recompleteMemo;
         if (memo.has(node))
             return memo.get(node) ?? null;
-        // ONE re-cover per produced node — never a re-cover inside a re-cover.
-        //
         // Re-covering is how a PRODUCED node's bytes enter the search at all: the
-        // cover machinery otherwise only ever sees the QUERY's spans.  That is
-        // needed once.  The alternation of decomposition and recomposition that
-        // follows — parts rewriting several times, siblings fusing, a recomposition
-        // feeding another — is the main search's own fuse/`rcmp` work, not this
-        // recursion's: 15-decomposition-gap §9–§12 all pass with this method
-        // disabled outright, and only §6 (the produced composite "p1 p2", whose
-        // bytes nothing else brings in) needs it.
+        // cover machinery otherwise only ever sees the QUERY's spans.  The recursion
+        // is allowed to nest — a chain IS nested completions — but it is bounded so
+        // the work stays the ANSWER's (AGENTS §2.8): the stack below is the cycle
+        // guard, only ACCEPTED completions recurse, and the nested solve decomposes
+        // the form by its own shape instead of re-recognising the corpus's hub forms
+        // inside it.
         //
-        // Nesting it was the defect.  Each level is a full {@link solve} with its
-        // own agenda and chart, exploring from a node the answer never asked about,
-        // so per-query cost tracked how densely the corpus interconnects the forms
-        // passed through — the growth AGENTS §2.8 forbids.  Measured on an
-        // 18.9M-node store: depth 331 and 9.1 GB for a 2-byte query, not
-        // terminating; and on the guard corpus every one of 125 nested re-covers
-        // was REJECTED by the resolve() gate below, expanding a 70-byte node into a
-        // 374-byte concatenation that names nothing.  All of it was waste.
-        //
-        // `recompleteOpen` is that stack, so a non-empty stack means we are already
-        // inside one.  This subsumes the old cycle guard: a node cannot recurse
-        // back into itself when nothing recurses at all.
-        if (this.recompleteOpen.size > 0)
+        // `recompleteOpen` IS the stack of the chain being built, so MEMBERSHIP is
+        // the cycle guard: a node already open on this chain cannot re-enter it.
+        // Testing the NODE — not the stack's size — is what lets a completion
+        // recurse as deep as the graph licenses, exactly the intrinsic convergence
+        // {@link solve}'s contract states.  Work stays the answer's because the
+        // recursion only ever advances through an ACCEPTED completion (below) and
+        // {@link cover} deepens only the top derivation.
+        if (this.recompleteOpen.has(node))
             return null;
         // A leaf or single-child node has no parts to recompose; skip before the
         // costly recognition so a plain terminal answer pays nothing.
@@ -782,16 +792,43 @@ export class GraphSearch {
         const bytes = this.store.bytesPrefix(node, ALL);
         this.recompleteOpen.add(node);
         try {
-            // Completion is cover: re-cover the produced bytes through the SAME solve
-            // routine, recognising them afresh.  No concepts/connectors (those need the
-            // caller's async pre-resolution) — the recursion explores edges and fusion,
-            // which is what a deeper rewrite chain is made of.
-            const solved = this.solve(bytes.length, this.host.recogniseSpan(bytes), new Map());
+            // Completion is cover, but the produced form is decomposed by its own
+            // shape.  The LEAVES and SPLITS are kept whole, so the split rule still
+            // recovers a part that straddles a content-defined cut (the fold cuts
+            // "p1 p2" as "p1 p"|"2", and findLeaf still resolves p1 and p2).  The
+            // recognised SITES are filtered to the node's own kids, because
+            // re-recognising arbitrary forms inside the bytes is what let a hub-heavy
+            // utterance explode: a 37-byte dialogue sentence carries seven hub
+            // openers, and re-covering them chained through the corpus's whole
+            // continuation population (2.5 GB and OOM for `"hi."`).  No
+            // concepts/connectors either (those need the caller's async
+            // pre-resolution) — the recursion follows edges and fusion, which is what
+            // a deeper rewrite chain is made of.
+            const rec = this.host.recogniseSpan(bytes);
+            const kids = new Set(nrec.kids);
+            const solved = this.solve(bytes.length, {
+                sites: rec.sites.filter((s) => kids.has(s.payload)),
+                leaves: rec.leaves,
+                splits: rec.splits,
+                starts: rec.starts,
+            }, new Map(), undefined, undefined, undefined, this.derivationSink);
             const answer = solved && concatBytes(solved.segs.map((s) => s.bytes));
-            const out = (answer !== null && !bytesEqual(answer, bytes) &&
-                this.host.resolve(answer) !== null)
-                ? answer
+            // ACCEPT, then CONTINUE THE CHAIN — but only along an accepted
+            // completion.  A re-cover whose result is not itself a learnt node (the
+            // 70→374-byte concatenations that name nothing) ends its branch here
+            // instead of recursing into work the answer never asked for, and an
+            // accepted one names a node that is re-covered in turn.  That is what
+            // keeps a deep chain possible while the work stays proportional to the
+            // chain rather than to the corpus's interconnections.
+            const composed = answer !== null && !bytesEqual(answer, bytes)
+                ? this.host.resolve(answer)
                 : null;
+            if (composed === null) {
+                memo.set(node, null);
+                return null;
+            }
+            const deeper = this.recompleteNode(composed);
+            const out = deeper ?? answer;
             memo.set(node, out);
             return out;
         }
@@ -803,13 +840,19 @@ export class GraphSearch {
      *  outs of a long query re-cover each distinct node at most once); reset at the
      *  top of {@link cover}. */
     recompleteMemo = new Map();
-    /** The node currently being re-completed — the recursion stack, and so also
-     *  the nesting depth.  {@link recompleteNode} refuses to start while it is
-     *  non-empty (one re-cover per produced node, never one inside another), which
-     *  is what keeps a query's cost proportional to its answer rather than to the
-     *  corpus; it therefore holds at most one id.  A Set, not a flag, because it
-     *  states WHICH node is open — the invariant a reader needs to check the
-     *  guard, and what makes the old cycle-guard reading still hold. */
+    /** The derivation sink of the TOP cover, threaded into every nested
+     *  completion so a produced form's own recompositions are reported in the
+     *  same trace instead of vanishing after the first layer.  Undefined when
+     *  nothing is inspecting, so an uninspected response pays nothing. */
+    derivationSink;
+    /** The chain of nodes currently being re-completed — the recursion STACK.
+     *  MEMBERSHIP is the cycle guard ({@link recompleteNode} refuses a node
+     *  already open on this chain), which is what lets a completion recurse as
+     *  deep as the graph licenses while the work stays the answer's: the
+     *  recursion only advances through an ACCEPTED completion, every produced
+     *  form is decomposed into its own kids, and the memo re-covers each node at
+     *  most once per cover.  A Set, not a flag, because it states WHICH node is
+     *  open — the invariant a reader needs to check the guard. */
     recompleteOpen = new Set();
     /** out(i,j,bytes,…): index it for the binary rules, then offer splicing a
      *  learnt connector (the in-search bridge), splitting (at a sub-leaf form

package/dist/src/mind/mind.js

@@ -143,10 +143,24 @@ export class Mind {
             const { store: optsStore, mechanisms: userMechs, mechanismFactories: userFacts, canon: optsCanon, profile: optsProfile, ...rest } = (optsOrCfg ?? {});
             this._canonOpt = optsCanon ?? null;
             this._profile = optsProfile === true;
+            // `explicitSeed` is read BEFORE resolveConfig folds the default in, so
+            // the store can be consulted only when the caller did not choose.
+            const explicitSeed = rest.seed;
             this.cfg = resolveConfig(rest);
             this.store = optsStore ?? new SQliteStore({
                 maxGroup: this.cfg.geometry.maxGroup,
             });
+            // THE ARTIFACT'S SEED GOVERNS.  `train.seed` is recovered by the store at
+            // open, exactly like `train.D` and `geometry.maxGroup`.  The seed feeds
+            // `makeKeyring`, `Space.rand` and the `Alphabet` below, so folding a
+            // query under config.ts's default (42) against a store trained with
+            // another seed (e.g. 7) lands in a DIFFERENT vector space than the one
+            // the artifact's nodes were folded into: recognition and resonance then
+            // read the wrong space and every answer degrades silently.  An explicit
+            // caller seed still wins — this only replaces the unconfigured default.
+            if (explicitSeed === undefined && this.store.trainSeed !== null) {
+                this.cfg.seed = this.store.trainSeed;
+            }
             userMechanisms = userMechs ?? [];
             userFactories = userFacts ?? [];
         }

package/dist/src/store-sqlite.js

@@ -360,6 +360,23 @@ export class SQliteStore extends AbstractStore {
                     this._maxGroup = g;
             }
         }
+        // Recover the TRAINING seed exactly as D and maxGroup are recovered.  The
+        // seed seeds the alphabet and the seat keyring (mind.ts), so a Mind that
+        // folds a query under any other seed lands in a different vector space
+        // than the one this artifact's nodes were folded into — recognition,
+        // resonance and every mechanism downstream then read the wrong space.  The
+        // trainer persists `train.seed` and refuses to resume against a store
+        // trained with a different one (example/train_base/main.ts), so the value
+        // is authoritative for this artifact.  Absent on a store that was never
+        // trained, where the caller's configured seed stands.
+        {
+            const row = this.sqlite.prepare("SELECT val FROM meta WHERE key = 'train.seed'").get();
+            if (row) {
+                const s = Number(row.val);
+                if (Number.isInteger(s) && s >= 0)
+                    this._trainSeed = s;
+            }
+        }
         // Persist maxGroup to meta when opening a FRESH store (no rows yet) so
         // indexSubtree always sees the training-time value even when the store is
         // accessed without a Mind / full snapshot.

package/dist/src/store.d.ts

@@ -114,6 +114,16 @@ export declare class BoundedMap<K, V> {
 }
 export interface Store {
     readonly D: number;
+    /** The seed the artifact was TRAINED with, recovered from the store's own
+     *  `train.seed` metadata, or null for a store that was never trained.
+     *
+     *  This is not decoration: the seed feeds the alphabet and the seat keyring
+     *  (see the Mind constructor), so folding a query under any other seed lands
+     *  in a different vector space than the one the artifact's nodes were folded
+     *  into.  A Mind opening a trained store MUST adopt this seed unless the
+     *  caller explicitly overrides it — the same discipline that recovers
+     *  `train.D` and `geometry.maxGroup` from the metadata. */
+    readonly trainSeed: number | null;
     /** The work accumulator for the inference call in flight, or null.  The
      *  Mind attaches one per profiled response and detaches it after (see
      *  src/meter.ts).  A store MUST only ever write to it — no read may reach
@@ -475,6 +485,10 @@ export declare abstract class AbstractStore implements Store {
     protected efFor(clusterCount: number): number;
     protected _D: number;
     protected _maxGroup: number;
+    /** `train.seed` recovered by the backend at open, or null when the store was
+     *  never trained.  A backend that omits it simply reports null, which leaves
+     *  the caller's configured seed in force. */
+    protected _trainSeed: number | null;
     protected readonly minHaloMass: number;
     protected readonly efSearch: number;
     protected readonly overfetch: number;
@@ -563,6 +577,10 @@ export declare abstract class AbstractStore implements Store {
     protected _edgeSrcCount: number;
     constructor(config: StoreConfig, D: number, maxGroup: number);
     get D(): number;
+    /** The seed the artifact was trained with, recovered from `train.seed` at
+     *  open.  Null for a store that was never trained.  See
+     *  {@link Store.trainSeed} for why this must govern inference. */
+    get trainSeed(): number | null;
     /** Await the async initialisation performed by the concrete constructor. */
     protected _ensureReady(): Promise<void>;
     has(id: NodeId): boolean;

package/dist/src/store.js

@@ -434,6 +434,10 @@ export class AbstractStore {
     // ── Config ─────────────────────────────────────────────────────────────
     _D;
     _maxGroup;
+    /** `train.seed` recovered by the backend at open, or null when the store was
+     *  never trained.  A backend that omits it simply reports null, which leaves
+     *  the caller's configured seed in force. */
+    _trainSeed = null;
     minHaloMass;
     efSearch;
     overfetch;
@@ -552,6 +556,12 @@ export class AbstractStore {
     get D() {
         return this._D;
     }
+    /** The seed the artifact was trained with, recovered from `train.seed` at
+     *  open.  Null for a store that was never trained.  See
+     *  {@link Store.trainSeed} for why this must govern inference. */
+    get trainSeed() {
+        return this._trainSeed;
+    }
     /** Await the async initialisation performed by the concrete constructor. */
     async _ensureReady() {
         if (!this._ready)

package/docs/INDEX.md

@@ -0,0 +1,71 @@
+# Sema Documentation Index
+
+Sema is a single system stated three ways: the law lives in `docs/architecture/`
+(what holds), the prescription in `AGENTS.md` bootloader (what to do and where),
+and the proof in `test/` (pins that fail when the law is broken).
+
+## Routing — what to read for each task
+
+| Task                        | Read                                                                               | Why                                                                                   |
+| --------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Add a mechanism             | `docs/architecture/mechanism-market.md` + `docs/mechanisms/*.md`                   | Market contract: decoupled, declared competence, visible budget, evidence travels     |
+| Add a threshold             | `docs/architecture/thresholds.md`                                                  | All cutoffs are formulas over D/W/N in `geometry.ts`; `config.ts` holds only budgets  |
+| Debug an answer             | `docs/architecture/cost-model.md` + `src/meter.ts`                                 | One cost ladder (`MICRO`/`STEP`/`CONCEPT`/`PASS`) decides every grounding choice      |
+| Understand the fold         | `docs/architecture/fold-contract.md`                                               | Deposit and inference must compute the same tree; boundaries are not turn metadata    |
+| Add a store backend         | `docs/architecture/store.md` + `docs/architecture/bounded-reads.md`                | `AbstractStore` owns domain logic; backends are thin wrappers with capped reads       |
+| Add an ALU operation        | `src/alu/README.md`                                                                | One `registry.derive` per op composing existing ops; no new `derive` needed           |
+| Add a matcher or projection | `docs/architecture/match-project.md`                                               | Mechanisms are `(matcher, direction, gate)` configs over the shared `match.ts` family |
+| Add a deduction rule        | `docs/architecture/cost-model.md` + `docs/architecture/determinism.md`             | Place cost on the ladder, keep heuristic admissible, extend `classifyMove`            |
+| Change vector search        | `docs/architecture/exact-vs-approximate.md` + `docs/architecture/bounded-reads.md` | Scores propose, bytes dispose; ANN is bounded by `hubBound`                           |
+| Profile or bound work       | `docs/architecture/meter.md` + `docs/architecture/bounded-reads.md`                | `meter.ts` is write-only; counters are product, phases are hints                      |
+
+## Architecture laws (13)
+
+| Law | File                                        | Summary                                                                                                     | Pins                 |
+| --- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------- |
+| 1   | `docs/architecture/determinism.md`          | No `Math.random`/`Date.now` in behaviour; seed-derived randomness; corpus-determined tie-breaks             | `test/20`            |
+| 2   | `docs/architecture/thresholds.md`           | Every decision cutoff derived in `geometry.ts` over D/W/N; no tunable knobs                                 | `test/40`, `test/64` |
+| 3   | `docs/architecture/exact-vs-approximate.md` | Vector scores rank only; identity via content-addressed lookup; five graded ladders                         | `test/51`            |
+| 4   | `docs/architecture/cost-model.md`           | Single ladder `MICRO`/`STEP`/`CONCEPT`/`PASS`; weight `moves + PASS·unaccounted`; `STEP`-grade compare      | `test/04`, `test/55` |
+| 5   | `docs/architecture/match-project.md`        | Shared `match.ts` family (`locate`/`alignGraded`/`frameSlots`/`project`); voicing gates belong to consumers | `test/24`, `test/76` |
+| 6   | `docs/architecture/mechanism-market.md`     | `PipelineMechanism` (`floor`/`run`/`parse`); admissible-floor pruning and investment discipline             | `test/01`, `test/04` |
+| 7   | `docs/architecture/commonality.md`          | Two populations: corpus-global (`reachOf`+`dominates`) vs weave-local (`depth[]`)                           | `test/17`, `test/34` |
+| 8   | `docs/architecture/bounded-reads.md`        | No per-query read grows with N; `hubBound=√N` enforced at store via LIMIT/probe/prefix caps                 | `test/77`, `test/90` |
+| 9   | `docs/architecture/store.md`                | `AbstractStore` owns dedup/indexing/batch; `store-sqlite.ts` is thin wrappers; canon index optional         | `test/08`            |
+| 10  | `docs/architecture/fold-contract.md`        | `perceiveDeposit` and `perceive` agree; `contentLevels` is single boundary rule; no W/offset dependence     | `test/59`, `test/63` |
+| 11  | `docs/architecture/memoization.md`          | `Precomputed` is per-response lazy cache (promise-cached async); `beginResponse`/`endResponse` lifecycle    | `test/42`            |
+| 12  | `docs/architecture/saturation.md`           | Every walk names a deciding saturation beside its cap; cap is safety net, not decision                      | `test/27`, `test/16` |
+| 13  | `docs/architecture/meter.md`                | `meter.ts` is write-only work accounting; counts are deterministic, phases nest                             | `test/55`            |
+
+## Mechanisms (8)
+
+| Mechanism         | File                                   | Role                                                      |
+| ----------------- | -------------------------------------- | --------------------------------------------------------- |
+| cover             | `docs/mechanisms/cover.md`             | Exact/computed-span covering via `GraphSearch`            |
+| cast              | `docs/mechanisms/cast.md`              | Weave-local analogy via `depth[]` frame gate              |
+| confluence        | `docs/mechanisms/confluence.md`        | Corpus-global filler/scaffolding gate over climb          |
+| extraction        | `docs/mechanisms/extraction.md`        | Located-frame read-out with anchored span accounting      |
+| reference         | `docs/mechanisms/reference.md`         | Slot-bound voicing of asker-supplied referents            |
+| recall            | `docs/mechanisms/recall.md`            | Nearest stored form; echo tier via substitution bridge    |
+| prefix-completion | `docs/mechanisms/prefix-completion.md` | Literal prefix of exactly one trained form                |
+| alu               | `docs/mechanisms/alu.md`               | Authoritative computed spans (`parse` → `aluToMechanism`) |
+
+## Supporting docs
+
+| Doc                                       | Role                                                                            |
+| ----------------------------------------- | ------------------------------------------------------------------------------- |
+| `docs/architecture/caches.md`             | Every acceleration is a `BoundedMap`; miss re-derives; budgets in `StoreConfig` |
+| `docs/architecture/halo-sketch.md`        | Halo & sketch — distributional memory, quantization, bottom-k profiles          |
+| `docs/architecture/factored-machinery.md` | Single-definition contracts table — one owner per shared symbol                 |
+
+## Cross-cutting
+
+- `docs/INVARIANTS.md` — the five invariants (determinism, derived thresholds,
+  exact-decides, one cost currency, bounded reads) with file-level routing.
+- `docs/failures/tempting-but-wrong.md` — refuted simplifications that passed
+  review but failed pins (e.g. reordering ladders, flattening attention
+  asymmetries, one-cone-exhausted stop).
+- `docs/harness/gates.md` — how `AGENTS.md` recipes,
+  `bench/profile-inference.mjs`, and `test/*.test.mjs` enforce the laws.
+- `docs/architecture/` — full per-law derivation (each file states why the law
+  is this way; no separate HOW).

package/docs/INVARIANTS.md

@@ -0,0 +1,19 @@
+# INVARIANTS — Laws, Proofs, Derivations
+
+> Law in `docs/architecture/*.md`, proof in `test/*.test.mjs`.
+
+| #  | Law                                  | Where defined (src symbol)                                                                                                            | Pins (test/N)       | Doc (docs/architecture/*.md) |
+| -- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------------- |
+| 1  | Determinism                          | `src/config.ts:seed` `src/alphabet.ts:Alphabet` `src/mind/traverse.ts:guidedFirst`                                                    | `test/20` `test/42` | `determinism.md`             |
+| 2  | Derived thresholds                   | `src/geometry.ts:mergeThreshold,identityBar,reachThreshold,significanceBar,consensusFloor,dominates`                                  | `test/64` `test/40` | `thresholds.md`              |
+| 3  | Exact decides / approximate proposes | `src/mind/primitives.ts:resolve` `src/mind/match.ts:locate,alignGraded` `src/mind/resonance.ts:bridge`                                | `test/51`           | `exact-vs-approximate.md`    |
+| 4  | One cost currency                    | `src/mind/graph-search.ts:MICRO,STEP,CONCEPT,PASS` `src/derive:lightestDerivation` (min,+) `src/mind/attention.ts:poolVotes` (+,+)    | `test/55` `test/04` | `cost-model.md`              |
+| 5  | Bounded reads                        | `src/store.ts:AbstractStore:nextFirst,parentsFirst,containersSlice,hasNext,bytesPrefix` `src/mind/traverse.ts:hubBound,hubCap`        | `test/90` `test/14` | `bounded-reads.md`           |
+| 6  | Fold contract                        | `src/geometry.ts:contentLevels` `src/mind/canonical.ts:canonicalWindows,chainReach` `src/canon.ts:canonicalizer`                      | `test/59` `test/63` | `fold-contract.md`           |
+| 7  | Mechanism market                     | `src/mind/pipeline-mechanism.ts:PipelineMechanism,Precomputed` `src/mind/pipeline.ts:think,worthRunning`                              | `test/01` `test/04` | `mechanism-market.md`        |
+| 8  | Two commonality measures             | `src/mind/traverse.ts:reachOf,dominates,corpusN` (global) `src/mind/match.ts:depth[],MIN_WEAVE` (weave-local)                         | `test/17` `test/34` | `commonality.md`             |
+| 9  | Memoization idempotence              | `src/mind/pipeline-mechanism.ts:Precomputed` `src/mind/mind.ts:beginResponse,endResponse,_resolvedSubtrees`                           | `test/42`           | `memoization.md`             |
+| 10 | Caches as budgets                    | `src/store.ts:BoundedMap` `src/config.ts:StoreConfig:bytesCacheMax,recCacheBytes,haloCacheBytes`                                      | `test/96` `test/91` | `caches.md`                  |
+| 11 | Honest degradation                   | `src/mind/pipeline.ts:weight=moves+PASS*unaccounted` `src/store.ts:BoundedMap:miss→re-derive`                                         | `test/28` `test/84` | `store.md`+`caches.md`       |
+| 12 | Meter contracts                      | `src/meter.ts:Meter,PhaseCost,time` `src/mind/pipeline-mechanism.ts:Precomputed.shared`                                               | `test/55`           | `meter.md`                   |
+| 13 | Saturation                           | `src/mind/traverse.ts:edgeAncestors:SaturationReason` `src/mind/junction.ts:junctionContainersFrom` `src/mind/resonance.ts:pivotInto` | `test/27` `test/16` | `saturation.md`              |