@hviana/sema 0.1.9 → 0.2.1

package/dist/src/derive/src/priority-queue.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Binary min-heap keyed by a numeric priority, carrying an arbitrary payload.
+ *
+ * It is the agenda of the lightest-derivation search, where the priority is the
+ * estimate f = g + h. Stale entries are tolerated by the consumer (lazy
+ * deletion), so there is no decrease-key: when an item's cost improves it is
+ * simply pushed again, and the older, higher-priority copy is recognised as
+ * stale and discarded when it surfaces. Parallel arrays (rather than an array
+ * of objects) keep the hot path allocation-free.
+ */
+export declare class MinHeap<T> {
+    private readonly keys;
+    private readonly vals;
+    get size(): number;
+    push(priority: number, value: T): void;
+    pop(): {
+        priority: number;
+        value: T;
+    } | undefined;
+}

package/dist/src/derive/src/priority-queue.js

@@ -0,0 +1,73 @@
+/**
+ * Binary min-heap keyed by a numeric priority, carrying an arbitrary payload.
+ *
+ * It is the agenda of the lightest-derivation search, where the priority is the
+ * estimate f = g + h. Stale entries are tolerated by the consumer (lazy
+ * deletion), so there is no decrease-key: when an item's cost improves it is
+ * simply pushed again, and the older, higher-priority copy is recognised as
+ * stale and discarded when it surfaces. Parallel arrays (rather than an array
+ * of objects) keep the hot path allocation-free.
+ */
+export class MinHeap {
+    keys = [];
+    vals = [];
+    get size() {
+        return this.keys.length;
+    }
+    push(priority, value) {
+        const keys = this.keys;
+        const vals = this.vals;
+        let i = keys.length;
+        keys.push(priority);
+        vals.push(value);
+        while (i > 0) {
+            const parent = (i - 1) >> 1;
+            if (keys[i] < keys[parent]) {
+                const tk = keys[i];
+                keys[i] = keys[parent];
+                keys[parent] = tk;
+                const tv = vals[i];
+                vals[i] = vals[parent];
+                vals[parent] = tv;
+                i = parent;
+            }
+            else
+                break;
+        }
+    }
+    pop() {
+        const keys = this.keys;
+        const vals = this.vals;
+        const n = keys.length;
+        if (n === 0)
+            return undefined;
+        const top = { priority: keys[0], value: vals[0] };
+        const lastKey = keys.pop();
+        const lastVal = vals.pop();
+        const m = keys.length;
+        if (m > 0) {
+            keys[0] = lastKey;
+            vals[0] = lastVal;
+            let i = 0;
+            for (;;) {
+                const left = 2 * i + 1;
+                const right = left + 1;
+                let best = i;
+                if (left < m && keys[left] < keys[best])
+                    best = left;
+                if (right < m && keys[right] < keys[best])
+                    best = right;
+                if (best === i)
+                    break;
+                const tk = keys[i];
+                keys[i] = keys[best];
+                keys[best] = tk;
+                const tv = vals[i];
+                vals[i] = vals[best];
+                vals[best] = tv;
+                i = best;
+            }
+        }
+        return top;
+    }
+}

