@hviana/sema 0.2.6 → 0.2.8

package/dist/src/bytes.d.ts

@@ -0,0 +1,14 @@
+/** True when two byte spans are equal in length and content. */
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+/** Concatenate byte arrays. Takes an array rather than rest params so
+ *  a large segment list can never overflow the call stack via spread. */
+export declare function concatBytes(parts: Uint8Array[]): Uint8Array;
+/** 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 declare function concat2(a: Uint8Array, b: Uint8Array): Uint8Array;
+/** 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 declare function latin1(b: Uint8Array): string;
+/** 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 declare function indexOf(hay: Uint8Array, needle: Uint8Array, from: number): number;

package/dist/src/bytes.js

@@ -0,0 +1,59 @@
+// 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, b) {
+    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) {
+    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, b) {
+    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) {
+    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, needle, from) {
+    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/dist/src/canon.d.ts

@@ -0,0 +1,26 @@
+/** A content canonicalizer: maps a byte span to the canonical representative
+ *  of its equivalence class.  Must be pure and deterministic.  Returning the
+ *  input unchanged is always sound (the class is then {input}). */
+export type Canon = (bytes: Uint8Array) => Uint8Array;
+/** The TEXT canonicalizer: Unicode-aware equivalence over every character
+ *  variation that does not change what the text SAYS —
+ *
+ *   • compatibility normalization (NFKC): full-width forms, ligatures,
+ *     composed vs decomposed accents collapse to one representation;
+ *   • case folding (locale-independent lowercase after NFKC — the standard
+ *     simple fold);
+ *   • whitespace: every INTERIOR run of Unicode whitespace becomes one plain
+ *     space.  EDGE whitespace is preserved verbatim: a span's leading or
+ *     trailing separator belongs BETWEEN forms, not to the form — trimming
+ *     it would let a recognised span swallow the boundary byte that
+ *     separates it from its neighbour (observed: "ice fire" composing to
+ *     "coldhot" because the span "ice " matched the stored "ice").
+ *
+ *  "WHAT  IS", "What is" and "ｗｈａｔ is" share one canonical form.  This is
+ *  deliberately conservative: punctuation, digits and word order are content
+ *  and pass through untouched. */
+export declare function textCanon(bytes: Uint8Array): Uint8Array;
+/** 32-bit FNV-1a over a canonical key — the integer the store's canon index
+ *  is keyed on.  Same construction as the node table's content hash; a
+ *  collision is resolved by verifying canon(stored) === key, never trusted. */
+export declare function canonHash(key: Uint8Array): number;

package/dist/src/canon.js

