@hviana/sema 0.7.3 → 0.7.5

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.

package/docs/failures/tempting-but-wrong.md

@@ -0,0 +1,144 @@
+# Tempting but Wrong — 12 Traps
+
+Twelve shortcuts that look plausible and break an invariant. Each states what
+not to do, why it fails, and what to do instead.
+
+### 1. `score >= threshold` decides identity
+
+- **WRONG:** Treat a RaBitQ cosine above a cutoff as proof the bytes are the
+  same node.
+- **WHY:** Scores are estimates that rank and gate; they never decide identity
+  (`AGENTS §2` Invariant 3 — Exact decides / approximate proposes).
+- **CORRECT:** Gate with the score, decide with
+  `resolve`/`findLeaf`/`canonResolve` and re-fold verification. Pinned by
+  `test/51-structural-resonance-ladder.test.mjs` and
+  `test/56-bridge-identity-admission.test.mjs`.
+
+### 2. `Math.random()` / `Date.now()` on a behavioural path
+
+- **WRONG:** Sample randomness or wall-clock time in grounding, indexing, or
+  tie-breaking.
+- **WHY:** Determinism is the product: same seed + deposit order + query ⇒
+  identical bytes (`AGENTS §2` Invariant 1).
+- **CORRECT:** Derive all randomness from `MindConfig.seed` via `rng`/`Prng`;
+  keep `example/train_base` as the only non-library exception. Pinned by
+  `test/20-stability.test.mjs` and
+  `test/42-recognise-trace-idempotence.test.mjs`.
+
+### 3. Last-inserted tie-break
+
+- **WRONG:** Break equal-rank ties by picking the most recently inserted
+  edge/node.
+- **WHY:** Tie-breaks must be corpus-determined and stable; last-inserted is
+  recency-dependent and was fixed as a bug (`AGENTS §2` Invariant 1 —
+  first-inserted fallback).
+- **CORRECT:** `guidedFirst`/`chooseNext`/`chooseAmong`: rank then
+  first-inserted (lowest node id / `LIMIT 1` insertion order). Pinned by
+  `test/03-recall.test.mjs` determinism suites.
+
+### 4. Tunable threshold in `config.ts`
+
+- **WRONG:** Add a new `threshold: number` to `src/config.ts` and tune it.
+- **WHY:** Every cutoff is a formula over `D`, `W`, or `N` in `src/geometry.ts`;
+  config holds only capacities/budgets (`AGENTS §2` Invariant 2 — Derived
+  thresholds).
+- **CORRECT:** Add `mergeThreshold`/`identityBar`/`significanceBar` etc.
+  derivation in `geometry.ts`; `traverse.ts:hubBound` for scale caps. Pinned by
+  `test/64-two-ended-thresholds.test.mjs` and
+  `test/40-choosenext-scale-guard.test.mjs`.
+
+### 5. Tuning `PASS` to encode policy
+
+- **WRONG:** Raise/lower `PASS` (1000/byte) so "computation always wins" or
+  another preference falls out of pricing.
+- **WHY:** The ladder's order `MICRO < STEP < CONCEPT < PASS` is the contract;
+  policy is enforced by masking, not pricing (`AGENTS §2` Invariant 4 — One cost
+  currency; `docs/architecture/cost-model.md` § Policy is not cost).
+- **CORRECT:** Keep `PASS` dominating; enforce precedence in the caller (e.g.
+  `pipeline.ts` masks recognised sites overlapped by `ComputedResult`). Pinned
+  by `test/04-think.test.mjs` and `test/55-cost-meter.test.mjs`.
+
+### 6. Reimplementing `locate`/`align` inside a mechanism
+
+- **WRONG:** Copy-paste matching logic into `mind/mechanisms/*.ts` with a
+  private gate.
+- **WHY:** Match/project/gate is factored once in `mind/match.ts` (`AGENTS §2`
+  Cross-cutting contracts; `AGENTS §3` — Where things live).
+- **CORRECT:** Configure the shared family:
+  `locate`/`alignRuns`/`alignGraded`/`frameSlots` + `follow`/`reverseContext` +
+  `isSpanShaped`/`carriesFillers` with a `geometry.ts` gate. Pinned by
+  `test/50-cast-analog-consensus-floor.test.mjs`.
+
+### 7. Putting voicing gates in `frameSlots`
+
+- **WRONG:** Make `frameSlots` refuse pairings that fail `carriesFillers` or
+  reference's four voicing conditions.
+- **WHY:** `frameSlots` reports (contracted gaps tagged
+  substitution/insertion/deletion); `carriesFillers` judges;
+  `Precomputed.frames` inventories — elects nothing (`AGENTS §2` Cross-cutting
+  contracts — `docs/architecture/factored-machinery.md` § Frame reading).
+- **CORRECT:** Report everything in the shared layer; apply
+  `substituteAll(contA, fillersA→fillersB)==contB` and
+  frame-dominance/`W`-reach/distinctness in the consumer (reference). Pinned by
+  `test/47-cast-comparison-coverage.test.mjs`.
+
+### 8. Swapping corpus-global and weave-local commonality
+
+- **WRONG:** Use `reachOf`/`dominates(reach,N)` to decide CAST's frame, or
+  `depth[i]`/`dominates(depth, aligned)` to decide climb/IDF.
+- **WHY:** They measure different things: global reach (minority discriminates,
+  powers climb/pooling) vs weave-local depth with `MIN_WEAVE=2` (what the local
+  cohort shares, powers CAST) (`AGENTS §2` Cross-cutting contracts — Two
+  measures of commonality).
+- **CORRECT:** Climb/attention uses corpus-global;
+  `frame(i) ⇔ depth[i]>MIN_WEAVE ∧ dominates(depth[i],aligned)` for CAST. Pinned
+  by `test/50-cast-analog-consensus-floor.test.mjs` and
+  `test/67-climb-anchor-breadth.test.mjs`.
+
+### 9. Materialise-then-slice instead of `LIMIT ?`
+
+- **WRONG:** `store.next(id).slice(0, k)` or `parents(id).length` to cap a
+  fan-out.
+- **WHY:** Per-query reads must not grow with `N`; caps are enforced in SQL as
+  `LIMIT ?` / `EXISTS` probes (`AGENTS §2` Invariant 5 — Bounded reads).
+- **CORRECT:** `nextFirst`/`parentsFirst`/`containersSlice` with `hubBound`
+  (`ceil(sqrt(N))`), `hasNext`/`hasParents`/`hasHalo` probes,
+  `bytesPrefix`/`contentLen` caps, `chainRun` CTE. Pinned by
+  `test/14-scaling.test.mjs` and `test/90-connector-read-cap.test.mjs`.
+
+### 10. Bypassing `recogniseMemo` under trace
+
+- **WRONG:** Skip `recogniseMemo`/`perceiveMemo`/`climbMemo` when
+  `ctx.trace !== null` to "emit more steps."
+- **WHY:** Only `guidedNext`/`sharedReachMemo` are trace-bypassed; bypassing
+  recognition re-runs `recogniseImpl` with a warm cache and changes site count —
+  31→5 observed (`AGENTS §2` Cross-cutting — `Precomputed` owns memoization;
+  `docs/architecture/memoization.md`).
+- **CORRECT:** Always consult `recogniseMemo`; `foldTree` already descends fully
+  when `visit` is present. Pinned by
+  `test/42-recognise-trace-idempotence.test.mjs`.
+
+### 11. Stopping junction ascent when one cone is exhausted
+
+- **WRONG:** Terminate the `junction.ts` walk as soon as parents or containers
+  run out.
+- **WHY:** Junction ascent climbs both cones within a bounded `√N·W` walk via
+  `WalkCache`; exhausting one cone does not imply the other is exhausted —
+  stopping early misses the shared ancestor (`AGENTS §2` Cross-cutting contracts
+  — `junction.ts` is the shared ascent; `AGENTS §3` — `WalkCache`).
+- **CORRECT:** Continue the live cone until the walk budget is spent or a
+  meeting point is found; cap reads with `hubBound`. Pinned by
+  `test/34-cross-region.test.mjs` and
+  `test/52-climb-consensus-instrumentation.test.mjs`.
+
+### 12. Imposing turn boundaries on `fold`
+
+- **WRONG:** Cut the byte stream at conversation turn edges before folding, so
+  deposits and queries fold differently.
+- **WHY:** Perception is a pure function of the bytes; deposit and inference
+  must compute the same tree for the same input (`AGENTS §1` Orientation — Hard
+  facts).
+- **CORRECT:** Fold content-defined cuts (`contentLevels` in `geometry.ts` +
+  `twoEndedSeat`); turns are API state in `mind/mind.ts`, not segmentation.
+  Pinned by `test/59-fold-invariance.test.mjs` and
+  `test/63-fold-invariants.test.mjs`.

