@hviana/sema 0.5.2 → 0.5.4

package/dist/src/bytes.d.ts

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

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

@@ -1,45 +0,0 @@
-/** 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;
-/** The span of `bytes` between its first and last non-whitespace byte — the
- *  QUESTION, with the caller's edge spacing dropped.  Returns a subarray (no
- *  copy), and the original when there is nothing to trim.
- *
- *  THIS LIVES HERE, not in the core byte utilities, for the reason stated at
- *  the top of this file: "nothing in the store or the mind's core knows what
- *  'case' or 'whitespace' is".  Edge spacing is a TEXT fact — for a binary or
- *  grid modality 0x20 is content, not presentation — so it belongs beside the
- *  text canonicalizer, is injected on the same modality test, and never leaks
- *  into a mechanism.  A modality that supplies its own canon supplies its own
- *  reading of "edge" too, or none.
- *
- *  Why trimming is sound HERE when {@link textCanon} deliberately refuses it:
- *  canon preserves edge whitespace because the hazard is a recognised SUB-span
- *  swallowing the boundary byte that separates it from its neighbour (observed:
- *  "ice " matching the stored "ice").  At the outer edges of a WHOLE input
- *  there is no neighbour — nothing precedes byte 0, nothing follows the last
- *  byte — so that hazard cannot arise, and only there. */
-export declare function textEdgeTrim(bytes: Uint8Array): Uint8Array;

package/dist/src/canon.js

@@ -1,85 +0,0 @@
-// 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;
-}
-/** The span of `bytes` between its first and last non-whitespace byte — the
- *  QUESTION, with the caller's edge spacing dropped.  Returns a subarray (no
- *  copy), and the original when there is nothing to trim.
- *
- *  THIS LIVES HERE, not in the core byte utilities, for the reason stated at
- *  the top of this file: "nothing in the store or the mind's core knows what
- *  'case' or 'whitespace' is".  Edge spacing is a TEXT fact — for a binary or
- *  grid modality 0x20 is content, not presentation — so it belongs beside the
- *  text canonicalizer, is injected on the same modality test, and never leaks
- *  into a mechanism.  A modality that supplies its own canon supplies its own
- *  reading of "edge" too, or none.
- *
- *  Why trimming is sound HERE when {@link textCanon} deliberately refuses it:
- *  canon preserves edge whitespace because the hazard is a recognised SUB-span
- *  swallowing the boundary byte that separates it from its neighbour (observed:
- *  "ice " matching the stored "ice").  At the outer edges of a WHOLE input
- *  there is no neighbour — nothing precedes byte 0, nothing follows the last
- *  byte — so that hazard cannot arise, and only there. */
-export function textEdgeTrim(bytes) {
-    const space = (b) => b === 0x20 || b === 0x09 || b === 0x0a || b === 0x0d;
-    let from = 0;
-    let to = bytes.length;
-    while (from < to && space(bytes[from]))
-        from++;
-    while (to > from && space(bytes[to - 1]))
-        to--;
-    return from === 0 && to === bytes.length ? bytes : bytes.subarray(from, to);
-}

package/dist/src/config.d.ts

@@ -1,111 +0,0 @@
-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

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

@@ -1,136 +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.
- */
-/**
- * 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>>;
-}
-/** Optional search-effort read-out, filled in place while the search runs.
- *  A plain structural record so the sublibrary stays firewalled (it imports
- *  nothing from Sema, and Sema copies these into its own accounting).  Purely
- *  observational: the search never reads it back. */
-export interface SearchStats {
-    /** Agenda entries popped, stale lazy-deletion entries included — the chart
-     *  work actually done. */
-    pops: number;
-    /** Agenda entries pushed by a successful relaxation. */
-    pushes: number;
-}
-/**
- * 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>, stats?: SearchStats): Derivation<I> | null;