@hviana/sema 0.7.3 → 0.7.5

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

@@ -0,0 +1,47 @@
+# Exact vs Approximate — The Law and Its Five Ladders
+
+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.
+
+## 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.
+
+## Graded evidence ladders
+
+Five subsystems share one shape — **exact → distributional → geometric** — with
+earlier tiers strictly preferred. Never reorder tiers; never let an approximate
+tier override an exact one.
+
+| # | Site               | Ladder (strong → weak)                                                                                                   | File                                      |
+| - | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
+| 1 | `resolve`          | exact content-addressed fold → `canonResolve` (equivalence class, hash-then-verify)                                      | `mind/primitives.ts`                      |
+| 2 | `locate`           | exact bytes → halo role → gist                                                                                           | `mind/match.ts`                           |
+| 3 | `alignGraded`      | literal W-gram runs → halo-matched sites + climb proposals (weave)                                                       | `mind/match.ts` / `pipeline-mechanism.ts` |
+| 4 | `bridge`           | junction containers → edge → synonym → whole-gist                                                                        | `mind/resonance.ts`                       |
+| 5 | `crossRegionVotes` | exact containers → single synonym → double → `structuralResonance` (synthetic gist, gated hardest — no byte containment) | `mind/attention.ts`                       |
+
+## Asymmetries (attention)
+
+Two rules in `attention.ts` encode "exact decides" and must not be flattened:
+
+- Only the **EXACT** tier may explain ordinary votes away.
+- Only **container-backed** evidence may consume its endpoints.
+
+## Pins
+
+- `test/51` pins the cross-region tier ladder and its gating.
+- Recognition idempotence under trace (`test/42`) depends on exact identity
+  remaining byte-determined, not score-determined.
+
+## Adding a matcher
+
+Add a tier to the shared family in `mind/match.ts` with a derived gate
+(`geometry.ts`), never a private `score >= k` check. A new mechanism is a
+`(matcher, direction, gate)` configuration over that family (§2.5).

package/docs/architecture/factored-machinery.md

