@hviana/sema 0.9.4 → 0.9.5

package/docs/architecture/match-project.md

@@ -1,61 +1,70 @@
 # 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.
+> **Law:** every grounding mechanism is a configuration
+> `(matcher, direction, gate)` over one shared family in `src/mind/match.ts`.
+> The family reports and moves. Only the consumer that speaks decides whether a
+> shape may be voiced.
 
-## The shared family in `mind/match.ts`
+## The family
 
-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.
+**Match: where the question sits in a learnt form.**
 
-## The triple
+- `locate` — the graded ladder, exact bytes → halo role → gist
+  (`exact-vs-approximate.md`).
+- `alignRuns` — literal `W`-gram runs, the weave.
+- `alignGraded` — literal runs plus halo-matched sites and climb proposals.
+- `alignAround` / `frameSlots` — a seeded frame whose gaps are contracted.
+- `bestHaloMate` — the best halo match within a list.
+- `analogyStrength` / `sharedFrameStrength` — distributional and structural
+  analogy.
 
-| 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` (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.                                                      |
+**Project: which way to move along the store from the match.**
 
-Mechanisms declare only `(matcher, direction, gate)`. Thresholds behind gates
-live in `src/geometry.ts` — the match layer never invents a cutoff.
+- `follow` — forward to a fixpoint. The first hop may be a `conceptHop`, which
+  borrows a halo sibling's edge.
+- `reverseContext` — backward, to a context.
+- `project` — forward, else backward.
 
-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`).
+**Gate: whether the shape licenses voicing.** There are two readings of
+"contained", and they are not interchangeable:
 
-## Frame reading — matcher reports, gate judges, inventory elects nothing
+- `isSpanShaped` — the open reading: a sparse subsequence.
+- `containsSpan` — the strict reading: a contiguous run, or a resolved node.
 
-`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.
+Two more gate functions: `skillExemplar` maps an anchor to its context and
+answer, and `carriesFillers` is the substitution licence.
 
-`carriesFillers` is the substitution gate. It judges byte-exactly:
+Every threshold behind a gate is derived in `geometry.ts`. The match layer never
+invents a cutoff.
 
-```
-substituteAll(contA, fillersA → fillersB) == contB
-```
+## Frame reading — the matcher reports, the gate judges, the inventory elects nothing
 
-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.
+- **`frameSlots` reports.** It contracts every gap to its varying core
+  (`contractGap`), tags it as a `substitution`, `insertion` or `deletion`, and
+  attaches `covered`, the bytes the frame accounts for. It applies no gate.
+- **`carriesFillers` judges, byte for byte:**
+  `substituteAll(contA, fillersA → fillersB) == contB`. If the equality holds,
+  voicing through the slot is a derivation. This is the only place that decision
+  is made.
+- **`Precomputed.frames` is the inventory.** It enumerates every pairing and
+  elects nothing.
 
-`Precomputed.frames` is the inventory. It enumerates every frame pairing the
-match layer finds and elects nothing — ranking and refusal belong to the
-consumer.
+## Why gates belong to the consumer
 
-## Voicing gates belong to the consumer
+A gate placed in the shared layer refuses on everyone's behalf. When
+`reference`'s voicing gates lived in `frameSlots`, the shared reading became
+shaped like `reference`, and it hid three of four real pairings from every other
+consumer, including a definite description standing where a noun stands. So each
+consumer owns its own refusal:
 
-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 gate into `match.ts` would hide who owns the refusal.
+- `reference` requires that the frame dominates the query, every slot reaches
+  `W` on both sides, there are substitutions only, the fillers are distinct, and
+  `carriesFillers` holds.
+- CAST, `recall` and `cover` apply their own gates to the same inventory.
 
 ## 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.
+- `test/47` — the frame reading split into matcher, inventory and gate.
+- `test/50` — voicing through `carriesFillers` in CAST and `reference`.
+- `test/24`, `test/76` — the match and project family and its span-shape
+  readings.

package/docs/architecture/mechanism-market.md

@@ -1,116 +1,112 @@
-# Mechanism Market — The Free-Will Architecture
+# Mechanism Market — Many Ways of Thinking, One Price
 
-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.
+> **Law:** every grounding mechanism, including the ALU and user extensions,
+> speaks one interface (`mind/pipeline-mechanism.ts`). The decider (`think`,
+> `mind/pipeline.ts`) weighs every candidate in one currency and never asks
+> which mechanism produced it.
 
-## Interface
+A question can be answered in several ways that are not interchangeable: compose
+it, carry structure between woven forms, intersect conditions, read a frame,
+voice a slot, recall the nearest form, complete a beginning, or compute. Sema
+keeps all of them and lets the evidence choose.
+
+## The 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
+  parse?(query): Promise<ComputedSpan[]>; // authoritative spans, collected before any floor
+  floor(ctx, query, pre, worthRunning): Promise<number | null>; // admissible bound, or null
+  run(ctx, query, pre): Promise<MechanismResult[]>;
 }
 interface MechanismResult {
-  bytes: Uint8Array;
-  accounted: Array<[number, number]>;
-  moves: number;
-  used?: ReadonlySet<number>;
-  scaffolding?: number;
-  provenance?: string;
-  complete?: boolean;
+  bytes;
+  accounted: Array<[number, number]>; // spans of the query explained
+  moves: number; // work done, on the cost ladder
+  used?;
+  scaffolding?;
+  provenance?;
+  complete?;
 }
 ```
 
