@hviana/sema 0.7.3 → 0.7.6

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.

package/docs/mechanisms/cover.md

@@ -0,0 +1,54 @@
+# Cover — Lightest Derivation over the Query
+
+Cover is graph search. Its axioms are the query's own decomposition and its goal
+is the cheapest cover of the query's bytes. It runs first so a computed-backed
+cover becomes a near-zero-cost incumbent.
+
+## Matcher — `locate` / recognition sites (`src/mind/recognition.ts`)
+
+Sites are spans of the query that name a node already in the store. Cover
+consumes them directly; any site whose bytes overlap a computed span is masked
+(computation always wins).
+
+## Projection — edges + conceptHop (`src/mind/match.ts`, `src/mind/graph-search.ts`)
+
+- `formRules` follow continuation edges (`GraphSearch.formRules`): each hop
+  costs `STEP` (1). Forks across all continuations up to the hub bound;
+  disambiguation is distributional, not heuristic.
+- Edge-less forms may hop via a halo sibling (`conceptHop` / `resolveConcepts`
+  in `src/mind/mechanisms/cover.ts`) at `CONCEPT` (10), borrowing a synonym's
+  continuation.
+
+## Gate — `leadsSomewhere` (`src/mind/traverse.ts`)
+
+A site participates only if it leads somewhere: it bears an edge (`hasNext`) or
+a halo (`hasHalo`). Forms that lead nowhere contribute nothing to any derivation
+and are filtered during recognition.
+
+## Cost (`src/mind/graph-search.ts`)
+
+| Symbol    | Value       | Rule                                            |
+| --------- | ----------- | ----------------------------------------------- |
+| `STEP`    | 1           | per edge hop                                    |
+| `CONCEPT` | 10          | abandoning a chain / synonym hop                |
+| `PASS`    | 1000 / byte | each unaccounted byte                           |
+| `MICRO`   | 1e-3        | per-byte A* heuristic (`h = (len-right)*MICRO`) |
+
+Mechanism weight is `moves + PASS * unaccounted_bytes`; comparison is at `STEP`
+grade, then by `scaffolding` bytes, then list order.
+
+## Pre-resolution (`src/mind/mechanisms/cover.ts`)
+
+`resolveConcepts` and `resolveConnectors` pre-resolve the async maps the
+synchronous search cannot gather: concept targets and learnt connectors, keyed
+by node pair. Bridges (`bridge`) splice connectors between rewrites.
+
+## Provenance
+
+`cover` for the query's own cover; `join` when fusing fragments into a deeper
+learned form.
+
+## Pins
+
+- `test/09-edges.test.mjs` — edge following and hop semantics
+- `test/19-nd.test.mjs` — form rules and multi-hop chains

package/docs/mechanisms/extraction.md

@@ -0,0 +1,53 @@
+# Extraction — Skill-Framed Span Read-out
+
+Extraction transfers a learnt span-in-context skill to an unseen query. A skill
+exemplar is a stored fact whose answer is a span of its context (or of its
+pieces); extraction locates the exemplar's framing bytes in the query and reads
+what sits between them.
+
+## Matcher — `skillExemplar` / `isSpanShaped` / `containsSpan` (`src/mind/match.ts`)
+
+An exemplar is span-shaped when its answer is an in-order embedding of its
+context. `isSpanShaped` is the open reading (sparse subsequence, any gaps) used
+to accept candidates; `answerRunsInContext` is the strong reading (greedy
+longest contiguous runs) used to decompose the answer for projection. Candidates
+are ranked anchors from `climbAttentionAll` (`Precomputed.spanShapedOf`), tried
+in order up to `pre.k`; sub-quantum (`< W = maxGroup`) or unanchored results are
+skipped.
+
+## Projection — read between located frames (`src/mind/mechanisms/extraction.ts`)
+
+`answerRunsInContext` splits the exemplar answer into pieces within its context.
+For each piece, the `W`-bounded pre-frame (and post-frame or next-piece
+pre-frame) is `locate`d in the query at recognition sites. Located frames define
+`start`/`end`; the bytes `query[start:end]` are read out. Multi-piece skills
+concatenate reads in order.
+
+## Gate — both borders located to account (`src/mind/mechanisms/extraction.ts`)
+
+Frames are evidence only when `locate` succeeds. An unanchored read (no frame
+located, `accounted === []`) is discarded — not an extraction. An open-ended
+read (only one border located) stays unaccounted.
+
+## Cost (`src/mind/graph-search.ts`)
+
+Mechanism weight is `moves + PASS * unaccounted_bytes` with
+`moves = CONCEPT + STEP * accounted.length`. Comparison is at `STEP` grade, then
+scaffolding, then list order.
+
+## Selective accounting
+
+Frames are always accounted when located. The read span between them is
+accounted only when bounded on both sides (`preBounded && postBounded`);
+otherwise it is PASS-priced like uncovered bytes, so a correct bounded
+extraction can outweigh an echoing juxtaposition.
+
+## Provenance
+
+`extract` (single-piece) or synthesised multi-piece read.
+
+## Pins
+
+- `test/00-extract.test.mjs` — skill transfer across values and relations
+- `test/68-extraction-unanchored.test.mjs` — unanchored gate (empty accounted is
+  silence)

