@hviana/sema 0.1.0

package/src/derive/src/deduction.ts

@@ -0,0 +1,263 @@
+/**
+ * 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";
+
+/**
+ * A weighted deduction rule (a hyperedge): the conjunction of `premises`
+ * derives `conclusion` at an additional `cost`.
+ */
+export interface Rule<I> {
+  premises: readonly I[];
+  conclusion: I;
+  /** Local (edge) cost added on top of the premises' costs. Non-negative. */
+  cost: number;
+  /** The combinator this rule's firing uses at its conclusion:
+   *   • `"min"` (default, omitted) — Knuth/A* proper: the conclusion's cost is
+   *     the CHEAPEST of any rule that reaches it, every other route discarded.
+   *     The shortest-path monoid (min, +) that makes the search admissible and
+   *     output-sensitive.
+   *   • `"sum"` — evidence pooling: EVERY firing of a sum rule contributes its
+   *     cost to the SAME conclusion (accumulated in {@link
+   *     DeductionSystem.pool}), instead of competing to be the one cheapest
+   *     route.  The (+, +) monoid a consensus vote needs — several
+   *     independent premises corroborating one conclusion — kept deliberately
+   *     OUT of the min-cost chart: a pooled conclusion is never relaxed into
+   *     `g`, never enters the agenda, and is never itself a premise — it is a
+   *     terminal aggregate the caller reads out of `pool` once the search is
+   *     done. */
+  combine?: "min" | "sum";
+}
+
+/** One rule's contribution to a pooled (`combine: "sum"`) conclusion — the
+ *  firing rule and the already-finalised derivations of its premises, so a
+ *  caller can render each contribution exactly as it would a min-cost step. */
+export interface PooledContribution<I> {
+  rule: Rule<I>;
+  premises: Array<Derivation<I>>;
+}
+
+/** The running aggregate at one pooled conclusion: every sum-mode rule that
+ *  has fired for it, accumulated. */
+export interface PooledConclusion<I> {
+  item: I;
+  cost: number;
+  contributions: Array<PooledContribution<I>>;
+}
+
+/** The problem the solver is given: items, rules, a goal, and a heuristic. */
+export interface DeductionSystem<I> {
+  /** Canonical key for chart memoization (the item's boundary signature). */
+  key(item: I): string;
+
+  /** Axioms: the atomic items and their base costs (the search's seeds). */
+  axioms(): Iterable<{ item: I; cost: number }>;
+
+  /**
+   * Lazily generate the demanded rules that have `item` among their premises.
+   * Called once, when `item` is finalised. `costOf` returns the finalised cost
+   * of any item (Infinity if not yet known) — use it for backward-demand /
+   * boundary filtering, e.g. drop a rule whose other premises are still open or
+   * whose conclusion can no longer beat the best 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;
+
+  /** Admissible, consistent lower bound on the cost from `item` to a goal. */
+  heuristic?(item: I): number;
+
+  /** Present only on a system that fires `combine: "sum"` rules — supplied
+   *  empty, populated in place as the search runs, read back once it returns
+   *  (typically `null`: a pooling system has no goal to reach, it exhausts its
+   *  axioms instead — see {@link lightestDerivation}).  Absent on every
+   *  ordinary min-cost system, which is what keeps pooling a zero-cost opt-in:
+   *  `relax` only takes the pooling branch when a rule declares `combine:
+   *  "sum"` AND this map is present. */
+  pool?: Map<string, PooledConclusion<I>>;
+}
+
+/** A node of the reconstructed derivation tree. */
+export interface Derivation<I> {
+  /** The derived item. */
+  item: I;
+  /** This item's minimum derivation cost (its g value). */
+  cost: number;
+  /** The rule that produced it, or null if it is an axiom. */
+  rule: Rule<I> | null;
+  /** Derivations of the rule's premises (empty for an axiom). */
+  premises: Array<Derivation<I>>;
+}
+
+/**
+ * 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<I>(
+  system: DeductionSystem<I>,
+): Derivation<I> | null {
+  const g = new Map<string, number>(); // best known cost per item
+  const proof = new Map<string, Rule<I> | null>(); // producing rule per item
+  const items = new Map<string, I>(); // key → the item it stands for
+  const hCache = new Map<string, number>();
+  const agenda = new MinHeap<{ key: string; g: number }>();
+
+  const heuristic = system.heuristic;
+  const h = (item: I, key: string): number => {
+    if (!heuristic) return 0;
+    let v = hCache.get(key);
+    if (v === undefined) {
+      v = heuristic(item);
+      hCache.set(key, v);
+    }
+    return v;
+  };
+
+  const costOf = (item: I): number => g.get(system.key(item)) ?? Infinity;
+
+  const relax = (item: I, cost: number, rule: Rule<I> | null): void => {
+    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);
+      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() as { value: { key: string; g: number } };
+    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) as I;
+    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<I>(
+  item: I,
+  system: DeductionSystem<I>,
+  g: Map<string, number>,
+  proof: Map<string, Rule<I> | null>,
+): Derivation<I> {
+  // 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<string, Derivation<I>>();
+  const stack: I[] = [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) as number,
+        rule,
+        premises: kids,
+      });
+    }
+  }
+
+  return done.get(system.key(item))!;
+}

package/src/derive/src/index.ts

@@ -0,0 +1,24 @@
+// 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 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/src/derive/src/priority-queue.ts

@@ -0,0 +1,70 @@
+/**
+ * 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<T> {
+  private readonly keys: number[] = [];
+  private readonly vals: T[] = [];
+
+  get size(): number {
+    return this.keys.length;
+  }
+
+  push(priority: number, value: T): void {
+    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(): { priority: number; value: T } | undefined {
+    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() as number;
+    const lastVal = vals.pop() as T;
+    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/src/derive/src/rewrite.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 { type DeductionSystem, lightestDerivation } from "./deduction.js";
+
+/** 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 function coverSequence<P>(
+  length: number,
+  candidates: ReadonlyArray<CandidateSpan<P>>,
+): Cover<P> {
+  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<Array<CandidateSpan<P>>> = Array.from(
+    { length },
+    () => [],
+  );
+  const byEdge = new Map<number, CandidateSpan<P>>();
+  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: DeductionSystem<number> = {
+    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: Array<CandidateSpan<P>> = [];
+  let node: typeof best | undefined = 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 };
+}