package/docs/harness/gates.md

@@ -0,0 +1,56 @@
+# Gates
+
+Four executable gates. Each: run the command, check what it guards, follow its
+§.
+
+## 1 — Correctness (all 87 suites)
+
+```bash
+npm test
+```
+
+Guards honest silence, determinism, and every pinned contract. Silence:
+unrelated queries ground to nothing (`test/28`, `50`, `56`, `67`, `76`, `84`).
+Determinism: same seed + deposit order + query gives byte-identical answer
+(`test/20`). Every invariant is pinned — a simplification that fails a test is
+wrong until the test is shown wrong. §14–25 (pipeline), §8 (derived thresholds),
+AGENTS.md §2 invariants 1–5.
+
+## 2 — Work accounting (profiler)
+
+```bash
+node bench/profile-inference.mjs        # add [n] to limit probes
+node bench/profile-inference.mjs --trace # trace is a debugging aid, not product
+```
+
+Guards without trace: counters deterministic and diffable between runs; phases
+nest (not disjoint — `think` contains every mechanism phase); shared analyses
+charged to themselves, not to the first toucher; millisecond fields are
+non-deterministic hints only. With `--trace`, recognition idempotence still
+holds (`test/42`). `src/meter.ts`, `docs/architecture/meter.md`, §26, AGENTS.md
+§2 invariant meter/cost.
+
+## 3 — Dependency footprint
+
+```bash
+node --test test/88-dependency-footprint.test.mjs
+```
+
+Guards `dist/src` imports only `node:` + relative paths, and `package.json`
+declares no `dependencies` (examples use `devDependencies` lazily). The
+near-zero footprint is a product feature. AGENTS.md §6, §3 (store has one
+runtime dep: `node:sqlite`).
+
+## 4 — Fold invariance and sublinear scaling
+
+```bash
+node --test test/59-fold-invariance.test.mjs test/63-fold-invariants.test.mjs
+node --test test/14-scaling.test.mjs
+```
+
+Guards: `59+63` — segmentation is content-defined (`contentBoundaries`), not
+positional; grid regression (14.3% survival) cannot pass. `14` — inference cost
+is sublinear in corpus size (power-law exponent ≪ 1) and constant-rate in input
+length; measured on independent disjoint corpora via log–log slope.
+`src/geometry.ts` (`contentLevels`), `docs/architecture/fold-contract.md` +
+`bounded-reads.md`, §10, §29.