package/dist/src/derive/src/rewrite.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Sequence segmentation on the lightest-derivation engine.
+ *
+ * The only structure here is the **frontier**: the items are the positions
+ * `0…length` of a sequence, and a derivation is a path through them. That is
+ * what keeps the search linear in the input rather than quadratic — there is no
+ * enumeration of span *pairs* and no chart of O(n²) sub-sequences.
+ *
+ * Candidate spans are produced **on demand**: when the search finalises a
+ * position it asks a {@link Trie} which learned forms begin there. The trie walk
+ * stops exactly where the data's patterns stop — a position with nothing learned
+ * dead-ends immediately, a position inside a long form walks precisely that far.
+ * Nothing is scanned ahead of demand and no length bound is imposed; the
+ * structure of what was learned is the bound.
+ *
+ * {@link coverSequence} is the segmentation primitive: the lightest set of
+ * non-overlapping spans covering a sequence. It is the principled,
+ * corpus-independent replacement for "scan the whole stream with an automaton,
+ * then greedily keep the longest non-overlapping matches" — same linear cost,
+ * but the *optimal* cover and only the work the goal demands.
+ */
+/** A candidate span over a sequence, carrying caller payload. */
+export interface CandidateSpan<P> {
+    /** Start offset (inclusive). */
+    start: number;
+    /** End offset (exclusive); must be > start. */
+    end: number;
+    /** Relative cost of using this span (default 1). Lower wins ties. */
+    weight?: number;
+    /** Caller data, returned on the chosen spans. */
+    payload: P;
+}
+export interface Cover<P> {
+    /** Chosen non-overlapping spans, left to right. */
+    spans: Array<CandidateSpan<P>>;
+    /** Symbols covered by the chosen spans. */
+    covered: number;
+    /** Symbols left uncovered. */
+    uncovered: number;
+}
+/**
+ * The lightest non-overlapping cover of `[0, length)` drawn from `candidates`.
+ *
+ * Primary objective: cover the most symbols (fewest left uncovered). Secondary:
+ * least total span weight — with the default unit weight this prefers fewer,
+ * longer spans, the optimal analogue of greedy longest-match, but it can return
+ * a pair of shorter spans when together they cover more than one long one (which
+ * greedy cannot). Modelled as a shortest path over frontier positions: from a
+ * position you either leave one symbol uncovered (costly) or take a candidate
+ * that starts there (cheap), reaching `length`.
+ *
+ * Cost: O((length + |candidates|) · log length) — the frontier has `length + 1`
+ * items, each finalised once, with one "skip" edge plus the candidates that
+ * start there. No quadratic span structure.
+ */
+export declare function coverSequence<P>(length: number, candidates: ReadonlyArray<CandidateSpan<P>>): Cover<P>;

package/dist/src/derive/src/rewrite.js

