@hviana/sema 0.8.9 → 0.9.1

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

@@ -21,22 +21,22 @@ proof in `test/` (pins that fail when the law is broken).
 
 ## Architecture laws (14)
 
-| 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; 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, 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`                             |
 
 ## Mechanisms (8)
 
@@ -65,6 +65,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,18 @@
 # 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`              |

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

package/docs/architecture/factored-machinery.md

@@ -7,19 +7,20 @@ Siblings: `match-project.md`, `commonality.md`, `meter.md`.
 
 ## Single-definition contracts
 
-| Symbol                                                        | Defined in               | One fact                                                                                                                                                                  |
-| ------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `contentLevels`                                               | `src/geometry.ts`        | Single boundary rule: cuts + levels from one rolling hash pass; every segmentation reads it.                                                                              |
-| `canonicalWindows` / `chainReach` / `leafIdRun` / `windowIds` | `src/mind/canonical.ts`  | Write/read contract: training interns `W-1,W` windows, reading chains to `W²` and probes `W`-windows — drift silences recognition.                                        |
-| `junction.ts` + `WalkCache`                                   | `src/mind/junction.ts`   | Shared junction ascent (parents + containers) with bounded `√N·W` walk; `WalkCache` memoizes capped reads/parents/containers per response; bridge and attention share it. |
-| `joinWithBridge`                                              | `src/mind/resonance.ts`  | One out-of-search assembly: `bridge(left,right)` or bare concat with `bridgeMiss` trace.                                                                                  |
-| `dismissedKnownContent`                                       | `src/mind/bridge.ts`     | Pure attestation: any unaccounted `W`-window that resolves as known content — shared gap guard for substitution and CAST.                                                 |
-| `sharedReachMemo`                                             | `src/mind/traverse.ts`   | One response-scoped `AncestorReach` memo (cleared on write and for traces); every `reachOf`/`edgeAncestors` consumer shares it.                                           |
-| `guidedFirst`                                                 | `src/mind/traverse.ts`   | Guided-or-first answer bytes: `guidedNext` else first-inserted edge (`LIMIT 1`).                                                                                          |
-| `leadsSomewhere`                                              | `src/mind/traverse.ts`   | Admission predicate: `hasNext` (cached) or `hasHalo`; sites that lead nowhere contribute no derivation.                                                                   |
-| `isChunk`                                                     | `src/sema.ts`            | `kids !== null && kids.every(k=>k.kids===null)` — smallest grouped unit; governs regions, seams, indexing.                                                                |
-| `twoEndedSeat`                                                | `src/sema.ts`            | One seat algebra: first half low seats, second half high seats; shared by perception, `fold`, and canonical folds.                                                        |
-| `closed`/`admissible`/`advance`                               | `src/mind/derivation.ts` | One admission for every derivation step and the readings every tier asks.                                                                                                 |
+| Symbol                                                        | Defined in                                              | One fact                                                                                                                                                                                      |
+| ------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contentLevels`                                               | `src/geometry.ts`                                       | Single boundary rule: cuts + levels from one rolling hash pass; every segmentation reads it.                                                                                                  |
+| `canonicalWindows` / `chainReach` / `leafIdRun` / `windowIds` | `src/mind/canonical.ts`                                 | Write/read contract: training interns `W-1,W` windows, reading chains to `W²` and probes `W`-windows — drift silences recognition.                                                            |
+| `junction.ts` + `WalkCache`                                   | `src/mind/junction.ts`                                  | Shared junction ascent (parents + containers) with bounded `√N·W` walk; `WalkCache` memoizes capped reads/parents/containers per response; bridge and attention share it.                     |
+| `joinWithBridge`                                              | `src/mind/resonance.ts`                                 | One out-of-search assembly: `bridge(left,right)` or bare concat with `bridgeMiss` trace.                                                                                                      |
+| `dismissedKnownContent`                                       | `src/mind/bridge.ts`                                    | Pure attestation: any unaccounted `W`-window that resolves as known content — shared gap guard for substitution and CAST.                                                                     |
+| `sharedReachMemo`                                             | `src/mind/traverse.ts`                                  | One response-scoped `AncestorReach` memo (cleared on write and for traces); every `reachOf`/`edgeAncestors` consumer shares it.                                                               |
+| `guidedFirst`                                                 | `src/mind/traverse.ts`                                  | Guided-or-first answer bytes: `guidedNext` else first-inserted edge (`LIMIT 1`).                                                                                                              |
+| `leadsSomewhere`                                              | `src/store.ts` (raw), `src/mind/traverse.ts` (memoised) | Admission predicate: `hasNext` or `hasHalo`, defined once on the store; traverse memoises the edge tier per response.                                                                         |
+| `isChunk`                                                     | `src/sema.ts`                                           | `kids !== null && kids.every(k=>k.kids===null)` — smallest grouped unit; governs regions, seams, indexing.                                                                                    |
+| `twoEndedSeat`                                                | `src/sema.ts`                                           | One seat algebra: first half low seats, second half high seats; shared by perception, `fold`, and canonical folds.                                                                            |
+| `closed`/`admissible`/`advance`/`closeOver`                   | `src/mind/derivation.ts`                                | One admission for every derivation step, the readings every tier asks, and the engine that walks the post-grounding layers.                                                                   |
+| `exactNode`                                                   | `src/mind/primitives.ts`                                | The exact content-addressed lookup (`resolve`, `canonResolve`): the identity fold (`contentIdentity`, geometry.ts) — a miss decided by the segment filter, a hit named bottom-up, no vectors. |
 
 ## Pins
 

package/docs/architecture/fold-contract.md

@@ -56,6 +56,50 @@ drift without a type error. Levels are read from the hash the cut was accepted
 at — level `L` when `h` vanishes mod `W^(L+1)` — so level-`L` cuts nest inside
 level-`(L-1)` and expected span is `W^(L+1)` bytes.
 
+## One shape, two algebras
+
+Which items group under which parent is decided by the cut levels, the keyring
+and — inside an over-long row — each item's `itemKey` (eight raw gist
+coordinates). `groupByLevel`/`foldSlice` are written ONCE over a fold algebra
+(`join`, `key`) and run over two of them: the vector fold (`perceive`) and the
+identity fold (`contentIdentity`), which names the node a stream folds to by
+asking the store bottom-up and reads only the coordinates `itemKey` hashes,
+lazily, with the same float32 additions in the same order. `exactNode` is the
+identity fold, so resolving a span builds no D-dimensional gist and leaves
+nothing in the perception memo (measured on the 31.7M-node store: one join query
+went 185 s / 4.4 GB retained → 40 s / 81 MB, same answer). A grouping rule
+written twice would be a write/read drift waiting to happen; written once, the
+two folds cannot disagree about the tree.
+
+## Same tree is not enough — the read side names as the write side names
+
+The store's `intern` names a branch by its children, and when they name none it
+looks up the FLAT node over the same bytes and REUSES it (step 1b, "same bytes,
+same node"). Every deposit interns flat nodes — its whole input and each
+canonical window — so a later deposit's branch is often stored as an earlier
+deposit's window (`ver` + `!` stored as the window `ver!`). The same tree is
+then named by a node no child lookup can reach. `exactNode` and `foldTree` name
+a branch exactly as `intern` does (`branchNaming`, `src/mind/primitives.ts`):
+the children first, the flat node over the same bytes when they name nothing —
+and an unnamed child does not settle it, since the write side minted that child
+and still reached step 1b. Measured on the 31.7M-node store: 7 of 80 dialogue
+turns asked verbatim had resolved to nothing and fell to the composition path
+(26–41 s); they now resolve to their own context.
+
+A name found only through the bytes is where the exact lookup used to MISS, and
+a flat index entry is not a learnt structure, so `resolve` still asks the
+canonical class there (`exactNaming`'s `byBytes`): it holds the learnt member
+that leads somewhere, when there is one. The store holds such byte-only names
+from an earlier deposit path (today's deposits always intern the structure
+beside the flat copy), which is why `test/152` builds the state through the
+store's write API.
+
+One stored turn of the same set still does not resolve: its context was stored
+with cuts at the ends of the conversation's EARLIER contexts (103 and 227 bytes
+into a 257-byte context) — a boundary-imposed shape neither today's deposit path
+nor the training-time one produces from these bytes, and that the read side
+could reproduce only by guessing turn boundaries, which this contract forbids.
+
 ## Optional canonical capability
 
 `canonAdd`/`canonFind` (`src/store.ts` — `canonCount`/`eachContent`) is an
@@ -81,7 +125,13 @@ any change here.
 - `test/59` — shift invariance floors (content-defined cuts preserved over
   random binary and prose).
 - `test/63` — offset/W invariance and `contentLevels` distribution expectations.
+- `test/148` — the identity fold names exactly what the vector fold names (every
+  sub-span of corpus and noise), and groups exactly as it does over long
+  low-entropy streams that force the `itemKey` split.
+- `test/152` — a deposit stored through an earlier deposit's flat window
+  resolves to its own context, both folds name it, and it is answered on the
+  exact path.
 
 See:
-`src/geometry.ts:contentLevels`/`contentBoundaries`/`contentFoldIncremental`/`stablePrefixFold`;
+`src/geometry.ts:contentLevels`/`contentBoundaries`/`contentFoldIncremental`/`stablePrefixFold`/`contentIdentity`;
 `AGENTS.md` §2 invariants.

package/docs/architecture/mechanism-market.md

@@ -67,6 +67,25 @@ Weight is one currency: `weight = moves + PASS · unaccountedBytes` where
   Cover runs first so a near-zero-cost computed span prunes the rest through the
   same mechanism — not a special case.
 
+- **A cheaper bound is looked at first.** Before mechanism `m` first-touches
+  anything, every LATER mechanism whose floor grade is strictly below `m`'s runs
+  ahead of it (cheapest first); the lowest grade they reach is `bound`, and any
+  mechanism floored above `bound` is skipped (`meter.mechanismsBounded`). The
+  bound is learnt by calling `floor` with a `worthRunning` that refuses — the
+  investment discipline makes that free. The DECISION is the declared order's: a
+  run-ahead mechanism bounds the final grade whether or not the declared order
+  would have run it (if pruned, the incumbent already sat at or below its
+  floor); every candidate above `bound` loses to the winner, and every mechanism
+  floored at or below it meets the same run-or-prune decision, so `consider`
+  replays the same candidates in declared order. Equal floors are not skipped,
+  so an earlier mechanism keeps the tie it would win. Running ahead is never
+  extra work: only a mechanism floored at or below `p` can prune `p`, and each
+  such mechanism has already run or runs ahead of `p`. Measured on the
+  31.7M-node store: a lowercased Persian turn (#83) went from 18.0 s to 1.2 s,
+  and #114 from 1.9 s to 0.7 s. In both, a grade-1 recall or prefix answer no
+  longer waits behind CAST's climb and weave. Of 42 composition-regime queries,
+  none changed its answer.
+
 - **Investment discipline.** `worthRunning` is passed _into_ `floor`. A floor
   that would first-touch an expensive shared analysis (`pre.attention()` climb,
   `pre.weave()`, `pre.resonance()`) checks `worthRunning(cheapestBound)` first
@@ -93,3 +112,5 @@ out so `PASS`-bridged bytes are still charged. `narrowDecision` and
 
 - `test/01-floor` — floor geometry.
 - `test/04-think` — decider, admissible pruning, investment discipline.
+- `test/153` — run-ahead bounds: the composition market is skipped below CAST's
+  floor, and the decision equals a declared-order oracle.

package/docs/architecture/memoization.md

@@ -47,9 +47,9 @@ conversation's persistent ones (content-keyed, cross-turn).
 | Memo                | Key                                       | Scope                                        |
 | ------------------- | ----------------------------------------- | -------------------------------------------- |
 | `perceiveMemo`      | `perceiveKey(bytes)` (latin1)             | response / conversation                      |
-| `recogniseMemo`     | `latin1Key(bytes)`                        | response / conversation                      |
-| `climbMemo`         | `latin1Key(bytes)`                        | response / conversation                      |
-| `canonMemo`         | `latin1Key(bytes)`                        | response (when `canon` set)                  |
+| `recogniseMemo`     | `latin1(bytes)`                           | response / conversation                      |
+| `climbMemo`         | `latin1(bytes)`                           | response / conversation                      |
+| `canonMemo`         | `latin1(bytes)`                           | response (when `canon` set)                  |
 | `_resolvedSubtrees` | `WeakMap<Sema, {id,len}>` (node identity) | response / conversation                      |
 | `_edgeChoice`       | `Map<nodeId, pick>`                       | response only — **cleared** in `endResponse` |
 | `_gistCache`        | `BoundedMap<nodeId, Vec>` 32 MB           | **session-lifetime** (not per-response)      |

package/docs/architecture/meter.md

@@ -3,7 +3,8 @@
 `src/meter.ts` is the one computational-usage accounting surface. It counts what
 inference _cost_ so a slow response can be attributed instead of guessed at. The
 rationale says why an answer was chosen; the meter says what it cost to choose
-it. Harness: `bench/profile-inference.mjs`.
+it. Harness: the public path — `new Mind({ profile: true })`, then
+`mind.lastCost` (`formatReport` / `sumReports`).
 
 ## Five contracts
 

package/docs/architecture/saturation.md

@@ -48,6 +48,18 @@ full — identical to the unbounded climb. Work is `O(bound)` contexts times loc
 structure, never `O(N)`. Container seeding is streamed in `bound`-sized pages
 for the same reason.
 
+Refuted tightening: **container fan-out as a hub** — deciding a containment seed
+saturated when its first `containersSlice(bound+1)` page overflows, the reading
+`junction.ts` applies to the same links. It conflates the PLACES a window occurs
+with the CONTEXTS it reaches, and saturation is defined over contexts. Proved on
+`test/49`'s fixture (N = 5, `sqrt(N)` = 3): `fran` sits in 4 containers yet its
+full climb reaches 2 contexts — discriminative — and the rule called it
+saturated, as it did `of f`, `fra`, `is`, `ranc`, `ance`. On the 31.7M-node
+store no such window climbed unsaturated (18 composition queries; those climbs
+were 38% of all visits), because at `sqrt(N)` = 1,560 a full page of containers
+rarely converges on few contexts — but the rule is the same wrong reading at
+both scales. The streamed seed stays.
+
 Trace records the first deciding stop as
 `SaturationStop { reason, node, observed, limit }` plus `visited`/`maxDepth`;
 absent when unsaturated or untraced.

package/docs/architecture/store.md

@@ -27,7 +27,23 @@ a row. `has(id)` is `id < 0 || id < _nextId`.
 A branch whose kids are all leaves is **flat** — stored as raw bytes in `leaf`
 with an empty `kids` blob as marker (`flatKidsBytes`/`flatBytesKids`). Dedup
 probes hash then verify: `hashOf`→`h`→`LIMIT 1` fetch→byte compare (bloom
-negative filter first).
+negative filter first). `flatBranchMayExist(bytes)` is the filter alone — its
+`false` is exact, its `true` means "look it up" — for a caller that will verify
+anyway: `exactNode` (primitives.ts) refuses a stream whose level-0 segment
+cannot exist before naming any node, so a resolve miss costs hashing.
+`findFlatBranch` memoizes HITS (`_flatKey`, keyed by the bytes themselves) and
+never misses — the filter answers first, so a span that is not stored builds no
+key, while the segments the identity fold names, asked by every span that
+contains them, cost a map hit. `flatSpans(bytes)` returns a prober over ONE
+buffer that answers exactly `findFlatBranch(bytes.subarray(s, e))`. `hashOf` is
+FNV-1a, a left fold, so the prober extends the hash each start was last probed
+at, and keeps one byte-short copy for the edge scan's trimmed retry. A span
+scanner sweeping ends upward pays O(1) per probe instead of O(span).
+Recognition's interior pass was hashing O(n·reach²) bytes: 251,660,406 for one
+response on the 31.7M-node store (`test/153.4`).
+
+`leadsSomewhere(id)` — `hasNext || hasHalo` — is the admission predicate's ONE
+raw definition; `traverse.ts` memoises its edge tier per response.
 
 `bytes(id)`/`bytesPrefix(id, cap)` are shared with `BoundedMap` caches — callers
 must **never mutate** the returned buffer. `contentLen(id, cap)` walks with
@@ -43,7 +59,14 @@ window apart. Gists sit in `_pendingGist` (byte-budgeted `BoundedMap`);
 `batchSize` batches. Buffers flush on cadence, `commit()`, and close. Halo mass
 re-indexes geometrically (`mass<=4 || powerOfTwo`) and encodes 2-bit quantized.
 Canon index is optional: `canonAdd`/ `canonFind`/`canonCount` over 32-bit
-canonical hashes, caller verifies bytes.
+canonical hashes, caller verifies bytes. The SQLite backend keeps a negative
+filter over the canon hashes too (kept exact on `canonAdd`; the table is never
+deleted from), because recognition and the join probe it once per span and
+almost every answer is "no such key". It is PERSISTED (`canon_bloom`) in the
+same transaction as the canon rows it covers, stamped with that commit's
+`canon.upto`; an open whose meta disagrees with the stamp (rows written without
+it) rebuilds it by one scan of the h column — seconds on a trained store, paid
+once instead of per process (`test/36`).
 
 ## Containment, batching, LRU