package/docs/mechanisms/alu.md

@@ -0,0 +1,75 @@
+# ALU — Computation as an Extension
+
+The ALU is a self-contained sublibrary (`src/alu/`) that knows nothing about the
+pipeline. `aluToMechanism` (`src/mind/mechanisms/alu.ts`) wraps it as an
+ordinary `PipelineMechanism`; cover owns masking.
+
+## How it joins search
+
+Every mechanism may implement `parse(query) → ComputedSpan[]` (`{i,j,bytes}`).
+`think` (`src/mind/pipeline.ts`) collects all parses before the grounding loop.
+`pre.computed` holds the authoritative spans. Each becomes a candidate at `STEP`
+(1) with `accounted: [[i,j]]`:
+
+```ts
+// src/mind/mechanisms/alu.ts — run()
+{ bytes: u.bytes, accounted: [[u.i, u.j]], moves: STEP }
+```
+
+`floor` returns `0` when `pre.computed` is non-empty, else `null`.
+
+## Masking — computation always wins
+
+`cover` (`src/mind/mechanisms/cover.ts`) masks any recognised site whose bytes
+overlap a computed span. A learned `2+2 → 5` is dropped; the computed `4` is the
+sole cover there. Masking is the only precedence — a computed span and a learned
+edge both cost `STEP`.
+
+A computed span and an unrelated rewrite still compose (`"ice 2+2" → "cold 4"`).
+
+## Registry — `derive` composes ops
+
+`OperationRegistry` (`src/alu/src/operation.ts`) holds every op indexed by
+canonical name and surface form. `prim` registers irreducible roots; `derive`
+registers a rewrite over existing ops via `ctx.apply`:
+
+```ts
+registry.derive(
+  "hypot",
+  2,
+  ["hypot"],
+  (args, ctx) =>
+    ctx.apply("sqrt", [ctx.apply("add", [
+      ctx.apply("multiply", [args[0], args[0]]),
+      ctx.apply("multiply", [args[1], args[1]]),
+    ])]),
+);
+```
+
+`derive(name, arity, surfaceForms, body)` — name it, list forms, write the body
+in terms of existing ops. No kernel or graph-search edit.
+
+## Broadcast — scalar ops over n-d
+
+One place (`OperationRegistry.context`): a non-structural op applied to `nd`
+lists lifts element-wise, recursing into nested `nd`. Structural ops (`nd`,
+`length`, `at`, `reduce`, …) are broadcast-exempt — they consume the list whole.
+So `add([1,2,3], 10) = [11,12,13]` without matrix code.
+
+## Resonance — meaning pre-resolved
+
+Operand meanings are pre-resolved before the synchronous kernel runs
+(`AluResonance` / `prefetchResonance` in `src/alu/src/resonance.ts`):
+`recogniseOp` maps a span to its operation concept, `opposite` finds the
+resonant inverse of a symbol for the polymorphic `inverse`. Literal surface
+forms need no host; meaning-based paths do.
+
+## Provenance
+
+Grounded ALU answers carry `alu`; `computeExtensions`/`evalComputation` trace
+the expression and result.
+
+## Pins
+
+- `test/18-alu.test.mjs` — arithmetic, masking, and resonance-gated ops
+- `test/19-nd.test.mjs` — `nd` lists, broadcast, and higher-order ops

