@hviana/sema 0.1.0

package/src/bytes.ts

@@ -0,0 +1,62 @@
+// bytes.ts — small, pure byte-span utilities.
+//
+// Nothing here knows about Sema, the store, or the search; these are the
+// mechanical operations on Uint8Arrays that the rest of the code leans on, kept
+// together so a reader meets them once and never wonders whether a given helper
+// hides a side effect.
+
+/** True when two byte spans are equal in length and content. */
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** Concatenate byte arrays. Takes an array rather than rest params so
+ *  a large segment list can never overflow the call stack via spread. */
+export function concatBytes(parts: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.length;
+  }
+  return out;
+}
+
+/** Join two byte spans — the hot two-operand case of {@link concatBytes},
+ *  fused without the array wrapper for the search's inner fuse loop. */
+export function concat2(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/** Latin-1 view of a byte span — a stable, lossless string key for chart
+ *  memoization (every byte 0–255 maps to one code unit). */
+export function latin1(b: Uint8Array): string {
+  let s = "";
+  for (let k = 0; k < b.length; k++) s += String.fromCharCode(b[k]);
+  return s;
+}
+
+/** First index ≥ `from` at which `needle` occurs in `hay`, or -1.  A short naive
+ *  scan — used only to locate a result span inside a learnt framing form. */
+export function indexOf(
+  hay: Uint8Array,
+  needle: Uint8Array,
+  from: number,
+): number {
+  if (needle.length === 0) return from;
+  outer:
+  for (let i = Math.max(0, from); i + needle.length <= hay.length; i++) {
+    for (let j = 0; j < needle.length; j++) {
+      if (hay[i + j] !== needle[j]) continue outer;
+    }
+    return i;
+  }
+  return -1;
+}

package/src/config.ts

@@ -0,0 +1,227 @@
+// config.ts — the single configuration interface for Sema.
+// Every tunable parameter lives here. Subsystems receive their subset.
+
+// ── Sub-interfaces (grouped by subsystem) ──
+
+// NOTE: there is deliberately no resonance-threshold config.  The concept
+// threshold is DERIVED from the geometry (see conceptThreshold(D) in
+// geometry.ts) and every consumer reads it from there; a config knob for it
+// existed once but was never read — a dead setting that silently did nothing.
+
+export interface AluConfig {
+  /** Whether the ALU sub-lib contributes computation rules to the graph search.
+   *  When false, no operator/operand pre-resolution runs and no ALU rule fires —
+   *  thinking behaves exactly as it did before ALU existed. */
+  enabled: boolean;
+  /** Convergence tolerance ε for the numerical limit layer (diff/solve/exp/…). */
+  tol: number;
+  /** Hard iteration ceiling for any convergence loop, so a non-converging
+   *  refinement still terminates. */
+  maxIter: number;
+  /** Decimal places a real result is rounded to before it is encoded to bytes.
+   *  Determinism here is load-bearing: the search keys an output span by its
+   *  bytes, so two derivations of the same value must spell it identically. */
+  precision: number;
+}
+
+export interface GeometryConfig {
+  /** Maximum siblings per tree fold. */
+  maxGroup: number;
+}
+
+export interface AlphabetConfig {
+  /** How different neighbouring byte vectors are from their coarse ancestors
+   *  (0 = identical, 1 = independent). */
+  roughness: number;
+  /** Seed XOR mask for the alphabet's PRNG derivation. */
+  seedMask: number;
+}
+
+export interface StoreConfig {
+  minHaloMass: number;
+  m: number;
+  efConstruction: number;
+  /** Construction budget for REACH-ONLY interior gists — the ~90% of content
+   *  index inserts that exist so a partial query can resonate a sub-region
+   *  and climb, never as dedup targets.  Deposit roots and halo-bearing
+   *  targets always build with the full `efConstruction`.  A smaller budget
+   *  here is the one deliberate speed-for-quality trade in ingestion (an
+   *  interior's layer-0 wiring is built from a narrower candidate beam);
+   *  the recall suite (partial recall, multi-topic attention, counterfactual
+   *  anchoring) is the gate for its value.  Set equal to `efConstruction`
+   *  to disable the trade. */
+  efConstructionInterior: number;
+  efSearch: number;
+  /** Compact the in-memory vector indices after this many vectors are written.
+   *  Compaction rebuilds an index from its live codes to reclaim the slots left
+   *  by tombstoned (updated/deleted) halo entries; pacing it on write VOLUME
+   *  (not on a flush count that goes quiet during repeat-heavy training) keeps
+   *  the index dense and query cost bounded. */
+  compactEveryNWrites: number;
+  /** Over-fetch factor for HNSW queries (ANN recall cushion). */
+  overfetch: number;
+  /** Combined buffered-write ceiling before a flush of both vector indices
+   *  (content + halo). Higher ⇒ fewer, larger flushes into the in-memory
+   *  indices and fewer write-transaction commits. */
+  batchSize: number;
+  /** Max entries in the store's exact-content dedup map (bounds RAM on huge
+   *  corpora; a miss only risks a duplicate node, never incorrectness). */
+  dedupCacheMax: number;
+  /** Max bytes of reconstructed content cached in memory (regenerable).
+   *  Large branch nodes cost more budget than small leaves, so the cache
+   *  naturally favours cheap, frequently-hit entries. */
+  bytesCacheMax: number;
+  /** Max bytes of node-record cache (avoids repeated SQLite lookups for
+   *  shared DAG nodes).  Each record is ~30-50 bytes. */
+  recCacheBytes: number;
+  /** Max bytes of ingest-result cache used by {@link CachedIngest}. */
+  ingestCacheBytes: number;
+  /** Max bytes of captured-but-not-yet-indexed node gists (D·4 each). A node's
+   *  gist enters the content index lazily, only when it first becomes a
+   *  resonance target (gains a continuation edge or a halo); until then its gist
+   *  waits here. A deposit links/pours a node right after interning it, so the
+   *  working set is one deposit's nodes — a modest budget captures ~all of it.
+   *  An eviction only means a node is reached by the structural DAG climb instead
+   *  of by direct resonance — a little recall reach, never correctness. */
+  pendingGistBytes: number;
+  /** Max bytes of EXACT halo accumulators kept in memory (D·4 each). The
+   *  durable halo row is 2-bit quantized; this cache keeps the accumulators a
+   *  session is actively pouring into at full precision, so within-session
+   *  accumulate-then-compare (concept formation as it happens) never
+   *  round-trips through the quantizer. An eviction or a reopen reads the
+   *  2-bit row — the fidelity every cross-session consumer already gets. */
+  haloCacheBytes: number;
+  /** Size, in MiB, of each `rabitq-hnsw` `VectorDatabase`'s memory budget
+   *  (forwarded as its `cacheSizeMb`).  It is the index's SINGLE memory knob: it
+   *  sizes both SQLite's page cache and the derived immutable-code LRU.  A PURE
+   *  latency optimisation — the index reads codes from SQLite on demand, so its
+   *  correctness and its asymptotic per-operation storage-read count are identical
+   *  with the budget at 0.  Exposed so a scaling test can set it to 0 and measure
+   *  the honest, cache-independent cost. */
+  vectorCacheMb: number;
+  /** Max entries in the skipped-interior LRU set.  Interiors that
+   *  {@link Store.indexSubtree} has already visited (indexed or skipped) are
+   *  remembered here so subsequent calls prune their subtrees.  Session-local
+   *  (regenerable). */
+  coveredIdsMax: number;
+  /** Max bytes of transparent-chain runs ({@link Store.chainRun}) cached for
+   *  the store's lifetime (~4 bytes per chain node).  Valid until any write
+   *  could break a node's transparency (a new structural parent or a new
+   *  continuation edge), when the whole cache is dropped — writes happen in
+   *  training bursts, reads in read-only query phases, so the cache pays for
+   *  itself exactly where it matters.  Regenerable; a miss re-walks. */
+  chainCacheBytes: number;
+}
+
+// ── The one configuration interface ──
+
+export interface MindConfig {
+  seed: number;
+  recallQueryK: number;
+  haloQueryK: number;
+  normalizeEpsilon: number;
+  cosineEpsilon: number;
+
+  alu: AluConfig;
+  geometry: GeometryConfig;
+  alphabet: AlphabetConfig;
+  store: StoreConfig;
+}
+
+// ── Defaults ──
+
+export const DEFAULT_CONFIG: MindConfig = {
+  seed: 42,
+  recallQueryK: 12,
+  haloQueryK: 12,
+  normalizeEpsilon: 1e-12,
+  cosineEpsilon: 1e-12,
+  alu: {
+    enabled: true,
+    tol: 1e-10,
+    maxIter: 1000,
+    precision: 6,
+  },
+  geometry: {
+    maxGroup: 4,
+  },
+  alphabet: {
+    roughness: 0.65,
+    seedMask: 0xa1fa17,
+  },
+  store: {
+    minHaloMass: 1,
+    m: 8,
+    efConstruction: 64,
+    efConstructionInterior: 16,
+    efSearch: 64,
+    compactEveryNWrites: 50_000,
+    overfetch: 4,
+    batchSize: 256,
+    dedupCacheMax: 1_000_000,
+    bytesCacheMax: 20_000_000,
+    recCacheBytes: 10_000_000,
+    ingestCacheBytes: 50_000_000,
+    pendingGistBytes: 16_000_000,
+    haloCacheBytes: 16_000_000,
+    vectorCacheMb: 64,
+    coveredIdsMax: 100_000,
+    chainCacheBytes: 16_000_000,
+  },
+};
+
+// ── Config resolver: partial input + defaults = full config ──
+
+export function resolveConfig(opts: Partial<MindConfig> = {}): MindConfig {
+  return {
+    seed: opts.seed ?? DEFAULT_CONFIG.seed,
+    recallQueryK: opts.recallQueryK ?? DEFAULT_CONFIG.recallQueryK,
+    haloQueryK: opts.haloQueryK ?? DEFAULT_CONFIG.haloQueryK,
+    normalizeEpsilon: opts.normalizeEpsilon ?? DEFAULT_CONFIG.normalizeEpsilon,
+    cosineEpsilon: opts.cosineEpsilon ?? DEFAULT_CONFIG.cosineEpsilon,
+    alu: {
+      enabled: opts.alu?.enabled ?? DEFAULT_CONFIG.alu.enabled,
+      tol: opts.alu?.tol ?? DEFAULT_CONFIG.alu.tol,
+      maxIter: opts.alu?.maxIter ?? DEFAULT_CONFIG.alu.maxIter,
+      precision: opts.alu?.precision ?? DEFAULT_CONFIG.alu.precision,
+    },
+    geometry: {
+      maxGroup: opts.geometry?.maxGroup ?? DEFAULT_CONFIG.geometry.maxGroup,
+    },
+    alphabet: {
+      roughness: opts.alphabet?.roughness ?? DEFAULT_CONFIG.alphabet.roughness,
+      seedMask: opts.alphabet?.seedMask ?? DEFAULT_CONFIG.alphabet.seedMask,
+    },
+    store: {
+      minHaloMass: opts.store?.minHaloMass ?? DEFAULT_CONFIG.store.minHaloMass,
+      m: opts.store?.m ?? DEFAULT_CONFIG.store.m,
+      efConstruction: opts.store?.efConstruction ??
+        DEFAULT_CONFIG.store.efConstruction,
+      efConstructionInterior: opts.store?.efConstructionInterior ??
+        DEFAULT_CONFIG.store.efConstructionInterior,
+      efSearch: opts.store?.efSearch ?? DEFAULT_CONFIG.store.efSearch,
+      compactEveryNWrites: opts.store?.compactEveryNWrites ??
+        DEFAULT_CONFIG.store.compactEveryNWrites,
+      overfetch: opts.store?.overfetch ?? DEFAULT_CONFIG.store.overfetch,
+      batchSize: opts.store?.batchSize ?? DEFAULT_CONFIG.store.batchSize,
+      dedupCacheMax: opts.store?.dedupCacheMax ??
+        DEFAULT_CONFIG.store.dedupCacheMax,
+      bytesCacheMax: opts.store?.bytesCacheMax ??
+        DEFAULT_CONFIG.store.bytesCacheMax,
+      recCacheBytes: opts.store?.recCacheBytes ??
+        DEFAULT_CONFIG.store.recCacheBytes,
+      ingestCacheBytes: opts.store?.ingestCacheBytes ??
+        DEFAULT_CONFIG.store.ingestCacheBytes,
+      pendingGistBytes: opts.store?.pendingGistBytes ??
+        DEFAULT_CONFIG.store.pendingGistBytes,
+      haloCacheBytes: opts.store?.haloCacheBytes ??
+        DEFAULT_CONFIG.store.haloCacheBytes,
+      vectorCacheMb: opts.store?.vectorCacheMb ??
+        DEFAULT_CONFIG.store.vectorCacheMb,
+      coveredIdsMax: opts.store?.coveredIdsMax ??
+        DEFAULT_CONFIG.store.coveredIdsMax,
+      chainCacheBytes: opts.store?.chainCacheBytes ??
+        DEFAULT_CONFIG.store.chainCacheBytes,
+    },
+  };
+}

package/src/derive/README.md

@@ -0,0 +1,295 @@
+# 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.
+
+## 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.
+
+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
+  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.
+
+## API
+
+```ts
+import {
+  type DeductionSystem,
+  type Derivation,
+  lightestDerivation,
+  type Rule,
+} from "derive";
+```
+
+### `lightestDerivation<I>(system: DeductionSystem<I>): 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
+}
+```
+
+## 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
+```
+
+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
+
+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`.
+
+```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 };
+  },
+};
+
+const best = lightestDerivation(system);
+// best.cost === 8, best.premises.length === 2 — it really used the bridge.
+```
+
+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.
+
+## 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.
+
+- **`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.
+
+- **`MinHeap<T>`** — the allocation-light binary heap the agenda is built on.
+
+## 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
+```