-- `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).
+`floor` returns `null` when the mechanism cannot apply. Otherwise it returns a
+lower bound that never overstates the cost.
 
-## Decider
+## The decider
 
-`think` iterates `defaultMechanisms` in list order:
+The default order is
+`cover, cast, confluence, extraction, reference, recall,
+prefix-completion`,
+then the ALU (`aluToMechanism`), then extensions. A mechanism reports what it
+did, never a price. The decider prices it in one place (`cost-model.md`):
 
 ```
-defaultMechanisms = [cover, cast, confluence, extraction, reference, recall,
-                     prefix-completion] + ALU (`aluToMechanism`) + extensions
+weight = moves + PASS · unaccountedBytes      grade = ⌊weight / STEP⌋
 ```
 
-Weight is one currency: `weight = moves + PASS · unaccountedBytes` where
-`unaccountedBytes = unexplainedSpans(query.length, accounted)`. Comparison is at
-`STEP` grade ; equal grade prefers fewer `scaffolding` bytes, then list order.
+The lowest grade wins. At equal grade, fewer `scaffolding` bytes win, then the
+earlier mechanism in the declared 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 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.
-4. **Evidence travels** — every candidate carries `accounted` (query spans
-   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.
+1. **Decoupled.** No mechanism imports another or asks what already decided.
+   Adding one touches no other.
+2. **Declared competence.** A mechanism abstains through binary structural gates
+   (query length, anchor shape, whether a weave exists), never through a learned
+   score, and the rationale says why it abstained.
+3. **Visible budget.** Every loop at corpus scale is capped by a named bound:
+   `hubBound`, or `Precomputed.k = 2·recallQueryK` (`bounded-reads.md`).
+4. **Evidence travels.** A candidate carries:
+   - `accounted` and `moves`;
+   - optionally `scaffolding`, the answer bytes lifted from unrecognised spans,
+     which only breaks ties;
+   - `complete`, a continuation reached by identity, which nothing after
+     grounding may extend;
+   - `used`, the anchors it speaks for;
+   - `provenance`.
+
+   The decider honours all of these 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.
-
-- **A cheaper bound is looked at first.** Before mechanism `m` first-touches
-  anything, every LATER mechanism whose floor grade is strictly below `m`'s runs
-  ahead of it (cheapest first); the lowest grade they reach is `bound`, and any
-  mechanism floored above `bound` is skipped (`meter.mechanismsBounded`). The
-  bound is learnt by calling `floor` with a `worthRunning` that refuses — the
-  investment discipline makes that free. The DECISION is the declared order's: a
-  run-ahead mechanism bounds the final grade whether or not the declared order
-  would have run it (if pruned, the incumbent already sat at or below its
-  floor); every candidate above `bound` loses to the winner, and every mechanism
-  floored at or below it meets the same run-or-prune decision, so `consider`
-  replays the same candidates in declared order. Equal floors are not skipped,
-  so an earlier mechanism keeps the tie it would win. Running ahead is never
-  extra work: only a mechanism floored at or below `p` can prune `p`, and each
-  such mechanism has already run or runs ahead of `p`. Measured on the
-  31.7M-node store: a lowercased Persian turn (#83) went from 18.0 s to 1.2 s,
-  and #114 from 1.9 s to 0.7 s. In both, a grade-1 recall or prefix answer no
-  longer waits behind CAST's climb and weave. Of 42 composition-regime queries,
-  none changed its answer.
-
-- **Investment discipline.** `worthRunning` is passed _into_ `floor`. A floor
-  that would first-touch an expensive shared analysis (`pre.attention()` climb,
-  `pre.weave()`, `pre.resonance()`) checks `worthRunning(cheapestBound)` first
-  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
-
-- **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 so `PASS`-bridged bytes are still charged. `narrowDecision` and
-`thinGrounding` are observational only.
+**Never compute what cannot change the decision.** `floor` runs for every
+mechanism before any `run`, and a mechanism runs only if
+`worthRunning(floor) = best === null || grade(floor) < grade(best)`. Every
+`floor` that would first touch an expensive shared analysis (`attention()`,
+`weave()`, `resonance()`) asks `worthRunning` first, and returns its uninvested
+bound if it would lose. `cast.ts` and `extraction.ts` are the references.
+
+**Look at a cheaper bound first.** Before a mechanism first touches anything,
+every later mechanism whose floor grade is strictly lower runs ahead of it,
+cheapest first. The lowest grade they reach becomes a bound, and any mechanism
+floored above that bound is skipped (`meter.mechanismsBounded`). The decision
+stays the declared order's:
+
+- every candidate above the bound loses to the winner;
+- every mechanism at or below the bound meets the same decision it would have
+  met in order;
+- equal floors are never skipped.
+
+This is never extra work. On the 31.7M-node store a lowercased Persian turn went
+from 18.0 s to 1.2 s, and another query from 1.9 s to 0.7 s, because a grade-1
+recall no longer waited behind CAST's climb. Of 42 composition queries, none
+changed its answer.
+
+## Accounting rules
+
+- **Extraction.** Located frames are evidence. The span between two frames
+  counts only when both borders were located, and an open-ended read is priced
+  by exclusion.
+- **Reverse reading.** `reverseContext` produces bytes but explains nothing
+  forward, so `accounted = []`. It is the last resort by arithmetic, not by
+  rule.
+- **A paid act is accounted.** The bridge charges `CONCEPT` per substitution, so
+  the substituted spans are `accounted`. Otherwise one act is charged twice, and
+  `PASS` per byte decides against it.
 
 ## Pins
 
-- `test/01-floor` — floor geometry.
-- `test/04-think` — decider, admissible pruning, investment discipline.
-- `test/153` — run-ahead bounds: the composition market is skipped below CAST's
-  floor, and the decision equals a declared-order oracle.
+- `test/01` — the floor's geometry.
+- `test/04` — the decider, admissible pruning and the investment discipline.
+- `test/153` — the run-ahead bound: a mechanism floored above it is skipped, and
+  the decision equals the declared-order oracle.

package/docs/architecture/memoization.md

@@ -1,96 +1,82 @@
-# Memoization — Shared Evidence Without Duplication
+# Memoization — Shared Evidence, Computed Once
 
-> **Law:** asking never writes, so structural reads are pure during one
-> response. Memoization elides probes, not evidence.
+> **Law:** asking never writes, so within one response every structural read is
+> pure. A memo may skip a probe. It may never change what inference computes.
 
-Two layers: `Precomputed` (response-scoped shared analyses) and `Mind`
-per-response memos. Both are accelerators that must not change what inference
-computes.
+**Why.** One question is read by up to eight mechanisms, and the same analysis
+(the consensus climb, the weave, a resonance query) must not be paid eight
+times. Nor may whoever asked first be billed for everyone.
 
-## Precomputed — one response, one container
+## `Precomputed` — one response, one container (`mind/pipeline-mechanism.ts`)
 
-`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.
+`think` creates it before any mechanism runs. It is the only place a response's
+shared evidence lives.
 