package/docs/mechanisms/prefix-completion.md

@@ -0,0 +1,54 @@
+# Prefix Completion — Literal Opening of One Trained Form
+
+The query is a proper prefix of exactly one trained form. That form is voiced
+whole; nothing is invented.
+
+## Gate — exactly one opener
+
+A candidate is a form whose bytes literally open with the query (every query
+byte matched in order from offset zero). Grounding requires **exactly one
+distinct continuation** over the candidate set:
+
+- **Candidates** = `formsOpenedBy` (content-addressed window index) ∪ memoised
+  `resonance` top-k — evaluated as one union so an exact-index ambiguity cannot
+  be hidden by the approximate tier.
+- **Distinctness** is by continuation bytes, not form id.
+- **Zero or ≥2 distinct continuations → refuse** (the prefix trap).
+
+## Cost (`src/mind/graph-search.ts`)
+
+| Symbol | Value | Rule                                              |
+| ------ | ----- | ------------------------------------------------- |
+| `STEP` | 1     | maximal claim: every query byte literally matched |
+
+`floor` returns `STEP`; `run` returns one candidate with `moves = STEP`,
+`accounted = [[0, query.length]]`, `bytes = form`.
+
+## `complete` flag
+
+The result carries `complete` semantics: the grounded bytes are a trained form
+reached by identity. Post-grounding (`reason` → `fuse`) must not extend them.
+
+## Guards (from `src/mind/mechanisms/prefix-completion.ts`)
+
+1. **Unreadable veto** — a saturating `bytesPrefix` read is a standing
+   disagreement; if any candidate saturates, none is licensed.
+2. **One grouping window** — continuation must be ≥ `W` (`maxGroup`);
+   sub-quantum tails are unvoiceable and also count as disagreement.
+3. **Uniqueness** — as above.
+
+Structural pre-check (`floor`): `query.length * W < query.length + W` → `null`
+(no room for a perceivable continuation).
+
+## Where it runs
+
+Last grounding mechanism in `defaultMechanisms` (`mind/pipeline.ts`); registered
+after recall so an exact self-match (`IDENTITY`) wins ties. Shares
+`formsOpenedBy` (`mind/traverse.ts`) and `Precomputed.resonance()`.
+
+## Pins
+
+- `test/70-prefix-completion.test.mjs` — literal prefix, ambiguity, sub-quantum,
+  saturating-read veto, determinism.
+- `test/72-prefix-candidate-supply.test.mjs` — `formsOpenedBy` ∪ `resonance`
+  union supply; resonance alone cannot rank a proper prefix.

package/docs/mechanisms/recall.md

