@hviana/sema 0.9.4 → 0.9.5

package/src/derive/README.md

@@ -1,295 +1,133 @@
 # derive
 
-A small, dependency-free library for computing the **lightest derivation** in a
-weighted deduction system — equivalently, an implicit **AND/OR hypergraph** — by
-A\* search. It is the generic graph-exploration core of symbolic processing: the
-engine knows nothing about what its items _are_, only how to canonicalise them,
-enumerate their rules, score them, and recognise the goal. Anything that can be
-phrased as "derive a global structure from weighted rules" — parsing, shortest
-paths, segmentation, rewriting, planning — is one call to the same search.
-
-It has no dependency on the rest of the codebase and is intended to be reused
-across mechanisms, in the spirit of a self-contained sublibrary.
+A small, dependency-free library that computes the **lightest derivation** in a
+weighted deduction system, equivalently an implicit **AND/OR hypergraph**, by
+A\* search. The engine knows nothing about what its items _are_. It only knows
+how to key them, enumerate their rules, bound them and recognise the goal.
+Parsing, shortest paths, segmentation, rewriting and planning are each one call
+to the same search. It imports nothing from the rest of the codebase.
 
 ## The algorithm
 
-The library implements **adapted A\* Lightest Derivation (adapted A\*LD)**:
-
-> P. F. Felzenszwalb and D. McAllester. _The Generalized A\* Architecture._
-> Journal of Artificial Intelligence Research 29 (2007) 153–190.
+The library implements an adapted A\* Lightest Derivation (A\*LD; P. F.
+Felzenszwalb & D. McAllester, _The Generalized A\* Architecture_, JAIR 29,
+2007). It unifies two classical results:
 
-adapted A\*LD generalises A\* from shortest paths to the problem of computing a
-lightest derivation of a goal from a set of weighted rules, searching an AND/OR
-graph bottom-up. It rests on two classical results and unifies them:
-
-- **Knuth (1977)**, _A generalization of Dijkstra's algorithm_ — the
-  lightest-derivation problem and its Dijkstra-like solution: process items in
-  priority order, and an item's cost is final the instant it is removed from the
+- **Knuth (1977)**, _A generalization of Dijkstra's algorithm_: process items in
+  order of priority, and an item's cost is final the moment it leaves the
   agenda.