-### Eager — populated before any `floor`/`run`
+**Eager**, populated before any `floor` or `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
+- `rec`, the recognition;
+- `computed`, every mechanism's `parse` spans;
+- `guide`, the query gist;
+- `k = 2·recallQueryK`.
 
-### Lazy — computed on first touch, cached by promise
+**Lazy**, cached by promise, so the first caller starts the work and every later
+caller awaits it:
 
-Expensive analyses are `async` and cached by promise: the first caller starts
-the work, every later caller awaits the same promise.
+- `attention()`, the consensus climb;
+- `weave()`;
+- `resonance()`, the single top-`k` ANN query;
+- `frames()`;
+- `spanShapedOf(anchor)` / `spanShapedAll()`;
+- the window identities `queryWindows`, `queryResolved` and `windowsOf`;
+- `reachMemo`.
 
-- `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, and two that ask the same question pay
+once. A `floor` checks `worthRunning` before it first touches an expensive
+analysis (`mechanism-market.md`). Each shared analysis is charged to its own
+meter phase through `Precomputed.shared`, never to whichever mechanism touched
+it first (`meter.md`).
 
-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/mind.ts`)
 
-## Mind memos — `beginResponse` → `endResponse`
+`respond` takes fresh maps. `respondTurn` reuses the conversation's maps, which
+are content-keyed across turns.
 
-`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                   | Lifetime                            |
+| ---------------------------------------------------- | --------------------- | ----------------------------------- |
+| `perceiveMemo`                                       | bytes + boundary set  | response or conversation            |
+| `recogniseMemo`, `climbMemo`                         | bytes                 | response or conversation            |
+| `canonMemo`                                          | bytes                 | response, when a `canon` is set     |
+| `_resolvedSubtrees`                                  | tree node (`WeakMap`) | response or conversation            |
+| `_edgeChoice` (the pick memo), `_edgeAsked`          | node / question       | response; cleared at the end        |
+| `sharedReachMemo`, structural probes (`traverse.ts`) | node                  | cleared on write or at 100K entries |
 
