@hviana/sema 0.5.2 → 0.5.4

package/dist/src/derive/src/deduction.js

@@ -1,159 +0,0 @@
-/**
- * Knuth's lightest-derivation algorithm with an A* outside bound.
- *
- * A *weighted deduction system* (equivalently an implicit AND-OR hypergraph) is
- * a set of items combined by inference rules
- *
- *     premise₁ ∧ … ∧ premiseₖ  --localCost-->  conclusion
- *
- * where a derivation's cost is the sum of the local costs of the rules used.
- * {@link lightestDerivation} finds a minimum-cost derivation of a goal item.
- * The engine is the Dijkstra-like core of Knuth (1977) — an item's cost is
- * final the moment it is popped — extended with an admissible heuristic so that
- * partial derivations which cannot lead cheaply to the goal are never expanded
- * (A* parsing). It is completely generic: it knows nothing of what items are,
- * only how to canonicalise them, enumerate their rules, score them, and test
- * the goal.
- *
- * The four reductions the search relies on:
- *   1. **Canonical chart memoization** — items are keyed by {@link
- *      DeductionSystem.key}; equivalent partial derivations collapse to one
- *      chart entry, the cheapest.
- *   2. **Backward demand filtering** — {@link DeductionSystem.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** — {@link DeductionSystem.heuristic} keeps the
- *      agenda ordered by g + h, so only competitive items are expanded.
- *   4. **Lazy hyperedge generation** — rules (including bridges) are produced by
- *      `rules` only when one of their premises is finalised, never up front.
- *
- * Correctness conditions (the caller must uphold these):
- *   - Local costs are non-negative (more generally, monotone / superior).
- *   - The heuristic never overestimates the remaining cost to a goal
- *     (admissible) and is hyperedge-consistent:
- *         h(conclusion) ≤ ruleCost + Σ h(premiseᵢ)
- *     i.e. relaxing a rule cannot decrease f. The default heuristic (0) is
- *     trivially consistent and turns the search into plain Knuth/Dijkstra.
- *   - {@link DeductionSystem.key} preserves every part of an item that can
- *     affect how it later combines (its "boundary signature"); anything the key
- *     drops is asserted to be irrelevant to future composition.
- */
-import { MinHeap } from "./priority-queue.js";
-/**
- * Find a lightest derivation of a goal item, or `null` if none exists.
- * `cost` on the returned root is the total derivation cost.
- */
-export function lightestDerivation(system, stats) {
-    const g = new Map(); // best known cost per item
-    const proof = new Map(); // producing rule per item
-    const items = new Map(); // key → the item it stands for
-    const hCache = new Map();
-    const agenda = new MinHeap();
-    const heuristic = system.heuristic;
-    const h = (item, key) => {
-        if (!heuristic)
-            return 0;
-        let v = hCache.get(key);
-        if (v === undefined) {
-            v = heuristic(item);
-            hCache.set(key, v);
-        }
-        return v;
-    };
-    const costOf = (item) => g.get(system.key(item)) ?? Infinity;
-    const relax = (item, cost, rule) => {
-        const key = system.key(item);
-        if (rule?.combine === "sum" && system.pool) {
-            // Evidence pooling: accumulate this firing rather than compete for the
-            // cheapest — see {@link Rule.combine}.  The premises are already
-            // finalised (the caller only relaxes a rule once every premise's cost
-            // is known), so their derivations can be read back immediately.
-            const premises = rule.premises.map((p) => reconstruct(p, system, g, proof));
-            const prior = system.pool.get(key);
-            system.pool.set(key, {
-                item,
-                cost: (prior?.cost ?? 0) + cost,
-                contributions: [...(prior?.contributions ?? []), { rule, premises }],
-            });
-            return;
-        }
-        const current = g.get(key);
-        if (current === undefined || cost < current) {
-            g.set(key, cost);
-            proof.set(key, rule);
-            items.set(key, item);
-            if (stats)
-                stats.pushes++;
-            agenda.push(cost + h(item, key), { key, g: cost });
-        }
-    };
-    for (const { item, cost } of system.axioms())
-        relax(item, cost, null);
-    while (agenda.size > 0) {
-        const { value } = agenda.pop();
-        if (stats)
-            stats.pops++;
-        const key = value.key;
-        // Lazy deletion: an entry is stale if a cheaper derivation has since been
-        // recorded for the same item.
-        if (value.g !== g.get(key))
-            continue;
-        const item = items.get(key);
-        if (system.isGoal(item)) {
-            return reconstruct(item, system, g, proof);
-        }
-        for (const rule of system.rules(item, costOf)) {
-            let sum = rule.cost;
-            let ready = true;
-            for (const p of rule.premises) {
-                const pc = g.get(system.key(p));
-                if (pc === undefined) {
-                    ready = false;
-                    break;
-                }
-                sum += pc;
-            }
-            if (ready)
-                relax(rule.conclusion, sum, rule);
-        }
-    }
-    return null;
-}
-function reconstruct(item, system, g, proof) {
-    // Iterative post-order over the derivation hypergraph.  In the rewrite
-    // search every rule has one premise, so the derivation is a chain whose
-    // length equals the number of frontier edges — which, with long inputs,
-    // can exceed the call stack.  Multi-premise rules (the test-suite bridge
-    // case) are handled by the same explicit stack.
-    const done = new Map();
-    const stack = [item];
-    while (stack.length > 0) {
-        const cur = stack[stack.length - 1]; // peek
-        const key = system.key(cur);
-        if (done.has(key)) {
-            stack.pop();
-            continue;
-        }
-        const rule = proof.get(key) ?? null;
-        const premises = rule?.premises ?? [];
-        // Push any unresolved premises (rightmost first → leftmost resolves first).
-        let pending = false;
-        for (let i = premises.length - 1; i >= 0; i--) {
-            if (!done.has(system.key(premises[i]))) {
-                stack.push(premises[i]);
-                pending = true;
-            }
-        }
-        if (!pending) {
-            stack.pop(); // this item
-            const kids = premises.map((p) => done.get(system.key(p)));
-            done.set(key, {
-                item: cur,
-                cost: g.get(key),
-                rule,
-                premises: kids,
-            });
-        }
-    }
-    return done.get(system.key(item));
-}

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