@@ -0,0 +1,100 @@
+/**
+ * Sequence segmentation on the lightest-derivation engine.
+ *
+ * The only structure here is the **frontier**: the items are the positions
+ * `0…length` of a sequence, and a derivation is a path through them. That is
+ * what keeps the search linear in the input rather than quadratic — there is no
+ * enumeration of span *pairs* and no chart of O(n²) sub-sequences.
+ *
+ * Candidate spans are produced **on demand**: when the search finalises a
+ * position it asks a {@link Trie} which learned forms begin there. The trie walk
+ * stops exactly where the data's patterns stop — a position with nothing learned
+ * dead-ends immediately, a position inside a long form walks precisely that far.
+ * Nothing is scanned ahead of demand and no length bound is imposed; the
+ * structure of what was learned is the bound.
+ *
+ * {@link coverSequence} is the segmentation primitive: the lightest set of
+ * non-overlapping spans covering a sequence. It is the principled,
+ * corpus-independent replacement for "scan the whole stream with an automaton,
+ * then greedily keep the longest non-overlapping matches" — same linear cost,
+ * but the *optimal* cover and only the work the goal demands.
+ */
+import { lightestDerivation } from "./deduction.js";
+/**
+ * The lightest non-overlapping cover of `[0, length)` drawn from `candidates`.
+ *
+ * Primary objective: cover the most symbols (fewest left uncovered). Secondary:
+ * least total span weight — with the default unit weight this prefers fewer,
+ * longer spans, the optimal analogue of greedy longest-match, but it can return
+ * a pair of shorter spans when together they cover more than one long one (which
+ * greedy cannot). Modelled as a shortest path over frontier positions: from a
+ * position you either leave one symbol uncovered (costly) or take a candidate
+ * that starts there (cheap), reaching `length`.
+ *
+ * Cost: O((length + |candidates|) · log length) — the frontier has `length + 1`
+ * items, each finalised once, with one "skip" edge plus the candidates that
+ * start there. No quadratic span structure.
+ */
+export function coverSequence(length, candidates) {
+    if (length <= 0)
+        return { spans: [], covered: 0, uncovered: 0 };
+    // Candidates indexed by where they start, and by their exact (start,end) edge
+    // for reconstruction. Both are O(|candidates|) to build and to read.
+    const byStart = Array.from({ length }, () => []);
+    const byEdge = new Map();
+    let maxWeight = 1;
+    for (const c of candidates) {
+        if (c.end <= c.start || c.start < 0 || c.end > length)
+            continue;
+        const w = c.weight ?? 1;
+        if (w > maxWeight)
+            maxWeight = w;
+        byStart[c.start].push(c);
+        const edge = c.start * (length + 1) + c.end;
+        const prev = byEdge.get(edge);
+        if (!prev || w < (prev.weight ?? 1))
+            byEdge.set(edge, c);
+    }
+    // One uncovered symbol must outweigh any sum of span weights, so coverage is
+    // strictly the primary objective and weight only breaks ties.
+    const skipCost = maxWeight * length + 1;
+    const system = {
+        key: (p) => "" + p,
+        axioms: () => [{ item: 0, cost: 0 }],
+        isGoal: (p) => p === length,
+        // No nonzero admissible bound is available here: a single candidate can
+        // cover the whole remainder for unit cost, so any per-symbol estimate would
+        // overestimate. With h = 0 this is exact Knuth/Dijkstra over the frontier —
+        // optimal, and linear in the positions. (The A* outside bound is for systems
+        // whose remaining cost can be genuinely lower-bounded; see the engine.)
+        *rules(p) {
+            if (p >= length)
+                return;
+            yield { premises: [p], conclusion: p + 1, cost: skipCost }; // leave uncovered
+            for (const c of byStart[p]) {
+                yield { premises: [p], conclusion: c.end, cost: c.weight ?? 1 };
+            }
+        },
+    };
+    const best = lightestDerivation(system);
+    if (!best)
+        return { spans: [], covered: 0, uncovered: length };
+    // Walk the frontier chain back to the axiom; an edge p→q is a chosen span iff
+    // a candidate spans exactly [p, q) (a covering edge is always cheaper than the
+    // skips it replaces, so it appears on the optimal path wherever it is used).
+    const spans = [];
+    let node = best;
+    while (node && node.rule) {
+        const to = node.item;
+        const from = node.premises[0].item;
+        const span = byEdge.get(from * (length + 1) + to);
+        if (span)
+            spans.push(span);
+        node = node.premises[0];
+    }
+    spans.reverse();
+    let covered = 0;
+    for (const s of spans)
+        covered += s.end - s.start;
+    return { spans, covered, uncovered: length - covered };
+}

