@hviana/sema 0.9.4 → 0.9.5

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.