@@ -0,0 +1,28 @@
+# Factored Machinery — One Definition, Many Consumers
+
+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`.
+
+## 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.                                                        |
+
+## Pins
+
+- `test/47` — frame reading split (matcher vs gate vs inventory).
+- `test/50` — CAST analog / consensus floor (dismissed content, `MIN_WEAVE` /
+  `dominates` frame, `carriesFillers` refusal).

package/docs/architecture/fold-contract.md

@@ -0,0 +1,87 @@
+# Fold Contract — One Tree For The Same Bytes
+
+> **Law:** `perceiveDeposit` ≡ `perceive` — same bytes ⇒ same tree and same node
+> id. Deposit imposes nothing (no boundaries, no turn convention). Geometry
+> never sees conversation metadata.
+
+## The identity
+
+Perception is a pure function of the bytes. The deposit path and the inference
+path compute the same content-defined fold for the same input, so a trained
+context node and `resolve(query)` reach the same node. When the two sides
+disagreed, alignment went quadratic (measured 5.2M cells on a 476-byte context
+vs 0 when they agree) and cumulative contexts stopped resolving to what they
+were trained as.
+
+## Deposit imposes nothing
+
+No boundaries, no turn convention, nothing read out of the bytes. Conversational
+turn offsets are API metadata — they feed `ConversationState`, `answeredSpans`
+and `currentTurnStart`; the geometry never sees them. Passing turn boundaries
+into the fold is a correctness bug, not a tuning choice.
+
+## Boundaries vs reuse — two problems
+
+`contentFoldIncremental` and `stablePrefixFold` solve different problems;
+conflating them is what once put an imposed boundary set on the inference path.
+
+| Mechanism                | What it buys                                              | Cost / shape                                                                                    |
+| ------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `contentFoldIncremental` | Transparent segment reuse (cost only)                     | Imposes nothing; tree identical to the cold fold                                                |
+| `stablePrefixFold`       | Caller-supplied cuts left-nested for prefix-ROOT identity | One prefix-ROOT per cut becomes an identical subtree (and same node id) inside the grown stream |
+
+Both carry the same precondition: `prev` must be a fold of a byte-identical
+prefix — reuse is keyed on `[start,end)` offsets, which cannot witness byte
+agreement. A mismatched `prev` produced a wrong tree on 336 of 400 random
+streams. `perceiveDeposit` discharges this via the prefix bytes as cache key; a
+conversation advances only by append. A caller that cannot prove the prefix must
+pass no `prev`.
+
+## Identity must not depend on W or absolute offset
+
+`contentLevels` is the single boundary rule (rolling hash over a bounded
+window). Any grouping by index — stride, tile, fixed-arity row — reintroduces
+the grid's phase bug: `riverFold` groups `W`-ary from byte 0, so the same byte
+run is a different subtree at a different offset. The content-defined hash
+removes this: a change upstream moves only the cut it falls inside; downstream
+cuts and segments are unchanged (99.7% cuts preserved on real deposits after
+shifts of 1..7 bytes vs 14.3% for the grid). The `groupByLevel` above the
+segments splits by content level, not by count.
+
+## `contentLevels` is single source; `contentBoundaries` is projection
+
+`contentBoundaries(space, bytes)` is `contentLevels(space, bytes).cuts`. It once
+carried its own rolling-hash loop, which is how a write side and a read side
+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.
+
+## Optional canonical capability
+
+`canonAdd`/`canonFind` (`src/store.ts` — `canonCount`/`eachContent`) is an
+optional backend capability. A backend may omit all four; resolution then has no
+equivalence fallback. The store never learns the equivalence — the canonicalizer
+(`Canon` in `src/canon.ts`, e.g. `textCanon`) is injected by the caller and
+every candidate is hash-then-verified (re-canonicalize stored bytes, compare). A
+hash collision costs a read, never a wrong id.
+
+## Cost of changing the cut distribution
+
+The cut rate, which bits are read, `minLen`/`maxLen`, and the forced cut at
+`maxLen` set the segment distribution every downstream mechanism is fitted to.
+Each has been changed experimentally and cost 5–21 tests (rate: 15–18, bits:
+19–21, normalized chunking: 5–6). `W-1` is the minimum (one window minus one);
+`seats.length` is the maximum (one flat node folds exactly one segment). The
+forced cut is load-bearing — relaxing it to reduce the current 32% forced rate
+looked like a tidying but broke the same suites. Re-measure the whole suite for
+any change here.
+
+## Pins
+
+- `test/59` — shift invariance floors (content-defined cuts preserved over
+  random binary and prose).
+- `test/63` — offset/W invariance and `contentLevels` distribution expectations.
+
+See:
+`src/geometry.ts:contentLevels`/`contentBoundaries`/`contentFoldIncremental`/`stablePrefixFold`;
+`AGENTS.md` bootloader invariants.

package/docs/architecture/halo-sketch.md

@@ -0,0 +1,99 @@
+# Halo & Sketch — Distributional Memory
+
+A node's **halo** is its distributional signature: the superposition of
+identity-bound company signatures poured from every episode it participated in.
+Its **gist** is the VSA fold of its own bytes — content, not company.
+
+## Two vectors per node, two indexes
+
+| Vector | Encodes                       | Index         | Query          |
+| ------ | ----------------------------- | ------------- | -------------- |
+| gist   | what the node _is made of_    | content index | `resonate`     |
+| halo   | what _company_ the node keeps | halo index    | `resonateHalo` |
+
+Both indexes are RaBitQ-IVF (`src/rabitq-ivf/`) — 1-bit ANN over the same
+vectors; scores are estimates, never identity. Halos are also persisted durably
+(see below).
+
+## Quantization — 2-bit on disk, float in session
+
+A halo is a superposition of quasi-orthogonal signatures, so coordinates are
+Gaussian. Storage exploits this:
+
+- **In-session accumulator** (`_haloExact` in `src/store.ts`): `Float32Array` —
+  exact, additive, incremented by `pourHalo`.
+- **Durable row** (`_dbUpsertHalo`): 2-bit Lloyd–Max quantizer — decision at
+  ±0.9816σ, levels at ±0.4528σ / ±1.5104σ, σ derived from the stored norm
+  (`norm/√D`). Header is the 4-byte norm; body is 2 bits/coordinate. Keeps ≥0.88
+  correlation with the exact vector.
+- **ANN index**: 1-bit RaBitQ, irreversible — answers only "which halos are near
+  this query?"
+
+Re-indexing is geometric: a halo re-enters the ANN when mass is small or crosses
+a power of two (`geometricMass`), so index writes are O(log mass).
+
+## Bottom-k sketch & company profile
+
+A whole-partner signature alone records tokens, not types — halos of genuine
+synonyms would be quasi-orthogonal. `companyProfile` (`src/mind/learning.ts`)
+superposes:
+
+1. the partner's own identity signature, plus
+2. the bottom-k **constituent sketch** — the
+   `k = profileCapacity(D) = floor(√D)` minimal units of its subtree with
+   smallest `unitPriority`, deduped.
+
+The sketch is composable (bottom-k of a union = bottom-k of children's
+sketches), durable derived state via `sketchGet`/`sketchPut`, and bounded: at
+most `k` constituents are classified, each by one `LIMIT`ed parent read
+(`hubBound`). Beyond `√D` terms a single constituent contributes less than
+`1/√D` — below RaBitQ noise — and extra terms shrink every accepted one; the cap
+is a correctness limit.
+
+## Gist vectors
+
+Folded by the river (`src/geometry.ts`): leaves are alphabet vectors, groups
+bind by two-ended seats, intermediate gists stay unnormalized (magnitude ∝
+√len), only the root is normalized. Gist resonance reads byte-proportional
+overlap; halo resonance reads distributional overlap — the two are independent.
+
+## Thresholds & gating
+
+All bars are derived in `src/geometry.ts`; no tunable constant:
+
+| Symbol             | Formula        | Use                                                                                               |
+| ------------------ | -------------- | ------------------------------------------------------------------------------------------------- |
+| `estimatorNoise`   | `1/√D`         | 1σ RaBitQ noise; contrastive margin must clear it                                                 |
+| `significanceBar`  | `3/√D`         | whole-query relatedness — 3σ above chance; gates consensus climb and `analogyStrength`            |
+| `conceptThreshold` | `0.5 + 0.5/√D` | halo concept sharing — structural midpoint + ½σ; gates `haloSiblings`, concept hops, articulation |
+
+The significance bar gates the whole query; `conceptThreshold` gates per-pair
+halo cosine.
+
+## Probes: `haloMass` and `hasHalo`
+
+- `haloMass(id)` — count of poured episodes; evidence weight, tie-breaker in
+  `chooseAmong`.
+- `hasHalo(id)` — existence probe (indexed point check, no vector decode);
+  mirrors `halo(id) !== null`. One tier of the `leadsSomewhere` admission
+  predicate (with `hasNext`/`hasParents`).
+
+Both are `meter`-counted probes, not full decodes — `halo(id)` is the bounded
+vector read; `resonateHalo` is the IVF ANN query.
+
+## Relation to invariants
+
+- **Derived thresholds** — all bars above live in `geometry.ts`.
+- **Exact decides / approximate proposes** — halo scores rank and gate; identity
+  is content-addressed. The graded ladder is exact → halo → gist
+  (`mind/match.ts`).
+- **Bounded reads** — `hasHalo`/`haloMass` are point probes; `resonateHalo` is
+  capped ANN; constituent classification uses `LIMIT hubBound+1` reads. No
+  per-query scan grows with corpus.
+
+## Pins
+
+- `test/08 storage halo` — halo persistence, 2-bit round-trip,
+  `haloMass`/`hasHalo` contract, index survival across reopen.
+- `test/35 ivf` — RaBitQ-IVF contract (recall vs brute force, sublinear
+  scaling); covers the halo index's own layer.

package/docs/architecture/match-project.md

@@ -0,0 +1,62 @@
+# Match → Project → Gate
+
+Every grounding mechanism is a configuration of one shared operation in
+`src/mind/match.ts`. The family is defined once and imported many times;
+duplicating it forks the corpus contract, moving it hides who owns the gate.
+
+## The shared family in `mind/match.ts`
+
+The match layer locates structure, the project layer moves along the store, and
+the gate layer decides whether the shape licences voicing. All three are pure
+functions over bytes and the store — no mechanism owns a private copy.
+
+## The triple
+
+| Role                          | Symbols                                                                                                                                                                                                                                                                                          | What it does                                                                            |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| **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.                                             |
+
+Mechanisms declare only `(matcher, direction, gate)`. Thresholds behind gates
+live in `src/geometry.ts` — the match layer never invents a cutoff.
+
+The graded ladder inside `locate` is exact → distributional → geometric:
+content-addressed identity first, halo similarity second, gist resonance last.
+Reordering the ladder or letting an approximate score override an exact hit is a
+correctness bug (see `exact-vs-approximate.md`).
+
+## Frame reading — matcher reports, gate judges, inventory elects nothing
+
+`frameSlots` is the shared frame reader. It contracts every gap via
+`contractGap` to its varying core, tags it `substitution` / `insertion` /
+`deletion`, and attaches `covered` — the bytes the frame accounts for. It
+applies no gate; it reports.
+
+`carriesFillers` is the substitution gate. It judges byte-exactly:
+
+```
+substituteAll(contA, fillersA → fillersB) == contB
+```
+
+If the equality holds, voicing through the slot is a derivation; if not, the
+slot cannot carry. This is the only place that decision is made.
+
+`Precomputed.frames` is the inventory. It enumerates every frame pairing the
+match layer finds and elects nothing — ranking and refusal belong to the
+consumer.
+
+## Voicing gates belong to the consumer
+
+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.
+
+## Pins
+
+- `test/47` — frame reading split (matcher vs gate vs inventory).
+- `test/50` — CAST / reference voicing via `carriesFillers`.
+- `test/24` / `test/76` — match/project family and span-shape readings.

package/docs/architecture/mechanism-market.md

@@ -0,0 +1,95 @@
+# Mechanism Market — The Free-Will Architecture
+
+Every grounding mechanism — including the ALU and user extensions — speaks one
+interface (`mind/pipeline-mechanism.ts`). The decider in `mind/pipeline.ts`
+(`think`) holds a plain list and never branches on which mechanism it holds.
+
+## Interface
+
+```ts
+interface PipelineMechanism {
+  parse?(query: Uint8Array): Promise<ComputedSpan[]>; // authoritative spans
+  floor(ctx, query, pre, worthRunning): Promise<number | null>; // bound or null
+  run(ctx, query, pre): Promise<MechanismResult[]>; // candidates
+}
+interface MechanismResult {
+  bytes: Uint8Array;
+  accounted: [number, number][];
+  moves: number;
+  unexplained: string;
+  scaffolding?: number;
+  complete?: boolean;
+}
+```
+
+- `parse` is optional; all results are collected into `Precomputed.computed`
+  before any `floor`/`run`.
+- `floor` returns `null` when structurally impossible, otherwise an admissible
+  lower bound (never overstates cost).
+- `run` returns candidates with travelling evidence (below).
+
+## Decider
+
+`think` in `mind/pipeline.ts` iterates `defaultMechanisms` in list order:
+
+```
+defaultMechanisms = [cover, cast, confluence, extraction, reference, recall,
+                     prefix-completion] + ALU (`aluToMechanism`) + extensions
+```
+
+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.
+
+## Four constraints
+
+1. **Decoupled** — zero cross-imports between `mind/mechanisms/*`. Adding one
+   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.
+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.
+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.
+
+## Two disciplines
+
+- **Admissible-floor pruning.** `floor` runs for every mechanism in list order
+  before any `run`. `run` fires only if `worthRunning(floor)` where
+  `worthRunning = (floor) => best === null || grade(floor) < grade(best.weight)`.
+  Cover runs first so a near-zero-cost computed span prunes the rest through the
+  same mechanism — not a special case.
+
+- **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.
+
+## Accounting
+
+- **Extraction:** located frames are always evidence; the span between them
+  counts only when _both_ borders were located. An open-ended read is priced by
+  exclusion (`PASS`/byte).
+- **Reverse reading:** `reverseContext` produces bytes but explains nothing
+  forward: `accounted = []`, weight ≈ `PASS·|query|` — last resort by
+  arithmetic, not rule.
+- **Paid acts are accounted:** the bridge's corroborated substitutions cost
+  `CONCEPT` each in `moves`, so their spans must be `accounted`; otherwise the
+  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.
+
+## Pins
+
+- `test/01-floor` — floor geometry.
+- `test/04-think` — decider, admissible pruning, investment discipline.

package/docs/architecture/memoization.md

@@ -0,0 +1,96 @@
+# Memoization — Shared Evidence Without Duplication
+
+> **Law:** asking never writes, so structural reads are pure during one
+> response. Memoization elides probes, not evidence.
+
+Two layers: `Precomputed` (response-scoped shared analyses) and `Mind`
+per-response memos. Both are accelerators that must not change what inference
+computes.
+
+## Precomputed — one response, one container
+
+`Precomputed` (`src/mind/pipeline-mechanism.ts`) is the sole place a response's
+shared evidence lives. Created by `think` (`src/mind/pipeline.ts`) before the
+mechanism loop.
+
+### Eager — populated before any `floor`/`run`
+
+- `rec: Recognition` — structural + canonical decomposition (`recognise`)
+- `computed: ComputedSpan[]` — `parse()` results from all mechanisms (e.g. ALU)
+- `guide: Vec` — query gist, the response-wide disambiguation guide
+- `k: number` — `cfg.recallQueryK * 2`, the breadth for resonance/weave/climb
+
+### Lazy — computed on first touch, cached by promise
+
+Expensive analyses are `async` and cached by promise: the first caller starts
+the work, every later caller awaits the same promise.
+
+- `attention()` — `climbAttentionAll` (roots + ranked anchors)
+- `weave()` — `alignGraded` over top-k anchors
+- `resonance()` — `store.resonate(guide, k)` (single ANN query)
+- `frames()` — `frameSlots` inventory from resonance
+- `spanShapedOf(anchor)` / `spanShapedAll()` — per-anchor `skillExemplar`,
+  memoised per id
+- `queryWindows` / `queryResolved` / `windowsOf(anchor)` — W-window identities
+- `reachMemo` — `sharedReachMemo(ctx)` (ancestor reach, § below)
+
+A mechanism that never asks pays nothing; two mechanisms asking the same
+question pay once. `floor()` must gate on `worthRunning` before first-touching
+an expensive analysis.
+
+## Mind memos — `beginResponse` → `endResponse`
+
+`Mind` (`src/mind/mind.ts:beginResponse`/`endResponse`) swaps per-response state
+for each inference call. `respond` takes fresh maps; `respondTurn` reuses the
+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)                  |
+| `_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)      |
+
+`_gistCache` (≈ 8K gists at D=1024) survives across responses; all others are
+dropped or cleared at `endResponse`. `_resolvedSubtrees` elides store probes
+when `visit` is absent; with a visitor it still walks in full (see
+`src/mind/primitives.ts:foldTree`).
+
+## Trace boundary — what is bypassed
+
+Traced responses must emit every step, but must not change the answer.
+
+- **Bypassed:** `_edgeChoice` via `guidedNext`
+  (`src/mind/traverse.ts:guidedNext`) and `sharedReachMemo`
+  (`src/mind/traverse.ts:sharedReachMemo`). Both return fresh empty maps when
+  `ctx.trace !== null`; `chooseNext` recomputes identically (pure over store +
+  guide).
+- **Always consulted:** `perceiveMemo`, `recogniseMemo`, `climbMemo` (and their
+  underlying `perceive`/`recognise`/`climbAttention` caches). Bypassing breaks
+  idempotence.
+
+`foldTree`'s subtree fast path is taken only when no `visit` is supplied. With a
+visitor (recognition, attention) the walk still descends; the cache elides only
+probes. Bypassing `recogniseMemo` under trace re-ran `recogniseImpl` with a warm
+`_resolvedSubtrees` and emitted fewer sites (observed 31 → 5) — a correctness
+change, not just a slowdown.
+
+## Meter — charge work to itself
+
+Shared analyses are charged to their own phase (`meter.time(phase, fn)` in
+`Precomputed.shared`), not to the mechanism that first touched them
+(`src/meter.ts:PhaseCost`). Without this, the profile reads "cast.floor costs 2
+s" when the cost was the consensus climb cast paid for on everyone's behalf.
+
+## Adding a shared analysis
+
+Add one lazy method to `Precomputed`. No new memo map elsewhere. Gate it behind
+`worthRunning` in `floor()`.
+
+## Pins
+
+- `test/42` — recognition idempotence under trace: traced and untraced
+  `recognise` return the same site count and cached object.

package/docs/architecture/meter.md

@@ -0,0 +1,55 @@
+# Meter — Work Accounting
+
+`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`.
+
+## Five contracts
+
+1. **Write-only from inference.** No counter reaches a decision, a threshold, or
+   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.
+
+4. **Count once.** Off by default and free when off
+   (`new Mind({ profile:
+   true })` to attach). A layer that wants to be
+   visible bumps a field in `meter.ts` — it does not grow a private counter.
+   (Legacy `danglingReads` / `compactFailures` in `store.ts` are health
+   counters, not per-response work.)
+
+5. **Shared analyses charged to themselves.** The first toucher pays the wall
+   clock, but every later consumer gets the result free. Attribution follows the
+   analysis, not the mechanism that first triggered it — otherwise the profile
+   misreads which work is expensive (e.g. the consensus climb billed through
+   whichever mechanism happened to need it first).
+
+## Where counters live
+
+`src/meter.ts:Meter` is the only definition of a counter name. Phases are
+charged via `meter.time(phase, fn)` / `meter.timeSync(phase, fn)`, which
+snapshot counters on entry and attribute the delta to the phase. The sync/async
+seam is load-bearing: synchronous layers (perception, recognition, graph search)
+must use `timeSync` so the profiled path does not await where the unprofiled
+path does not.
+
+`CostReport` is plain JSON (`version`, `elapsedMs`, `queryBytes`, `counters`,
+`phases`). Zero-valued counters are dropped; `formatReport` renders the three
+heaviest counters per phase.
+
+## Pins
+
+- `test/55` — `Meter`, `CostReport`, `searchPops` / `searchPushes`, phase
+  nesting.