package/dist/src/derive/src/trie.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Forward prefix trie over integer symbols — the lazy site matcher.
+ *
+ * This is the matching primitive the lightest-derivation search consults *on
+ * demand*: given a position in a sequence, {@link Trie.matchesAt} walks forward
+ * from the root and reports every stored pattern that begins there, in
+ * O(longest matching pattern). Nothing is scanned that the search never asks
+ * about — there is no global automaton, no failure links, no precomputed match
+ * table. That is the whole point: rewrite sites are *materialised only when
+ * demanded* (the "lazy hyperedge generation" of the rewrite search), so the
+ * matcher itself stays trivial and the search decides what to look at.
+ *
+ * It is fully generic and self-contained: symbols are non-negative integers
+ * (bytes 0–255, Unicode code points, opcodes, …); patterns are any
+ * `ArrayLike<number>` (`Uint8Array` or `number[]`); each pattern carries an
+ * arbitrary `payload` returned on every match. The trie also exposes a tiny
+ * cursor API ({@link Trie.root}, {@link Trie.step}, {@link Trie.terminal}) so a
+ * caller can extend a partial match symbol-by-symbol — e.g. to ask "could this
+ * span still grow into a known form?" while composing.
+ *
+ * ## Memory
+ *
+ * Most states (99.7 % in typical use) have exactly one outgoing transition.
+ * Storing a full `Map` per state would cost ~88 bytes each. Instead, a singleton
+ * transition is packed inline into two typed arrays — `_nxt` (Int32Array, 4
+ * bytes) and `_sym` (Uint8Array, 1 byte) — for ~5 bytes per state, a 17×
+ * reduction. Only the rare multi-transition state (~0.3 %) allocates a `Map`,
+ * kept in a sparse `_multi` table keyed by state number.
+ */
+/** One pattern occurrence found by the trie. */
+export interface Match<P> {
+    /** Start offset in the searched sequence (inclusive). */
+    start: number;
+    /** End offset (exclusive); `end - start === length`. */
+    end: number;
+    /** Length of the matched pattern. */
+    length: number;
+    /** Pattern id, assigned in insertion order (0-based). */
+    id: number;
+    /** Payload registered with the pattern. */
+    payload: P;
+}
+export declare class Trie<P = undefined> {
+    private _nxt;
+    private _sym;
+    private _multi;
+    private _end;
+    private readonly _lens;
+    private readonly _vals;
+    private _len;
+    constructor();
+    /** The root state, for cursor walks. */
+    get root(): number;
+    /** Number of distinct patterns stored. */
+    get size(): number;
+    /** Allocate a fresh state, growing the typed arrays by a fixed increment
+     *  when full.  No power-of-2 doubling — the transient double-memory spike
+     *  during growth is bounded to the increment. */
+    private _state;
+    /** Follow symbol `c` from state `s`.  Returns the next state, or -1. */
+    private _follow;
+    /** Follow one symbol from `state`; returns the next state or -1 if none. */
+    step(state: number, symbol: number): number;
+    /** The pattern ending exactly at `state`, or null. */
+    terminal(state: number): {
+        id: number;
+        payload: P;
+    } | null;
+    /** Length of the pattern with this id. */
+    lengthOf(id: number): number;
+    /**
+     * Insert a pattern, returning its id. Inserting the same symbol-sequence
+     * twice returns the first id and keeps the first payload (patterns are keyed
+     * by content). Empty patterns are ignored and return -1.
+     */
+    insert(pattern: ArrayLike<number>, payload: P): number;
+    /**
+     * Every stored pattern that begins exactly at `pos` in `seq`, shortest first.
+     * Walks forward from the root in O(longest match); reports nothing about any
+     * other position. This is the on-demand probe the search uses.
+     */
+    matchesAt(seq: ArrayLike<number>, pos: number): Array<Match<P>>;
+    /**
+     * Every occurrence of every pattern anywhere in `seq` (eager form, the union
+     * of {@link matchesAt} over all start positions). O(seq · longest pattern),
+     * independent of how many patterns are stored. Use {@link matchesAt} when the
+     * search only needs the sites at a particular position.
+     */
+    scan(seq: ArrayLike<number>): Array<Match<P>>;
+}

package/dist/src/derive/src/trie.js

