@hviana/sema 0.7.3 → 0.7.6

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.

package/docs/architecture/saturation.md

@@ -0,0 +1,92 @@
+# Saturation — Named Stop, Not Cap
+
+> **Law:** every walk names a deciding saturation beside its cap. The cap is a
+> safety net; saturation is the derived stop that decides and terminates.
+
+A walk with only a cap drifts to the cap. A walk with a saturation stops the
+moment the answer (saturated vs. decided) is known — bounded, exact below the
+bound, and named in the trace.
+
+## Cap vs. saturation
+
+| Role       | Value                                                        | Nature                                           |
+| ---------- | ------------------------------------------------------------ | ------------------------------------------------ |
+| Cap        | `hubBound = ceil(sqrt(N))` per read; `hubBound * W` per walk | Safety net — prevents corpus-proportional work   |
+| Saturation | Named derived stop (`SaturationReason`)                      | Decision — proves continuing cannot discriminate |
+
+`N = corpusN = max(2, edgeSourceCount())`, `W = maxGroup`. Defined once in
+`mind/traverse.ts` (`corpusN`, `hubBound`, `boundFor`); never spelled inline.
+
+## edgeAncestors — EXPAND-UNTIL-DECIDED
+
+`mind/traverse.ts:edgeAncestors` is the model: it climbs the structural DAG
+(parents + containment) until one of five saturations decides, and is exact
+below every one of them.
+
+1. **Predecessor fan-in** — `prevCount(node) > bound` via `store.prevCount`. One
+   indexed count; no read. Proves `> bound` distinct contexts on its own.
+2. **Distinct-context limit** — `ctxSeen.size > bound` after
+   `prevFirst(node, bound)`. The accumulated set of distinct contexts reachable
+   from roots visited so far exceeds `sqrt(N)`.
+3. **Parent fan-out** — `parentsFirst(node, bound+1).length > bound`. One
+   `LIMIT bound+1` read distinguishes "exactly bound parents" from "hub". The
+   node itself is not expanded; saturated reaches are never voted.
+4. **Lateral-cone cumulative** — `lateral > bound`, where `lateral` sums
+   `fresh-1` over every expanded node's extra parents beyond its first. The
+   per-node guard catches concentration at one node; this catches the same
+   commonness distributed across the cone. A deep chain in one structure accrues
+   zero laterals and still reaches its root at any depth.
+5. **Byte-atom commonality** — `atomIsHub(N,W)` when
+   `atomReach(N,W) = max(1, ceil(N*W/256)) > bound`. Atoms carry no kid/contain
+   rows, so containment is unmeasurable; the uniform-expectation floor replaces
+   it. Above the scale the atom abstains as voter (edges remain traversable for
+   tier-0 recall).
+
+Below every threshold the walk is exact — `prevFirst(bound)` is the full list,
+`parentsFirst(bound+1)` is the full list, `containersSlice` pages are walked in
+full — identical to the unbounded climb. Work is `O(bound)` contexts times local
+structure, never `O(N)`. Container seeding is streamed in `bound`-sized pages
+for the same reason.
+
+Trace records the first deciding stop as
+`SaturationStop { reason, node, observed, limit }` plus `visited`/`maxDepth`;
+absent when unsaturated or untraced.
+
+## pivotInto — longest-wins
+
+`mind/resonance.ts:pivotInto` ranks candidates by `contentLen(id, answerLen+1)`
+descending (first-inserted tie-break). The byte score is length itself, so the
+scan is decided at the first candidate that passes every filter — a shorter
+candidate can never outscore it. At most one winner's bytes are reconstructed;
+every shorter proposal is skipped without a read. Saturation, not cap.
+
+## Junction — hub guards vs. budget
+
+`mind/junction.ts:junctionContainersFrom` has three disciplines:
+
+- **Phrase-scale reads** — `bytesPrefix(maxContainer+1)` per visit; a node
+  beyond the cap prunes its branch.
+- **Per-node hub guards** (real saturations) — `parentsFirst(bound+1) > bound`
+  not expanded; one `containersSlice(bound+1)` page beyond `bound` not expanded.
+  Each is exact below `bound`.
+- **Expansion budget** — at most `bound * W` pops total (shared across a tier's
+  walks). Budget exhaustion is an abstention (`junctionBudgetExhausted`) that
+  falls through to the resonance tier — a net, not a saturation.
+
+Refuted tightening: applying `edgeAncestors`' cumulative lateral-cone limit here
+would discard half the successful junctions (measured lateral 1425/1426 at
+`bound` ~ 570).
+
+Refuted early-stop: **one-cone-exhausted** — stopping when one side's upward
+cone empties — is wrong in both hub-guarded and hub-flagged forms. A junction
+can be reachable from only one side when that side's seed is a fold sub-node of
+the container (`test/16`: "cold or hot" reached from window "cold" while 3-byte
+"hot" cone is empty; `test/34` n-ary binding fails the same way). Exhausting one
+cone never proves no junction remains; the walk must keep the `bound*W` net
+after per-node saturations.
+
+## Pins
+
+- `test/16` — one-cone-exhausted refutation (bridge junction).
+- `test/34` — one-cone-exhausted refutation (n-ary cross-region binding).
+- `test/27` — saturation-drop gate (leading/trailing saturated intervals).

