@hviana/sema 0.8.3 → 0.8.5

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) `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`              |
+| #  | 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
 

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,11 +11,11 @@ _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`
 
@@ -23,20 +23,29 @@ _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
 

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/mechanism-market.md

@@ -14,12 +14,12 @@ 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;
-  used?: ReadonlySet<number>;
 }
 ```
 
@@ -53,11 +53,11 @@ Weight is one currency: `weight = moves + PASS · unaccountedBytes` where
    `√N` via `hubBound`/`hubCap` and `k = 2·recallQueryK` (`Precomputed.k`).
    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
-   all three 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
 
@@ -86,7 +86,7 @@ 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 so `PASS`-bridged bytes are still charged. `unexplained`, `narrowDecision`,
+out so `PASS`-bridged bytes are still charged. `narrowDecision` and
 `thinGrounding` are observational only.
 
 ## Pins

package/docs/architecture/meter.md

@@ -11,11 +11,10 @@ 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.
+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

package/docs/architecture/store.md

@@ -37,8 +37,8 @@ root never costs a full walk.
 ## Gist, halo, dedup
 
 On `put*`, content dedup (`hashOf`→probe→mint) gates first. Short keys are
-cached (`DEDUP_KEY_MAX` bypass). Near-dedup merges by `mergeThreshold(D)` on
-unit gist cosine. Gists sit in `_pendingGist` (byte-budgeted `BoundedMap`);
+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.

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

package/docs/failures/tempting-but-wrong.md

@@ -1,7 +1,17 @@
 # Tempting but Wrong — 13 Traps
 
 Thirteen shortcuts that look plausible and break an invariant. Each states what
-not to do, why it fails, and what to do instead.
+not to do, why it fails, and what to do instead. **Some things are universal:
+discovering bugs:**
+
+- A bug must be pinned by a test that shows it.
+- This test cannot be accidental; it is subtle and requires deep analysis. That
+  is, it is not the test itself that reveals the bug, but rather the class of
+  errors to which the bug belongs.
+- This is difficult to do because the suite's small synthetic corpus easily
+  leads to accidental bugs, and real-world corpus must not be compromised.
+- Something that happens due to deduplication, a tie-breaking rule, etc., isn't
+  a bug—and that’s a subtle point.
 
 ### 1. `score >= threshold` decides identity
 

package/docs/harness/gates.md

@@ -12,9 +12,9 @@ npm test
 Guards honest silence, determinism, and every pinned contract. Silence:
 unrelated queries ground to nothing (`test/28`, `50`, `56`, `67`, `76`, `84`).
 Determinism: same seed + deposit order + query gives byte-identical answer
-(`test/20`). Every invariant is pinned — a simplification that fails a test is
-wrong until the test is shown wrong. §14–25 (pipeline), §64 (derived
-thresholds), AGENTS.md §2 invariants 1–5.
+(`test/20`). Every invariant is pinned, the closure law included
+(`test/133`–`140`). §14–25 (pipeline), §64 (derived thresholds), AGENTS.md §2
+invariants 1–5.
 
 ## 2 — Work accounting (profiler)
 