@@ -0,0 +1,217 @@
+/**
+ * Forward prefix trie over integer symbols — the lazy site matcher.
+ *
+ * This is the matching primitive the lightest-derivation search consults *on
+ * demand*: given a position in a sequence, {@link Trie.matchesAt} walks forward
+ * from the root and reports every stored pattern that begins there, in
+ * O(longest matching pattern). Nothing is scanned that the search never asks
+ * about — there is no global automaton, no failure links, no precomputed match
+ * table. That is the whole point: rewrite sites are *materialised only when
+ * demanded* (the "lazy hyperedge generation" of the rewrite search), so the
+ * matcher itself stays trivial and the search decides what to look at.
+ *
+ * It is fully generic and self-contained: symbols are non-negative integers
+ * (bytes 0–255, Unicode code points, opcodes, …); patterns are any
+ * `ArrayLike<number>` (`Uint8Array` or `number[]`); each pattern carries an
+ * arbitrary `payload` returned on every match. The trie also exposes a tiny
+ * cursor API ({@link Trie.root}, {@link Trie.step}, {@link Trie.terminal}) so a
+ * caller can extend a partial match symbol-by-symbol — e.g. to ask "could this
+ * span still grow into a known form?" while composing.
+ *
+ * ## Memory
+ *
+ * Most states (99.7 % in typical use) have exactly one outgoing transition.
+ * Storing a full `Map` per state would cost ~88 bytes each. Instead, a singleton
+ * transition is packed inline into two typed arrays — `_nxt` (Int32Array, 4
+ * bytes) and `_sym` (Uint8Array, 1 byte) — for ~5 bytes per state, a 17×
+ * reduction. Only the rare multi-transition state (~0.3 %) allocates a `Map`,
+ * kept in a sparse `_multi` table keyed by state number.
+ */
+const ROOT = 0;
+export class Trie {
+    // ── compact transition storage ──────────────────────────────────────────
+    // _nxt[s]  —  -1   terminal (no outgoing transition)
+    //             -2   multi-transition → _multi.get(s)
+    //             >=0  singleton target; the symbol is _sym[s]
+    _nxt;
+    _sym;
+    _multi = null;
+    // _end[s] is the pattern id ending exactly at s, or -1.
+    _end;
+    // Per-pattern data, indexed by pattern id.
+    _lens = [];
+    _vals = [];
+    _len = 1; // next free state (state 0 = root)
+    constructor() {
+        const c = 256;
+        this._nxt = new Int32Array(c);
+        this._sym = new Uint8Array(c);
+        this._end = new Int32Array(c);
+        this._nxt[ROOT] = -1;
+        this._end[ROOT] = -1;
+    }
+    /** The root state, for cursor walks. */
+    get root() {
+        return ROOT;
+    }
+    /** Number of distinct patterns stored. */
+    get size() {
+        return this._lens.length;
+    }
+    // ── internal helpers ────────────────────────────────────────────────────
+    /** Allocate a fresh state, growing the typed arrays by a fixed increment
+     *  when full.  No power-of-2 doubling — the transient double-memory spike
+     *  during growth is bounded to the increment. */
+    _state() {
+        const s = this._len++;
+        if (s >= this._nxt.length) {
+            const c = s + 4096;
+            const nn = new Int32Array(c);
+            nn.set(this._nxt);
+            this._nxt = nn;
+            const ns = new Uint8Array(c);
+            ns.set(this._sym);
+            this._sym = ns;
+            const ne = new Int32Array(c);
+            ne.set(this._end);
+            this._end = ne;
+        }
+        this._nxt[s] = -1;
+        this._end[s] = -1;
+        return s;
+    }
+    /** Follow symbol `c` from state `s`.  Returns the next state, or -1. */
+    _follow(s, c) {
+        const n = this._nxt[s];
+        if (n >= 0)
+            return this._sym[s] === c ? n : -1;
+        if (n === -2)
+            return this._multi.get(s).get(c) ?? -1;
+        return -1; // n === -1
+    }
+    // ── cursor API (allocation-free) ─────────────────────────────────────────
+    /** Follow one symbol from `state`; returns the next state or -1 if none. */
+    step(state, symbol) {
+        return this._follow(state, symbol);
+    }
+    /** The pattern ending exactly at `state`, or null. */
+    terminal(state) {
+        const id = this._end[state];
+        return id === -1 ? null : { id, payload: this._vals[id] };
+    }
+    /** Length of the pattern with this id. */
+    lengthOf(id) {
+        return this._lens[id];
+    }
+    // ── build ───────────────────────────────────────────────────────────────
+    /**
+     * Insert a pattern, returning its id. Inserting the same symbol-sequence
+     * twice returns the first id and keeps the first payload (patterns are keyed
+     * by content). Empty patterns are ignored and return -1.
+     */
+    insert(pattern, payload) {
+        const n = pattern.length;
+        if (n === 0)
+            return -1;
+        let s = ROOT;
+        for (let i = 0; i < n; i++) {
+            const c = pattern[i];
+            const t = this._nxt[s];
+            if (t === -1) {
+                // Terminal — place first transition as a singleton.
+                const ns = this._state();
+                this._nxt[s] = ns;
+                this._sym[s] = c;
+                s = ns;
+            }
+            else if (t >= 0) {
+                // Singleton — either advance on match, or expand to multi.
+                if (this._sym[s] === c) {
+                    s = t;
+                }
+                else {
+                    const map = new Map();
+                    map.set(this._sym[s], t);
+                    const ns = this._state();
+                    map.set(c, ns);
+                    if (!this._multi)
+                        this._multi = new Map();
+                    this._multi.set(s, map);
+                    this._nxt[s] = -2;
+                    s = ns;
+                }
+            }
+            else {
+                // Multi (t === -2) — extend the existing Map.
+                const map = this._multi.get(s);
+                let ns = map.get(c);
+                if (ns === undefined) {
+                    ns = this._state();
+                    map.set(c, ns);
+                }
+                s = ns;
+            }
+        }
+        if (this._end[s] !== -1)
+            return this._end[s]; // already present
+        const id = this._lens.length;
+        this._lens.push(n);
+        this._vals.push(payload);
+        this._end[s] = id;
+        return id;
+    }
+    // ── matching ───────────────────────────────────────────────────────────
+    /**
+     * Every stored pattern that begins exactly at `pos` in `seq`, shortest first.
+     * Walks forward from the root in O(longest match); reports nothing about any
+     * other position. This is the on-demand probe the search uses.
+     */
+    matchesAt(seq, pos) {
+        const out = [];
+        let s = ROOT;
+        for (let i = pos, n = seq.length; i < n; i++) {
+            s = this._follow(s, seq[i]);
+            if (s === -1)
+                break;
+            const id = this._end[s];
+            if (id !== -1) {
+                out.push({
+                    start: pos,
+                    end: i + 1,
+                    length: this._lens[id],
+                    id,
+                    payload: this._vals[id],
+                });
+            }
+        }
+        return out;
+    }
+    /**
+     * Every occurrence of every pattern anywhere in `seq` (eager form, the union
+     * of {@link matchesAt} over all start positions). O(seq · longest pattern),
+     * independent of how many patterns are stored. Use {@link matchesAt} when the
+     * search only needs the sites at a particular position.
+     */
+    scan(seq) {
+        const out = [];
+        for (let pos = 0, n = seq.length; pos < n; pos++) {
+            let s = ROOT;
+            for (let i = pos; i < n; i++) {
+                s = this._follow(s, seq[i]);
+                if (s === -1)
+                    break;
+                const id = this._end[s];
+                if (id !== -1) {
+                    out.push({
+                        start: pos,
+                        end: i + 1,
+                        length: this._lens[id],
+                        id,
+                        payload: this._vals[id],
+                    });
+                }
+            }
+        }
+        return out;
+    }
+}

