@hviana/sema 0.9.3 → 0.9.5

package/AGENTS.md

@@ -1,9 +1,10 @@
 # AGENTS.md — the Sema development manual
 
-The working manual for anyone (human or AI agent) changing Sema. For pattern
-detail, see `docs/INDEX.md` → `docs/architecture/*.md`. You should be able to
-develop against this document and docs/ alone; read `docs/architecture/` for why
-a pattern holds.
+The working manual for anyone (human or AI agent) changing Sema. Read
+`docs/PHILOSOPHY.md` first: it follows information from deposit to answer and
+says why the parts fit. Then `docs/INDEX.md` routes each task to the law it
+touches in `docs/architecture/`. You should be able to develop against this
+document and `docs/` alone.
 
 ## 1. Orientation
 
@@ -32,7 +33,7 @@ Mental model, top to bottom:
 ```
 mind/pipeline.ts     grounding decider: mechanisms compete on one cost scale
 mind/mechanisms/*    cover · cast · confluence · extraction · reference · recall · prefix-completion · alu
-mind/*               match/project, attention, recognition, junction ascent, graph search, learning, rationale
+mind/*               recognition, attention, match/project, evidence, closure, graph search, learning, rationale
 store.ts             AbstractStore: ALL DAG store domain logic
 store-sqlite.ts      the one concrete backend (thin SQL wrappers)
 geometry.ts + vec/alphabet/sema/canon  vectors, fold, every derived threshold, canonicalizer
@@ -82,6 +83,10 @@ corpus-determined, not interchangeable (`determinism.md`).
 | Weighted deduction + cost ladder     | `src/mind/graph-search.ts` (engine in `src/derive/`)                                               |
 | Match/project family                 | `src/mind/match.ts`                                                                                |
 | Graph traversal, corpus scale        | `src/mind/traverse.ts`                                                                             |
+| Witnessed evidence (`witness`)       | `src/mind/evidence.ts`                                                                             |
+| Closure law and engine (`closeOver`) | `src/mind/derivation.ts`                                                                           |
+| Post-grounding walk and fusion       | `src/mind/reasoning.ts`                                                                            |
+| Canonical windows                    | `src/mind/canonical.ts`                                                                            |
 | Consensus climb + attention          | `src/mind/attention.ts`                                                                            |
 | Substitution bridge (recall tier)    | `src/mind/bridge.ts`                                                                               |
 | Recognition / junction / resonance   | `src/mind/recognition.ts`, `src/mind/junction.ts`, `src/mind/resonance.ts`                         |
@@ -132,8 +137,12 @@ against built `dist/` (`npm test`; one suite:
 numbered suite. Many tests pin contracts that look like implementation details
 (ladder order, span-shape readings, `MechanismResult.complete`, fold invariance,
 recognition idempotence, honest silence). A simplification that fails an
-existing test is wrong until the test is proven wrong. Sublibraries test
-themselves in `src/{alu,derive,rabitq-ivf}/test/` with zero Sema dependency.
+existing test is wrong until the test is proven wrong; read
+`docs/failures/tempting-but-wrong.md` before trying one. `src/alu/` and
+`src/derive/` test themselves in their own `test/` with zero Sema dependency;
+`rabitq-ivf` is pinned by `test/35-ivf`. `test/137` also reads `docs/`: an
+export only the docs describe counts as documented, so deleting its mention can
+fail the dead-export guard.
 
 ## 6. Instrumentation — the meter and the rationale ARE the dev surface
 

package/dist/src/mind/learning.js

@@ -109,18 +109,17 @@ export async function indexSubSpans(ctx, tree, ids) {
  *  root id, id map, and the changed (new) subtrees for halo reinforcement. */
 export async function deposit(ctx, input, track, conversational = false) {
     const bytes = inputBytes(ctx, input);
-    // Deposit-shaped perception: stable-prefix tree SEEDING (see
-    // perceiveDeposit) — an accumulated context re-folds only its new suffix,
-    // O(turn) instead of O(context) per conversation turn.  Cache-only here
-    // (no store-probe fallback): a knownPrefixLength scan on every novel fact
-    // would cost O(n²) hashing, while conversation replays are always warm —
-    // re-deposition replays from the first turn, rebuilding the cache as it
-    // goes.  `conversational` scopes the STABLE-PREFIX variant (turn-boundary
-    // folding, matching query-time perception) to ingestPair's own growing
-    // context argument — a bare ingestOne deposit whose bytes merely happen
-    // to extend an earlier UNRELATED deposit (no conversational relationship)
-    // must keep the plain fold, or two coincidentally-prefix-sharing facts
-    // would stop sharing structure with each other.
+    // Deposit-shaped perception (perceiveDeposit): the plain content fold, the
+    // same tree inference computes for these bytes.  An accumulated context
+    // reuses the already-folded segments of its cached prefix
+    // (contentFoldIncremental), so it re-folds only its new suffix — O(turn)
+    // instead of O(context) per conversation turn.  The reuse is transparent:
+    // a hit saves time and never changes the tree.  Cache-only here (no
+    // store-probe fallback): conversation replays are always warm, because
+    // re-deposition replays from the first turn and rebuilds the cache as it
+    // goes.  `conversational` only decides which deposits WRITE the cache —
+    // ingestPair's growing context, not every unrelated fact — a budget
+    // choice, not a correctness one (fold-contract.md).
     const tree = perceiveDeposit(ctx, bytes, conversational);
     const ids = new Map();
     const rootId = await internTreeIds(ctx, tree, ids);

package/dist/src/mind/mind.js

@@ -685,10 +685,10 @@ export class Mind {
         // No recognise-memo pre-seeding here: that used to be necessary because
         // the flat/positional fold lost visibility into an earlier turn's own
         // structure once later bytes shifted its position (foldTree no longer
-        // visited the turn's root node).  The STABLE-PREFIX fold (see {@link
-        // ConversationData}) makes every turn's subtree independent of what
-        // follows it by construction, so recognise() finds it correctly on its
-        // own, first-touch, exactly once per turn.
+        // visited the turn's root node).  The content-defined fold (see {@link
+        // ConversationData}) cuts by the bytes, never by position, so an earlier
+        // turn's structure is the same whatever follows it, and recognise() finds
+        // it on its own, first-touch, exactly once per turn.
         this.beginResponse(inspectRationale, this._canonFor(typeof turn === "string" ? textCanon : null), data);
         try {
             const response = await this._groundAndVoice(newContext, "respondTurn");

package/dist/src/mind/types.d.ts

@@ -356,9 +356,8 @@ export interface MindContext extends GraphSearchHost {
      *  with `bytesToTree` on every turn, so every key was fresh and this cache
      *  could not hit even once — the O(suffix) claim above described an
      *  intention rather than the code.  It now grows the context through
-     *  {@link stablePrefixFoldIncremental}, which reuses each already-folded
-     *  segment: measured over four turns, turn 4 shared 69 of its 95 nodes with
-     *  turn 3 (26 new ≈ the new turn's own size). */
+     *  contentFoldIncremental, which reuses each already-folded segment as the
+     *  same object (~92% of nodes reused by identity across turns). */
     _resolvedSubtrees: WeakMap<Sema, {
         id: number;
         len: number;
@@ -396,18 +395,14 @@ export interface MindContext extends GraphSearchHost {
      *  never a correctness risk. */
     _gistCache: BoundedMap<number, Vec>;
     /** DEPOSIT-path perception cache: content key (latin1) of a deposited
-     *  input → its accumulated turn BOUNDARIES plus reusable fold state.  A
-     *  deposit whose content extends a cached entry IS a conversation context
-     *  grown by one turn — the cached length is the new boundary — so it
-     *  folds with the SAME stable-prefix fold query-time perception uses
-     *  (structural train/inference agreement, load-bearing for recall),
-     *  reusing every already-folded segment via `stable` (see StableFold) —
-     *  O(turn) per deposit instead of O(context).  A first-seen input takes the
-     *  same fold with no boundaries at all, and caches the segments it produced
-     *  so a later turn of the same conversation reuses them.  Purely a
-     *  performance cache for the FOLD STATE; the boundaries are semantic but
-     *  derived only from the deposit sequence itself (an evicted chain falls
-     *  back to plain-fold behavior, exactly the pre-boundary shape). */
+     *  input → its reusable content-fold state ({@link DepositCacheEntry}).  A
+     *  deposit whose bytes extend a cached entry reuses that entry's
+     *  already-folded segments (contentFoldIncremental) — O(turn) per deposit
+     *  instead of O(context) — and gets exactly the tree a cold fold would
+     *  give, the same one query-time perception computes.  It holds no turn
+     *  boundaries: the fold imposes none (fold-contract.md).  Written only by
+     *  conversational deposits, so the 8-entry budget keeps the live chains;
+     *  an evicted chain costs a re-fold, never a different tree. */
     _depositTrees: BoundedMap<string, DepositCacheEntry>;
     /** The byte lengths present in {@link _depositTrees} — the candidate
      *  prefix lengths probed (longest first).  Drifts on eviction (a stale

package/dist/src/store.d.ts

@@ -44,11 +44,11 @@ export declare class BoundedMap<K, V> {
     /** How a HIT records recency.
      *
      *  `"reorder"` (default) promotes the entry to most-recent by
-     *  `m.delete(k); m.set(k, v)` — exact LRU, and the only policy that is
-     *  safe for a cache whose CONTENTS are load-bearing rather than merely
-     *  warm.  `_depositTrees` (8 entries, feeds stablePrefixFoldIncremental)
-     *  is exactly that: which of its entries survives changes how the next
-     *  turn FOLDS, so test/13 D1 flips answer when the victim changes.
+     *  `m.delete(k); m.set(k, v)` — exact LRU, the policy for any cache whose
+     *  choice of victim must follow use exactly.  `_depositTrees` (8 entries,
+     *  feeds contentFoldIncremental) keeps it so the live conversation chains
+     *  stay warm; its reuse is transparent, so a wrong victim costs a re-fold,
+     *  never a different tree (fold-contract.md).
      *
      *  `"clock"` records recency as a BIT instead of as position, spent by
      *  the eviction sweep (see `nextOldest`).  Correct only for a TRANSPARENT
@@ -64,11 +64,11 @@ export declare class BoundedMap<K, V> {
     /** How a HIT records recency.
      *
      *  `"reorder"` (default) promotes the entry to most-recent by
-     *  `m.delete(k); m.set(k, v)` — exact LRU, and the only policy that is
-     *  safe for a cache whose CONTENTS are load-bearing rather than merely
-     *  warm.  `_depositTrees` (8 entries, feeds stablePrefixFoldIncremental)
-     *  is exactly that: which of its entries survives changes how the next
-     *  turn FOLDS, so test/13 D1 flips answer when the victim changes.
+     *  `m.delete(k); m.set(k, v)` — exact LRU, the policy for any cache whose
+     *  choice of victim must follow use exactly.  `_depositTrees` (8 entries,
+     *  feeds contentFoldIncremental) keeps it so the live conversation chains
+     *  stay warm; its reuse is transparent, so a wrong victim costs a re-fold,
+     *  never a different tree (fold-contract.md).
      *
      *  `"clock"` records recency as a BIT instead of as position, spent by
      *  the eviction sweep (see `nextOldest`).  Correct only for a TRANSPARENT

package/dist/src/store.js

@@ -95,11 +95,11 @@ export class BoundedMap {
     /** How a HIT records recency.
      *
      *  `"reorder"` (default) promotes the entry to most-recent by
-     *  `m.delete(k); m.set(k, v)` — exact LRU, and the only policy that is
-     *  safe for a cache whose CONTENTS are load-bearing rather than merely
-     *  warm.  `_depositTrees` (8 entries, feeds stablePrefixFoldIncremental)
-     *  is exactly that: which of its entries survives changes how the next
-     *  turn FOLDS, so test/13 D1 flips answer when the victim changes.
+     *  `m.delete(k); m.set(k, v)` — exact LRU, the policy for any cache whose
+     *  choice of victim must follow use exactly.  `_depositTrees` (8 entries,
+     *  feeds contentFoldIncremental) keeps it so the live conversation chains
+     *  stay warm; its reuse is transparent, so a wrong victim costs a re-fold,
+     *  never a different tree (fold-contract.md).
      *
      *  `"clock"` records recency as a BIT instead of as position, spent by
      *  the eviction sweep (see `nextOldest`).  Correct only for a TRANSPARENT

package/docs/INDEX.md

@@ -1,71 +1,74 @@
 # Sema Documentation Index
 
-Sema is a single system stated three ways: the law lives in `docs/architecture/`
-(what holds), the prescription in `AGENTS.md` (what to do and where), and the
-proof in `test/` (pins that fail when the law is broken).
+Sema is one system, stated four ways:
 
-## Routing — what to read for each task
+| Where                | It says                                                                                   |
+| -------------------- | ----------------------------------------------------------------------------------------- |
+| `docs/PHILOSOPHY.md` | the path of information from deposit to answer, and why it holds together. Read it first. |
+| `docs/architecture/` | the laws: what holds and why, measured                                                    |
+| `AGENTS.md`          | the prescription: what to do, and where                                                   |
+| `test/`              | the proof: pins that fail when a law is broken                                            |
 
-| Task                        | Read                                                                               | Why                                                                                   |
-| --------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| Add a mechanism             | `docs/architecture/mechanism-market.md` + `docs/mechanisms/*.md`                   | Market contract: the four constraints                                                 |
-| Add a threshold             | `docs/architecture/thresholds.md`                                                  | All cutoffs are formulas over D/W/N; `config.ts` holds budgets only                   |
-| Debug an answer             | `docs/architecture/cost-model.md` + `src/meter.ts`                                 | One ladder decides every grounding choice                                             |
-| Understand the fold         | `docs/architecture/fold-contract.md`                                               | Deposit and inference compute the same tree                                           |
-| Add a store backend         | `docs/architecture/store.md` + `docs/architecture/bounded-reads.md`                | `AbstractStore` owns domain logic; backends are thin wrappers with capped reads       |
-| Add an ALU operation        | `src/alu/README.md`                                                                | One `registry.derive` per op composing existing ops; no new `derive` needed           |
-| Add a matcher or projection | `docs/architecture/match-project.md`                                               | Mechanisms are `(matcher, direction, gate)` configs over the shared `match.ts` family |
-| Add a deduction rule        | `docs/architecture/cost-model.md` + `docs/architecture/determinism.md`             | Place cost on the ladder, keep heuristic admissible, extend `classifyMove`            |
-| Change vector search        | `docs/architecture/exact-vs-approximate.md` + `docs/architecture/bounded-reads.md` | Scores propose, bytes dispose; ANN is bounded by `hubBound`                           |
-| Profile or bound work       | `docs/architecture/meter.md` + `docs/architecture/bounded-reads.md`                | `meter.ts` is write-only; counters are product, phases are hints                      |
+`docs/INVARIANTS.md` routes every law to its code and its pins.
 
-## Architecture laws (15)
+## What to read for each task
 
-| Law | File                                        | Summary                                                                                                                                                                                                                                                                                                                                                  | Pins                                         |
-| --- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| 1   | `docs/architecture/determinism.md`          | No `Math.random`/`Date.now` in behaviour; seed-derived randomness; corpus-determined tie-breaks                                                                                                                                                                                                                                                          | `test/20`                                    |
-| 2   | `docs/architecture/thresholds.md`           | Every decision cutoff derived in `geometry.ts` over D/W/N; no tunable knobs                                                                                                                                                                                                                                                                              | `test/40`, `test/64`                         |
-| 3   | `docs/architecture/exact-vs-approximate.md` | Vector scores rank only; identity via content-addressed lookup; six graded ladders                                                                                                                                                                                                                                                                       | `test/51`                                    |
-| 4   | `docs/architecture/cost-model.md`           | Single ladder `MICRO`/`STEP`/`CONCEPT`/`PASS`; weight `moves + PASS·unaccounted`; `STEP`-grade compare                                                                                                                                                                                                                                                   | `test/04`, `test/55`                         |
-| 5   | `docs/architecture/match-project.md`        | Shared `match.ts` family (`locate`/`alignGraded`/`frameSlots`/`project`); voicing gates belong to consumers                                                                                                                                                                                                                                              | `test/24`, `test/76`                         |
-| 6   | `docs/architecture/mechanism-market.md`     | `PipelineMechanism` (`floor`/`run`/`parse`); admissible-floor pruning, investment discipline, run-ahead bounds                                                                                                                                                                                                                                           | `test/01`, `test/04`, `test/153`             |
-| 7   | `docs/architecture/commonality.md`          | Three: global (`reachOf`+`dominates`), weave-local (`depth[]`), window rarity                                                                                                                                                                                                                                                                            | `test/17`, `test/34`                         |
-| 8   | `docs/architecture/bounded-reads.md`        | No per-query read grows with N; `hubBound=√N` enforced at store via LIMIT/probe/prefix caps                                                                                                                                                                                                                                                              | `test/77`, `test/90`                         |
-| 9   | `docs/architecture/store.md`                | `AbstractStore` owns dedup/indexing/batch; `store-sqlite.ts` is thin wrappers; canon index optional                                                                                                                                                                                                                                                      | `test/08`                                    |
-| 10  | `docs/architecture/fold-contract.md`        | `perceiveDeposit` and `perceive` agree; the read side names a branch as `intern` does; `contentLevels` is single boundary rule; no W/offset dependence                                                                                                                                                                                                   | `test/59`, `test/63`, `test/148`, `test/152` |
-| 11  | `docs/architecture/memoization.md`          | `Precomputed` is per-response lazy cache (promise-cached async); `beginResponse`/`endResponse` lifecycle                                                                                                                                                                                                                                                 | `test/42`                                    |
-| 12  | `docs/architecture/saturation.md`           | Every walk names a deciding saturation beside its cap; cap is safety net, not decision                                                                                                                                                                                                                                                                   | `test/27`, `test/16`                         |
-| 13  | `docs/architecture/meter.md`                | `meter.ts` is write-only work accounting; counts are exact, phases nest                                                                                                                                                                                                                                                                                  | `test/55`                                    |
-| 14  | `docs/architecture/closure.md`              | A derivation is closed when its structure accounts for the question's remainder; every transition asks that law, one engine walks the layers                                                                                                                                                                                                             | `test/133`–`151`                             |
-| 15  | `docs/architecture/evidence.md`             | A stored form is identified when the material at hand (question ∪ the node a derivation stands on) witnesses every byte of it, order-free; the question NAMES a continuation through its establishing context, or through another instance of its frame (a co-instance, never voiced as the answer); a step it did not name pays from what is still owed | `test/154`, `test/155`                       |
+| Task                           | Read                                                            |
+| ------------------------------ | --------------------------------------------------------------- |
+| Understand the whole           | `PHILOSOPHY.md`                                                 |
+| Change perception or identity  | `fold-contract.md`, `store.md`, `exact-vs-approximate.md`       |
+| Add a store backend            | `store.md`, `bounded-reads.md`                                  |
+| Add or change a threshold      | `thresholds.md`                                                 |
+| Add a mechanism                | `mechanism-market.md`, `match-project.md`, `docs/mechanisms/`   |
+| Add a deduction rule           | `cost-model.md`, `closure.md`, `determinism.md`                 |
+| Change what counts as evidence | `evidence.md`, `commonality.md`                                 |
+| Change vector search           | `exact-vs-approximate.md`, `halo-sketch.md`, `bounded-reads.md` |
+| Add a walk or a fan-out        | `bounded-reads.md`, `saturation.md`                             |
+| Profile or bound work          | `meter.md`, `memoization.md`, `caches.md`                       |
+| Add an ALU operation           | `src/alu/README.md`                                             |
+| Simplify something             | `docs/failures/tempting-but-wrong.md` first                     |
 
-## Mechanisms (8)
+## The laws (`docs/architecture/`)
 
-| Mechanism         | File                                   | Role                                                      |
-| ----------------- | -------------------------------------- | --------------------------------------------------------- |
-| cover             | `docs/mechanisms/cover.md`             | Exact/computed-span covering via `GraphSearch`            |
-| cast              | `docs/mechanisms/cast.md`              | Weave-local analogy via `depth[]` frame gate              |
-| confluence        | `docs/mechanisms/confluence.md`        | Corpus-global filler/scaffolding gate over climb          |
-| extraction        | `docs/mechanisms/extraction.md`        | Located-frame read-out with anchored span accounting      |
-| reference         | `docs/mechanisms/reference.md`         | Slot-bound voicing of asker-supplied referents            |
-| recall            | `docs/mechanisms/recall.md`            | Nearest stored form; echo tier via substitution bridge    |
-| prefix-completion | `docs/mechanisms/prefix-completion.md` | Literal prefix of exactly one trained form                |
-| alu               | `docs/mechanisms/alu.md`               | Authoritative computed spans (`parse` → `aluToMechanism`) |
+| #  | Doc                       | Law                                                                                                                |
+| -- | ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| 1  | `determinism.md`          | the same seed, deposits and question give the same bytes; ties are broken by the corpus, never by chance           |
+| 2  | `thresholds.md`           | every cutoff is a formula over `D`, `W`, `N`; `config.ts` holds budgets only                                       |
+| 3  | `exact-vs-approximate.md` | scores propose, bytes dispose; every graded ladder is exact first                                                  |
+| 4  | `cost-model.md`           | one currency: `MICRO < STEP < CONCEPT < PASS`, and the price is the unexplained question                           |
+| 5  | `match-project.md`        | a mechanism is `(matcher, direction, gate)` over one family; the gate belongs to the consumer                      |
+| 6  | `mechanism-market.md`     | one interface, one price; never compute what cannot change the decision                                            |
+| 7  | `commonality.md`          | frame against filler is read over a named population: corpus, cohort or places, never substituted                  |
+| 8  | `bounded-reads.md`        | no per-query read grows with `N`; the store enforces `hubBound = ⌈√N⌉`                                             |
+| 9  | `store.md`                | a node is named by its content; `AbstractStore` owns every domain decision                                         |
+| 10 | `fold-contract.md`        | deposit and question fold the same bytes into the same tree and the same node; nothing outside the bytes shapes it |
+| 11 | `memoization.md`          | asking never writes; shared analyses are computed once per response, and tracing changes no answer                 |
+| 12 | `saturation.md`           | every walk names the stop that decides it; the cap is only a net                                                   |
+| 13 | `meter.md`                | the meter is write-only; counters are exact, milliseconds are hints                                                |
+| 14 | `closure.md`              | a step is admitted only when it closes, moves to unconsumed structure, or carries what is owed                     |
+| 15 | `evidence.md`             | the question names the step; another instance of its frame says what the relation is, never what it asks about     |
 
-## Supporting docs
+Supporting docs: `halo-sketch.md` (distributional memory), `caches.md` (every
+acceleration is a budget), `factored-machinery.md` (one definition, many
+consumers).
 
-| Doc                                       | Role                                                                            |
-| ----------------------------------------- | ------------------------------------------------------------------------------- |
-| `docs/architecture/caches.md`             | Every acceleration is a `BoundedMap`; miss re-derives; budgets in `StoreConfig` |
-| `docs/architecture/halo-sketch.md`        | Halo & sketch — distributional memory, quantization, bottom-k profiles          |
-| `docs/architecture/factored-machinery.md` | Single-definition contracts table — one owner per shared symbol                 |
+## Mechanisms (`docs/mechanisms/`)
 
-## Cross-cutting
+| Mechanism           | Answers by                                                                    |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `cover`             | composing the question from its recognised sites, by graph search             |
+| `cast`              | carrying structure between woven forms: substitution, redirection, comparison |
+| `confluence`        | intersecting what independent conditions reach                                |
+| `extraction`        | reading a span between frames located in the question                         |
+| `reference`         | voicing a learnt frame's slot with the asker's own bytes                      |
+| `recall`            | the nearest stored form, or honest silence                                    |
+| `prefix-completion` | completing a known beginning of exactly one form                              |
+| `alu`               | computation, which is authoritative                                           |
 
-- `docs/INVARIANTS.md` — the five invariants (determinism, derived thresholds,
-  exact-decides, one cost currency, bounded reads) with file-level routing.
-- `docs/failures/tempting-but-wrong.md` — refuted simplifications that passed
-  review but failed pins.
-- `docs/harness/gates.md` — how `AGENTS.md` recipes, the meter's public path
-  (`profile: true` → `mind.lastCost`), and `test/*.test.mjs` enforce the laws.
-- `docs/architecture/` — per-law derivation: each file says why, not how.
+## Elsewhere
+
+- `docs/failures/tempting-but-wrong.md` — shortcuts that passed review and
+  failed the evidence.
+- `docs/harness/gates.md` — the four executable gates.
+- `src/derive/`, `src/alu/`, `src/rabitq-ivf/` — firewalled sublibraries, each
+  with its own README and tests.

package/docs/INVARIANTS.md

@@ -1,19 +1,37 @@
-# INVARIANTS — Laws, Proofs, Derivations
+# INVARIANTS — Where Each Law Lives and What Pins It
 
-| #  | Law                                  | Defined in                                                                                                                                                             | Pins                           | Doc                       |
-| -- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------- |
-| 1  | Determinism                          | `src/config.ts:seed` `src/alphabet.ts:Alphabet` `src/mind/traverse.ts:guidedFirst`                                                                                     | `test/20` `test/42`            | `determinism.md`          |
-| 2  | Derived thresholds                   | `src/geometry.ts:mergeThreshold,identityBar,reachThreshold,significanceBar,consensusFloor,dominates`                                                                   | `test/64` `test/40`            | `thresholds.md`           |
-| 3  | Exact decides / approximate proposes | `src/mind/primitives.ts:resolve` `src/mind/match.ts:locate,alignGraded` `src/mind/resonance.ts:bridge`                                                                 | `test/51`                      | `exact-vs-approximate.md` |
-| 4  | One cost currency                    | `src/mind/graph-search.ts:MICRO,STEP,CONCEPT,PASS` `src/derive:lightestDerivation` (min,+) `src/mind/attention.ts:poolVotes` (+,+)                                     | `test/55` `test/04`            | `cost-model.md`           |
-| 5  | Bounded reads                        | `src/store.ts:AbstractStore:nextFirst,parentsFirst,containersSlice,hasNext,bytesPrefix` `src/mind/traverse.ts:hubBound,hubCap`                                         | `test/90` `test/14`            | `bounded-reads.md`        |
-| 6  | Fold contract                        | `src/geometry.ts:contentLevels,contentIdentity` `src/mind/primitives.ts:branchNaming` `src/mind/canonical.ts:canonicalWindows,chainReach` `src/canon.ts:canonicalizer` | `test/59` `test/63` `test/152` | `fold-contract.md`        |
-| 7  | Mechanism market                     | `src/mind/pipeline-mechanism.ts:PipelineMechanism,Precomputed` `src/mind/pipeline.ts:think,worthRunning`                                                               | `test/01` `test/04` `test/153` | `mechanism-market.md`     |
-| 8  | Two commonality measures             | `src/mind/traverse.ts:reachOf,dominates,corpusN` (global) `cast.ts:depth[],MIN_WEAVE` (weave-local)                                                                    | `test/17` `test/34`            | `commonality.md`          |
-| 9  | Memoization idempotence              | `src/mind/pipeline-mechanism.ts:Precomputed` `src/mind/mind.ts:beginResponse,endResponse,_resolvedSubtrees`                                                            | `test/42`                      | `memoization.md`          |
-| 10 | Caches as budgets                    | `src/store.ts:BoundedMap` `src/config.ts:StoreConfig:bytesCacheMax,recCacheBytes,haloCacheBytes`                                                                       | `test/96` `test/91`            | `caches.md`               |
-| 11 | Honest degradation                   | `src/mind/pipeline.ts:weight=moves+PASS*unaccounted` `src/store.ts:BoundedMap:miss→re-derive`                                                                          | `test/28` `test/84`            | `store.md`+`caches.md`    |
-| 12 | Meter contracts                      | `src/meter.ts:Meter,PhaseCost,time` `src/mind/pipeline-mechanism.ts:Precomputed.shared`                                                                                | `test/55`                      | `meter.md`                |
-| 13 | Saturation                           | `traverse.ts:edgeAncestors,types.ts:SaturationReason` `src/mind/junction.ts:junctionContainersFrom` `src/mind/resonance.ts:pivotInto`                                  | `test/27` `test/16`            | `saturation.md`           |
-| 14 | Closure                              | `src/mind/derivation.ts:admissible,advance,closeOver`                                                                                                                  | `test/133`–`151`               | `closure.md`              |
-| 15 | Witnessed evidence                   | `src/mind/evidence.ts:witness,windowIndex` `src/mind/traverse.ts:chooseNext,askedEvidence,namedContinuations,answersOtherQuestions,coInstanceFiller,scaffoldExtents`   | `test/154`, `test/155`         | `evidence.md`             |
+`AGENTS.md` §2 names the five invariants that every change must keep. This table
+routes all fifteen laws (numbered as in `INDEX.md`) to the code that defines
+them and the tests that fail when they break.
+
+| #  | Law                    | Defined in                                                                                                                                 | Pins                                         |
+| -- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
+| 1  | Determinism            | `config.ts` (`seed`), `alphabet.ts`, `traverse.ts` (`guidedFirst`, `chooseNext`)                                                           | `test/20`, `test/42`                         |
+| 2  | Derived thresholds     | `geometry.ts`, `traverse.ts` (`corpusN`, `hubBound`, `atomReach`), `canonical.ts` (`chainReach`)                                           | `test/40`, `test/64`, `test/78`              |
+| 3  | Exact decides          | `mind/primitives.ts` (`resolve`, `exactNode`), `match.ts` (`locate`, `alignGraded`), `resonance.ts` (`bridge`), `attention.ts`             | `test/51`, `test/56`                         |
+| 4  | One cost currency      | `graph-search.ts` (`MICRO`, `STEP`, `CONCEPT`, `PASS`), `src/derive` (min, +), `attention.ts` (`poolVotes`, +, +), `pipeline.ts` (`weigh`) | `test/04`, `test/55`, `test/151`             |
+| 5  | Match → project → gate | `match.ts`                                                                                                                                 | `test/24`, `test/47`, `test/76`              |
+| 6  | Mechanism market       | `pipeline-mechanism.ts` (`PipelineMechanism`, `Precomputed`), `pipeline.ts` (`think`, `worthRunning`)                                      | `test/01`, `test/04`, `test/153`             |
+| 7  | Commonality            | `traverse.ts` (`reachOf`, `dominates`, `hubWindows`), `cast.ts` (`depth[]`, `MIN_WEAVE`), `bridge.ts` (rarity)                             | `test/17`, `test/34`, `test/73`              |
+| 8  | Bounded reads          | `store.ts` (`*First`, `containersSlice`, `has*`, `bytesPrefix`, `chainRun`), `traverse.ts` (`hubBound`, `hubCap`)                          | `test/14`, `test/89`, `test/90`, `test/119`  |
+| 9  | Store                  | `store.ts` (`AbstractStore`, `intern`), `store-sqlite.ts`                                                                                  | `test/02`, `test/08`, `test/36-bloom`        |
+| 10 | Fold contract          | `geometry.ts` (`contentLevels`, `contentIdentity`), `primitives.ts` (`branchNaming`), `canonical.ts`, `canon.ts`                           | `test/59`, `test/63`, `test/148`, `test/152` |
+| 11 | Memoization            | `pipeline-mechanism.ts` (`Precomputed`), `mind.ts` (`beginResponse`, `endResponse`)                                                        | `test/42`, `test/155.4`                      |
+| 12 | Saturation             | `traverse.ts` (`edgeAncestors`), `junction.ts` (`junctionContainersFrom`), `resonance.ts` (`pivotInto`), `types.ts` (`SaturationStop`)     | `test/16`, `test/27`, `test/34`, `test/49`   |
+| 13 | Meter                  | `meter.ts`, `Precomputed.shared`                                                                                                           | `test/55`                                    |
+| 14 | Closure                | `derivation.ts` (`admissible`, `advance`, `closeOver`)                                                                                     | `test/133`–`151`                             |
+| 15 | Witnessed evidence     | `evidence.ts` (`witness`, `windowIndex`), `traverse.ts` (`chooseNext`, `answersOtherQuestions`, `coInstanceFiller`, `scaffoldExtents`)     | `test/154`, `test/155`, `test/76`            |
+
+Caches (`caches.md`: every acceleration is a `BoundedMap`, and a miss
+re-derives) are pinned by `test/91` and `test/96`.
+
+## Honest silence
+
+Every law above serves one contract the code cites by this file's name: **when
+the evidence does not decide, say less, never something invented.** A budget
+that runs out abstains and is counted (`junctionBudgetExhausted`). A cache miss
+re-derives, never approximates. A question whose every window is scaffolding is
+not bridged. When nothing accounts for the question, the price makes silence the
+lightest answer, and an answer that is only near says so. A gap is honest; an
+assembly carrying content the evidence did not license is a fabrication. Pinned
+by `test/28`, `test/73` and `test/84`.