@hviana/sema 0.8.2 → 0.8.5

package/docs/INDEX.md

@@ -8,10 +8,10 @@ proof in `test/` (pins that fail when the law is broken).
 
 | Task                        | Read                                                                               | Why                                                                                   |
 | --------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| Add a mechanism             | `docs/architecture/mechanism-market.md` + `docs/mechanisms/*.md`                   | Market contract: decoupled, declared competence, visible budget, evidence travels     |
-| Add a threshold             | `docs/architecture/thresholds.md`                                                  | All cutoffs are formulas over D/W/N in `geometry.ts`; `config.ts` holds only budgets  |
-| Debug an answer             | `docs/architecture/cost-model.md` + `src/meter.ts`                                 | One cost ladder (`MICRO`/`STEP`/`CONCEPT`/`PASS`) decides every grounding choice      |
-| Understand the fold         | `docs/architecture/fold-contract.md`                                               | Deposit and inference must compute the same tree; boundaries are not turn metadata    |
+| Add a mechanism             | `docs/architecture/mechanism-market.md` + `docs/mechanisms/*.md`                   | Market contract: the four constraints                                                 |
+| Add a threshold             | `docs/architecture/thresholds.md`                                                  | All cutoffs are formulas over D/W/N; `config.ts` holds budgets only                   |
+| Debug an answer             | `docs/architecture/cost-model.md` + `src/meter.ts`                                 | One ladder decides every grounding choice                                             |
+| Understand the fold         | `docs/architecture/fold-contract.md`                                               | Deposit and inference compute the same tree                                           |
 | Add a store backend         | `docs/architecture/store.md` + `docs/architecture/bounded-reads.md`                | `AbstractStore` owns domain logic; backends are thin wrappers with capped reads       |
 | Add an ALU operation        | `src/alu/README.md`                                                                | One `registry.derive` per op composing existing ops; no new `derive` needed           |
 | Add a matcher or projection | `docs/architecture/match-project.md`                                               | Mechanisms are `(matcher, direction, gate)` configs over the shared `match.ts` family |