package/dist/src/derive/test/derive.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/derive/test/derive.test.js

@@ -0,0 +1,122 @@
+// Self-contained tests for the `derive` library: the lightest-derivation
+// engine (including a multi-premise *bridge* rule), the on-demand trie matcher,
+// and the optimal cover. Uses node:test; no dependency on sema.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { coverSequence, lightestDerivation, Trie, } from "../src/index.js";
+// ── trie: on-demand matching, no length bound ──────────────────────────────
+test("trie matchesAt reports forms beginning exactly at a position", () => {
+    const t = new Trie();
+    t.insert([1, 2], "ab");
+    t.insert([1, 2, 3], "abc");
+    t.insert([2, 3], "bc");
+    const at0 = t.matchesAt([1, 2, 3, 4], 0).map((m) => m.payload);
+    assert.deepEqual(at0, ["ab", "abc"]); // both forms starting at 0, shortest first
+    const at1 = t.matchesAt([1, 2, 3, 4], 1).map((m) => m.payload);
+    assert.deepEqual(at1, ["bc"]);
+    const at3 = t.matchesAt([1, 2, 3, 4], 3).map((m) => m.payload);
+    assert.deepEqual(at3, []); // nothing learned here → dead-ends immediately
+});
+test("trie scan finds every occurrence; duplicate inserts share an id", () => {
+    const t = new Trie();
+    const id1 = t.insert([7, 7], 1);
+    const id2 = t.insert([7, 7], 2); // same content
+    assert.equal(id1, id2);
+    assert.equal(t.size, 1);
+    const hits = t.scan([7, 7, 7]);
+    assert.equal(hits.length, 2); // [0,2) and [1,3)
+});
+// ── engine: Dijkstra/Knuth core with a bridge (multi-premise) rule ─────────
+test("lightestDerivation solves a hypergraph with a bridge premise", () => {
+    // Items: "A", "B", "AB". Axioms A (3) and B (4). A binary bridge A ∧ B → AB
+    // at cost 1. The only derivation of AB costs 3 + 4 + 1 = 8.
+    const A = "A", B = "B", AB = "AB";
+    const system = {
+        key: (s) => s,
+        axioms: () => [{ item: A, cost: 3 }, { item: B, cost: 4 }],
+        isGoal: (s) => s === AB,
+        *rules(item) {
+            // Bridge fires from either premise; the engine waits until 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 d = lightestDerivation(system);
+    assert.ok(d);
+    assert.equal(d.item, AB);
+    assert.equal(d.cost, 8);
+    assert.equal(d.premises.length, 2); // it really used the bridge
+});
+test("lightestDerivation picks the cheaper of competing derivations", () => {
+    // Two ways to reach the goal G from axiom S: S→G cost 10, or S→M→G cost 3+3.
+    const system = {
+        key: (s) => s,
+        axioms: () => [{ item: "S", cost: 0 }],
+        isGoal: (s) => s === "G",
+        *rules(item) {
+            if (item === "S") {
+                yield { premises: ["S"], conclusion: "G", cost: 10 };
+                yield { premises: ["S"], conclusion: "M", cost: 3 };
+            }
+            if (item === "M")
+                yield { premises: ["M"], conclusion: "G", cost: 3 };
+        },
+    };
+    const d = lightestDerivation(system);
+    assert.ok(d);
+    assert.equal(d.cost, 6); // via M, not the direct 10
+    assert.equal(d.rule?.premises[0], "M");
+});
+test("lightestDerivation returns null when the goal is unreachable", () => {
+    const system = {
+        key: (n) => "" + n,
+        axioms: () => [{ item: 0, cost: 0 }],
+        isGoal: (n) => n === 99,
+        *rules(n) {
+            if (n < 3)
+                yield { premises: [n], conclusion: n + 1, cost: 1 };
+        },
+    };
+    assert.equal(lightestDerivation(system), null);
+});
+// ── cover: optimal, not greedy ─────────────────────────────────────────────
+test("coverSequence maximises coverage, beating greedy longest-match", () => {
+    // Over [0,4): one long span [1,4) (len 3) vs two short [0,2),[2,4) (cover 4).
+    // Greedy-longest takes [1,4) and covers 3; the optimal cover takes the pair.
+    const cover = coverSequence(4, [
+        { start: 1, end: 4, payload: "long" },
+        { start: 0, end: 2, payload: "left" },
+        { start: 2, end: 4, payload: "right" },
+    ]);
+    assert.equal(cover.covered, 4);
+    assert.equal(cover.uncovered, 0);
+    assert.deepEqual(cover.spans.map((s) => s.payload), ["left", "right"]);
+});
+test("coverSequence prefers fewer, longer spans on ties (unit weight)", () => {
+    // [0,3) covers the same as [0,1)+[1,3) but in one span → preferred.
+    const cover = coverSequence(3, [
+        { start: 0, end: 3, payload: "whole" },
+        { start: 0, end: 1, payload: "a" },
+        { start: 1, end: 3, payload: "b" },
+    ]);
+    assert.deepEqual(cover.spans.map((s) => s.payload), ["whole"]);
+});
+test("coverSequence leaves genuinely uncovered gaps uncovered", () => {
+    const cover = coverSequence(10, [
+        { start: 0, end: 3, payload: "x" },
+        { start: 6, end: 9, payload: "y" },
+    ]);
+    assert.equal(cover.covered, 6);
+    assert.equal(cover.uncovered, 4);
+    assert.deepEqual(cover.spans.map((s) => s.payload), ["x", "y"]);
+});
+test("coverSequence honours weights when coverage ties", () => {
+    // Both single-span covers cover all 2 symbols; the lighter weight wins.
+    const cover = coverSequence(2, [
+        { start: 0, end: 2, weight: 5, payload: "heavy" },
+        { start: 0, end: 2, weight: 1, payload: "light" },
+    ]);
+    assert.deepEqual(cover.spans.map((s) => s.payload), ["light"]);
+});