@hviana/sema 0.7.2 → 0.7.5

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/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;
@@ -570,9 +588,6 @@ export declare abstract class AbstractStore implements Store {
     nodeCount(): number;
     size(): Promise<number>;
     get(id: NodeId): NodeRec | null;
-    /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
-     *  Iterative post-order on an explicit stack — the call stack never sees the
-     *  tree depth, so even an adversarial chain of nodes stays safe. */
     /** How many reads hit a MISSING node record this session (a dangling edge
      *  or kid id).  Zero in a healthy store; a growing count means references
      *  outlive their records — the read degrades safely to empty bytes, this
@@ -582,6 +597,25 @@ export declare abstract class AbstractStore implements Store {
      *  nothing is profiling.  Every read below bumps it through `?.`, so an
      *  unprofiled store pays one null check per read and allocates nothing. */
     meter: Meter | null;
+    /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
+     *  Iterative post-order on an explicit stack — the call stack never sees the
+     *  tree depth, so even an adversarial chain of nodes stays safe.
+     *
+     *  TERMINATION.  The walk memoizes into a LOCAL map, and `_bytesCache` is
+     *  consulted only as a warm hint whose hit is immediately promoted into that
+     *  map.  It used to use `_bytesCache` itself as the memo, which is not a
+     *  memo at all: it EVICTS, and its `"smallest"` policy prefers precisely the
+     *  freshly-resolved small children that the pending parents on the stack are
+     *  waiting for.  A parent then finds them uncached again, re-pushes them,
+     *  they are re-resolved, re-inserted, re-evicted — the loop makes no
+     *  progress and never exits.  Latent until the cache saturates, then
+     *  unconditional: observed in the wild at 19.9M nodes with the 20 MB cache
+     *  pinned at 19,999,962/20,000,000 bytes, spinning 8h45m on a node whose
+     *  whole content was 124 bytes (5 kids, 2 of them perpetually re-evicted).
+     *  Because the loop is synchronous, no timer could fire — the trainer's stall
+     *  watchdog never got a turn either.  A local map resolves each node at most
+     *  once per call, so the walk terminates by construction and `_bytesCache`
+     *  goes back to being a pure speed hint. */
     bytes(id: NodeId): Uint8Array;
     /** First `maxLen` bytes of a node.  Walks only the leftmost branch,
      *  stopping at `maxLen` — so a 1 MB document root costs the same as a
@@ -665,7 +699,20 @@ export declare abstract class AbstractStore implements Store {
      *  common-prefix / common-suffix trim: whatever remains after both trims is
      *  the single differing span (substitution, insertion or deletion), and both
      *  remainders must fit the budget.  Scattered differences leave a wide
-     *  middle and are rejected. */
+     *  middle and are rejected.
+     *
+     *  Every read here is CAPPED (§2.8).  It used to open with
+     *  `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the
+     *  full materialising `bytes()` read — on the deposit hot path, and only
+     *  then compare lengths.  So a candidate the length test was about to reject
+     *  had already been reconstructed byte for byte.  The LENGTHS decide first
+     *  instead, from the `contentLen` memo the interning order has already built
+     *  bottom-up, and the target's length is itself read under a cap: a target
+     *  longer than `la + W` is rejected without touching one of its bytes.
+     *  Same semantics — the old capped `b` read would have produced
+     *  `a.length + W + 1` here and failed the very same test — strictly fewer
+     *  byte reads.  The `+ 1` on each byte cap keeps `_prefix`'s
+     *  "complete reconstruction" test true, so the results still cache. */
     private differsByOneWindow;
     putLeaf(bytes: Uint8Array, gist: Vec): Promise<NodeId>;
     putBranch(kids: NodeId[], gist: Vec): Promise<NodeId>;

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)
@@ -591,9 +601,6 @@ export class AbstractStore {
             this._recCache.set(id, rec);
         return rec;
     }
-    /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
-     *  Iterative post-order on an explicit stack — the call stack never sees the
-     *  tree depth, so even an adversarial chain of nodes stays safe. */
     /** How many reads hit a MISSING node record this session (a dangling edge
      *  or kid id).  Zero in a healthy store; a growing count means references
      *  outlive their records — the read degrades safely to empty bytes, this
@@ -603,6 +610,25 @@ export class AbstractStore {
      *  nothing is profiling.  Every read below bumps it through `?.`, so an
      *  unprofiled store pays one null check per read and allocates nothing. */
     meter = null;
+    /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
+     *  Iterative post-order on an explicit stack — the call stack never sees the
+     *  tree depth, so even an adversarial chain of nodes stays safe.
+     *
+     *  TERMINATION.  The walk memoizes into a LOCAL map, and `_bytesCache` is
+     *  consulted only as a warm hint whose hit is immediately promoted into that
+     *  map.  It used to use `_bytesCache` itself as the memo, which is not a
+     *  memo at all: it EVICTS, and its `"smallest"` policy prefers precisely the
+     *  freshly-resolved small children that the pending parents on the stack are
+     *  waiting for.  A parent then finds them uncached again, re-pushes them,
+     *  they are re-resolved, re-inserted, re-evicted — the loop makes no
+     *  progress and never exits.  Latent until the cache saturates, then
+     *  unconditional: observed in the wild at 19.9M nodes with the 20 MB cache
+     *  pinned at 19,999,962/20,000,000 bytes, spinning 8h45m on a node whose
+     *  whole content was 124 bytes (5 kids, 2 of them perpetually re-evicted).
+     *  Because the loop is synchronous, no timer could fire — the trainer's stall
+     *  watchdog never got a turn either.  A local map resolves each node at most
+     *  once per call, so the walk terminates by construction and `_bytesCache`
+     *  goes back to being a pure speed hint. */
     bytes(id) {
         if (this.meter) {
             this.meter.byteReads++;
@@ -619,10 +645,22 @@ export class AbstractStore {
             return hit;
         const stack = [id];
         const cache = this._bytesCache;
+        // The walk's own memo.  Entries are the same shared arrays `_bytesCache`
+        // holds (no extra copy), and it lives exactly as long as this call.
+        const done = new Map();
         while (stack.length > 0) {
             const nid = stack[stack.length - 1]; // peek
-            // Already resolved by an earlier traversal.
-            if (cache.get(nid)) {
+            // Already resolved by this walk — the ONLY authority the readiness test
+            // below trusts, because it cannot be evicted underneath us.
+            if (done.has(nid)) {
+                stack.pop();
+                continue;
+            }
+            // Warm hint: a hit is promoted into `done` in the same step, so from
+            // here on the entry is pinned for the rest of the walk.
+            const warm = cache.get(nid);
+            if (warm !== undefined) {
+                done.set(nid, warm);
                 stack.pop();
                 continue;
             }
@@ -634,21 +672,26 @@ export class AbstractStore {
                 // The cache makes the empty read permanent for the session; the
                 // counter survives as the visible trace.
                 this.danglingReads++;
+                done.set(nid, _ZERO);
                 cache.set(nid, _ZERO);
                 stack.pop();
                 continue;
             }
             if (rec.leaf) {
-                cache.set(nid, new Uint8Array(rec.leaf));
+                // COPY before caching: rec.leaf is the node record's own buffer, and
+                // handing it out would let one mutating caller corrupt the record.
+                const leaf = new Uint8Array(rec.leaf);
+                done.set(nid, leaf);
+                cache.set(nid, leaf);
                 stack.pop();
                 continue;
             }
-            // Branch — push any uncached children (reverse order so they resolve
-            // left-to-right).  If every child is already cached, concatenate now.
+            // Branch — push any unresolved children (reverse order so they resolve
+            // left-to-right).  If every child is resolved, concatenate now.
             const kids = rec.kids ?? [];
             let ready = true;
             for (let i = kids.length - 1; i >= 0; i--) {
-                if (!cache.get(kids[i])) {
+                if (!done.has(kids[i])) {
                     stack.push(kids[i]);
                     ready = false;
                 }
@@ -656,10 +699,11 @@ export class AbstractStore {
             if (!ready)
                 continue;
             stack.pop();
-            const out = concat(kids.map((k) => cache.get(k)));
+            const out = concat(kids.map((k) => done.get(k)));
+            done.set(nid, out);
             cache.set(nid, out);
         }
-        const out = cache.get(id) ?? _ZERO;
+        const out = done.get(id) ?? _ZERO;
         if (this.meter)
             this.meter.bytesRead += out.length;
         return out;
@@ -1189,10 +1233,33 @@ export class AbstractStore {
      *  common-prefix / common-suffix trim: whatever remains after both trims is
      *  the single differing span (substitution, insertion or deletion), and both
      *  remainders must fit the budget.  Scattered differences leave a wide
-     *  middle and are rejected. */
+     *  middle and are rejected.
+     *
+     *  Every read here is CAPPED (§2.8).  It used to open with
+     *  `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the
+     *  full materialising `bytes()` read — on the deposit hot path, and only
+     *  then compare lengths.  So a candidate the length test was about to reject
+     *  had already been reconstructed byte for byte.  The LENGTHS decide first
+     *  instead, from the `contentLen` memo the interning order has already built
+     *  bottom-up, and the target's length is itself read under a cap: a target
+     *  longer than `la + W` is rejected without touching one of its bytes.
+     *  Same semantics — the old capped `b` read would have produced
+     *  `a.length + W + 1` here and failed the very same test — strictly fewer
+     *  byte reads.  The `+ 1` on each byte cap keeps `_prefix`'s
+     *  "complete reconstruction" test true, so the results still cache. */
     differsByOneWindow(kids, targetId, W) {
-        const a = concat(kids.map((k) => this.bytesPrefix(k, Number.MAX_SAFE_INTEGER)));
-        const b = this.bytesPrefix(targetId, a.length + W + 1);
+        const lens = kids.map((k) => this.contentLen(k));
+        let la = 0;
+        for (const n of lens)
+            la += n;
+        const cap = la + W + 1;
+        // `contentLen` under a cap returns a clamped LOWER BOUND once the partial
+        // sum reaches it, so `>= cap` is exactly "longer than la + W".
+        const lb = this.contentLen(targetId, cap);
+        if (lb >= cap || Math.abs(la - lb) > W)
+            return false;
+        const a = concat(kids.map((k, i) => this.bytesPrefix(k, lens[i] + 1)));
+        const b = this.bytesPrefix(targetId, lb + 1);
         if (Math.abs(a.length - b.length) > W)
             return false;
         const n = Math.min(a.length, b.length);

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`              |

package/docs/architecture/bounded-reads.md

@@ -0,0 +1,85 @@
+# Bounded Reads — No Per-Query Read Grows With the Corpus
+
+> **Law:** the cost of one query is proportional to the query, not to how much
+> was learned. No per-query read may grow with corpus size N.
+
+Every fan-out, walk, and disambiguation is capped at `hubBound` —
+`ceil(sqrt(N))` — derived once from `corpusN` and floored at 2 so `sqrt` and
+`ln` stay meaningful on a near-empty store. There is no second convention; do
+not invent one.
+
+## Scale
+
+```
+corpusN(ctx) = max(2, store.edgeSourceCount())   // distinct learnt contexts
+hubBound(ctx) = ceil(sqrt(corpusN(ctx)))          // >= 2, the store cap
+hubCap(ctx, ids) = ids.slice(0, hubBound(ctx))    // list-side reading
+boundFor(n) = ceil(sqrt(max(2, n)))               // ctx-free reading
+```
+
+Defined once in `mind/traverse.ts` (`corpusN`, `hubBound`, `hubCap`,
+`boundFor`). Every consumer imports them; never spell `Math.sqrt` inline.
+
+## Enforcement at the store level
+
+The cap is not advisory — adapters must make bounded reads bounded in SQL.
+
+### 1. LIMITed reads — real `LIMIT ?`
+
+`nextFirst(id, limit)`, `prevFirst(id, limit)`, `parentsFirst(id, limit)`,
+`containersSlice(child, offset, limit)`.
+
+Same statement and `ORDER BY` as the full read, with `LIMIT ?`. Never
+"materialise then slice". Reading `hubBound + 1` parents decides "hub or not"
+exactly without reading the rest. Implemented as thin wrappers in
+`store-sqlite.ts` over `AbstractStore` in `store.ts`.
+
+### 2. Existence probes — indexed point probes
+
+`hasNext(id)`, `hasParents(id)`, `hasContainers(child)`, `hasHalo(id)`,
+`prevCount(id)`.
+
+One indexed `EXISTS` / `COUNT` probe that never decodes vectors or unpacks
+blobs. Use them for every "does this lead anywhere?" question instead of
+`next(id).length > 0` or `prev(id).length`. `prevCount` is the reverse-edge
+support count for `chooseNext`/`chooseAmong`; `hasNext`/`hasHalo` gate the
+`leadsSomewhere` admission predicate in `mind/traverse.ts`.
+
+### 3. Prefix-capped reads — reject without reconstruction
+
+`bytesPrefix(id, cap)` and `contentLen(id, cap)`.
+
+`contentLen` under a cap returns an exact length below the cap and `>= cap`
+otherwise — an indexed memo walk that stops early, never a full subtree walk.
+`bytesPrefix` stops after `cap` bytes. A candidate exceeding the cap is rejected
+on the length probe alone; the weave, junction walks, and bridge all read this
+way. Uncapped reads there cost seconds per query on a large store.
+
+### 4. Transparent scaffolding — one bounded read
+
+`chainRun(id)` climbs a run of transparent nodes (exactly one parent, no edges)
+in a single recursive CTE, cached for the store lifetime and dropped on writes
+that break transparency. The climber hops the whole run where a node-at-a-time
+ascent would pay three probes per node.
+
+## Maintenance only
+
+The full materialising reads — `next(id)`, `prev(id)`, `parents(id)`,
+`containers(child)` — exist for inspection, repair, and compaction only
+(`compactContentIndex`, `repairContentIndex`). Keep them off hot paths.
+
+## Adding a walk
+
+Any new fan-out walk uses `hubBound`/`hubCap`. Do not call `edgeSourceCount()`
+or `Math.ceil(Math.sqrt(...))` inline, and do not invent a per-walk limit. The
+walk's saturation decision (when to stop) is separate from the cap (the safety
+net); a walk with only a cap drifts to the cap.
+
+## Pins
+
+- `test/14` — sublinear inference in corpus size and constant-rate in input
+  length; training throughput floor; exact recall at scale.
+- `test/89` — completion recursion stays output-sensitive (nested searches/pops
+  sublinear); guards the count of reads, not just per-read size.
+- `test/90` — connector probe (`resolveConnectors`) reads by the query length
+  (`QUERY.length + 1`), not by the learnt continuation; per-read size bound.

package/docs/architecture/caches.md

@@ -0,0 +1,89 @@
+# Caches — Every Acceleration Is a BoundedMap
+
+> **Law:** every acceleration is a `BoundedMap` with a byte budget. A miss
+> re-derives from durable state. Degradation order is speed/reach lost, never
+> identity.
+
+No cache may change what is stored, what is resolved, or what tree is folded.
+Eviction costs a re-read, a re-walk, or a narrower reach — never a wrong answer
+or a wrong tree.
+
+## `BoundedMap` — the one cache primitive
+
+`src/store.ts:BoundedMap<K,V>` — LRU with byte accounting (`maxBytes`, `sizeOf`,
+`evict`, `recency`).
+
+- `evict: "lru"` — uniform-cost entries (dedup, vectors, records).
+- `evict: "smallest"` — variable-cost reconstruction (`_bytesCache`): protects
+  expensive large branches over cheap leaves.
+- `recency: "reorder"` (default) — exact LRU via `delete+set`; required when
+  eviction choice is load-bearing (`_depositTrees` — 8 entries, victim changes
+  fold).
+- `recency: "clock"` — bit instead of reorder; only for transparent caches where
+  wrong victim costs a re-read (`_bytesCache`, `_recCache`). Measured: same
+  entries cached, hot-path time 55% → bit.
+
+Persistent cursor over V8 insertion order makes eviction amortised O(1);
+candidate window for `"smallest"` never rescans from front.
+
+## Store caches — budgets in `src/config.ts:StoreConfig`
+
+| Cache               | Field                      | Budget                       | `sizeOf`            | Eviction       |
+| ------------------- | -------------------------- | ---------------------------- | ------------------- | -------------- |
+| dedup leaf/branch   | `_leafKey` / `_branchKey`  | `dedupCacheMax` 1M entries   | 1                   | lru            |
+| reconstructed bytes | `_bytesCache`              | `bytesCacheMax` 20 MB        | `byteLength`        | smallest+clock |
+| content length      | `_lenCache`                | `bytesCacheMax`              | 16                  | lru            |
+| node records        | `_recCache`                | `recCacheBytes` 10 MB        | leaf+4·kids+12      | lru+clock      |
+| pending gists       | `_pendingGist`             | `pendingGistBytes` 16 MB     | `byteLength` (D·4)  | lru            |
+| halo exact / norm   | `_haloExact` / `_haloNorm` | `haloCacheBytes` 16 MB each  | `byteLength`        | lru            |
+| skipped interiors   | `_coveredIds`              | `coveredIdsMax` 100K entries | 1                   | lru            |
+| indexed ids         | `_indexedIds`              | `coveredIdsMax`              | 1                   | lru            |
+| transparent chains  | `_chainMemo`               | `chainCacheBytes` 16 MB      | 4·len+32            | lru            |
+| ingest memo         | `CachedIngest._memo`       | `ingestCacheBytes` 50 MB     | vector+ids+keyBytes | lru            |
+
+ANN read caches (`_resonateCache`, `_resonateHaloCache`) are `Map<string,Hit[]>`
+keyed by `vecKey(v)+":"+k`, dropped on any index mutation.
+`vectorCacheMb`/`sqliteCacheMb` are pure page-cache latency knobs.
+
+`_bytesCache` only caches complete reconstructions — `bytesPrefix(id,cap)` with
+`got < cap`; a truncated prefix is never stored. `_chainMemo` is dropped on any
+write that could break transparency; `_pendingGist` eviction falls back to DAG
+climb; halo eviction re-decodes the durable 2-bit row.
+
+## Mind caches — session and per-response
+
+| Cache               | Location                                         | Budget    | Scope / invalidation                                               |
+| ------------------- | ------------------------------------------------ | --------- | ------------------------------------------------------------------ |
+| `_gistCache`        | `Mind._gistCache`                                | 32 MB     | session-lifetime, never invalidated (perception pure)              |
+| `_depositTrees`     | `Mind._depositTrees`                             | 8 entries | session; `perceiveDeposit` only when `conversational`              |
+| `_depositLens`      | `Mind._depositLens`                              | —         | byte lengths for prefix probes; cleared with map when >64          |
+| `_internIds`        | `Mind._internIds: WeakMap<Sema,number>`          | —         | Mind lifetime; ids permanent                                       |
+| `_resolvedSubtrees` | `Mind._resolvedSubtrees: WeakMap<Sema,{id,len}>` | —         | per-response/conversation; fast path only when `visit===undefined` |
+
+`REACH_MEMO_MAX` / `STRUCT_MEMO_MAX` 100K (`src/mind/traverse.ts`) — whole-climb
+and per-node structural probes (`hasNext`/`prevCount`/`hasParents`); cleared on
+write or when cap reached. `reachMemo`/`structCaches` keyed by `_structMemoKey`,
+bypassed under trace.
+
+## Deposit caches — offset-keyed, caller-discharged
+
+`_depositTrees`/`_depositLens`/`_internIds`/`_resolvedSubtrees` key **offsets**,
+not bytes, for O(1) reuse. Offsets alone cannot witness byte agreement — caller
+must discharge it.
+
+- Correct: conversation append — each turn extends the prior cumulative context
+  by its own bytes; longest cached proper prefix hit (`L < bytes.length`) reuses
+  `contentFoldIncremental` segments bit-identically.
+- Wrong: mismatched `prev` reused by offset produced wrong tree (336 vs 400
+  bytes) — a coincidental prefix length aliased unrelated content.
+- Now: `perceiveDeposit` keys by `latin1Key(bytes.subarray(0,L))` (prefix
+  bytes), probes longest cached proper prefix first; `_depositTrees` populated
+  only for conversational deposits (budget discipline), otherwise cold path
+  always correct.
+
+## Pins
+
+- `test/91` — `chainRun` via capped `_prefix`: bounded transparent-chain hop,
+  not per-node probes.
+- `test/96` — `_bytesCache` is byte-accounted `BoundedMap` that evicts; miss
+  re-derives.