@@ -23,9 +23,9 @@ node bench/profile-inference.mjs        # add [n] to limit probes
 node bench/profile-inference.mjs --trace # trace is a debugging aid, not product
 ```
 
-Guards without trace: counters deterministic and diffable between runs; phases
-nest (not disjoint — each phase is charged by its own layer); shared analyses
-charged to themselves, not to the first toucher; millisecond fields are
+Guards without trace: counters exact and diffable between COLD runs; phases nest
+(not disjoint — each phase is charged by its own layer); shared analyses charged
+to themselves, not to the first toucher; millisecond fields are
 non-deterministic hints only. With `--trace`, recognition idempotence still
 holds (`test/42`). `src/meter.ts`, `docs/architecture/meter.md`, §55,
 `AGENTS.md` §6.

package/docs/mechanisms/cover.md

@@ -33,8 +33,8 @@ and are filtered during recognition.
 | `PASS`    | 1000 / byte | each unaccounted byte                           |
 | `MICRO`   | 1e-3        | per-byte A* heuristic (`h = (len-right)*MICRO`) |
 
-Mechanism weight is `moves + PASS * unaccounted_bytes`; comparison is at `STEP`
-grade, then by `scaffolding` bytes, then list order.
+The cover reports `moves` (its derivation's discrete work) and `accounted`; the
+ladder prices both.
 
 ## Pre-resolution (`src/mind/mechanisms/cover.ts`)
 

package/example/demo.ts

@@ -1,44 +1,97 @@
-// demo.ts — one short session that drives the WHOLE pipeline from one memory.
+// demo.ts — a corpus goes in, and the memory is read back out.
 //
-// We give Sema a handful of plain notes, then ask things that no single note
-// answers. The headline query is the third one: from three worked examples Sema
-// learns the shape of "X was painted by Y", lifts the painter out of a sentence
-// it has NEVER seen, and then — in the same pass — reasons forward to a separate
-// fact about that painter. The reply contains no word from the question. That is
-// retrieval, generalization, and reasoning composing as a single act, with every
-// step traceable back to the notes behind it.
+// Sema is given a small corpus of plain notes, each one the shape every deposit
+// has: a context, and what follows it. Then the memory is read two ways — what
+// it HOLDS (`sampleCorpus`), and which of its notes a question REACHES
+// (`searchCorpusText`). Both run through the same content-addressed machinery an
+// answer uses (src/mind/corpus.ts); nothing is indexed and nothing is written.
+//
+// The search addresses content EXACTLY, not by keyword: a question reaches a
+// note when it shares chunk-aligned content with it, so a question with no such
+// overlap is reported as exactly that — a STATE, rendered by the text layer
+// (`CorpusTextResult.note`), never as prose the engine invented.
+//
+// The last act is two ordinary answers, each with its derivation streamed as it
+// unfolds, the PROVENANCE that names the route it grounded on, and the work it
+// cost read off the meter: the rationale and the meter ARE the explanation
+// surface (AGENTS.md §6).
+
+import { decodeText, formatReport, Mind, SQliteStore } from "../src/index.js";
+
+// One relation shown three times — a pattern taught purely by example — plus a
+// stray fact keyed on a name none of the examples mention.
+const CORPUS: Array<[string, string]> = [
+  ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
+  ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
+  [
+    "The Night Watch was painted by Rembrandt van Rijn.",
+    "Rembrandt van Rijn",
+  ],
+  ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
+  ["The Weeping Woman was painted by Pablo Picasso.", "Pablo Picasso"],
+];
 
-import { Mind } from "../src/index.js";
-import { SQliteStore } from "../src/store-sqlite.js";
+// Questions the corpus can address, and one it cannot — the honest miss.
+const QUERIES = [
+  "The Mona Lisa was painted by Leonardo da Vinci.",
+  "Pablo Picasso",
+  "xylophone",
+];
+
+// One question answered by composing across the notes, and one answered by
+// computing: the two routes the corpus search does not take.
+const ASKS = [
+  "The Weeping Woman was painted by Pablo Picasso.",
+  "a museum charges 12*4 for a family ticket",
+];
 
 async function main(): Promise<void> {
-  const mind = new Mind({ store: new SQliteStore({ path: ":memory:" }) });
-  const ask = async (q: string) => (await mind.respondText(q)).trim();
-
-  // ── Jot down what we know. Each line is just (context → what follows). ──
-  await mind.ingest([
-    // One relation, shown three times — a pattern taught purely by example:
-    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
-    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
-    [
-      "The Night Watch was painted by Rembrandt van Rijn.",
-      "Rembrandt van Rijn",
-    ],
-    // One stray fact, keyed on a name none of the examples mention:
-    ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
-  ]);
-
-  // 1) GENERALIZE — apply the learned pattern to an unseen sentence and read out
-  //    the painter. "Pablo Picasso" was never given as an answer; Sema locates it
-  //    by analogy to the three examples.
-  console.log(await ask("The Weeping Woman was painted by Pablo Picasso."));
-  // → "Pablo Picasso co-founded the Cubist movement"
-  //   …and, having found the painter, it KEEPS GOING: the name bridges into the
-  //   one fact it holds about him. The answer appears in no word of the question.
-
-  // 2) COMPUTE — exact arithmetic, grounded right where the notes go silent.
-  console.log(await ask("a museum charges 12*4 for a family ticket"));
-  // → "48"
+  const mind = new Mind({
+    store: new SQliteStore({ path: ":memory:" }),
+    profile: true,
+  });
+  await mind.ingest(CORPUS);
+
+  // 1) WHAT THE MEMORY HOLDS — real pairs, browsed, no query and no random draw.
+  console.log("— the corpus, as the memory holds it —");
+  for (const p of mind.sampleCorpus(4).pairs) {
+    console.log(`  ${decodeText(p.context)}  →  ${decodeText(p.continuation)}`);
+  }
+
+  // 2) SEARCH — which stored notes does a question reach? A question that
+  //    addresses the corpus answers with pairs; one that shares nothing with it
+  //    answers with a note saying so.
+  for (const q of QUERIES) {
+    const r = mind.searchCorpusText(q, 3);
+    console.log(`\n— "${q}" —  ${r.resolved} resolved / ${r.reached} reached`);
+    if (r.note !== undefined) console.log(`  ${r.note}`);
+    for (const p of r.pairs) {
+      console.log(
+        `  ${p.context}  →  ${p.continuation}  (${p.matchedBytes} matched)`,
+      );
+    }
+  }
+
+  // 3) ANSWERS, WITH THEIR DERIVATION — the same pipeline, read as data. Steps
+  //    repeat (recognise re-enters under every mechanism that needs it), so each
+  //    distinct mechanism-and-note is printed once, in the order it first ran.
+  for (const q of ASKS) {
+    const seen = new Set<string>();
+    const trace: string[] = [];
+    const r = await mind.respond(q, (s) => {
+      const line = `${s.mechanism.join(" › ")}${s.note ? ` — ${s.note}` : ""}`;
+      if (seen.has(line)) return;
+      seen.add(line);
+      trace.push(`${"  ".repeat(Math.max(0, s.mechanism.length - 1))}${line}`);
+    });
+    console.log(`\n— "${q}" —  ${r.provenance ?? "no answer"}`);
+    console.log(`  ${decodeText(r.bytes).trim()}`);
+    console.log("— how —");
+    for (const s of trace) console.log(s);
+    if (mind.lastCost !== null) {
+      console.log(`— what it cost —\n${formatReport(mind.lastCost)}`);
+    }
+  }
 
   await mind.store.close();
 }

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@hviana/sema",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "exports": "./src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "repository": {
     "type": "git",

package/src/geometry.ts

@@ -180,19 +180,6 @@ export function consensusFloor(N: number): number {
   return Math.log(N) + 1 / 2;
 }
 
-/** The coverage bar for the reach (interior) index, when vector-similarity
- *  gating is used.  Returns the concept threshold — the structural midpoint
- *  (~0.5 at D=1024) where two forms are "more similar than not."
- *
- *  Currently UNUSED in the hot training path: interior nodes are indexed
- *  unconditionally (hash-cons dedup bounds the index naturally).
- *  Post-hoc structural compaction ({@link Store.compactContentIndex})
- *  replaces runtime coverage gating with a batch pass that removes
- *  structurally-isolated entries.  Derived, never tuned. */
-export function coverageBar(_maxGroup: number, D: number): number {
-  return conceptThreshold(D);
-}
-
 // ---- types ----
 
 export interface Folded {