-- **A\* parsing** (Klein & Manning, 2003) — adding an admissible heuristic so
-  that partial derivations which cannot lead cheaply to the goal are never
-  expanded.
-
-For a problem that happens to be a shortest path, adapted A\*LD reduces exactly
-to A\*. With a small number of antecedents per rule it runs in **O(M log N)** (M
-rules, N items), and — crucially — it is **output-sensitive**: only items `B`
-with `ℓ(B) ≤ ℓ(goal)` are ever expanded, where `ℓ(B)` is the cost of `B`'s
-lightest derivation. Work is proportional to the goal, not to the size of the
-implicit graph, so there is no need for length caps or other artificial bounds
-to keep it tractable.
-
-> **Evidence pooling via semiring generalization.** The `derive` engine is no
-> the pure classic A\*LD algorithm. It has been extended with **additive
-> evidence accumulation** — a second combining mode (`combine: "sum"`) that
-> operates in the **arithmetic (+, +) semiring** instead of the standard
-> **tropical (min, +) semiring** of shortest-path search. Under the min-cost
-> regime, only the single cheapest route to a conclusion survives; under the
-> arithmetic semiring, every independent line of evidence corroborating the same
-> conclusion is **pooled** — its cost is summed, its contribution is recorded,
-> and nothing is discarded for not being the cheapest. This is how Sema forms
-> consensus votes from multiple independent query regions: each region
-> contributes its evidence, and the pooled aggregate is the conclusion's total
-> evidential support. A pooled conclusion never competes in the min-cost chart,
-> never re-enters the agenda, and is read back by the caller once the search
-> exhausts its axioms — making evidence pooling a zero-cost opt-in that coexists
-> with the classic algorithm in a single search.
-
-## What "lightest derivation" means
-
-A **weighted deduction system** is a set of _items_ combined by inference rules
-
-```
-premise₁ ∧ … ∧ premiseₖ  --localCost-->  conclusion
-```
-
-A _derivation_ of an item is a tree: the root is a rule, its children are
-derivations of that rule's premises, and the leaves are axioms. A derivation's
-cost is the sum of the local costs of the rules it uses. `ℓ(B)` is the minimum
-such cost over all derivations of `B`. The search returns a derivation achieving
-`ℓ(goal)`, or `null` if the goal is underivable.
-
-A rule with one premise is an ordinary (OR) edge; a rule with several premises
-is an **AND** node that _composes_ its premises — this is what makes the
-structure a hypergraph rather than a plain graph, and it is how partial results
-are joined (for example, combining two recognised spans into one).
-
-### Bridges: composing premises into a coherent whole
-
-A multi-premise rule is a **bridge**: it derives a conclusion from two (or more)
-already-derived items and charges a local cost for the join. Bridges are the
-mechanism by which independently-derived parts are assembled — and because a
-bridge's conclusion is itself an ordinary item, it can serve as a premise of a
-_further_ bridge, so bridges chain associatively: `A∧B → AB`, then `AB∧C → ABC`,
-all within one search. The cost of the join is paid inside the derivation, so
-the lightest derivation is the globally most coherent assembly of the parts, not
-a left-to-right stitch decided after the fact.
-
-This is what backs the connector ("bridge") mechanism in the surrounding mind:
-two rewritten spans are joined by a bridge whose local cost reflects how well a
-learned connector fits between them, and a third span chains onto the result by
-the same rule — so a multi-part answer is found as one whole, with no
-accumulated gaps, and never as a post-processing pass.
-
-Two properties make bridges safe to lean on:
-
-- **Lazy, order-free firing.** A bridge is emitted from `rules` when _either_
-  premise is finalised; the engine fires it only once _all_ its premises are
-  known (see `lightestDerivation`'s readiness check). So a bridge may be yielded
-  twice — once from each side — and the engine deduplicates by waiting for the
-  full conjunction. The caller need not know which premise finalises first.
-- **Robust reconstruction.** Recovering the derivation tree is iterative (an
-  explicit post-order stack), so it handles both arbitrarily long single-premise
-  chains — which, on long inputs, would overflow a recursive walk — and
-  multi-premise bridges uniformly. A bridged conclusion's `premises` array holds
-  one `Derivation` per premise, in rule order.
-
-## The four mechanisms
-
-The search stays proportional to the goal because of four reductions, three of
-which the caller participates in through the `DeductionSystem` interface:
-
-1. **Canonical chart memoization** — items are keyed by `key(item)`; equivalent
-   partial derivations collapse to a single chart entry, the cheapest one.
-2. **Backward demand filtering** — `rules` only emits rules whose conclusion can
-   still reach the goal, so work unrelated to the goal is never generated.
-3. **A\* lower-bound pruning** — `heuristic` keeps the agenda ordered by
-   `g + h`, so only competitive items are expanded.
-4. **Lazy hyperedge generation** — rules are produced by `rules` only when one
-   of their premises is finalised, never enumerated up front.
+- **A\* parsing** (Klein & Manning, 2003): an admissible heuristic keeps partial
+  derivations that cannot reach the goal cheaply from ever being expanded.
+
+On a shortest-path problem it reduces exactly to A\*. With a small number of
+premises per rule it runs in `O(M log N)`. It is **output-sensitive**: only
+items whose lightest cost is at most the goal's are ever expanded, so its work
+is proportional to the goal, not to the size of the implicit graph, and it needs
+no length caps.
+
+A **derivation** of an item is a tree: its root is a rule, its children derive
+that rule's premises, and its leaves are axioms. Its cost is the sum of the
+local costs of the rules it uses. A rule with one premise is an OR edge. A rule
+with several premises is an AND node that **composes** them. That is what makes
+the structure a hypergraph, and it is how separately derived parts are joined
+(`A ∧ B → AB`, then `AB ∧ C → ABC`). Because the join is paid inside the search,
+the lightest derivation is the most coherent assembly of the parts overall, not
+a left-to-right stitch decided afterwards.
+
+## Two combinators
+
+| `Rule.combine`    | Semiring           | At the conclusion                                                                                                                    |
+| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `"min"` (default) | (min, +), tropical | the cheapest route wins and every other is discarded. This is the search proper.                                                     |
+| `"sum"`           | (+, +)             | every firing adds its cost to the same conclusion, in `system.pool`. Independent lines of evidence corroborate instead of competing. |
+
+A pooled conclusion never enters the agenda and is never a premise. It is a
+terminal aggregate the caller reads from `pool` once the search has exhausted
+its axioms. A system without `pool` never takes this branch, so pooling costs
+nothing to systems that do not use it.
+
+## Why the search stays proportional to the goal
+
+1. **Canonical chart memoization.** Items are keyed by `key(item)`, so
+   equivalent partial derivations collapse to one entry, the cheapest.
+2. **Backward demand filtering.** `rules` emits only rules whose conclusion can
+   still reach the goal.
+3. **A\* pruning.** `heuristic` orders the agenda by `g + h`.
+4. **Lazy hyperedges.** A rule is produced only when one of its premises is
+   finalised, and fires only once all of its premises are known. It may be
+   yielded from either side, and the engine waits for the full conjunction.
+
+The derivation tree is reconstructed iteratively, so very long chains cannot
+overflow the stack.
 
 ## API
 
 ```ts
-import {
-  type DeductionSystem,
-  type Derivation,
-  lightestDerivation,
-  type Rule,
-} from "derive";
-```
-
-### `lightestDerivation<I>(system: DeductionSystem<I>): Derivation<I> | null`
+lightestDerivation<I>(system: DeductionSystem<I>, stats?: SearchStats): Derivation<I> | null
 
-Runs the search and returns the root of a lightest derivation tree (`null` if
-the goal cannot be derived). `root.cost` is the total derivation cost; the tree
-is walked through `root.premises`.
-
-### `DeductionSystem<I>`
-
-The problem you hand the solver. `I` is your item type — anything at all.
-
-```ts
 interface DeductionSystem<I> {
-  // Canonical key for chart memoization (the item's "boundary signature":
-  // everything that can affect how it later combines).
-  key(item: I): string;
-
-  // The atomic items and their base costs — the search's seeds.
-  axioms(): Iterable<{ item: I; cost: number }>;
-
-  // Lazily yield the rules that have `item` among their premises. Called once,
-  // when `item` is finalised. `costOf(other)` returns another item's finalised
-  // cost (Infinity if not yet known) — use it to drop rules whose other
-  // premises are still open or whose conclusion can no longer beat the goal.
-  rules(item: I, costOf: (other: I) => number): Iterable<Rule<I>>;
-
-  // Whether `item` satisfies the goal. The first finalised goal wins.
-  isGoal(item: I): boolean;
-
-  // Optional admissible, consistent lower bound on the cost from `item` to a
-  // goal. Omit it (or return 0) for plain Knuth/Dijkstra.
-  heuristic?(item: I): number;
-}
-```
-
-### `Rule<I>` and `Derivation<I>`
-
-```ts
-interface Rule<I> {
-  premises: readonly I[]; // the conjunction (one premise = an OR edge; many = an AND node)
-  conclusion: I;
-  cost: number; // local cost, non-negative
-}
-
-interface Derivation<I> {
-  item: I;
-  cost: number; // this item's lightest-derivation cost (its g)
-  rule: Rule<I> | null; // the producing rule, or null for an axiom
-  premises: Array<Derivation<I>>; // derivations of the rule's premises
+  key(item: I): string;                                   // chart key: everything that can affect later combination
+  axioms(): Iterable<{ item: I; cost: number }>;          // the seeds
+  rules(item: I, costOf: (other: I) => number): Iterable<Rule<I>>; // called once, when `item` is finalised
+  isGoal(item: I): boolean;                               // the first finalised goal wins
+  heuristic?(item: I): number;                            // admissible, consistent; omit for Knuth/Dijkstra
+  pool?: Map<string, PooledConclusion<I>>;                // present only for `combine: "sum"` systems
 }
-```
-
-## Example: shortest path is a special case
-
-A weighted directed graph is a deduction system in which every node is an item
-and every edge is a one-premise rule. The lightest derivation of the target is
-the shortest path — adapted A\*LD collapses to A\*.
-
-```ts
-import { type DeductionSystem, lightestDerivation } from "derive";
-
-const edges: Record<string, Array<[string, number]>> = {
-  a: [["b", 1], ["c", 4]],
-  b: [["c", 1], ["d", 5]],
-  c: [["d", 1]],
-  d: [],
-};
 
-const shortestPath: DeductionSystem<string> = {
-  key: (n) => n,
-  *axioms() {
-    yield { item: "a", cost: 0 };
-  },
-  *rules(node) {
-    for (const [to, w] of edges[node] ?? []) {
-      yield { premises: [node], conclusion: to, cost: w };
-    }
-  },
-  isGoal: (n) => n === "d",
-  heuristic: () => 0, // any admissible lower bound focuses the search
-};
-
-const best = lightestDerivation(shortestPath);
-// best.cost === 3, and a → b → c → d is recovered from best.premises
+interface Rule<I> { premises: readonly I[]; conclusion: I; cost: number; combine?: "min" | "sum" }
+interface Derivation<I> { item: I; cost: number; rule: Rule<I> | null; premises: Derivation<I>[] }
+interface SearchStats { pops: number; pushes: number }
 ```
 
-To compose rather than merely traverse, give a rule **several** premises: the
-search will derive each one and only fire the rule once they are all finalised,
-charging `cost` on top of their combined cost.
-
-## Example: a bridge composes two parts into one
+`costOf(other)` returns another item's finalised cost, or `Infinity` if it is
+not yet known. Use it to drop rules whose other premises are still open, or
+whose conclusion can no longer beat the goal.
 
-Two axioms `A` (3) and `B` (4) and a bridge `A ∧ B → AB` (1). The bridge is
-yielded from _either_ premise; the engine waits until both are finalised, then
-charges the join. The only derivation of `AB` costs `3 + 4 + 1 = 8`, and its
-`premises` array holds the derivations of `A` and `B`.
+## Example — a bridge composes two parts
 
 ```ts
-import { type DeductionSystem, lightestDerivation } from "derive";
-
 const system: DeductionSystem<string> = {
   key: (s) => s,
   axioms: () => [{ item: "A", cost: 3 }, { item: "B", cost: 4 }],
   isGoal: (s) => s === "AB",
   *rules(item) {
-    // Fired from either side; the engine composes once both are known.
-    if (item === "A") yield { premises: ["A", "B"], conclusion: "AB", cost: 1 };
-    if (item === "B") yield { premises: ["A", "B"], conclusion: "AB", cost: 1 };
+    if (item === "A" || item === "B") {
+      yield { premises: ["A", "B"], conclusion: "AB", cost: 1 };
+    }
   },
 };
-
-const best = lightestDerivation(system);
-// best.cost === 8, best.premises.length === 2 — it really used the bridge.
+lightestDerivation(system); // cost 8 = 3 + 4 + 1; premises hold A's and B's derivations
 ```
 
-Add a rule `AB ∧ C → ABC` and the bridge chains: the lightest derivation of
-`ABC` composes all three parts, the join cost paid inside the search.
+A weighted graph is the special case where every rule has one premise. There,
+the lightest derivation of the target is the shortest path.
 
 ## Correctness conditions
 
-The engine is correct provided the caller upholds the conditions adapted A\*LD
-requires:
-
-- **Non-negative local costs** (more generally, monotone): adding a rule never
-  lowers a derivation's cost.
-- **Admissible, consistent heuristic**: `heuristic` never overestimates the cost
-  remaining to a goal, and is hyperedge-consistent,
-  `h(conclusion) ≤ ruleCost + Σ h(premiseᵢ)`. The default (`0`) is trivially
-  consistent and yields plain Knuth/Dijkstra.
-- **Faithful `key`**: two items with the same key must be interchangeable in
-  every rule. The key must preserve every part of an item that can affect future
-  composition; anything it drops is asserted irrelevant.
-
-## Companion utilities
-
-Three small, independently useful pieces share the package, all aligned with the
-same "only the work the goal demands" philosophy:
-
-- **`Trie<P>`** — a forward prefix matcher used as a _lazy recognition index_.
-  `matchesAt(seq, pos)` walks forward from the root and reports every stored
-  pattern beginning at `pos` in time proportional to the longest match; a
-  position with nothing learned dead-ends at once, and no length bound is
-  imposed — the structure of what was inserted is the bound. A cursor API
-  (`root`, `step`, `terminal`) supports incremental walks; `scan(seq)` reports
-  all matches across all positions.
+- **Local costs are non-negative,** or more generally monotone.
+- **The heuristic is admissible and consistent:**
+  `h(conclusion) ≤ ruleCost + Σ h(premiseᵢ)`. The default `0` is trivially so.
+- **`key` is faithful:** two items with the same key must be interchangeable in
+  every rule. Whatever the key drops is asserted to be irrelevant.
 
-- **`coverSequence<P>(length, candidates)`** — the segmentation primitive: the
-  lightest set of non-overlapping spans covering a sequence, computed on the
-  engine. It is the principled, corpus-independent replacement for "scan with an
-  automaton, then greedily keep the longest non-overlapping matches" — the same
-  linear cost, but the _optimal_ cover.
+## Companions
 
-- **`MinHeap<T>`** — the allocation-light binary heap the agenda is built on.
+- **`Trie<P>`** is a lazy forward prefix matcher. `matchesAt(seq, pos)` reports
+  every stored pattern that starts at `pos`, in time proportional to the longest
+  match, and `scan(seq)` reports all of them. A cursor API (`root`, `step`,
+  `terminal`) walks incrementally.
+- **`coverSequence(length, candidates)`** returns the lightest set of
+  non-overlapping spans covering a sequence. It is the optimal replacement for
+  "keep the longest matches greedily", at the same linear cost.
+- **`MinHeap<T>`** is the agenda's heap.
 
 ## Layout
 
 ```
-derive/
-├── README.md            this file
-└── src/
-    ├── deduction.ts      lightestDerivation — the adapted A*LD engine
-    ├── trie.ts           Trie — lazy forward prefix matcher
-    ├── rewrite.ts        coverSequence — optimal sequence cover
-    ├── priority-queue.ts MinHeap — the agenda's heap
-    └── index.ts          public surface
+src/deduction.ts       lightestDerivation, the engine
+src/trie.ts            Trie
+src/rewrite.ts         coverSequence
+src/priority-queue.ts  MinHeap
+src/index.ts           public surface
+test/derive.test.ts    self-contained tests
 ```

package/src/mind/learning.ts

@@ -122,18 +122,17 @@ export async function deposit(
   { tree: Sema; rootId: number; ids: Map<Sema, number>; changed: Sema[] }
 > {
   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<Sema, number>();

package/src/mind/mind.ts

@@ -1063,10 +1063,10 @@ export class Mind implements MindContext {
     // 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),

package/src/mind/types.ts

@@ -400,9 +400,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 }> | null;
   /** Completed assistant-turn byte spans in the current cumulative query.
    *  Empty for ordinary respond(); response-scoped structural context for
@@ -435,18 +434,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/src/rabitq-ivf/README.md

@@ -25,20 +25,23 @@ detected by length.
 - **Clusters, not a graph.** The collection is partitioned into clusters, each
   with a binary pivot code and its member codes packed in fixed-size chunk
   blobs.
-- **Insert = route + append.** Find the nearest pivot (one linear Hamming scan
-  of the RAM-resident pivot table) and append to that cluster's tail chunk. No
-  beam search, no neighbour rewiring — per-insert cost is essentially flat in
-  collection size.
+- **Insert = route + append.** Find a nearest pivot and append to that cluster's
+  tail chunk. Routing is two-level: Hamming-scan the RAM-resident majority-bit
+  super-pivots (one per 64 clusters), then the members of the 4 nearest groups.
+  There is no beam search and no neighbour rewiring, so the cost of an insert is
+  essentially flat in collection size.
 - **Query = probe + scan.** Rank all pivots with the accurate RaBitQ estimator,
   scan the `ceil(efSearch/4)` nearest clusters with the same estimator, keep the
   top k. Per-query storage reads are bounded by nprobe × chunks-per-cluster —
   constant once the collection has split.
 - **Adaptive, deterministic splits.** A cluster reaching 4096 entries is
   median-split on the margin between two farthest-point seeds (two exact halves,
-  cascade-proof), and both halves get fresh majority-bit pivots. There is no
-  RNG: the index is a pure function of the insertion sequence.
-- **Same durability discipline as the rest of Sema**: WAL, batched caller-owned
-  transactions (`upsertMany`), 1 KiB pages, 64 MiB WAL autocheckpoint.
+  cascade-proof), and both halves get fresh majority-bit pivots. Splitting and
+  routing use no randomness, and RaBitQ's rotation is seeded, so the index is a
+  pure function of the seed and the insertion sequence.
+- **The same durability discipline as the rest of Sema:** WAL, batched
+  caller-owned transactions (`upsertMany`), 1 KiB pages, 64 MiB WAL
+  autocheckpoint.
 
 ## Usage
 

package/src/store.ts

@@ -136,11 +136,11 @@ export 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