package/docs/mechanisms/cast.md

@@ -0,0 +1,75 @@
+# CAST — Counterfactual Transfer via Weave
+
+Counterfactual transfer over the query's **weave**: when byte-string evidence
+from multiple independently-learnt structures aligns to genuinely different
+query spans, CAST transfers structure between them (substitution, redirection,
+analogical comparison). One `alignGraded` weave, multiple schemas; each firing
+schema yields its own candidate and `think`'s single weight comparison picks.
+
+## Matcher
+
+`alignGraded` over the current query bytes: literal W-gram runs first, then
+halo-matched `pre.rec.sites`. The product is `pre.weave()` — `points[]` (each
+with graded `runs[]`) and a per-query-byte `depth[]` (how many structures cover
+that byte). CAST's single-vs-multi test is measured from those runs: a second
+point must add ≥ one perception quantum of coverage the widest point does not.
+
+## Gate — weave-local discriminative frame
+
+Two derived components, both from the weave itself (no tuned threshold):
+
+1. **MIN_WEAVE = 2** — CAST needs ≥ 2 points to form a weave. Frame requires
+   _more_ than the minimum: `depth[i] > MIN_WEAVE`, i.e. ≥ 3 structures agree on
+   the byte. With only the minimum pair no byte is frame.
+
+2. **Half-dominance** — `dominates(n, total)` (> half scaffolding no longer
+   discriminates). Per byte:
+   `frame(i) ⇔ depth[i] > MIN_WEAVE ∧ dominates(depth[i], aligned)`. Per run:
+   `usable(r) ⇔ ¬dominates(framedCount(qs,qe), runLen)`.
+
+`depth` counts **distinct structures**, not accumulated weight — a byte covered
+by the same structure twice still has depth 1. Counting weight instead lets
+shared frame (" describe it", "the importance of") survive as content and makes
+substitution fire on reordered single-fact queries. The split is 29/42 vs 6/42
+when wrong.
+
+This frame gate is **weave-local** ("what the aligned structures share among
+themselves"), not corpus-local (`reachOf` + `dominates` IDF). A phrase common to
+the aligned exemplars is frame here even when it reaches a corpus minority. Do
+not replace it with the structural IDF — refuted on the `test/17` reorder probe.
+The gate does not use `frameSlots` and therefore **does not consume frame
+slots** — it is not the cohort-local `frameSlots` voice gate.
+
+Other admission gates (query ≥ 2 quanta, ≥ 2 ranked anchors, weave touches a
+committed attention root, genuinely woven — not every run restating a recognised
+site) are structural competence checks; see `cast.ts`.
+
+## Cost
+
+**2·STEP** (`STEP + STEP`): one projection per transfer act that the taken
+branch performs (halo-mediated analogy adds `CONCEPT`). Weight is
+`moves + PASS·unaccountedBytes` as usual; `accounted` is schema-specific — only
+the two points that schema actually transferred between.
+
+## Investment discipline
+
+Floor is `2·STEP`. Before touching the shared expensive analyses
+(`pre.attention()` climb, `pre.weave()`), check `worthRunning(2*STEP)` and
+return the uninvested bound when it already loses. Never compute a shared
+analysis just to discard it.
+
+## Pins
+
+- **test/17 intelligence** — reordered single-fact must not trigger
+  substitution; the weave-local frame (depth as distinct-structure count +
+  half-dominance) is what suppresses it.
+- **test/29 counterfactual** — B/C families pin substitution / redirection /
+  comparison and their seat displacements.
+- **test/43 seat** — `seatOfNode` direction (establishing reverse vs forward vs
+  fallback) that the schemas displace through.
+
+## Source
+
+`src/mind/mechanisms/cast.ts` (`counterfactualTransfer`, `seatOfNode`,
+`MIN_WEAVE`), `src/mind/match.ts` (`alignGraded`, `project`, `depth`),
+`src/geometry.ts` (`dominates`), `src/mind/graph-search.ts` (`STEP`).

package/docs/mechanisms/confluence.md

@@ -0,0 +1,36 @@
+# Confluence — Multi-Condition Meeting Point
+
+Conjunctive queries whose answer lives in no single fact, only where independent
+evidence streams intersect. Each condition reaches its own exemplar set; the
+entity satisfying all lives at their meeting point.
+
+Source: `src/mind/mechanisms/confluence.ts` (`confluenceJoin`,
+`confluenceMechanism`).
+
+## Matcher
+
+`crossRegionVotes` tiers over the consensus climb (`pre.attention()` ranked
+anchors). Streams are anchors bound by identity to disjoint discriminative query
+spans; two streams are independent when their `cover` spans are disjoint. The
+meet is set intersection by content-addressed identity (`windowsOf` /
+`findBranch` window ids): present in both anchors, absent from the query.
+
+## Gate
+
+Corpus-global IDF, not weave-local. A window's `reachOf(ctx, wid, N, memo)`
+(`edgeAncestors` contexts-reached via `sharedReachMemo`) is gated by
+`dominates(reach, N)` (`geometry.ts` half-dominance, `reach*2 > N`). Majority
+reach is scaffolding and never binds a constraint nor survives the meet;
+minority reach is filler/entity. Single-window meets and sub-`2W` spans are
+refused.
+
+## Cost
+
+One currency (`mind/graph-search.ts`): `STEP=1`, `CONCEPT=10`, `PASS=1000`/byte.
+`moves = STEP·slots + CONCEPT` (floor `3·STEP`: two constraints + meet). Weight
+`moves + PASS·unaccounted` compared at `STEP` grade (`pipeline.ts:think`).
+
+## Pins
+
+`test/32-confluence.test.mjs` — two-constraint intersection, order invariance,
+empty-intersection honesty, cross-domain relational joins.