package/docs/architecture/store.md

@@ -0,0 +1,79 @@
+# Store — AbstractStore Owns the Domain, Adapters Own the Wires
+
+> **Law:** `AbstractStore` (`src/store.ts`) owns every domain decision — dedup,
+> near-dedup, gist/halo indexing, containment, batching, LRU, compaction.
+> `SQliteStore` (`src/store-sqlite.ts`) implements only `_db*`/`_vec*` thin
+> wrappers.
+
+## Template method
+
+```
+AbstractStore          all logic: caches, merge gates, halo schedule,
+                       buffers, chain transparency, length walks
+  └─ SQliteStore       SQL + VectorDatabase glue — one statement per method
+  └─ <NewBackend>      same contract — subclass AbstractStore only
+```
+
+A new backend subclasses `AbstractStore`; never re-implements dedup or batching.
+
+## IDs and leaves
+
+Branch ids are dense non-negative `0,1,2,…` (`_nextId`, never deleted).
+Single-byte leaves are **implicit** negative ids `-256..-1` (`-(byte+1)`), never
+a row. `has(id)` is `id < 0 || id < _nextId`.
+
+## Flat branches and bytes
+
+A branch whose kids are all leaves is **flat** — stored as raw bytes in `leaf`
+with an empty `kids` blob as marker (`flatKidsBytes`/`flatBytesKids`). Dedup
+probes hash then verify: `hashOf`→`h`→`LIMIT 1` fetch→byte compare (bloom
+negative filter first).
+
+`bytes(id)`/`bytesPrefix(id, cap)` are shared with `BoundedMap` caches — callers
+must **never mutate** the returned buffer. `contentLen(id, cap)` walks with
+memo; when `cap` is given it saturates (`>= cap` without finishing) so one huge
+root never costs a full walk.
+
+## Gist, halo, dedup
+
+On `put*`, content dedup (`hashOf`→probe→mint) gates first. `DedupKey` caches
+short keys (`DEDUP_KEY_MAX` bypass). Near-dedup merges by `mergeThreshold(D)` on
+unit gist cosine. Gists sit in `_pendingGist` (byte-budgeted `BoundedMap`);
+`indexSubtree` & `pourHalo` promote via `_vecContentUpsert`/`_vecHaloUpsert` in
+`batchSize` batches. Buffers flush on cadence, `commit()`, and close. Halo mass
+re-indexes geometrically (`mass<=4 || powerOfTwo`) and encodes 2-bit quantized.
+Canon index is optional: `canonAdd`/ `canonFind`/`canonCount` over 32-bit
+canonical hashes, caller verifies bytes.
+
+## Containment, batching, LRU
+
+`addContainer(child,parent)` buffers per child; flush appends via
+`_dbAppendContain` (packed pages, geometric merge) — never rewrite the whole
+list. `containersSlice` pages through it. Edges and kids write through the same
+deferred transaction.
+
+Every in-memory cache is a `BoundedMap` with byte accounting and eviction (`lru`
+vs `smallest` + `clock`/`reorder` recency). ANN reads
+(`resonate`/`resonateHalo`) are content-addressed (`vecKey`) and dropped on any
+index mutation; `RESonate_CACHE_MAX=4096`.
+
+## Maintenance (incremental)
+
+- `compactContentIndex(minParents)` — scans only entries since last watermark
+  (`_vecContentEntriesSince`), removes indexed-but-isolated nodes (`<minParents`
+  parents, no edges/halos), compacts the vector DB.
+- `repairContentIndex(regenerateGist)` — walks `_dbEdgeOrHaloIds()` candidates
+  only, re-inserts missing bridge nodes whose gists were evicted before
+  indexing.
+- `buildCanonIndex` (`_buildCanonIndex`) — iterates `eachContent(fromId)` and
+  `canonAdd`s; `fromId` makes refresh incremental.
+
+Full scans (`parents()`, `next()`, `containers()`) are maintenance-only — hot
+paths use `LIMIT`ed probes (`parentsFirst`/`nextFirst`/`prevFirst`), `has*`,
+`prevCount`.
+
+## Adding a backend
+
+Implement every `protected abstract _db*`/`_vec*` in `src/store.ts` as a thin
+wrapper around your storage. Keep `_dbGet*First`/`Slice` as real `LIMIT` queries
+and `has*`/`COUNT` as point probes — never materialise-then-slice.

package/docs/architecture/thresholds.md