-| Memo                | Key                                       | Scope                                        |
-| ------------------- | ----------------------------------------- | -------------------------------------------- |
-| `perceiveMemo`      | `perceiveKey(bytes)` (latin1)             | response / conversation                      |
-| `recogniseMemo`     | `latin1(bytes)`                           | response / conversation                      |
-| `climbMemo`         | `latin1(bytes)`                           | response / conversation                      |
-| `canonMemo`         | `latin1(bytes)`                           | response (when `canon` set)                  |
-| `_resolvedSubtrees` | `WeakMap<Sema, {id,len}>` (node identity) | response / conversation                      |
-| `_edgeChoice`       | `Map<nodeId, pick>`                       | response only — **cleared** in `endResponse` |
-| `_gistCache`        | `BoundedMap<nodeId, Vec>` 32 MB           | **session-lifetime** (not per-response)      |
+`foldTree` takes the `_resolvedSubtrees` fast path only when no visitor is
+passed. A walk that emits sites always descends in full, and the cache only
+elides store probes.
 
-`_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`).
+## The trace boundary
 
-## Trace boundary — what is bypassed
+A traced response must emit every step and still give the same answer.
 
-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.
+- **Bypassed under trace:** the pick memo (`guidedNext`) and `sharedReachMemo`.
+  Both return fresh maps, and `chooseNext` recomputes the same pick from the
+  store and the question.
+- **Always consulted:** `perceiveMemo`, `recogniseMemo` and `climbMemo`.
+  Bypassing `recogniseMemo` once re-ran recognition over a warm subtree cache
+  and emitted 5 sites instead of 31. That was a change in the answer, not just a
+  slowdown.
+- **The pick memo is cleared when the climb publishes its points.** A pick made
+  earlier read less evidence, and keeping it made traced and untraced responses
+  disagree.
 
 ## Adding a shared analysis
 