@@ -1,8 +0,0 @@
-export { lightestDerivation } from "./deduction.js";
-export type { SearchStats } from "./deduction.js";
-export type { DeductionSystem, Derivation, PooledConclusion, PooledContribution, Rule, } from "./deduction.js";
-export { coverSequence } from "./rewrite.js";
-export type { CandidateSpan, Cover } from "./rewrite.js";
-export { Trie } from "./trie.js";
-export type { Match } from "./trie.js";
-export { MinHeap } from "./priority-queue.js";

package/dist/src/derive/src/index.js

@@ -1,11 +0,0 @@
-// derive — A* lightest-derivation rewrite search.
-//
-// A small, self-contained library for finding minimum-cost derivations in a
-// weighted deduction system (an implicit AND-OR hypergraph), with on-demand
-// (lazy) rule generation and an admissible A* outside bound. It has no
-// dependency on the rest of the codebase and is reusable for any
-// symbolic-rewriting mechanism. See ./../README.md for the design.
-export { lightestDerivation } from "./deduction.js";
-export { coverSequence } from "./rewrite.js";
-export { Trie } from "./trie.js";
-export { MinHeap } from "./priority-queue.js";

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

@@ -1,20 +0,0 @@
-/**
- * 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

@@ -1,73 +0,0 @@
-/**
- * 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

@@ -1,56 +0,0 @@
-/**
- * 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

@@ -1,100 +0,0 @@
-/**
- * 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

@@ -1,90 +0,0 @@
-/**
- * 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>>;
-}