@hviana/sema 0.9.3 → 0.9.5

package/docs/architecture/closure.md

@@ -1,120 +1,101 @@
-# 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, one law and one engine, asked by every tier that decides whether to
-continue: the chart's frontier, the market's candidates, the post-grounding
-walk, fusion, and the mechanisms' own gates. None re-spells a condition the law
-owns.
-
-## The unit — `src/mind/derivation.ts`
-
-| 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 boundary
-
-`product` (what it stands on, its identity being `resolve(product)`),
-`accounted` (the price its steps summed) and `remainder` (the question's debt,
-at one quantum) are the derivation's own. What it REACHED and what it SPENT are
-the layer's (`reaches`, `consumed`), never a field here: the law decides
-admission and consumption, the layer decides frontier and termination.
+# Closure — One Law for Every Transition
+
+> **Law:** a step is admitted only when it **closes** the derivation, **moves**
+> to structure the derivation has not consumed, or **carries** material the
+> asker left unaccounted.
+
+**Why.** Every tier that decides whether to continue asks this one law, and none
+re-spells a condition it owns. Those tiers are the chart's frontier, the market,
+the walk after grounding, fusion, and the mechanisms' own gates. Without the law
+a derivation could wander: restate what it already said, cycle, or extend into
+facts nobody asked for.
+
+## The unit — `DerivationState` (`src/mind/derivation.ts`)
+
+| Field       | Meaning                                                                             |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `product`   | the answer bytes, what the derivation stands on; its identity is `resolve(product)` |
+| `accounted` | the asker's spans its steps explain, a cost quantity                                |
+| `remainder` | what the asker still owes, per span, at the `W` floor; empty means **closed**       |
+| `cost`      | its position on the ladder                                                          |
+| `fixed`     | a declared fixpoint: the query _is_ the context, so no transition is offered        |
+| `used`      | the anchors the product speaks for; an empty set declares that it voices nothing    |
+
+There is no identity field, no frontier, no producer and no count. What the
+derivation _reached_ and _spent_ belongs to the layer, which holds the structure
+and hands the law its witnesses (`contains`, `moves`). 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.
-
-The walk ends when the layer stops offering or the law refuses; owning no
-search, the law cannot prevent a cycle — that is the layer's, over the structure
-it holds. A transition is only ever `advance`: a fusion the law refuses is not
-taken (there is no hand-built fallback).
+`admissible(state, continuation, query, W)` returns the witnesses a step pays
+in, or `null`. `advance(state, continuation, witnesses)` is the only transition.
+No state is built by hand anywhere else (`test/137.7`).
+
+- **A state is born owing** everything its product does not carry.
+- **`carries` admits by engagement and consumes nothing.** Only a declared move
+  consumes, and only the material its window proves. Both shortcuts were
+  refuted: draining whole spans (`test/110`) and trusting the window alone
+  (`test/138`).
+- **A step the question did not name pays from what it still owes.** Naming is
+  the evidence law (`evidence.md`).
+- **The law owns no search, so it cannot prevent a cycle.** That belongs to the
+  layer, which holds the structure. A fusion the law refuses is simply not
+  taken, and there is no hand-built fallback.
 
 ## The engine — `closeOver`
 