-Add one lazy method to `Precomputed`. No new memo map elsewhere. Gate it behind
-`worthRunning` in `floor()`.
+Add one lazy method to `Precomputed`, never a memo map elsewhere, and guard it
+behind `worthRunning` in `floor`.
 
 ## Pins
 
-- `test/42` — recognition idempotence under trace: traced and untraced
-  `recognise` return the same site count and cached object.
+- `test/42` — recognition is idempotent under trace: same site count, same
+  cached object.
+- `test/155.4` — traced and untraced responses agree once the climb publishes
+  its points.

package/docs/architecture/meter.md

@@ -1,55 +1,45 @@
-# Meter — Work Accounting
+# Meter — What an Answer Cost
 
-`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: the public path — `new Mind({ profile: true })`, then
-`mind.lastCost` (`formatReport` / `sumReports`).
+> **Law:** `src/meter.ts` is the one surface that accounts for work. Inference
+> writes to it and never reads it. Its counters are exact. Its milliseconds are
+> hints.
 
-## 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 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.
+The rationale says why an answer was chosen; the meter says what choosing it
+cost. Together they are Sema's development instrumentation, read only through
+the public path: `new Mind({ profile: true })`, then `mind.lastCost`
+(`formatReport`, `sumReports`).
 
-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.
+## Five contracts
 
-`CostReport` is plain JSON (`version`, `elapsedMs`, `queryBytes`, `counters`,
-`phases`). Zero-valued counters are dropped; `formatReport` renders the three
-heaviest counters per phase.
+1. **Write-only.** No counter reaches a decision, a threshold or an ordering.
+   Every call site is `meter?.x++` on a nullable field, so determinism survives
+   because the meter is observed, never consulted.
+2. **Counters decide; milliseconds hint.** Counters are deterministic and can be
+   diffed. Compare two cold runs, because a repeated query meters less as memos
+   warm. `elapsedMs` and per-phase `ms` depend on the machine: on a busy
+   workstation, back-to-back runs of one build differ by up to ±15%. Judge a
+   change by its counter deltas, never by time alone.
+3. **Phases nest; they do not partition.** A phase is charged by the layer doing
+   the work, and a mechanism's `floor` includes whatever shared analysis it
+   touched first. Read a phase as inclusive wall-clock time and never sum
+   phases. `CostReport.elapsedMs` is the only whole.
+4. **One home for every counter name.** The meter is off by default and free
+   when off. A layer that wants to be visible adds a field to `Meter`. It never
+   grows a private counter, a log or a timing probe (`AGENTS.md` §6). The
+   store's `danglingReads` and `compactFailures` are session health counters,
+   not per-response work.
+5. **A shared analysis has its own phase.** Phases are charged with
+   `meter.time(phase, fn)`, or with `timeSync` for synchronous layers, so the
+   profiled path never awaits where the unprofiled path does not.
+   `Precomputed.shared` gives each shared analysis its own phase. Otherwise the
+   profile would read "`cast.floor` costs 2 s" when the cost was the consensus
+   climb, run on everyone's behalf.
+
+`CostReport` is plain JSON: `version`, `elapsedMs`, `queryBytes`, `counters` and
+`phases`. Zero counters are dropped, and `formatReport` shows the three heaviest
+counters in each phase.
 
 ## Pins
 
-- `test/55` — `Meter`, `CostReport`, `searchPops` / `searchPushes`, phase
+- `test/55` — `Meter`, `CostReport`, `searchPops`/`searchPushes`, and phase
   nesting.