@hviana/sema 0.9.0 → 0.9.2

package/dist/src/store-sqlite.js

@@ -124,6 +124,17 @@ CREATE TABLE IF NOT EXISTS canon (
   id INTEGER NOT NULL,
   PRIMARY KEY (h, id)
 ) WITHOUT ROWID;
+-- The canon index's negative filter, persisted so an open does not rescan the
+-- h column (seconds on a trained store).  Written in the SAME transaction as
+-- the canon rows it covers, stamped with the meta 'canon.upto' of that commit;
+-- a stamp that disagrees with the meta (rows a writer added without it) makes
+-- the filter stale, and it is rebuilt from the table instead.
+CREATE TABLE IF NOT EXISTS canon_bloom (
+  id   INTEGER PRIMARY KEY CHECK (id = 1),
+  bits BLOB NOT NULL,
+  n    INTEGER NOT NULL,
+  upto TEXT NOT NULL
+);
 -- CONSTITUENT SKETCH (Store.sketchGet/sketchPut): the bottom-k minimal
 -- constituents of a node's subtree, k = √D, chosen by identity hash.  The blob is
 -- a packed int32 little-endian run, already in hash order; an EMPTY blob is a
@@ -223,6 +234,20 @@ export class SQliteStore extends AbstractStore {
     _bloom = null;
     /** Dedup probes answered by the filter alone this session (observability). */
     bloomSkips = 0;
+    /** The same negative filter over the CANON index's key hashes.  Recognition's
+     *  canonical admission and the join's canonical entity scan ask `canonFind`
+     *  once per probed span, and almost every answer is "no such key" — on an
+     *  index that is often EMPTY (it is built only by `buildCanonIndex`).
+     *  Loaded on first use from `canon_bloom` when its stamp matches the meta,
+     *  else built by one sequential scan of the h column; kept exact on
+     *  `canonAdd` (rebuilt bigger from the table, uncommitted rows included,
+     *  when growth saturates it) and persisted with the commit that wrote the
+     *  rows.  The canon table is never deleted from, so the filter can never
+     *  hold a false negative: a miss it reports is a miss the query would have
+     *  returned. */
+    _canonBloom = null;
+    /** The in-memory canon filter differs from the persisted one. */
+    _canonBloomDirty = false;
     _insertNode = null;
     _insertKid = null;
     _selContain = null;
@@ -453,8 +478,10 @@ export class SQliteStore extends AbstractStore {
             "n = excluded.n, upto = excluded.upto").run(this._bloom.bits, this._bloom.n, this._nextId);
     }
     _dbClose() {
-        if (this.sqlite)
+        if (this.sqlite) {
             this._bloomPersist();
+            this._canonBloomPersist();
+        }
         if (this.content) {
             this.content.close();
             this.content = null;
@@ -478,6 +505,8 @@ export class SQliteStore extends AbstractStore {
     _dbCommitTx() {
         if (!this._inTx || !this.sqlite)
             return;
+        // The canon filter commits WITH the rows it covers — see canon_bloom.
+        this._canonBloomPersist();
         this._inTx = false; // clear first so a throw can't wedge us mid-commit
         this.sqlite.exec("COMMIT");
     }
@@ -534,6 +563,16 @@ export class SQliteStore extends AbstractStore {
         const row = this._selFlat.get(h, bytes);
         return row ? row.id : null;
     }
+    /** The node filter alone: never a false negative (every inserted hash is
+     *  added before any probe can see it), so `false` is exact. */
+    _dbFlatMayExist(h, bytes) {
+        if (this._bloom === null)
+            return super._dbFlatMayExist(h, bytes);
+        if (this._bloom.mightContain(h))
+            return true;
+        this.bloomSkips++;
+        return false;
+    }
     _dbFindBranchByKids(h, packed) {
         if (this._bloom && !this._bloom.mightContain(h)) {
             this.bloomSkips++;
@@ -855,8 +894,57 @@ export class SQliteStore extends AbstractStore {
         // bulk index build coalesces instead of paying autocommit per row.
         this._dbBeginTx();
         this._insCanon.run(h, id);
+        const b = this._canonFilter();
+        b.add(h);
+        // Rebuilt bigger at once, from the table as THIS connection sees it — the
+        // persisted filter cannot stand in, it lacks this transaction's rows.
+        if (b.saturated)
+            this._canonBloom = this._canonScan();
+        this._canonBloomDirty = true;
+    }
+    /** The canon filter: the persisted one when its stamp matches the meta,
+     *  else built from the index as it stands. */
+    _canonFilter() {
+        if (this._canonBloom === null) {
+            const row = this.sqlite.prepare("SELECT bits, n, upto FROM canon_bloom WHERE id = 1").get();
+            if (row !== undefined && row.upto === this._canonStamp()) {
+                const b = new NodeBloom(31 - Math.clz32(row.bits.length * 8));
+                b.bits.set(row.bits);
+                b.n = row.n;
+                this._canonBloom = b;
+            }
+            else {
+                this._canonBloom = this._canonScan();
+                this._canonBloomDirty = true;
+            }
+        }
+        return this._canonBloom;
+    }
+    _canonScan() {
+        const b = new NodeBloom(bloomLog2For(this.canonCount()));
+        const scan = this.sqlite.prepare("SELECT h FROM canon");
+        scan.setReturnArrays(true);
+        for (const r of scan.iterate())
+            b.add(r[0]);
+        return b;
+    }
+    /** What a persisted canon filter is stamped with: the incremental build's
+     *  cursor, which every canon writer advances in the transaction it writes. */
+    _canonStamp() {
+        return this._dbGetMeta("canon.upto") ?? "";
+    }
+    _canonBloomPersist() {
+        const b = this._canonBloom;
+        if (b === null || !this._canonBloomDirty || !this.sqlite)
+            return;
+        this.sqlite.prepare("INSERT INTO canon_bloom (id, bits, n, upto) VALUES (1, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET bits = excluded.bits, " +
+            "n = excluded.n, upto = excluded.upto").run(b.bits, b.n, this._canonStamp());
+        this._canonBloomDirty = false;
     }
     canonFind(h) {
+        if (!this._canonFilter().mightContain(h))
+            return [];
         if (!this._selCanon) {
             this._selCanon = this.sqlite.prepare("SELECT id FROM canon WHERE h = ?");
         }

package/dist/src/store.d.ts

@@ -1,5 +1,5 @@
 import { Vec } from "./vec.js";
-import { type StoreConfig } from "./config.js";
+import type { StoreConfig } from "./config.js";
 import type { Meter } from "./meter.js";
 /** A node id: a dense, non-negative integer assigned in creation order. */
 export type NodeId = number;
@@ -166,6 +166,20 @@ export interface Store {
      *  bytes — the allocation-free probe span scanners use.  Optional: a store
      *  without it is simply probed through `findBranch`. */
     findFlatBranch?(bytes: Uint8Array): NodeId | null;
+    /** Whether a flat branch with these bytes MAY exist.  `false` is EXACT — no
+     *  such node exists, and a {@link findFlatBranch} would return null; `true`
+     *  means only that a lookup is needed.  The existence half of the probe,
+     *  without its verification: a caller that will resolve the bytes anyway
+     *  (and so verify them) asks this to refuse a miss without paying for the
+     *  lookup a hit would repeat.  Optional, like the probe it answers for. */
+    flatBranchMayExist?(bytes: Uint8Array): boolean;
+    /** A {@link findFlatBranch} over spans of ONE buffer: `probe(start, end)`
+     *  answers exactly `findFlatBranch(bytes.subarray(start, end))`, but a span's
+     *  content hash extends the one its start was last probed at, so a scanner
+     *  that sweeps ends upward per start pays O(1) per probe instead of
+     *  O(span).  The buffer must not change while the prober is used.
+     *  Optional, like the probe it accelerates. */
+    flatSpans?(bytes: Uint8Array): (start: number, end: number) => NodeId | null;
     /** The branch nodes that list `id` among their children — the reverse of
      *  `get(id).kids`. Lets the structural DAG be climbed upward, from a
      *  recognised fragment to the larger learned forms that contain it. */
@@ -314,6 +328,12 @@ export interface Store {
      *  the search's fuse guard) must ask this instead: one row read, a mass
      *  compare, no decode. */
     hasHalo(id: NodeId): boolean;
+    /** THE ADMISSION PREDICATE — whether `id` LEADS SOMEWHERE: it bears a
+     *  continuation edge ({@link hasNext}) or a halo ({@link hasHalo}).  A form
+     *  that leads nowhere contributes nothing to any derivation.  This is the ONE
+     *  raw definition; `traverse.ts`'s `leadsSomewhere` is the same predicate with
+     *  its edge tier memoised for the response.  Two point probes at most. */
+    leadsSomewhere(id: NodeId): boolean;
     /** How many episode signatures were poured into `id`'s halo — the DIRECT
      *  measure of distributional evidence (each training pair pours once, so
      *  repetition counts, unlike {@link prevCount}, which counts DISTINCT
@@ -507,6 +527,9 @@ export declare abstract class AbstractStore implements Store {
     /** Exact-content dedup: content-key → node id. Intrinsic compression. */
     protected readonly _leafKey: BoundedMap<string, NodeId>;
     protected readonly _branchKey: BoundedMap<string, NodeId>;
+    /** {@link findFlatBranch}'s hits, keyed by the bytes themselves (latin1 —
+     *  exact, unlike the hash keys above). */
+    protected readonly _flatKey: BoundedMap<string, NodeId>;
     /** Reconstructed-bytes read cache (regenerable), keyed by node id. */
     protected readonly _bytesCache: BoundedMap<NodeId, Uint8Array>;
     /** contentLen memo — content is immutable, so entries never invalidate. */
@@ -643,10 +666,29 @@ export declare abstract class AbstractStore implements Store {
      *  answers most of those with no I/O at all, so the allocations dominated.
      *
      *  Pass a subarray: it is a view, so a caller scanning spans of a query
-     *  allocates nothing per probe.  Deliberately NOT memoized — its callers
-     *  probe many spans that miss, and a key string per probe is the cost this
-     *  exists to remove. */
+     *  allocates nothing per probe that misses.  HITS ARE MEMOIZED, MISSES ARE
+     *  NOT: the negative filter answers first, so a span that is not stored
+     *  builds no key; one that may be pays a key and then usually skips the
+     *  lookup — the spans the identity fold names are segments, a few bytes
+     *  each, asked over and over by every span that contains them.  A node, once
+     *  minted, keeps its bytes and its id, so a cached hit never goes stale. */
     findFlatBranch(bytes: Uint8Array): NodeId | null;
+    /** {@link Store.flatSpans}.  Each start keeps the hash of the span it was
+     *  last probed to, plus the hash one byte short of it; a probe ending at or
+     *  past that end extends it, one ending one byte short of it reuses the
+     *  second, and any other probe hashes from the start.  `hashOf` is FNV-1a,
+     *  a left fold over the bytes, so an extended hash IS the span's hash —
+     *  same key, same filter answer, same lookup. */
+    flatSpans(bytes: Uint8Array): (start: number, end: number) => NodeId | null;
+    /** {@link findFlatBranch} past the hash: `h` must be `hashOf(bytes)`. */
+    private _findFlatHashed;
+    /** {@link Store.flatBranchMayExist} — the backend's negative filter when it
+     *  keeps one ({@link _dbFlatMayExist}), else the lookup itself. */
+    flatBranchMayExist(bytes: Uint8Array): boolean;
+    /** Default: no filter, so anything MAY exist and the lookup decides.  A
+     *  backend with a negative filter over node hashes overrides this to answer
+     *  from the filter alone. */
+    protected _dbFlatMayExist(_h: number, _bytes: Uint8Array): boolean;
     findBranch(kids: NodeId[]): NodeId | null;
     parents(id: NodeId): NodeId[];
     parentsFirst(id: NodeId, limit: number): NodeId[];
@@ -792,6 +834,8 @@ export declare abstract class AbstractStore implements Store {
     /** {@link Store.hasHalo} — MUST mirror {@link halo}'s null condition
      *  exactly (row present AND mass ≥ minHaloMass), minus the decode. */
     hasHalo(id: NodeId): boolean;
+    /** {@link Store.leadsSomewhere} — edge first (the cheaper, commoner probe). */
+    leadsSomewhere(id: NodeId): boolean;
     pourHalo(id: NodeId, add: Vec): Promise<void>;
     resonateHalo(v: Vec, k: number): Promise<Hit[]>;
     private pending;

package/dist/src/store.js

@@ -29,6 +29,7 @@
 // essentials required for SQLite + VectorDatabase communication.
 import { addInto, copy, dot, normalize } from "./vec.js";
 import { identityBar } from "./geometry.js";
+import { latin1 } from "./bytes.js";
 /** Entry cap for the two ANN read caches ({@link AbstractStore._resonateCache}
  *  / `_resonateHaloCache`).  They are only dropped on index writes, so a long
  *  query-only session otherwise grows them without bound — a slow memory/GC
@@ -335,11 +336,13 @@ export function unpackKids(blob) {
 }
 /** 32-bit FNV-1a of a byte blob — the integer content hash `idx_node_h` keys
  *  on. Collisions are resolved by verifying the stored blob, never trusted. */
+const FNV_OFFSET = 0x811c9dc5 >>> 0;
+const FNV_PRIME = 0x01000193;
 function hashOf(bytes) {
-    let h = 0x811c9dc5 >>> 0;
+    let h = FNV_OFFSET;
     for (let i = 0; i < bytes.length; i++) {
         h ^= bytes[i];
-        h = Math.imul(h, 0x01000193) >>> 0;
+        h = Math.imul(h, FNV_PRIME) >>> 0;
     }
     return h >>> 0;
 }
@@ -458,6 +461,9 @@ export class AbstractStore {
     /** Exact-content dedup: content-key → node id. Intrinsic compression. */
     _leafKey;
     _branchKey;
+    /** {@link findFlatBranch}'s hits, keyed by the bytes themselves (latin1 —
+     *  exact, unlike the hash keys above). */
+    _flatKey;
     /** Reconstructed-bytes read cache (regenerable), keyed by node id. */
     _bytesCache;
     /** contentLen memo — content is immutable, so entries never invalidate. */
@@ -542,6 +548,7 @@ export class AbstractStore {
         this.compactEveryNWrites = config.compactEveryNWrites;
         this._leafKey = new BoundedMap(config.dedupCacheMax);
         this._branchKey = new BoundedMap(config.dedupCacheMax);
+        this._flatKey = new BoundedMap(config.dedupCacheMax, undefined, "lru", "clock");
         this._bytesCache = new BoundedMap(config.bytesCacheMax, (v) => v.byteLength, "smallest", "clock");
         this._lenCache = new BoundedMap(config.bytesCacheMax, () => 16);
         this._recCache = new BoundedMap(config.recCacheBytes, (r) => (r.leaf?.byteLength ?? 0) + (r.kids?.length ?? 0) * 4 + 12, "lru", "clock");
@@ -848,13 +855,82 @@ export class AbstractStore {
      *  answers most of those with no I/O at all, so the allocations dominated.
      *
      *  Pass a subarray: it is a view, so a caller scanning spans of a query
-     *  allocates nothing per probe.  Deliberately NOT memoized — its callers
-     *  probe many spans that miss, and a key string per probe is the cost this
-     *  exists to remove. */
+     *  allocates nothing per probe that misses.  HITS ARE MEMOIZED, MISSES ARE
+     *  NOT: the negative filter answers first, so a span that is not stored
+     *  builds no key; one that may be pays a key and then usually skips the
+     *  lookup — the spans the identity fold names are segments, a few bytes
+     *  each, asked over and over by every span that contains them.  A node, once
+     *  minted, keeps its bytes and its id, so a cached hit never goes stale. */
     findFlatBranch(bytes) {
+        return this._findFlatHashed(hashOf(bytes), bytes);
+    }
+    /** {@link Store.flatSpans}.  Each start keeps the hash of the span it was
+     *  last probed to, plus the hash one byte short of it; a probe ending at or
+     *  past that end extends it, one ending one byte short of it reuses the
+     *  second, and any other probe hashes from the start.  `hashOf` is FNV-1a,
+     *  a left fold over the bytes, so an extended hash IS the span's hash —
+     *  same key, same filter answer, same lookup. */
+    flatSpans(bytes) {
+        const n = bytes.length;
+        const runEnd = new Int32Array(n + 1).fill(-1);
+        const runH = new Uint32Array(n + 1);
+        const shortH = new Uint32Array(n + 1);
+        return (start, end) => {
+            let h;
+            let from;
+            const e0 = runEnd[start];
+            if (e0 >= 0 && e0 <= end) {
+                h = runH[start];
+                from = e0;
+            }
+            else if (e0 >= 0 && e0 - 1 === end && end > start) {
+                h = shortH[start];
+                from = end;
+            }
+            else {
+                h = FNV_OFFSET;
+                from = start;
+            }
+            let prev = h;
+            for (let i = from; i < end; i++) {
+                prev = h;
+                h = Math.imul(h ^ bytes[i], FNV_PRIME) >>> 0;
+            }
+            if (from < end) {
+                runEnd[start] = end;
+                runH[start] = h;
+                shortH[start] = prev;
+            }
+            return this._findFlatHashed(h, bytes.subarray(start, end));
+        };
+    }
+    /** {@link findFlatBranch} past the hash: `h` must be `hashOf(bytes)`. */
+    _findFlatHashed(h, bytes) {
         if (this.meter)
             this.meter.branchLookups++;
-        return this._dbFindBranchByLeaf(hashOf(bytes), bytes);
+        if (!this._dbFlatMayExist(h, bytes))
+            return null;
+        const key = bytes.length <= DEDUP_KEY_MAX ? latin1(bytes) : null;
+        if (key !== null) {
+            const hit = this._flatKey.get(key);
+            if (hit !== undefined)
+                return hit;
+        }
+        const id = this._dbFindBranchByLeaf(h, bytes);
+        if (id !== null && key !== null)
+            this._flatKey.set(key, id);
+        return id;
+    }
+    /** {@link Store.flatBranchMayExist} — the backend's negative filter when it
+     *  keeps one ({@link _dbFlatMayExist}), else the lookup itself. */
+    flatBranchMayExist(bytes) {
+        return this._dbFlatMayExist(hashOf(bytes), bytes);
+    }
+    /** Default: no filter, so anything MAY exist and the lookup decides.  A
+     *  backend with a negative filter over node hashes overrides this to answer
+     *  from the filter alone. */
+    _dbFlatMayExist(_h, _bytes) {
+        return true;
     }
     findBranch(kids) {
         if (this.meter)
@@ -1731,6 +1807,10 @@ export class AbstractStore {
         const r = this._dbGetHalo(id);
         return r !== null && r.mass >= this.minHaloMass;
     }
+    /** {@link Store.leadsSomewhere} — edge first (the cheaper, commoner probe). */
+    leadsSomewhere(id) {
+        return this.hasNext(id) || this.hasHalo(id);
+    }
     async pourHalo(id, add) {
         await this._ensureReady();
         // A node with a halo is a genuine resonance target — the consensus climb

package/docs/INDEX.md

@@ -19,24 +19,25 @@ proof in `test/` (pins that fail when the law is broken).
 | 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 (14)
+## Architecture laws (15)
 
-| 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`          | Three: global (`reachOf`+`dominates`), weave-local (`depth[]`), window rarity                                   | `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 exact, phases nest                                         | `test/55`            |
-| 14  | `docs/architecture/closure.md`              | A derivation is closed when its structure accounts for the question's remainder; every transition asks that law | `test/133`–`147`     |
+| 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; six 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, investment discipline, run-ahead bounds                                                                                                                                                     | `test/01`, `test/04`, `test/153`             |
+| 7   | `docs/architecture/commonality.md`          | Three: global (`reachOf`+`dominates`), weave-local (`depth[]`), window rarity                                                                                                                                                                                      | `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; the read side names a branch as `intern` does; `contentLevels` is single boundary rule; no W/offset dependence                                                                                                             | `test/59`, `test/63`, `test/148`, `test/152` |
+| 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 exact, phases nest                                                                                                                                                                                            | `test/55`                                    |
+| 14  | `docs/architecture/closure.md`              | A derivation is closed when its structure accounts for the question's remainder; every transition asks that law, one engine walks the layers                                                                                                                       | `test/133`–`151`                             |
+| 15  | `docs/architecture/evidence.md`             | A stored form is identified when the material at hand (question ∪ the node a derivation stands on) witnesses every byte of it, order-free; the question NAMES a continuation through its establishing context; a step it did not name pays from what is still owed | `test/154`                                   |
 
 ## Mechanisms (8)
 
@@ -65,6 +66,6 @@ proof in `test/` (pins that fail when the law is broken).
   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.
-- `docs/harness/gates.md` — how `AGENTS.md` recipes,
-  `bench/profile-inference.mjs`, and `test/*.test.mjs` enforce the laws.
+- `docs/harness/gates.md` — how `AGENTS.md` recipes, the meter's public path
+  (`profile: true` → `mind.lastCost`), and `test/*.test.mjs` enforce the laws.
 - `docs/architecture/` — per-law derivation: each file says why, not how.

package/docs/INVARIANTS.md

@@ -1,18 +1,19 @@
 # INVARIANTS — Laws, Proofs, Derivations
 
-| #  | Law                                  | Defined in                                                                                                                            | Pins                | Doc                       |
-| -- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------- |
-| 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) `cast.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                           | `traverse.ts:edgeAncestors,types.ts:SaturationReason` `src/mind/junction.ts:junctionContainersFrom` `src/mind/resonance.ts:pivotInto` | `test/27` `test/16` | `saturation.md`           |
-| 14 | Closure                              | `src/mind/derivation.ts:closed,admissible,advance`                                                                                    | `test/133`–`147`    | `closure.md`              |
+| #  | Law                                  | Defined in                                                                                                                                                             | Pins                           | Doc                       |
+| -- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------- |
+| 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,contentIdentity` `src/mind/primitives.ts:branchNaming` `src/mind/canonical.ts:canonicalWindows,chainReach` `src/canon.ts:canonicalizer` | `test/59` `test/63` `test/152` | `fold-contract.md`        |
+| 7  | Mechanism market                     | `src/mind/pipeline-mechanism.ts:PipelineMechanism,Precomputed` `src/mind/pipeline.ts:think,worthRunning`                                                               | `test/01` `test/04` `test/153` | `mechanism-market.md`     |
+| 8  | Two commonality measures             | `src/mind/traverse.ts:reachOf,dominates,corpusN` (global) `cast.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                           | `traverse.ts:edgeAncestors,types.ts:SaturationReason` `src/mind/junction.ts:junctionContainersFrom` `src/mind/resonance.ts:pivotInto`                                  | `test/27` `test/16`            | `saturation.md`           |
+| 14 | Closure                              | `src/mind/derivation.ts:admissible,advance,closeOver`                                                                                                                  | `test/133`–`151`               | `closure.md`              |
+| 15 | Witnessed evidence                   | `src/mind/evidence.ts:witness,windowIndex` `src/mind/traverse.ts:chooseNext,askedEvidence,namedContinuations,scaffoldExtents`                                          | `test/154`                     | `evidence.md`             |

package/docs/architecture/bounded-reads.md

@@ -81,5 +81,5 @@ net); a walk with only a cap drifts to the cap.
   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
+- `test/90` — connector probe (`offerConnectors`) reads by the query length
   (`QUERY.length + 1`), not by the learnt continuation; per-read size bound.

package/docs/architecture/caches.md

@@ -31,6 +31,7 @@ candidate window for `"smallest"` never rescans from front.
 | Cache               | Field                      | Budget                       | `sizeOf`            | Eviction       |
 | ------------------- | -------------------------- | ---------------------------- | ------------------- | -------------- |
 | dedup leaf/branch   | `_leafKey` / `_branchKey`  | `dedupCacheMax` 1M entries   | 1                   | lru            |
+| flat-branch hits    | `_flatKey`                 | `dedupCacheMax` 1M entries   | 1                   | lru+clock      |
 | 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      |
@@ -76,10 +77,10 @@ must discharge it.
   `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.
+- Now: `perceiveDeposit` keys by `latin1(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
 

package/docs/architecture/closure.md

@@ -3,9 +3,10 @@
 > **Law:** a step is admitted only when it CLOSES the derivation, or MOVES to
 > structure it has not consumed, or CARRIES material the asker left unaccounted.
 
-One unit and one law, asked by every tier that decides whether to continue: the
-chart's frontier, the market's candidates, the post-grounding walk, fusion, and
-the mechanisms' own gates. None re-spells a condition the law owns.
+One unit, one law and one engine, asked by every tier that decides whether to
+continue: the chart's frontier, the market's candidates, the post-grounding
+walk, fusion, and the mechanisms' own gates. None re-spells a condition the law
+owns.
 
 ## The unit — `src/mind/derivation.ts`
 
@@ -43,7 +44,35 @@ not carry.
 
 The walk ends when the layer stops offering or the law refuses; owning no
 search, the law cannot prevent a cycle — that is the layer's, over the structure
-it holds.
+it holds. A transition is only ever `advance`: a fusion the law refuses is not
+taken (there is no hand-built fallback).
+
+## The engine — `closeOver`
+
+`closeOver(state, query, W, layers, enter?)` closes a derivation under the law,
+layer by layer. A layer (`ClosureLayer`) is a named `Offer` with its own
+instrumentation hooks; each is walked by `closure` to its own end, and the state
+it reaches is the state the next layer is offered against. Layers are PHASES, in
+order, never revisited.
+
+- **¬FIXED is the engine's.** A fixed state admits no transition, so no layer is
+  entered for it — the walk-skip and fusion-skip a caller used to spell by hand
+  are the law's first clause, taken before any layer pays.
+- **Engagement is the layer's.** A layer that has nothing to offer a state
+  (`engages`) is not entered: no offer, no meter phase.
+- **The pipeline's post-grounding stage IS the engine**, with two layers: the
+  walk (`walkLayer` — forward absorb or pivot) and the fusion (`fusionLayer` —
+  one composed transition, engaged only while the derivation is open). There is
+  no hand-built state anywhere outside `advance` (`test/137.7`).
+
+## The four quantities (trap 13), and where each stands
+
+| Quantity                | Status                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| offer of a hop          | Consequence. Chart: the corpus's continuations under the READ cap, each a MOVE priced STEP, the search decides (`test/112`). Walk: absorb/pivot, the law admits.                                                                                                                                                                                                                                  |
+| depth of a join         | Consequence. The join consumes the shortest tail prefix naming a learnt key that leads — CONTAINS (resolves) ∧ MOVES (leads) — and chains until the tail is consumed; no count (`test/108`). It is priced for the facts a lightest derivation STANDS ON, round by round (`solve`'s join license), never for every fact the exploration reaches — the `deepen` cure for the `recompleteNode` trap. |
+| scope of a gap          | Consequence for alignment (`alignAround` walks outward, no cap). NOT for recognition's interior pass: its reach `W⁴ + 2r` bounds an exhaustive embedded-form probe; exact unbounded reach needs a whole-stream index the store does not have.                                                                                                                                                     |
+| scope of a substitution | Consequence: the gap between two aligned anchors (`unexplainedSpans`), gated as scaffolding by the global commonality reading. The filler-unanimity window (`chainReach`) is a derived decision scale, not an explosion cap.                                                                                                                                                                      |
 
 ## One cost home
 
@@ -51,7 +80,7 @@ it holds.
 `weigh`). A mechanism reports `moves` and `accounted` — what it did — and never
 a price; `cover` reports its chart derivation's work.
 
-## Two limits, proved and left out
+## Three limits, proved and left out
 
 1. **The chart cannot evaluate accounting** — its interface has no parameter for
    it, and carrying it per item was measured and rejected. The chart reads the
@@ -62,6 +91,9 @@ a price; `cover` reports its chart derivation's work.
    `reason`'s echo guards stop with the remainder non-empty, and recall's
    reverse tiers close with an empty accounting. That is a fact about the
    asker's material in the store, available only to the layer holding it.
+3. **The extension is not priced into the market** (`test/136.2`): the engine
+   closes the WINNER only; pricing each candidate's closure would run the walk
+   for every candidate, and that comparison has not been measured.
 
 ## Layering
 
@@ -78,3 +110,11 @@ vocabulary, not the tracer's.
 - `test/142`, `test/143` — the offer's contract, and the cycles.
 - `test/144`, `test/146`, `test/147` — identity is content, the `contains` gate,
   the witness ladder.
+- `test/137.7` — no transition is built by hand outside the law.
+- `test/149` — the engine: ¬FIXED first, layers as phases, engagement, a refusal
+  ends one layer, and the pipeline sequences no layer by hand.
+- `test/150` — the join prices the facts a derivation stands on, not every fact
+  the exploration reaches (a hub's degree changes nothing).
+- `test/151` — the cover's other async premises (connectors, concept hops) are
+  resolved where the search reaches them; a span's cheapest completion
+  dominates; a grounding on the whole query pays no fusion climb.

package/docs/architecture/cost-model.md

@@ -56,6 +56,21 @@ minimum per-byte cost in the ladder (every real per-byte cost is `>= MICRO`,
 including `PASS`), and only the suffix past `right` is counted, so `h` never
 exceeds the true remaining cost.
 
+## Dominance — why `PASS ≫ STEP` does not flood the chart
+
+The heuristic charges `MICRO` for a byte the goal will pay `PASS` for, so a
+cover that leaves bytes unexplained lets the search spend up to `PASS / STEP`
+hops looking for one more explained byte. Coverage itself cannot use them: every
+recognised completion of `[i, j)` advances the cover from `i` to `j` at the same
+`MICRO`. So a form or completion of `[i, j)` whose cost has reached that of a
+completion of `[i, j)` already yielded is DOMINATED and fires no rule
+(`buildSearch`, metered as `searchDominated`): every completion it could lead to
+costs at least as much, and a tie goes to the one yielded first. What a
+completion's BYTES could still do — fuse, splice, join — fires from the
+completion the search would stand on for that span, the same cure the join
+license and `deepen` apply. The first hop's stop-here (`STEP + CONCEPT`) is then
+a real horizon: no chain deeper than it is expanded.
+
 ## Policy is not cost
 
 "Computation always wins" is **not** priced into the ladder (a computed result
@@ -69,3 +84,4 @@ the sole completion there. Keep policy in callers; keep the engine neutral.
 - `test/53` — cross-region probe instrumentation
 - `test/54` — evidence `k` instrumentation
 - `test/55` — cost meter (`Meter`, `CostReport`, `searchPops`/`searchPushes`)
+- `test/151` — dominance: a hub's degree generates no chart work