-`closeOver(state, query, W, layers, enter?)` closes a derivation under the law,
-layer by layer. A layer (`ClosureLayer`) is a named `Offer` with its own
-instrumentation hooks; each is walked by `closure` to its own end, and the state
-it reaches is the state the next layer is offered against. Layers are PHASES, in
-order, never revisited.
-
-- **¬FIXED is the engine's.** A fixed state admits no transition, so no layer is
-  entered for it — the walk-skip and fusion-skip a caller used to spell by hand
-  are the law's first clause, taken before any layer pays.
-- **Engagement is the layer's.** A layer that has nothing to offer a state
-  (`engages`) is not entered: no offer, no meter phase.
-- **The pipeline's post-grounding stage IS the engine**, with two layers: the
-  walk (`walkLayer` — forward absorb or pivot) and the fusion (`fusionLayer` —
-  one composed transition, engaged only while the derivation is open). There is
-  no hand-built state anywhere outside `advance` (`test/137.7`).
-
-## The four quantities (trap 13), and where each stands
-
-| Quantity                | Status                                                                                                                                                                                                                                                                                                                                                                                            |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| offer of a hop          | Consequence. Chart: the corpus's continuations under the READ cap, each a MOVE priced STEP, the search decides (`test/112`). Walk: absorb/pivot, the law admits.                                                                                                                                                                                                                                  |
-| depth of a join         | Consequence. The join consumes the shortest tail prefix naming a learnt key that leads — CONTAINS (resolves) ∧ MOVES (leads) — and chains until the tail is consumed; no count (`test/108`). It is priced for the facts a lightest derivation STANDS ON, round by round (`solve`'s join license), never for every fact the exploration reaches — the `deepen` cure for the `recompleteNode` trap. |
-| scope of a gap          | Consequence for alignment (`alignAround` walks outward, no cap). NOT for recognition's interior pass: its reach `W⁴ + 2r` bounds an exhaustive embedded-form probe; exact unbounded reach needs a whole-stream index the store does not have.                                                                                                                                                     |
-| scope of a substitution | Consequence: the gap between two aligned anchors (`unexplainedSpans`), gated as scaffolding by the global commonality reading. The filler-unanimity window (`chainReach`) is a derived decision scale, not an explosion cap.                                                                                                                                                                      |
-
-## One cost home
-
-`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.
-
-## Three limits, proved and left out
-
-1. **The chart cannot evaluate accounting** — its interface has no parameter for
-   it, and carrying it per item was measured and rejected. The chart reads the
-   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.
-3. **The extension is not priced into the market** (`test/136.2`): the engine
-   closes the WINNER only; pricing each candidate's closure would run the walk
-   for every candidate, and that comparison has not been measured.
+`closeOver(state, query, W, layers)` closes a derivation layer by layer. A layer
+(`ClosureLayer`) is a named offer with its own instrumentation. Layers are
+phases: each runs to its own end, in order, and is never revisited.
+
+- **"Not fixed" is checked first.** A fixed state admits no transition, so no
+  layer is entered.
+- **Engagement is the layer's.** A layer with nothing to offer a state
+  (`engages`) is not entered, and pays no offer and no meter phase.
+- **The pipeline's post-grounding stage is this engine,** with two layers. The
+  walk (`walkLayer`) absorbs forward or pivots. The fusion (`fusionLayer`) makes
+  one composed transition, and engages only while the derivation is open.
+
+## What the law decides, and what it does not
+
+- **The offer of a hop is a consequence.** The chart offers the corpus's
+  continuations under the read cap, each a move priced `STEP`, and the search
+  decides (`test/112`).
+- **The depth of a join is a consequence.** A join consumes the shortest tail
+  prefix that names a learnt key leading somewhere, and chains until the tail is
+  consumed (`test/108`). It is priced only for the facts the lightest derivation
+  stands on, never for everything the exploration reached (`test/150`).
+- **A gap's reach is not a consequence everywhere.** In alignment it is: the
+  walk goes outward with no cap. Recognition's interior pass is bounded at
+  `W⁴ + 2r`, because exact unbounded reach would need a whole-stream index the
+  store does not have.
+
+Three limits were proved and deliberately left out:
+
+1. **The chart cannot evaluate accounting.** Carrying it per item was measured
+   and rejected, so the chart reads the law off its items: identity is the key,
+   continuation is a rule existing, closure is the goal test.
+2. **Closure by the query's position in the graph is the layer's, not the
+   unit's.** The echo guards stop with the remainder non-empty, and recall's
+   reverse tiers close with nothing accounted.
+3. **The extension is not priced into the market.** Only the winner is closed,
+   because pricing every candidate's closure has not been measured
+   (`test/136.2`).
 
 ## 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.
+`derivation.ts` imports only `../bytes.js` and sits below `graph-search.ts`,
+`match.ts`, `rationale.ts` and `pipeline.ts`. The span algebra
+(`unexplainedSpans` and its relatives) lives here as the law's vocabulary.
 
 ## 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 nothing.
+- `test/133`–`137` — the law's home, its readings, refusal and limits.
+- `test/138`, `test/139` — a cycle cannot close a derivation, and a carried move
+  can; carrying is engagement, not explanation.
 - `test/142`, `test/143` — the offer's contract, and the cycles.
-- `test/144`, `test/146`, `test/147` — identity is content, the `contains` gate,
-  the witness ladder.
-- `test/137.7` — no transition is built by hand outside the law.
-- `test/149` — the engine: ¬FIXED first, layers as phases, engagement, a refusal
-  ends one layer, and the pipeline sequences no layer by hand.
-- `test/150` — the join prices the facts a derivation stands on, not every fact
-  the exploration reaches (a hub's degree changes nothing).
-- `test/151` — the cover's other async premises (connectors, concept hops) are
-  resolved where the search reaches them; a span's cheapest completion
-  dominates; a grounding on the whole query pays no fusion climb.
+- `test/149` — the engine: "not fixed" first, layers as phases, engagement, and
+  no layer sequenced by hand.
+- `test/150`, `test/151` — the join prices only what the derivation stands on,
+  and a hub's degree costs nothing.

package/docs/architecture/commonality.md

@@ -1,54 +1,63 @@
-# Three Measures of Commonality
+# Commonality — What Is Shared, Relative to Whom
 
-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.
+> **Law:** every judgement of relevance cuts a population into what it shares
+> (frame, scaffolding) and what varies (filler, the discriminating part). The
+> cut is always read over a named population. Sema uses three populations, with
+> three measures, and never substitutes one for another.
 
-## Corpus-global — `reachOf` + `dominates`
+Commonality and discrimination are the two sides of one cut, and the cut has no
+absolute answer. `the importance of` is frame among the essay prompts aligned to
+a question and filler across the corpus. Reading one population's cut with
+another population's measure was refuted every time it was tried (`test/17`, and
+the container-as-hub saturation in `saturation.md`).
 
-_Defined in `src/mind/traverse.ts` + `src/geometry.ts`; used by climb,
-containment, IDF pooling._
+## The three populations
 
-For a node id, `reachOf(id, N)` counts how many learnt contexts contain it
-(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.
+**Corpus contexts: how widely a node is used.**
 
-## Weave-local — `depth[]` + `MIN_WEAVE` + `dominates`
+- Measure: `reachOf(id, N)`, the learnt contexts its containment and edge climb
+  reaches, capped and memoized in `sharedReachMemo`.
+- Cut: `dominates(reach, N)`. A majority is scaffolding, and a minority
+  discriminates. The climb reads the graded form of the same cut, weighing a
+  region by `ln(N/c)`.
+- Read by the consensus climb, `confluence`'s gate and edge following.
 
-_Defined and gated in `src/mind/mechanisms/cast.ts` (`depth[]` from the shared
-weave, `MIN_WEAVE`); used by CAST._
+**The cohort: the structures aligned to this question.**
 
-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 (pairs are
-ambiguous with insertions), and `dominates(depth[i], aligned)` a majority of the
-cohort:
+- Measure: `depth[i]`, the number of distinct structures in the weave that cover
+  byte `i`. They are counted as distinct, never by weight.
+- Cut: `frame(i) ⇔ depth[i] > MIN_WEAVE ∧ dominates(depth[i], aligned)`, with
+  `MIN_WEAVE = 2`, because a pair is ambiguous when insertions are possible.
+- Read by CAST (`cast.ts`).
 
-```
-frame(i) ⇔ depth[i] > MIN_WEAVE ∧ dominates(depth[i], aligned)
-```
+**Places: where a window occurs.**
 
-This powers CAST's frame gate — what the cohort shares vs what differentiates
-one member — and never consults corpus reach.
+- Measure: `containersSlice(id, 0, bound + 1).length`, the window's containers.
+- Cut: `0` anchors nothing, and `≥ 2` marks the window as reused. Above the hub
+  bound, the window is scaffolding.
+- Read by the bridge and by attention, which anchor on the rarest window first,
+  and by the scaffolding readings (`scaffoldExtents`,
+  `allWindowsAreScaffolding`).
 
-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.
+**Scaffolding is nobody's evidence and nobody's debt.** A window in more than
+`√N` places explains nothing, because every fact holds it. So a step cannot pay
+the question by restating `is`, and a cover span made only of scaffolding is not
+accounted (`evidence.md`).
 
-## Container-local — the window's rarity
+`hubWindows` floors that bound at `chainReach(W) = W²`. Inside one deposit's
+fold, a window is already contained by up to that many chunks and branches. On a
+store of a few facts, `√N` alone would call every window scaffolding, which
+measures fold structure, not commonness (`test/22`).
 
-_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.
+Two limits bound every cut. Below lies chance: one pair, or a resemblance under
+`3/√D`, cannot be told from accident. Above lies ubiquity: what everyone holds
+discriminates nothing and abstracts nothing.
 
 ## Pins
 
-- `test/17` — weave-local frame / `MIN_WEAVE` / `dominates` vs corpus-global
-  reach.
+- `test/17` — the weave-local frame, `MIN_WEAVE` and `dominates`, against corpus
+  reach (the reorder probe).
 - `test/34` — containment and reach-driven disambiguation.
+- `test/73` — a question made only of scaffolding is abstained from by the
+  bridge.
+- `test/22` — the hub floor on small stores.

package/docs/architecture/cost-model.md

@@ -1,87 +1,65 @@
 # Cost Model — One Currency
 
-Every mechanism and every byte competes on one cost ladder defined in
-`src/mind/graph-search.ts`. GraphSearch and `pipeline.ts:think` use the same
-units, so a mechanism-level choice and a byte-level choice are the same kind of
-decision: a lightest derivation.
-
-## Ladder (`src/mind/graph-search.ts`)
-
-| Cost      | Value         | Meaning                                                                                                                                                                           |
-| --------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MICRO`   | `1e-3`        | Recognised advance (one `rec` bridge); per-byte unit of the A\* heuristic. A recomposed form's onward edge is also `MICRO`.                                                       |
-| `STEP`    | `1`           | Every edge hop (first or fifth), every computed result, every projection. Charging every hop makes the lightest derivation the shortest chain.                                    |
-| `CONCEPT` | `10`          | Halo-mediated act (synonym hop, consensus climb) and abandoning an edge chain early (`CONCEPT` above chain cost — genuine fixpoint at `+0` always beats giving up at same depth). |
-| `PASS`    | `1000` / byte | Carrying a byte nothing explains. Dominates everything so the search always prefers to recognise.                                                                                 |
-
-Only the **ordering** `MICRO < STEP < CONCEPT < PASS` matters; any constants
-with that order give the same derivations.
-
-## Pipeline weighing (`src/mind/pipeline.ts:think`)
-
-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 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
-
-- **(min, +) tropical** — lightest derivation in `GraphSearch` via `src/derive`
-  (`lightestDerivation`). Cost accumulates with `+`, choice selects `min`.
-  Powers `cover`/`form`/`out`, edge following, fusing, and the A\* agenda
-  (`g + h`).
-
-- **(+, +) arithmetic** — evidence pooling in `src/mind/attention.ts:poolVotes`.
-  Each region's vote is an axiom; rules carry `Rule.combine = 'sum'` so costs to
-  the same anchor **add** rather than minimise. Powers IDF-weighted consensus,
-  `votes`/`votesIdf`/`support`, and `regionSupport`/`regionPeak`.
-
-## Admissibility
-
-The A\* heuristic is admissible and consistent:
-
-```
-h(it) = (queryLen - right) * MICRO
-```
-
-`right` is `p` for `cover(p)` or `j` for `form/out [i,j)`. `MICRO` is the
-minimum per-byte cost in the ladder (every real per-byte cost is `>= MICRO`,
-including `PASS`), and only the suffix past `right` is counted, so `h` never
-exceeds the true remaining cost.
-
-## Dominance — why `PASS ≫ STEP` does not flood the chart
-
-The heuristic charges `MICRO` for a byte the goal will pay `PASS` for, so a
-cover that leaves bytes unexplained lets the search spend up to `PASS / STEP`
-hops looking for one more explained byte. Coverage itself cannot use them: every
-recognised completion of `[i, j)` advances the cover from `i` to `j` at the same
-`MICRO`. So a form or completion of `[i, j)` whose cost has reached that of a
-completion of `[i, j)` already yielded is DOMINATED and fires no rule
-(`buildSearch`, metered as `searchDominated`): every completion it could lead to
-costs at least as much, and a tie goes to the one yielded first. What a
-completion's BYTES could still do — fuse, splice, join — fires from the
-completion the search would stand on for that span, the same cure the join
-license and `deepen` apply. The first hop's stop-here (`STEP + CONCEPT`) is then
-a real horizon: no chain deeper than it is expanded.
+> **Law:** every choice, whether a byte inside the search or a mechanism in the
+> market, is a lightest derivation on one ladder (`mind/graph-search.ts`). The
+> price is the question left unexplained, never confidence.
+
+**Why.** Exact identity yields no confidence to choose by. What can be measured
+exactly is how much of the question an answer accounts for. Pricing that makes
+the winner the reading that explains the most, not the one most eager to speak.
+When nothing explains the question, silence is the lightest answer.
+
+## The ladder
+
+| Cost      | Value       | Charged for                                                                                                                                  |
+| --------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MICRO`   | `1e-3`      | a recognised advance, and a recomposed form's onward edge; it is also the A\* heuristic's unit per byte                                      |
+| `STEP`    | `1`         | every edge hop, computed result and projection. Charging every hop makes the lightest derivation the shortest chain                          |
+| `CONCEPT` | `10`        | an act mediated by a halo (a synonym hop, the consensus climb), and abandoning a chain early, so that a real fixpoint always beats giving up |
+| `PASS`    | `1000`/byte | carrying a byte nothing explains. It dominates everything, so the search always prefers to recognise                                         |
+
+Only the order `MICRO < STEP < CONCEPT < PASS` matters. Any constants with that
+order give the same derivations. The market weighs candidates on the same
+ladder, `moves + PASS·unaccounted`, compared at `STEP` grade
+(`mechanism-market.md`).
+
+## Two semirings, one engine (`src/derive`)
+
+- **(min, +), the tropical semiring:** the lightest derivation. Costs add along
+  a derivation, and the cheapest route to a conclusion wins. This powers
+  `cover`, form and continuation rules, edge following, fusion, and the A\*
+  agenda.
+- **(+, +), the arithmetic semiring:** pooled evidence. Rules with
+  `combine: "sum"` add every independent line of evidence for a conclusion
+  instead of keeping the cheapest. This powers the consensus climb's votes
+  (`poolVotes`).
+
+## Admissibility and dominance
+
+The heuristic `h = (queryLen − right) · MICRO` is admissible and consistent.
+`MICRO` is the smallest cost per byte, and only the suffix past the item is
+counted.
+
+Because the heuristic charges `MICRO` for a byte the goal will charge `PASS`
+for, the search could spend up to `PASS/STEP` hops looking for one more
+explained byte. Coverage cannot use them: every recognised completion of
+`[i, j)` advances the cover at the same price. So a form or completion of
+`[i, j)` that costs as much as one already yielded is **dominated**, and fires
+no rule (`searchDominated`). Fusion, splicing and joining fire from the
+completion the search stands on, never from every alternative it reached. That
+makes the first hop's stop-here (`STEP + CONCEPT`) a real horizon.
 
 ## Policy is not cost
 
-"Computation always wins" is **not** priced into the ladder (a computed result
-costs `STEP`, same as a learned edge). It is enforced by masking: `cover.ts`
-removes recognised sites overlapped by a `ComputedResult`, so the computation is
-the sole completion there. Keep policy in callers; keep the engine neutral.
+"Computation always wins" is not priced. A computed result costs `STEP`, like a
+learnt edge. It is enforced by masking: `cover.ts` removes any recognised site
+overlapped by a computed span. Keep policy in the callers, and keep the engine
+neutral. Tuning `PASS` to encode a preference breaks the one contract the ladder
+has, its order.
 
 ## Pins
 
-- `test/52` — climb consensus instrumentation
-- `test/53` — cross-region probe instrumentation
-- `test/54` — evidence `k` instrumentation
-- `test/55` — cost meter (`Meter`, `CostReport`, `searchPops`/`searchPushes`)
-- `test/151` — dominance: a hub's degree generates no chart work
+- `test/04`, `test/55` — the decider's weighing, and the cost meter.
+- `test/151` — dominance: a hub's degree generates no work in the chart.
+- `test/52`, `test/53`, `test/54` — instrumentation of the climb, the
+  cross-region probe and evidence `k`.

package/docs/architecture/determinism.md

@@ -1,73 +1,61 @@
-# Determinism — Same Seed + Same Deposits + Same Query ⇒ Same Bytes
+# Determinism — Same Seed, Same Deposits, Same Question, Same Bytes
 
-## The law
+> **Law:** the same `seed`, the same deposit order and the same query give a
+> byte-identical answer. Every path that can reach output is a function of
+> `(seed, store contents, query bytes)`.
 
-> Same `seed` + same deposit order + same query ⇒ byte-identical answer.
+**Why.** An answer meant to be audited, contested or certified must replay.
+Reproducibility is a property of the architecture, not a flag.
 
-Determinism is the product. Every code path that can reach output must be
-deterministic given `(seed, store contents, query bytes)`.
+## Forbidden on a behavioural path
 
-## Forbidden
+- `Math.random` and `Date.now`.
+- Iteration over an unordered collection whose order can reach output.
 
-No `Math.random` or `Date.now` in behaviour, and no iteration over unordered
-collections where order can reach output. Example-only uses
-(`example/train_base`) are outside the library contract. If a test becomes
-flaky, the contract was broken, not the test.
+If a test becomes flaky, the contract was broken, not the test. Uses inside
+`example/` are outside the library contract.
 
 ## All randomness flows from `seed`
 
-`MindConfig.seed` (`src/config.ts:resolveConfig`, `DEFAULT_CONFIG`) is the sole
-entropy root. Subsystems derive deterministically:
+`MindConfig.seed` (`config.ts`) is the only entropy root:
 
-- **Alphabet** — `Alphabet` (`src/alphabet.ts`) via `rng` (`src/vec.ts:rng`)
-  seeded as `seed ^ seedMask`; builds 16→64→256 vectors.
-- **Keyring / Space** — `Space.seats` (`src/sema.ts:Space`) via `makeKeyring`
-  (`src/vec.ts:makeKeyring`) and `rng` seeded from `seed` in `Mind`
-  (`src/mind/mind.ts`); `fold`/`twoEndedSeat`/`companySignature` are pure over
-  `Space`.
-- **Vector indexes** — `VectorDatabase` (`src/rabitq-ivf/src/database.ts`) and
-  `Prng` (`src/rabitq-ivf/src/rabitq.ts`) seeded from config; insertion order is
-  the stored order, not a random choice.
+- the **alphabet** (`alphabet.ts`) is drawn from `rng(seed ^ seedMask)`;
+- the **keyring of seats** (`makeKeyring`) is drawn from the seed in `Mind`;
+- the **vector indexes** (`rabitq-ivf`) are seeded from config, and insertion
+  order is their stored order;
+- **company signatures** are seeded by node id (`companySignature`), not by the
+  seed or by observation order. That is why halo comparisons survive a change of
+  seed while gist comparisons do not (`halo-sketch.md`).
 
-No other PRNG source may affect grounding. Thresholds in `geometry.ts` are
-derived from `D`/`W`/`N`, not sampled.
+## Ties are broken by the corpus
 
-## Tie-breaks are corpus-determined
+Every choice bottoms out in a fixed order, and the fallback is
+**first-inserted**: the lowest node id, or the `LIMIT 1` insertion order. Never
+last-inserted, because that would make an answer depend on recency instead of
+evidence. The order of teaching is part of what was taught, and a correction
+prevails only by evidence.
 
-Every choice bottoms out in a fixed ordering — insertion order or lowest node id
-— not interchangeable (`test/34`). The fallback is **first-inserted**:
+- **`chooseNext` / `guidedFirst`** (`traverse.ts`) try three things in turn: a
+  continuation the question names (`evidence.md`); then distributional support,
+  `prevCount` and then halo mass; then first-inserted.
+- **`chooseAmong`** takes `argmaxCosine` over `candidateGist`, capped at
+  `hubCap`, and resolves ties by stable scan.
+- **Ties in the junction bridge** go to the shortest interior, then the lowest
+  node id.
 
-- `guidedFirst` (`src/mind/traverse.ts:guidedFirst`) — guided pick via
-  `chooseNext` else first-inserted edge (`nextFirst` LIMIT 1).
-- `chooseNext` (`src/mind/traverse.ts:chooseNext`) — capped `nextFirst` read
-  (`hubBound`), ranked by `prevCount` then `haloMass`; equal ⇒ first-inserted.
-- `chooseAmong` (`src/mind/traverse.ts:chooseAmong`) — `hubCap` + `argmaxCosine`
-  over `candidateGist`; first-inserted on tie via stable scan.
-- `companySignature` (`src/sema.ts:companySignature`) — `rng(id ^ 0x9e3779b9)`,
-  i.e. seeded by node id, not observation order.
+When you add a choice among equals, name its tie-break explicitly and make it
+corpus-determined.
 
-Never use last-inserted.
+## Memoization and tracing must not change the answer
 
-## Memoization and trace must not break identity
-
-Per-response memos (`Precomputed`, `perceiveMemo`, `recogniseMemo`, `climbMemo`,
-`_resolvedSubtrees` via `foldTree`, `_edgeChoice`, `_gistCache` in
-`src/mind/mind.ts` / `src/mind/pipeline-mechanism.ts` /
-`src/mind/primitives.ts`) are sound because asking never writes. Only
-`guidedNext`/`sharedReachMemo` are trace-bypassed;
-`perceiveMemo`/`recogniseMemo`/`climbMemo` are always consulted — `foldTree`'s
-subtree fast path skips `visit` (and site emission) for cached subtrees, so
-bypassing makes `recognise` non-idempotent.
-
-## Follow it
-
-When you add any choice among equals, name the tie-break explicitly and make it
-corpus-determined. Thread new randomness through `seed`-derived `rng`; never
-call `Math.random`/`Date.now` on a behavioural path.
+Memos are sound because asking never writes. Which ones a trace bypasses, and
+why the pick memo is cleared when the climb publishes its points, is
+`memoization.md`'s trace boundary.
 
 ## Pins
 
-- `test/42` pins recognition idempotence under trace — traced and untraced
-  `recognise` must return the same cached object and site count.
-- Determinism suites — `test/03`, `test/04`, `test/08`, `test/20` — assert same
-  seed + same training ⇒ byte-identical answers and stores.
+- `test/20`, `test/03`, `test/04`, `test/08` — the same seed and the same
+  training give byte-identical answers and stores.
+- `test/42` — recognition is idempotent under trace.
+- `test/155.4` — traced and untraced responses agree after the climb publishes.
+- `test/34` — tie-breaks are corpus-determined, not interchangeable.