@@ -0,0 +1,79 @@
+# Thresholds — derived, never tuned
+
+Every decision cutoff is a formula over `D` (vector dimension), `W` (`maxGroup`,
+perception window), or `N` (corpus size). No threshold is tuned or added to
+`src/config.ts`.
+
+## Source of truth
+
+- `src/geometry.ts` — all similarity/decision thresholds.
+- `src/mind/traverse.ts` — corpus-scale readings that parameterise bounded
+  walks.
+- `src/sema.ts` — positional coordinate algebra.
+- `src/config.ts` — capacities and budgets only (cache byte budgets, batch
+  sizes, index parameters, query `k`, ALU precision, seed). Never a threshold.
+
+## Geometry thresholds (`src/geometry.ts`)
+
+| Symbol                  | Definition                                                                   | Formula                             |
+| ----------------------- | ---------------------------------------------------------------------------- | ----------------------------------- |
+| `mergeThreshold(D)`     | Store identity bar — cosine at which `intern` treats two gists as same node  | `1 - 1/√D`                          |
+| `identityBar(D,W,len)`  | Scale-aware whole-span identity claim                                        | `max(mergeThreshold(D), 1 - W/len)` |
+| `reachThreshold(W)`     | Recall confidence floor — half a river quantum                               | `1 - 1/(2·W)`                       |
+| `estimatorNoise(D)`     | RaBitQ noise floor — 1σ of random cosine                                     | `1/√D`                              |
+| `significanceBar(D)`    | Whole-query relatedness — 3σ above chance                                    | `3/√D`                              |
+| `conceptThreshold(D)`   | Halo concept sharing — structural midpoint + ½σ                              | `0.5 + 0.5/√D`                      |
+| `dominates(part,whole)` | Half-dominance predicate                                                     | `part*2 > whole`                    |
+| `profileCapacity(D)`    | Superposition capacity — terms before readout collapses                      | `floor(√D)` (min 1)                 |
+| `consensusFloor(N)`     | Pooled-vote significance floor                                               | `ln(N) + ½`                         |
+| `coverageBar(_,D)`      | Reach-index gating (currently unused hot-path; batch compaction replaces it) | `conceptThreshold(D)`               |
+
+`N` in `consensusFloor` is `corpusN` (edge-source count, floored at 2).
+
+## Corpus-scale readings (`src/mind/traverse.ts`)
+
+| Symbol           | Definition                                             | Formula                     |
+| ---------------- | ------------------------------------------------------ | --------------------------- |
+| `corpusN`        | Distinct learnt contexts, floored                      | `max(2, edgeSourceCount())` |
+| `hubBound`       | Hub bound, used for every `LIMIT` read                 | `ceil(√max(2,N))`           |
+| `hubCap(ids)`    | Fan-out cap — list-side reading of `hubBound`          | `ids.slice(0, hubBound)`    |
+| `atomReach(N,W)` | Uniform-expectation floor on a byte atom's commonality | `max(1, ceil(N·W/256))`     |
+| `atomIsHub(N,W)` | Whether atom abstains as consensus voter               | `atomReach > hubBound`      |
+
+`hubBound` is enforced at the store level (`nextFirst`, `parentsFirst`,
+`containersSlice`, `hasNext`/`hasParents`, `bytesPrefix`, `chainRun`).
+`atomReach` is the honest floor for atoms — they carry no kid/contain rows, so
+their reach is unmeasurable and must not default to "maximally rare".
+
+## Seat algebra (`src/sema.ts`)
+
+`twoEndedSeat(seatCount, size, index)` — the one positional-coordinate algebra
+shared by perception, `fold`, and every synthetic/canonical fold. First half
+uses low seats, second half uses high seats:
+`index < (size+1)/2 ? index : seatCount-size+index`.
+
+## Two derivations that bite
+
+**1. `identityBar` is scale-aware.** A fixed cosine `1-1/√D` over a `4·√D`-byte
+span tolerates four whole windows of foreign bytes while still claiming
+"near-identical". An identity claim may tolerate at most one window `W` (the
+perception quantum, same budget as `differsByOneWindow` in near-dedup), so the
+bar must be `1-W/len` floored at `mergeThreshold`. Reusing `mergeThreshold` for
+a whole-span claim silently widens the byte budget with span length.
+
+**2. `consensusFloor` is priced for pooled climb votes, not for support
+counts.** Each region contributes at most `ln(N/c) ≤ ln(N)`; `ln(N)+½` demands
+corroboration beyond one maximally-specific region. `chooseNext`'s `bestSupport`
+(`prevCount` of one destination) is N-invariant — bounded by retellings of that
+fact, not by `N`. Gating it against `consensusFloor` guarantees failure once `N`
+is large enough (observed: 2-vs-1-1-1 corroboration refused at N≈325K, falling
+back to a noisy concept-hop).
+
+## Pins
+
+- `test/40-choosenext-scale-guard` — `consensusFloor` must not gate `chooseNext`
+  support counts.
+- `test/64-two-ended-thresholds` — `mergeThreshold` / `identityBar` /
+  `reachThreshold` derivations and the scale-aware floor.
+- `test/78-atom-hub-recognition-cliff` — `atomReach` / `atomIsHub` hub
+  abstention at scale.