@@ -0,0 +1,57 @@
+// canon.ts — content canonicalization for equivalence-class resolution.
+//
+// The store is content-addressed on RAW bytes: "What", "WHAT" and "what" are
+// three different hashes, so a query whose surface form varies from the
+// trained form resolves to nothing even though the CONTENT is the same.  A
+// CANONICALIZER maps every surface variant of the same content onto one
+// canonical byte string; the store keeps a small hash index from canonical
+// keys to node ids (see Store.canonAdd/canonFind), and resolution falls back
+// to that index when the exact content-addressed lookup misses.
+//
+// The canonicalizer is MODALITY-SPECIFIC and always INJECTED — nothing in the
+// store or the mind's core knows what "case" or "whitespace" is.  The text
+// canonicalizer below is the one `respondText`/`respondTurnText` pass down;
+// a grid or audio modality would supply its own (or none).
+//
+// Canonical keys are equivalence-class LABELS, never content: they are hashed
+// and verified (canon(stored bytes) must equal canon(query bytes) before an
+// id is accepted), so a hash collision costs a read, never a wrong id — the
+// same discipline as the node table's own `h` index.
+const dec = new TextDecoder("utf-8", { fatal: false });
+const enc = new TextEncoder();
+/** The TEXT canonicalizer: Unicode-aware equivalence over every character
+ *  variation that does not change what the text SAYS —
+ *
+ *   • compatibility normalization (NFKC): full-width forms, ligatures,
+ *     composed vs decomposed accents collapse to one representation;
+ *   • case folding (locale-independent lowercase after NFKC — the standard
+ *     simple fold);
+ *   • whitespace: every INTERIOR run of Unicode whitespace becomes one plain
+ *     space.  EDGE whitespace is preserved verbatim: a span's leading or
+ *     trailing separator belongs BETWEEN forms, not to the form — trimming
+ *     it would let a recognised span swallow the boundary byte that
+ *     separates it from its neighbour (observed: "ice fire" composing to
+ *     "coldhot" because the span "ice " matched the stored "ice").
+ *
+ *  "WHAT  IS", "What is" and "ｗｈａｔ is" share one canonical form.  This is
+ *  deliberately conservative: punctuation, digits and word order are content
+ *  and pass through untouched. */
+export function textCanon(bytes) {
+    const s = dec
+        .decode(bytes)
+        .normalize("NFKC")
+        .toLowerCase()
+        .replace(/(\S)\s+(?=\S)/g, "$1 ");
+    return enc.encode(s);
+}
+/** 32-bit FNV-1a over a canonical key — the integer the store's canon index
+ *  is keyed on.  Same construction as the node table's content hash; a
+ *  collision is resolved by verifying canon(stored) === key, never trusted. */
+export function canonHash(key) {
+    let h = 0x811c9dc5 >>> 0;
+    for (let i = 0; i < key.length; i++) {
+        h ^= key[i];
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h >>> 0;
+}

package/dist/src/config.d.ts

@@ -0,0 +1,111 @@
+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;
+    /** Query breadth of the IVF vector indices: clusters probed per query =
+     *  ceil(efSearch / 4).  Inserts have no quality knob — the partitioned
+     *  index routes and appends, so ingestion cost is flat by construction. */
+    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 vector-index 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-ivf` `VectorDatabase`'s memory budget
+     *  (forwarded as its `cacheSizeMb` — its SQLite page cache).  A PURE latency
+     *  optimisation — the index reads chunk blobs from SQLite on demand, so its
+     *  correctness and its 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;
+    /** Size, in MiB, of the MAIN DAG database's SQLite page cache.  The node /
+     *  kid / edge / contain tables serve millions of point probes per training
+     *  session (content-addressed findLeaf/findBranch, parent probes, contain
+     *  appends); SQLite's default cache (~2 MiB) thrashes once the DB outgrows
+     *  it, so every probe pays a file read.  A PURE latency knob — correctness
+     *  and result identical at any value. */
+    sqliteCacheMb: 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;
+}
+export interface MindConfig {
+    seed: number;
+    recallQueryK: number;
+    haloQueryK: number;
+    normalizeEpsilon: number;
+    cosineEpsilon: number;
+    alu: AluConfig;
+    geometry: GeometryConfig;
+    alphabet: AlphabetConfig;
+    store: StoreConfig;
+}
+export declare const DEFAULT_CONFIG: MindConfig;
+export declare function resolveConfig(opts?: Partial<MindConfig>): MindConfig;

package/dist/src/config.js

@@ -0,0 +1,91 @@
+// config.ts — the single configuration interface for Sema.
+// Every tunable parameter lives here. Subsystems receive their subset.
+// ── Defaults ──
+export const DEFAULT_CONFIG = {
+    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,
+        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,
+        sqliteCacheMb: 64,
+        coveredIdsMax: 100_000,
+        chainCacheBytes: 16_000_000,
+    },
+};
+// ── Config resolver: partial input + defaults = full config ──
+export function resolveConfig(opts = {}) {
+    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,
+            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,
+            sqliteCacheMb: opts.store?.sqliteCacheMb ??
+                DEFAULT_CONFIG.store.sqliteCacheMb,
+            coveredIdsMax: opts.store?.coveredIdsMax ??
+                DEFAULT_CONFIG.store.coveredIdsMax,
+            chainCacheBytes: opts.store?.chainCacheBytes ??
+                DEFAULT_CONFIG.store.chainCacheBytes,
+        },
+    };
+}

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

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function lightestDerivation<I>(system: DeductionSystem<I>): Derivation<I> | null;

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

@@ -0,0 +1,155 @@
+/**
+ * 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) {
+    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);
+            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();
+        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

@@ -0,0 +1,7 @@
+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/dist/src/derive/src/index.js

@@ -0,0 +1,11 @@
+// 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";