@@ -0,0 +1,69 @@
+# Recall — Nearest Stored Form
+
+Recall resonates the whole query's gist against the content index and grounds
+the nearest learned form. Resonance proposes; bytes decide.
+
+## Gist and budget
+
+Query gist is `pre.guide`; the single top-k read is `pre.resonance()` shared
+across the response. `Precomputed.k = 2·recallQueryK` tiers 0b/1/2/3 through it;
+the last tier re-folds bytes.
+
+## Tiers (degrading)
+
+| Tier | Name                  | Gate                                                                                                                                                       | Action                                                                                                            |
+| ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| 0    | Exact identity        | `pre.queryResolved` exists                                                                                                                                 | Reverse-recall (`reverseContext`) to best-resonating predecessor at `STEP`                                        |
+| 0b   | RC8 argument binding  | One maximal `≥2W` edge-source constituent, no substantial `≥2W` form outside it                                                                            | `follow` its continuation; refuses if result is a subspan of the query                                            |
+| 1    | Clean resonance       | `score ≥ identityBar(D,W,len)` per hit                                                                                                                     | `project` hit; restating hits (bytes or `canon`-equivalent) only via reverse-recall                               |
+| 2    | Scaffolding-dominated | `score ≥ significanceBar(D)` and consensus-climb anchor clears `consensusFloor(N)` or `dominates(breadth,1) && peak>ln2`, and query is not all-scaffolding | `project` anchor at `CONCEPT`; refuses if continuation voices the anchor's displaced filler or is a query subspan |
+| 3    | Last resort + bridge  | Query-relative fraction `max(0,cos−sig)·√(lenG/lenQ) ≥ reachThreshold(W)`                                                                                  | Best grounded `project` hit at `STEP`                                                                             |
+
+W = `maxGroup` (river window); bars from `src/geometry.ts`.
+
+## Echo — the refusing tail
+
+If no tier grounded, the exact cosine of the top hit is re-folded (`gistOf` on
+its bytes). Decision uses that exact value in the same query-relative,
+chance-corrected fraction — never the RaBitQ estimate. Below `reach` → silence;
+restating → silence; otherwise the hit's own bytes are returned as an ungrounded
+echo.
+
+## Provenance
+
+Grounded answers carry `recall`; the echo carries `recall-echo` (`echoed: true`
+on `RecallResult`). Consumers distinguish a continuation through learned edges
+from a near-identity echo.
+
+## Substitution bridge — refusal-path only (`src/mind/bridge.ts`)
+
+Runs only after every gist tier failed, reusing the same top-k proposals (the
+bridge's cap is `2·recallQueryK`; every proposal is byte-verified). A candidate
+context is byte-aligned around the rarest stored W-windows. A mismatch becomes a
+corroborated substitution only when its query span is corpus-attested (every
+W-window stored, one reused ≥2 containers), its geometry clears
+`conceptThreshold(D)` or its halo clears `significanceBar(D)`, its frame is
+unanimous, and the raw gap is length-balanced. Coverage must dominate the query
+and no dismissed gap may hide known content (`dismissedKnownContent` gate). Cost
+is `CONCEPT` per substitution plus `STEP`; accounted spans include matched and
+substituted ranges (so a 28/29-byte paraphrase is not charged `PASS` per
+substituted byte — observed double-charge that let `cast` outbid the bridge).
+Zero-substitution identity bridges carry `complete: true` (the whole read-out);
+substituted bridges do not.
+
+Scaffolding-only queries abstain: when every stored window that could anchor is
+saturated (corpus-global scaffolding, `allWindowsAreScaffolding`), the bridge
+returns nothing — a single substituted word cannot carry the semantic load.
+
+## Cost
+
+Tiers 0/1/3 price `STEP` (one hop); tier 2 and the bridge price `CONCEPT` per
+substitution/scaffold step. Mechanism `floor` is `STEP`; weight is
+`moves + PASS·unaccounted`.
+
+## Pins
+
+- `test/03-recall.test.mjs` — exact identity and reverse-recall
+- `test/16-bridge.test.mjs` — corroborated substitutions
+- `test/73-scaffolding-only-bridge-abstains.test.mjs` — scaffolding-only queries
+  stay silent