@@ -19,23 +19,24 @@ 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 (13)
+## 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`          | Two populations: corpus-global (`reachOf`+`dominates`) vs weave-local (`depth[]`)                           | `test/17`, `test/34` |
-| 8   | `docs/architecture/bounded-reads.md`        | No per-query read grows with N; `hubBound=√N` enforced at store via LIMIT/probe/prefix caps                 | `test/77`, `test/90` |
-| 9   | `docs/architecture/store.md`                | `AbstractStore` owns dedup/indexing/batch; `store-sqlite.ts` is thin wrappers; canon index optional         | `test/08`            |
-| 10  | `docs/architecture/fold-contract.md`        | `perceiveDeposit` and `perceive` agree; `contentLevels` is single boundary rule; no W/offset dependence     | `test/59`, `test/63` |
-| 11  | `docs/architecture/memoization.md`          | `Precomputed` is per-response lazy cache (promise-cached async); `beginResponse`/`endResponse` lifecycle    | `test/42`            |
-| 12  | `docs/architecture/saturation.md`           | Every walk names a deciding saturation beside its cap; cap is safety net, not decision                      | `test/27`, `test/16` |
-| 13  | `docs/architecture/meter.md`                | `meter.ts` is write-only work accounting; counts are deterministic, phases nest                             | `test/55`            |
+| 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`–`140`     |
 
 ## Mechanisms (8)
 
@@ -63,9 +64,7 @@ proof in `test/` (pins that fail when the law is broken).
 - `docs/INVARIANTS.md` — the five invariants (determinism, derived thresholds,
   exact-decides, one cost currency, bounded reads) with file-level routing.
 - `docs/failures/tempting-but-wrong.md` — refuted simplifications that passed
-  review but failed pins (e.g. reordering ladders, flattening attention
-  asymmetries, one-cone-exhausted stop).
+  review but failed pins.
 - `docs/harness/gates.md` — how `AGENTS.md` recipes,
   `bench/profile-inference.mjs`, and `test/*.test.mjs` enforce the laws.
-- `docs/architecture/` — full per-law derivation (each file states why the law
-  is this way; no separate HOW).
+- `docs/architecture/` — per-law derivation: each file says why, not how.

package/docs/INVARIANTS.md

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

package/docs/architecture/bounded-reads.md

@@ -3,10 +3,10 @@
 > **Law:** the cost of one query is proportional to the query, not to how much
 > was learned. No per-query read may grow with corpus size N.
 
-Every fan-out, walk, and disambiguation is capped at `hubBound` —
-`ceil(sqrt(N))` — derived once from `corpusN` and floored at 2 so `sqrt` and
-`ln` stay meaningful on a near-empty store. There is no second convention; do
-not invent one.
+Every fan-out, walk, and disambiguation reads at most the OLDEST `hubBound` —
+`ceil(sqrt(N))`, floored at 2 for a near-empty store. A better-supported
+candidate beyond that prefix is invisible: a trade, and there is no second
+convention.
 
 ## Scale
 
@@ -18,7 +18,7 @@ boundFor(n) = ceil(sqrt(max(2, n)))               // ctx-free reading
 ```
 
 Defined once in `mind/traverse.ts` (`corpusN`, `hubBound`, `hubCap`,
-`boundFor`). Every consumer imports them; never spell `Math.sqrt` inline.
+`boundFor`). Every consumer imports them; never re-derive them inline.
 
 ## Enforcement at the store level
 

package/docs/architecture/closure.md

@@ -0,0 +1,65 @@
+# Closure — One Law, One Unit, Every Transition
+
+> **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.
+
+## The unit — `src/mind/derivation.ts`
+
+| Field       | What it is                                            |
+| ----------- | ----------------------------------------------------- |
+| `product`   | the answer bytes so far                               |
+| `accounted` | the spans of the asker's bytes it explains            |
+| `remainder` | what the asker still owes, per span, at the `W` floor |
+| `cost`      | the currency's total for the steps taken              |
+| `fixed`     | a declared fixpoint: no transition is offered         |
+| `used`      | the anchors the producer speaks for                   |
+
+No identity field (`resolve(product)` is one), no structure field, no frontier
+field, no producer field, and no count of any kind. The witnesses `contains` and
+`moves` are the LAYER's: it holds the structure and hands them in, so the law
+never probes the store.
+
+## The transition
+
+`admissible(state, continuation, query, W)` returns the witnesses the step pays
+in, or `null`; `advance(state, continuation, witnesses)` is the only transition.
+The remainder is consumed only by a declared move, and only by the material that
+move CARRIES: `carries` admits by ENGAGEMENT and consumes nothing, a move
+consumes what its window proves. Whole-span draining was refuted by `test/110`,
+the window alone by `test/138`. The state is BORN owing what its product does
+not carry.
+
+## One cost home
+
+`moves + PASS · unaccountedBytes` is computed in ONE place (`pipeline.ts`,
+`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
+
+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
+   same law off an item: identity is its `key`, continuation the rule's
+   existence, progress the frontier advancing, closure the goal test, `fix` is
+   `fixed`.
+2. **Closure by the query's position in the graph is not a term of the unit** —
+   `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.
+
+## Layering
+
+Imports `../bytes.js` only, and sits below `graph-search.ts`, `match.ts`,
+`rationale.ts` and `pipeline.ts`. The span algebra lives here too — the law's
+vocabulary, not the tracer's.
+
+## Pins
+
+- `test/133`–`137` — the law's home, readings, refusal, limits.
+- `test/138` — a cycle cannot close it; a carried move can.
+- `test/139` — carrying is ENGAGEMENT, not explanation.
+- `test/140` — irrelevant supply changes no answer.

package/docs/architecture/commonality.md

@@ -1,9 +1,9 @@
-# Two Measures of Commonality
+# Three Measures of Commonality
 
-Sema needs "what is shared" in two different populations. One is corpus-global
-(how widely a structure is reused), the other is weave-local (what a local
-cohort of overlapping forms agrees on). They use different data and different
-formulas and must not be conflated.
+Sema needs "what is shared" in three populations: corpus-global (how widely a
+structure is reused), weave-local (what a local cohort of overlapping forms
+agrees on), and container-local (how many containers hold a byte window).
+Different data, different formulas, never conflated.
 
 ## Corpus-global — `reachOf` + `dominates`
 
@@ -11,32 +11,41 @@ _Defined in `src/mind/traverse.ts` + `src/geometry.ts`; used by climb,
 containment, IDF pooling._
 
 For a node id, `reachOf(id, N)` counts how many learnt contexts contain it
-(ancestor reach via capped graph walks, memoised per response in
-`sharedReachMemo`). `dominates(reach, N)` then asks whether that reach is above
-the corpus-determined majority threshold (derived in `geometry.ts` over `N`).
-Intuition: minority reach discriminates (a filler), majority reach is
-scaffolding. Powers the consensus climb, edge following, and vote pooling.
+(capped graph walks, memoised per response in `sharedReachMemo`).
+`dominates(reach, N)` asks whether that reach is above the corpus-determined
+majority threshold (`geometry.ts`, over `N`). Minority reach discriminates (a
+filler), majority reach is scaffolding. Powers the climb, edge following and
+vote pooling.
 
 ## Weave-local — `depth[]` + `MIN_WEAVE` + `dominates`
 
-_Defined in `src/mind/match.ts` (`depth[]`, `MIN_WEAVE`, `frame`) and gated in
-`src/mind/match.ts:frame`; used by CAST._
+_Defined and gated in `src/mind/mechanisms/cast.ts` (`depth[]` from the shared
+weave, `MIN_WEAVE`); used by CAST._
 
 For an alignment weave, `depth[i]` counts how many aligned structures cover byte
-`i` of the query. `MIN_WEAVE = 2` requires agreement beyond a pair (pair columns
-are ambiguous with insertions/deletions), and `dominates(depth[i], aligned)`
-requires agreement by a majority of the aligned cohort:
+`i` of the query; `MIN_WEAVE = 2` requires agreement beyond a pair (pairs are
+ambiguous with insertions), and `dominates(depth[i], aligned)` a majority of the
+cohort:
 
 ```
 frame(i) ⇔ depth[i] > MIN_WEAVE ∧ dominates(depth[i], aligned)
 ```
 
-This powers CAST's frame gate: what the local cohort shares vs what
-differentiates one member. It never consults corpus reach.
+This powers CAST's frame gate — what the cohort shares vs what differentiates
+one member — and never consults corpus reach.
 
-The two measures answer different questions over different populations; CAST's
-frame must not be replaced by a reach check and the climb must not be driven by
-weave depth.
+The three answer different questions over different populations; CAST's frame
+must not be replaced by a reach check, and the climb must not be driven by weave
+depth.
+
+## Container-local — the window's rarity
+
+_Defined in `src/mind/bridge.ts` (`containersSlice(id, 0, bound + 1).length`);
+used by the bridge, and by attention's anchoring._
+
+`rarity` counts how many containers hold a byte window: zero anchors nothing,
+two or more marks it REUSED (`winReused`), and the bridge sorts its anchors by
+it, so the rarest leads. Purpose: choosing what to anchor on.
 
 ## Pins
 

package/docs/architecture/cost-model.md

@@ -19,17 +19,17 @@ with that order give the same derivations.
 
 ## Pipeline weighing (`src/mind/pipeline.ts:think`)
 
-Mechanism candidates are weighed in the same ladder:
+Candidates are weighed in ONE place — a mechanism reports `moves` and
+`accounted`, never a price:
 
 ```
 weight = moves + PASS * unaccounted_bytes
 grade  = floor(weight / STEP)
 ```
 
-`unaccounted` is the query bytes no `accounted` span covers. Comparison is at
-`STEP` resolution: lowest `grade` wins. At equal grade the candidate with fewer
-`scaffolding` bytes (answer bytes lifted from unrecognised spans) wins; only
-then does mechanism list order decide.
+`unaccounted` is what no `accounted` span covers. Comparison is at `STEP`
+resolution: lowest `grade` wins; at equal grade fewer `scaffolding` bytes
+(answer bytes lifted from unrecognised spans) wins; then list order.
 
 ## Two semirings
 
@@ -59,8 +59,8 @@ exceeds the true remaining cost.
 ## Policy is not cost
 
 "Computation always wins" is **not** priced into the ladder (a computed result
-costs `STEP`, same as a learned edge). It is enforced by masking: `pipeline.ts`
-removes recognised sites overlapped by a `ComputedResult` so the computation is
+costs `STEP`, same as a learned edge). It is enforced by masking: `cover.ts`
+removes recognised sites overlapped by a `ComputedResult`, so the computation is
 the sole completion there. Keep policy in callers; keep the engine neutral.
 
 ## Pins

package/docs/architecture/determinism.md

@@ -20,7 +20,7 @@ flaky, the contract was broken, not the test.
 entropy root. Subsystems derive deterministically:
 
 - **Alphabet** — `Alphabet` (`src/alphabet.ts`) via `rng` (`src/vec.ts:rng`)
-  seeded as `seed ^ seedMask`; builds 16→64→256 vectors by refinement.
+  seeded as `seed ^ seedMask`; builds 16→64→256 vectors.
 - **Keyring / Space** — `Space.seats` (`src/sema.ts:Space`) via `makeKeyring`
   (`src/vec.ts:makeKeyring`) and `rng` seeded from `seed` in `Mind`
   (`src/mind/mind.ts`); `fold`/`twoEndedSeat`/`companySignature` are pure over
@@ -34,8 +34,8 @@ derived from `D`/`W`/`N`, not sampled.
 
 ## Tie-breaks are corpus-determined
 
-Every choice among equals bottoms out in a fixed ordering — insertion order or
-lowest node id. The universal no-evidence fallback is **first-inserted**:
+Every choice bottoms out in a fixed ordering — insertion order or lowest node id
+— not interchangeable (`test/34`). The fallback is **first-inserted**:
 
 - `guidedFirst` (`src/mind/traverse.ts:guidedFirst`) — guided pick via
   `chooseNext` else first-inserted edge (`nextFirst` LIMIT 1).
@@ -46,7 +46,7 @@ lowest node id. The universal no-evidence fallback is **first-inserted**:
 - `companySignature` (`src/sema.ts:companySignature`) — `rng(id ^ 0x9e3779b9)`,
   i.e. seeded by node id, not observation order.
 
-Last-inserted was once used in one place; it was a bug. Never reintroduce it.
+Never use last-inserted.
 
 ## Memoization and trace must not break identity
 
@@ -56,7 +56,7 @@ Per-response memos (`Precomputed`, `perceiveMemo`, `recogniseMemo`, `climbMemo`,
 `src/mind/primitives.ts`) are sound because asking never writes. Only
 `guidedNext`/`sharedReachMemo` are trace-bypassed;
 `perceiveMemo`/`recogniseMemo`/`climbMemo` are always consulted — `foldTree`'s
-subtree fast path skips `visit` (and thus site emission) for cached subtrees, so
+subtree fast path skips `visit` (and site emission) for cached subtrees, so
 bypassing makes `recognise` non-idempotent.
 
 ## Follow it
@@ -69,5 +69,5 @@ call `Math.random`/`Date.now` on a behavioural path.
 
 - `test/42` pins recognition idempotence under trace — traced and untraced
   `recognise` must return the same cached object and site count.
-- Determinism suites — `test/03`, `test/04`, `test/08`, `test/20` and others
-  assert same seed + same training ⇒ byte-identical answers and stores.
+- Determinism suites — `test/03`, `test/04`, `test/08`, `test/20` — assert same
+  seed + same training ⇒ byte-identical answers and stores.

package/docs/architecture/exact-vs-approximate.md

@@ -2,16 +2,16 @@
 
 Vector scores (`resonate` / `resonateHalo`) are RaBitQ **estimates**. They rank
 candidates and gate broad regions; they never decide identity. Identity is
-decided only by content-addressed lookup — `resolve` / `findLeaf` / `findBranch`
-/ `canonResolve` — and by re-folding bytes to verify.
+content-addressed lookup — `resolve` / `findLeaf` / `findBranch` /
+`canonResolve` — with ONE exception: the store's near-merge (`store.ts`).
 
 ## The law
 
 > Scores propose, bytes dispose.
 
 Even recall's echo decision re-folds the top hit's bytes rather than trusting
-the estimate it already has. No `score >= threshold` path may mint an identity
-claim; thresholds derived in `geometry.ts` gate search breadth, not truth.
+the estimate. No OTHER `score >= threshold` path may mint an identity;
+thresholds gate breadth, not truth.
 
 ## Graded evidence ladders
 

package/docs/architecture/factored-machinery.md

@@ -3,23 +3,23 @@
 Every shared operation is defined once and imported many times. Duplicating it
 forks the corpus contract; moving it hides who owns the gate.
 
-For the match → project → gate family see `match-project.md`; for the two
-commonality measures see `commonality.md`; for work accounting see `meter.md`.
+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.                                                        |
+| 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.                                                                                                 |
 
 ## Pins
 

package/docs/architecture/match-project.md

@@ -16,7 +16,7 @@ functions over bytes and the store — no mechanism owns a private copy.
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
 | **Match** (locate structure)  | `locate` (exact → halo → gist ladder), `alignRuns` (literal W-gram weave), `alignGraded` (literal + halo gaps), `alignAround` / `frameSlots` (seeded frame with contracted gaps), `bestHaloMate` (in-list halo), `analogyStrength` / `sharedFrameStrength` (distributional + structural analogy) | Finds where a query sits in a learnt form.                                              |
 | **Project** (direction)       | `follow` (forward to fixpoint, first hop may `conceptHop`), `reverseContext` (reverse to context), `project` (forward else reverse), `conceptHop` (halo sibling with edge)                                                                                                                       | Moves along the store from the match — forward toward answers, reverse toward contexts. |
-| **Gate** (structural licence) | `isSpanShaped` (sparse subsequence — open reading), `carriesFillers` (substitution carriage — strict voicing licence)                                                                                                                                                                            | Decides whether the shape licences voicing.                                             |
+| **Gate** (structural licence) | `isSpanShaped` (OPEN reading — sparse subsequence), `containsSpan` (STRICT reading — contiguous run or resolved node), `skillExemplar` (anchor → context + answer), `carriesFillers` (substitution carriage — strict voicing licence)                                                            | Two readings; not interchangeable.                                                      |
 
 Mechanisms declare only `(matcher, direction, gate)`. Thresholds behind gates
 live in `src/geometry.ts` — the match layer never invents a cutoff.
@@ -52,8 +52,7 @@ The shared layer never refuses on a consumer's behalf. Reference owns its four
 gates: frame dominates the query, each slot reaches `W` on both sides, no
 insertion/deletion, fillers pairwise distinct — plus `carriesFillers` on the
 chosen pair. CAST, recall, and cover each apply their own gate over the same
-shared inventory. Moving a consumer's gate into `match.ts` would hide who is
-responsible for the refusal.
+shared inventory. Moving a gate into `match.ts` would hide who owns the refusal.
 
 ## Pins
 

package/docs/architecture/mechanism-market.md

@@ -14,10 +14,11 @@ interface PipelineMechanism {
 }
 interface MechanismResult {
   bytes: Uint8Array;
-  accounted: [number, number][];
+  accounted: Array<[number, number]>;
   moves: number;
-  unexplained: string;
+  used?: ReadonlySet<number>;
   scaffolding?: number;
+  provenance?: string;
   complete?: boolean;
 }
 ```
@@ -30,7 +31,7 @@ interface MechanismResult {
 
 ## Decider
 
-`think` in `mind/pipeline.ts` iterates `defaultMechanisms` in list order:
+`think` iterates `defaultMechanisms` in list order:
 
 ```
 defaultMechanisms = [cover, cast, confluence, extraction, reference, recall,
@@ -39,8 +40,7 @@ defaultMechanisms = [cover, cast, confluence, extraction, reference, recall,
 
 Weight is one currency: `weight = moves + PASS · unaccountedBytes` where
 `unaccountedBytes = unexplainedSpans(query.length, accounted)`. Comparison is at
-`STEP` grade (`grade = floor(weight/STEP)`); equal grade prefers fewer
-`scaffolding` bytes, then list order.
+`STEP` grade ; equal grade prefers fewer `scaffolding` bytes, then list order.
 
 ## Four constraints
 
@@ -48,16 +48,16 @@ Weight is one currency: `weight = moves + PASS · unaccountedBytes` where
    never touches another; no mechanism asks what already decided.
 2. **Declared competence** — binary structural gates inside `floor`/`run` (query
    length, anchor shape, weave existence). Never a learned score; rationale
-   states exactly why a mechanism abstained.
+   states why a mechanism abstained.
 3. **Visible budget** — every corpus-scale loop is capped at a named constant:
    `√N` via `hubBound`/`hubCap` and `k = 2·recallQueryK` (`Precomputed.k`).
-   Enforced at the store level.
+   Enforced at the store.
 4. **Evidence travels** — every candidate carries `accounted` (query spans
-   explained), `moves` (priced on `MICRO/STEP/CONCEPT/PASS`), `unexplained`
-   (diagnostic label); optionally `scaffolding` (answer bytes from unrecognised
-   spans — equal-grade tie-break) and `complete` (trained-form continuation
-   reached via identity; post-grounding must not extend). The decider honours
-   both without knowing who set them.
+   explained) and `moves` (priced on `MICRO/STEP/CONCEPT/PASS`); optionally
+   `scaffolding` (answer bytes from unrecognised spans — equal-grade tie-break),
+   `complete` (trained-form continuation reached via identity; post-grounding
+   must not extend) and `provenance`. The decider honours them without knowing
+   who set them.
 
 ## Two disciplines
 
@@ -70,8 +70,8 @@ Weight is one currency: `weight = moves + PASS · unaccountedBytes` where
 - **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
-  and returns the uninvested bound when it already loses. Never compute a shared
-  analysis just to discard it. `cast.ts`/`extraction.ts` are the references.
+  and returns the uninvested bound if it loses. Never compute a shared analysis
+  just to discard it. `cast.ts`/`extraction.ts` are the references.
 
 ## Accounting
 
@@ -86,8 +86,8 @@ Weight is one currency: `weight = moves + PASS · unaccountedBytes` where
   same act is charged twice (`PASS`/byte dominates).
 
 `accounted` is a cost-ladder quantity; `cover.ts` leaves masked computed spans
-out of it so `PASS`-bridged bytes are still charged. `unexplained`,
-`narrowDecision`, `thinGrounding` are observational only.
+out so `PASS`-bridged bytes are still charged. `narrowDecision` and
+`thinGrounding` are observational only.
 
 ## Pins
 

package/docs/architecture/meter.md

@@ -11,17 +11,16 @@ it. Harness: `bench/profile-inference.mjs`.
    an ordering. Determinism survives only because the meter is observed, never
    consulted. Every call site is `meter?.x++` on a nullable field.
 
-2. **Counters vs hints.** Counters are deterministic and diffable between runs;
-   the same query on the same store meters identically, so a regression is
-   visible in a diff. Millisecond fields (`elapsedMs`, per-phase `ms`) are
-   non-deterministic hints reported separately — never use them to gate
-   behaviour.
-
-3. **Phases nest, they do not partition.** `think` contains every mechanism
-   phase; a mechanism's `floor` contains whatever shared analysis it
-   first-touched; `recall.run` contains `substitutionBridge`. Read a phase as
-   inclusive wall-clock — never sum phases and expect the total.
-   `CostReport.elapsedMs` is the only whole.
+2. **Counters vs hints.** Counters are exact and diffable: a regression shows in
+   a diff of two COLD runs; a repeated query meters less, as memos warm.
+   Millisecond fields (`elapsedMs`, per-phase `ms`) are non-deterministic hints
+   reported separately — never use them to gate behaviour.
+
+3. **Phases nest, they do not partition.** Each phase is charged by the layer
+   doing the work (`recognise`, the climb's two, the bridge), and a mechanism's
+   `floor` contains whatever shared analysis it first-touched. Read a phase as
+   inclusive wall-clock; never sum phases. `CostReport.elapsedMs` is the only
+   whole.
 
 4. **Count once.** Off by default and free when off
    (`new Mind({ profile:

package/docs/architecture/store.md

@@ -36,9 +36,9 @@ root never costs a full walk.
 
 ## Gist, halo, dedup
 
-On `put*`, content dedup (`hashOf`→probe→mint) gates first. `DedupKey` caches
-short keys (`DEDUP_KEY_MAX` bypass). Near-dedup merges by `mergeThreshold(D)` on
-unit gist cosine. Gists sit in `_pendingGist` (byte-budgeted `BoundedMap`);
+On `put*`, content dedup (`hashOf`→probe→mint) gates first. Short keys are
+cached (`DEDUP_KEY_MAX` bypass). Near-dedup: `identityBar(D, W, len)`, one
+window apart. Gists sit in `_pendingGist` (byte-budgeted `BoundedMap`);
 `indexSubtree` & `pourHalo` promote via `_vecContentUpsert`/`_vecHaloUpsert` in
 `batchSize` batches. Buffers flush on cadence, `commit()`, and close. Halo mass
 re-indexes geometrically (`mass<=4 || powerOfTwo`) and encodes 2-bit quantized.
@@ -55,7 +55,7 @@ deferred transaction.
 Every in-memory cache is a `BoundedMap` with byte accounting and eviction (`lru`
 vs `smallest` + `clock`/`reorder` recency). ANN reads
 (`resonate`/`resonateHalo`) are content-addressed (`vecKey`) and dropped on any
-index mutation; `RESonate_CACHE_MAX=4096`.
+index mutation; `RESONATE_CACHE_MAX=4096`.
 
 ## Maintenance (incremental)
 

package/docs/architecture/thresholds.md

@@ -17,7 +17,7 @@ perception window), or `N` (corpus size). No threshold is tuned or added to
 
 | Symbol                  | Definition                                                                   | Formula                             |
 | ----------------------- | ---------------------------------------------------------------------------- | ----------------------------------- |
-| `mergeThreshold(D)`     | Store identity bar — cosine at which `intern` treats two gists as same node  | `1 - 1/√D`                          |
+| `mergeThreshold(D)`     | Cosine below which two gists are near enough to consider merging             | `1 - 1/√D`                          |
 | `identityBar(D,W,len)`  | Scale-aware whole-span identity claim                                        | `max(mergeThreshold(D), 1 - W/len)` |
 | `reachThreshold(W)`     | Recall confidence floor — half a river quantum                               | `1 - 1/(2·W)`                       |
 | `estimatorNoise(D)`     | RaBitQ noise floor — 1σ of random cosine                                     | `1/√D`                              |