@metta-ts/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,632 @@
+type IntVal = number | bigint;
+/** A bigint that fits the safe-integer range collapses to a number; everything else stays bigint. */
+declare function canonInt(n: IntVal): IntVal;
+declare function addInt(x: IntVal, y: IntVal): IntVal;
+declare function subInt(x: IntVal, y: IntVal): IntVal;
+declare function mulInt(x: IntVal, y: IntVal): IntVal;
+/** Integer division truncating toward zero (matches the existing `Math.trunc(a/b)` semantics). */
+declare function intDiv(x: IntVal, y: IntVal): IntVal;
+declare function intMod(x: IntVal, y: IntVal): IntVal;
+declare function intAbs(n: IntVal): IntVal;
+declare function isZero(n: IntVal): boolean;
+/** Coerce either representation to a double for the f64 math ops (precision loss is acceptable there). */
+declare function toF64(n: IntVal): number;
+/** Three-way compare of two integer values, exact (promotes to bigint when needed). Value-level
+ *  analogue of `compareNumbers`, used by the deterministic-core compiler on unwrapped ints. */
+declare function cmpIntVal(a: IntVal, b: IntVal): number;
+
+/**
+ * The MeTTa term model. A discriminated union on `kind` (convention C1).
+ * Every variant declares ALL seven fields in the SAME order so V8 keeps one
+ * hidden class across atoms (monomorphic property access on the hot path).
+ * Unused fields are `undefined`, never absent, never deleted (C1).
+ */
+type MetaType = "Symbol" | "Variable" | "Expression" | "Grounded";
+interface SymAtom {
+    readonly kind: "sym";
+    readonly name: string;
+    readonly items: undefined;
+    readonly value: undefined;
+    readonly typ: undefined;
+    readonly exec: undefined;
+    readonly match: undefined;
+    readonly ground: true;
+}
+interface VarAtom {
+    readonly kind: "var";
+    readonly name: string;
+    readonly items: undefined;
+    readonly value: undefined;
+    readonly typ: undefined;
+    readonly exec: undefined;
+    readonly match: undefined;
+    readonly ground: false;
+}
+interface ExprAtom {
+    readonly kind: "expr";
+    readonly name: undefined;
+    readonly items: readonly Atom[];
+    readonly value: undefined;
+    readonly typ: undefined;
+    readonly exec: undefined;
+    readonly match: undefined;
+    /** True iff no variable occurs anywhere inside (a precomputed ground flag): lets `applySubst`,
+     *  `atomVars`, and `occurs` short-circuit instantly on closed terms. Computed once at construction. */
+    readonly ground: boolean;
+}
+/** A grounded value (LeaTTa `Ground`). Numbers track int vs float so `3` and `3.0` stay distinct. */
+type Ground = {
+    readonly g: "int";
+    readonly n: number | bigint;
+} | {
+    readonly g: "float";
+    readonly n: number;
+} | {
+    readonly g: "str";
+    readonly s: string;
+} | {
+    readonly g: "bool";
+    readonly b: boolean;
+} | {
+    readonly g: "unit";
+} | {
+    readonly g: "error";
+    readonly msg: string;
+} | {
+    readonly g: "ext";
+    readonly kind: string;
+    readonly id: string;
+};
+/** A grounded atom: a structured `Ground` value with a derived type atom, plus optional executor
+ *  and custom matcher (used by DAS-style grounded atoms; core built-in ops dispatch by symbol). */
+interface GndAtom {
+    readonly kind: "gnd";
+    readonly name: undefined;
+    readonly items: undefined;
+    readonly value: Ground;
+    readonly typ: Atom;
+    readonly exec: GroundedExec | undefined;
+    readonly match: GroundedMatch | undefined;
+    readonly ground: true;
+}
+type Atom = SymAtom | VarAtom | ExprAtom | GndAtom;
+/** A grounded atom's executor: applied when the atom heads an expression `(<gnd> arg...)`. Receives
+ *  the evaluated argument atoms and returns the result atoms. May throw to signal a runtime error. */
+type GroundedExec = (args: readonly Atom[]) => readonly Atom[];
+type GroundedMatch = (other: Atom) => readonly unknown[];
+/** Structural equality of grounded values (LeaTTa `Ground.BEq`). */
+declare function groundEq(a: Ground, b: Ground): boolean;
+/** Interned symbol atom: equal names share one object (reference equality, low allocation). */
+declare function sym(name: string): SymAtom;
+/** Variable atom. Not interned: freshening needs distinct identities. */
+declare function variable(name: string): VarAtom;
+declare function expr(items: readonly Atom[]): ExprAtom;
+/** The built-in type atom for a grounded value (LeaTTa `getTypes` on grounded). */
+declare function groundType(v: Ground): Atom;
+declare function gnd(value: Ground, typ?: Atom, exec?: GroundedExec, match?: GroundedMatch): GndAtom;
+/** Grounded literal constructors. */
+declare const gint: (n: IntVal) => GndAtom;
+declare const gfloat: (n: number) => GndAtom;
+declare const gstr: (s: string) => GndAtom;
+declare const gbool: (b: boolean) => GndAtom;
+declare const gunit: GndAtom;
+declare function metaType(a: Atom): MetaType;
+/** A 32-bit structural hash: equal structures hash equal. O(1) amortised for a fresh atom whose subterms
+ *  are already hashed. Collisions are possible, so callers verify a match with `atomEq`. */
+declare function hashOf(a: Atom): number;
+/** Total term size (LeaTTa `Atom.size`): leaves are 1, an expression is 1 + sum of parts. */
+declare function atomSize(a: Atom): number;
+/** All variable names occurring in an atom (LeaTTa `Atom.vars`), in first-seen order, deduped. */
+declare function atomVars(a: Atom, out?: string[]): string[];
+/** Collect an atom's variable names into `out`, deduping via the shared `seen` set (O(1) membership instead
+ *  of a linear `out.includes`). Hot accumulation loops (scopeVars/frameVars) reuse one `seen` across many
+ *  atoms so the whole walk stays linear; `atomVars` is the one-shot wrapper that seeds `seen` from `out`. */
+declare function collectVars(a: Atom, out: string[], seen: Set<string>): void;
+/** The empty expression `()` (LeaTTa `Atom.empty`), the success marker used by `assert*`. */
+declare const emptyExpr: ExprAtom;
+/** Is this atom an `(Error ...)` expression? */
+declare function isErrorAtom(a: Atom): boolean;
+declare const isExpr: (a: Atom) => a is ExprAtom;
+declare const isVar: (a: Atom) => a is VarAtom;
+declare const isSym: (a: Atom) => a is SymAtom;
+declare const isGnd: (a: Atom) => a is GndAtom;
+/** Structural equality. Interned symbols short-circuit to reference identity. */
+declare function atomEq(a: Atom, b: Atom): boolean;
+
+interface ValRel {
+    readonly tag: "val";
+    readonly x: string;
+    readonly a: Atom;
+    readonly y: undefined;
+}
+interface EqRel {
+    readonly tag: "eq";
+    readonly x: string;
+    readonly a: undefined;
+    readonly y: string;
+}
+type BindingRel = ValRel | EqRel;
+type Bindings = readonly BindingRel[];
+declare const emptyBindings: Bindings;
+/** The atom bound to `$x` by a direct `val` relation, if any (eq aliases are not followed). */
+declare function lookupVal(b: Bindings, x: string): Atom | undefined;
+/** Remove direct value bindings for `x`; equality relations remain. */
+declare function removeVal(b: Bindings, x: string): Bindings;
+/** True if the set contains a trivial self-loop (`$x ← $x` or `$x = $x`). */
+declare function hasLoop(b: Bindings): boolean;
+/** Bind `$x ← a`, dropping any previous value binding for `$x`. Raw: no consistency check. */
+declare function addValRaw(b: Bindings, x: string, a: Atom): Bindings;
+/** Add the alias `$x = $y` (a no-op when `x = y`). Raw: no consistency check. */
+declare function addEqRaw(b: Bindings, x: string, y: string): Bindings;
+
+interface Leaf<V> {
+    readonly kind: "leaf";
+    readonly key: string;
+    readonly val: V;
+}
+interface Collision<V> {
+    readonly kind: "collision";
+    readonly entries: ReadonlyArray<Leaf<V>>;
+}
+type Branch<V> = ReadonlyArray<PNode<V>>;
+type PNode<V> = Leaf<V> | Collision<V> | Branch<V> | null;
+/** A persistent string -> V map. `null` is the empty map. */
+type PMap<V> = Branch<V> | null;
+
+/** Distinct ground atoms sharing one 32-bit hash, each with its multiplicity in the log. */
+type Bucket = ReadonlyArray<{
+    readonly atom: Atom;
+    readonly count: number;
+}>;
+interface LogNode {
+    readonly atom: Atom;
+    readonly prev: AtomLog;
+    readonly size: number;
+    /** Exact-match index over the ground atoms in this log (and all earlier nodes). */
+    readonly groundIdx: PMap<Bucket>;
+    /** Count of non-ground atoms in this log; the index fast path is valid only when this is 0. */
+    readonly nonGround: number;
+}
+/** An atom log: `null` is empty; otherwise the most recently appended atom and the rest. */
+type AtomLog = LogNode | null;
+
+type ReduceResult = {
+    readonly tag: "ok";
+    readonly results: readonly Atom[];
+} | {
+    readonly tag: "runtimeError";
+    readonly msg: string;
+} | {
+    readonly tag: "incorrectArgument";
+    readonly msg: string;
+} | {
+    readonly tag: "noReduce";
+};
+type GroundFn = (args: readonly Atom[]) => ReduceResult;
+type GroundingTable = Map<string, GroundFn>;
+/** Replace the line-output sink used by `println!`/`trace!` (returns the previous sink). */
+declare function setOutputSink(fn: (line: string) => void): (line: string) => void;
+/** Replace the raw (no-newline) sink used by `print!` (returns the previous sink). */
+declare function setRawSink(fn: (text: string) => void): (text: string) => void;
+/** Names of the PeTTa-compat grounded ops. They yield to user `=` rules (PeTTa is rules-first, builtins as
+ *  fallback), so a program that defines its own e.g. `sort`/`length` is not shadowed by the stdlib one. */
+declare const pettaOpNames: ReadonlySet<string>;
+/** The arithmetic / boolean / list-surgery / math grounding core every KB starts with. */
+declare function baseTable(): GroundingTable;
+/** The full standard-library grounding table (base + stdlib grounded ops + PeTTa-compat). Later entries do
+ *  not override earlier ones (Map keeps the first), so Hyperon ops win any name shared with PeTTa-compat. */
+declare function stdTable(): GroundingTable;
+/** Dispatch `op` through the grounding table, or `noReduce` if unknown. */
+declare function callGrounded(gt: GroundingTable, op: string, args: readonly Atom[]): ReduceResult;
+
+/** Thrown by a compiled node when it meets a case it cannot handle faithfully (division by zero);
+ *  the caller catches it (along with a native stack `RangeError`) and re-runs the call in the
+ *  interpreter, which is sound because the compiled subset is side-effect-free. */
+declare const BAIL: unique symbol;
+declare class Tup {
+    readonly v: readonly IntVal[];
+    constructor(v: readonly IntVal[]);
+}
+type FrameVal = IntVal | Tup;
+type Ty = "int" | "bool" | `tuple${number}`;
+/** A compiled function. `run` is filled after the whole dependency group is compiled, so mutual
+ *  recursion resolves through the holder object. */
+interface CompiledHolder {
+    arity: number;
+    retType: Ty;
+    paramTypes: Ty[];
+    run: (vals: FrameVal[]) => FrameVal | boolean;
+}
+type CompiledFns = Map<string, CompiledHolder>;
+/** Compile every compilable pure single-clause function in `env` to a memoised native closure.
+ *  Phase 1 infers return types (fixpoint, optimistic over recursion). Phase 2 compiles bodies with
+ *  those types and drops any that fail end-to-end (a call to an uncompilable function fails too). */
+declare function compileEnv(env: MinEnv): CompiledFns;
+/** Run a compiled function for a ground-int call, returning the result atom, or `undefined` to fall
+ *  back to the interpreter (not compiled, non-int args, or a runtime bail). */
+declare function runCompiled(env: MinEnv, op: string, partAtoms: readonly Atom[]): Atom | undefined;
+
+/** A grounded operation that runs asynchronously, for the async runner. */
+type AsyncGroundFn = (args: readonly Atom[]) => Promise<ReduceResult>;
+/** Thrown when synchronous evaluation reaches an async grounded operation. Use the async runner. */
+declare class AsyncInSyncError extends Error {
+    constructor(op: string);
+}
+type Ret = "none" | "chain" | "function";
+interface Frame {
+    readonly atom: Atom;
+    readonly ret: Ret;
+    readonly vars: readonly string[];
+    readonly fin: boolean;
+}
+interface StackCons {
+    readonly head: Frame;
+    readonly tail: Stack;
+}
+type Stack = StackCons | null;
+interface Item {
+    readonly stack: Stack;
+    readonly bnd: Bindings;
+}
+interface MinEnv {
+    ruleIndex: Map<string, Array<[Atom, Atom]>>;
+    varRules: Array<[Atom, Atom]>;
+    sigs: Map<string, Atom[]>;
+    gt: GroundingTable;
+    atoms: Atom[];
+    types: Map<string, Atom[]>;
+    imports: Map<string, Atom[]>;
+    exprTypes: Array<[Atom, Atom]>;
+    /** Async grounded operations, dispatched by the async runner; empty for pure synchronous evaluation. */
+    agt: Map<string, AsyncGroundFn>;
+    /** Per-runner `with-mutex` locks (a Promise chain per key), so mutexes do not leak across runners. */
+    mutexes: Map<string, Promise<void>>;
+    factIndex: Map<string, Atom[]>;
+    argIndex: Map<string, Atom[]>;
+    nonGroundAtPos: Map<string, Atom[]>;
+    varHeadedFacts: Atom[];
+    /** Automatic-tabling memo: a ground pure call's printed form maps to its ordered result bag.
+     *  `undefined` when tabling is disabled. */
+    table?: Map<string, Atom[]>;
+    /** Functor names proven tabling-safe by `analyzePurity`; recomputed when equations change. */
+    pureFunctors?: Set<string>;
+    /** Memo for `getTypes` of ground atoms: a ground atom's type is a pure function of the env's type tables,
+     *  which only change via `addAtomToEnv` (where this is reset). Keyed by atom identity, so the recursion
+     *  reuses the type of every shared subterm (a growing Peano/list term is the worst case otherwise). */
+    typeCache?: WeakMap<Atom, Atom[]> | undefined;
+    /** Optional parallel branch evaluator for `hyperpose` (set by the Node runner to a worker_threads pool;
+     *  undefined in the browser). Given the formatted branch atoms and whether to stop at the first result,
+     *  returns each branch's result atoms, or `null` for a branch that errored or (under firstOnly) lost the
+     *  race. It re-evaluates each branch from the program's rules in a worker, so it is only used when a branch
+     *  is pure and the space carries no runtime additions, so it is identical to evaluating in line. */
+    parEval?: (branchSrcs: string[], firstOnly: boolean) => (Atom[] | null)[];
+    /** Compiled pure deterministic functions (the int/bool functional core); undefined when disabled. */
+    compiled?: CompiledFns;
+    /** Set when an equation changed, so the compiler re-runs before the next query. */
+    compileDirty?: boolean;
+    /** Opt-in PeTTa-style auto-currying, enabled by `(import! &self curry)`. When set, a symbol-headed
+     *  call applied to fewer arguments than the function's arity reduces to `(partial fn (args))` instead
+     *  of staying irreducible. Off by default, so the Hyperon oracle baseline is unaffected. */
+    curry?: boolean;
+}
+/** An empty environment for grounding table `gt`. Grow it with `addAtomToEnv`. */
+declare function emptyEnv(gt: GroundingTable): MinEnv;
+/** Incorporate one atom into `env` (mutating): rule index, signatures, types, and the atom list.
+ *  Lets a sequential runner extend the env per atom instead of rebuilding it each query; correctness
+ *  gated by the 270/270 oracle. */
+declare function addAtomToEnv(env: MinEnv, x: Atom): void;
+declare function buildEnv(atoms: Atom[], gt: GroundingTable): MinEnv;
+interface World {
+    spaces: Map<string, Atom[]>;
+    store: Map<number, Atom>;
+    tokens: Map<string, Atom>;
+    selfExtra: AtomLog;
+    selfRules: Map<string, Array<[Atom, Atom]>>;
+    selfVarRules: ReadonlyArray<[Atom, Atom]>;
+    maxStackDepth: number;
+}
+interface St {
+    counter: number;
+    world: World;
+}
+declare const initSt: () => St;
+declare function freshenRule(counter: number, lhs: Atom, rhs: Atom): [Atom, Atom];
+declare function getTypes(env: MinEnv, a: Atom): Atom[];
+declare function mettaEval(env: MinEnv, fuel: number, st: St, bnd: Bindings, a: Atom): [Array<[Atom, Bindings]>, St];
+/** Async type-directed evaluation: awaits async grounded operations (`env.agt`). An optional `signal`
+ *  makes it cancellable (used by `race` to stop losing branches). */
+declare function mettaEvalAsync(env: MinEnv, fuel: number, st: St, bnd: Bindings, a: Atom, signal?: AbortSignal): Promise<[Array<[Atom, Bindings]>, St]>;
+/** Evaluate `atom` (i.e. interpret `(eval atom)`) under `env`, returning the result atoms. */
+declare function evalAtom(env: MinEnv, atom: Atom, st?: St, fuel?: number): [Atom[], St];
+
+/** Ops that read or write mutable state, do I/O, read types/spaces, or introduce nondeterminism.
+ *  A functor whose body reaches any of these (directly or transitively) is not tabled in P1. */
+declare const IMPURE_OPS: ReadonlySet<string>;
+/** The set of functor names safe to table. Conservative: a variable-headed (`$x`-headed) equation can match
+ *  anything, so its presence disables tabling entirely. (`varRules` also holds expression-headed equations,
+ *  which match only their own constructor and are harmless here.) */
+declare function analyzePurity(env: MinEnv): Set<string>;
+/** The memo key for a ground call. The call has no variables, so its printed form is canonical. */
+declare function tableKey(call: Atom): string;
+/** A key is well-formed only if it contains no Float leaf (IEEE-754 breaks lawful equality, so a
+ *  float-keyed table could merge or split keys differently from `match`). Mutable references never
+ *  appear in a ground call, so the float check is the only one needed in P1. */
+declare function keyWellFormed(a: Atom): boolean;
+
+/** A relation: a set of tuples, each a binding of this relation's variables to values. */
+interface Relation<V> {
+    readonly vars: readonly string[];
+    readonly tuples: ReadonlyArray<ReadonlyMap<string, V>>;
+}
+/** The worst-case-optimal join (generic join / leapfrog-triejoin family): all bindings of every variable
+ *  satisfying all relations. Each relation is indexed once into a trie over its variables in the join
+ *  order, so binding a variable intersects the relations' current trie levels by key lookup rather than
+ *  rescanning every tuple. That avoids the naive generic join's repeated tuple scans. `key` maps a
+ *  value to a comparable string; pass `varOrder` to fix the elimination order (first-seen otherwise). */
+declare function wcoJoin<V>(rels: ReadonlyArray<Relation<V>>, key: (v: V) => string, varOrder?: readonly string[]): Array<Map<string, V>>;
+
+/** A substitution: an association list of variable name to atom. */
+type Subst = ReadonlyArray<readonly [string, Atom]>;
+declare const emptySubst: Subst;
+/** First value assigned to `x`, if any. */
+declare function lookupSubst(s: Subst, x: string): Atom | undefined;
+/** Drop every binding for `x`. */
+declare function eraseSubst(s: Subst, x: string): Subst;
+/** `(x,a) :: erase s x` (LeaTTa `Subst.extend`). */
+declare function extendSubst(s: Subst, x: string, a: Atom): Subst;
+/** Apply `s` to an atom: replace each variable by its assigned value (one pass; the substituted
+ *  value is not itself re-substituted). */
+declare function applySubst(s: Subst, a: Atom): Atom;
+/** Occurs-check: does `$x` appear anywhere in the atom? */
+declare function occurs(x: string, a: Atom): boolean;
+
+/** Most-general unifier of two atoms, or null if they do not unify. */
+declare function unifyTop(a: Atom, b: Atom): Subst | null;
+/** Whether two atoms unify (the satisfiability check used by addVarBinding). */
+declare function unifiable(a: Atom, b: Atom): boolean;
+
+/** A custom matcher for grounded atoms; may be nondeterministic. */
+type GroundMatcher = (left: Atom, right: Atom) => Bindings[];
+/** Add `$x ← v` to `b` consistently. If `$x` is already bound to a different value, reconcile the old value
+ *  against the new one (propagating the unification constraint), rejecting a cyclic result. Mirrors hyperon's
+ *  `add_var_binding` with LeaTTa's occurs check. */
+declare function addVarBinding(b: Bindings, x: string, v: Atom): Bindings[];
+/** Add the alias `$x = $y` to `b` consistently. If both are already value-bound to different values,
+ *  reconcile those values (mirrors hyperon's `add_var_equality`); otherwise record the equality. */
+declare function addVarEquality(b: Bindings, x: string, y: string): Bindings[];
+/** Combine two binding sets into all their consistent unions (LeaTTa `merge`). */
+declare function merge(a: Bindings, b: Bindings): Bindings[];
+/** Match atoms in the official left/right style (LeaTTa `matchAtomsWith`). `leftSuffix` (default empty)
+ *  scopes the LEFT atom's variables: a left variable `$x` is treated as `$x<suffix>`, so a rule LHS can be
+ *  matched without first cloning it with freshened variables. */
+declare function matchAtomsWith(custom: GroundMatcher | undefined, l: Atom, r: Atom, leftSuffix?: string): Bindings[];
+/** Match pattern `l` against `r` with the default matcher (no custom grounded matching). */
+declare function matchAtoms(l: Atom, r: Atom): Bindings[];
+/** Match a rule LHS `l` against `r`, scoping `l`'s variables with `suffix` (so the rule need not be cloned
+ *  with freshened variables first). The resulting bindings key the rule variables as `name<suffix>`, exactly
+ *  as upfront freshening would, so `instantiate(_, rhs, suffix)` resolves the matching RHS identically. */
+declare function matchAtomsScoped(l: Atom, r: Atom, suffix: string): Bindings[];
+
+/** A binding set viewed as a substitution: value bindings only; `eq` aliases are dropped. */
+declare function bindingsToSubst(b: Bindings): Subst;
+/** Apply a binding set to an atom: replace each variable by its value binding (eq aliases dropped), one
+ *  pass. Walks `b` directly via `lookupVal` instead of first materializing a `Subst` array on every call.
+ *  that conversion was pure allocation on the hot substitution path (instantiate dominated the emit
+ *  profile). A new term is built only where a child changed; the empty binding and closed subterms
+ *  short-circuit to sharing. */
+declare function instantiate(b: Bindings, a: Atom, suffix?: string): Atom;
+
+declare function alphaEq(a: Atom, b: Atom): boolean;
+
+type TokenConstructor = (token: string) => Atom;
+declare class Tokenizer {
+    private readonly entries;
+    /** Register a (regex, constructor). Order matters: the first matching pattern wins. */
+    register(re: RegExp, make: TokenConstructor): void;
+    /** A grounded atom for `token`, or undefined if no pattern matches (caller falls back to Symbol). */
+    tokenize(token: string): Atom | undefined;
+}
+
+interface TopAtom {
+    readonly atom: Atom;
+    readonly bang: boolean;
+}
+declare function parse(src: string, tk: Tokenizer): Atom | undefined;
+/** Parse a whole program into its sequence of top-level atoms. */
+declare function parseAll(src: string, tk: Tokenizer): TopAtom[];
+/** Print an atom back to MeTTa source (inverse of parse for normalized input). */
+declare function format(a: Atom): string;
+
+interface Space {
+    add(atom: Atom): void;
+    /** Remove the first structurally-equal atom; returns whether one was removed. */
+    remove(atom: Atom): boolean;
+    /** All binding sets under which `pattern` matches a stored atom. `freshen`, if given, is applied
+     *  to each stored atom before matching (rule-variable freshening). */
+    query(pattern: Atom, freshen?: (a: Atom) => Atom): Bindings[];
+    atoms(): readonly Atom[];
+}
+/** Linear-scan in-memory space. Indexing is a future extension behind this same interface. */
+declare class InMemorySpace implements Space {
+    private readonly store;
+    add(atom: Atom): void;
+    remove(atom: Atom): boolean;
+    query(pattern: Atom, freshen?: (a: Atom) => Atom): Bindings[];
+    atoms(): readonly Atom[];
+}
+
+/** The standard tokenizer: integer/float literals and the `True`/`False` grounded booleans. */
+declare function standardTokenizer(): Tokenizer;
+/** The prelude's atoms (parsed once and cached). */
+declare function preludeAtoms(): Atom[];
+interface QueryResult {
+    readonly query: Atom;
+    readonly results: Atom[];
+}
+declare const DEFAULT_FUEL = 100000;
+interface RunOptions {
+    readonly tabling?: boolean;
+    readonly maxStackDepth?: number;
+    readonly parEvalImpl?: (rulesSrc: string, branchSrcs: string[], firstOnly: boolean) => (string[] | null)[];
+}
+/** Evaluate a parsed program sequentially. `imports` backs `import!` (pre-read by the caller). */
+declare function evalSequential(atoms: readonly {
+    atom: Atom;
+    bang: boolean;
+}[], fuel?: number, imports?: Map<string, Atom[]>, opts?: RunOptions): QueryResult[];
+/** Parse and run a MeTTa source string sequentially. */
+declare function runProgram(src: string, fuel?: number, imports?: Map<string, Atom[]>, opts?: RunOptions): QueryResult[];
+/** Async sequential evaluation: like `runProgram`, but `!`-queries are awaited, so async grounded
+ *  operations (registered in `asyncOps`) can perform I/O. Sync programs give identical results to
+ *  `runProgram`; the async path only differs when an async op is actually reached. */
+declare function runProgramAsync(src: string, asyncOps?: Map<string, AsyncGroundFn>, fuel?: number, imports?: Map<string, Atom[]>): Promise<QueryResult[]>;
+/** Module names referenced by top-level `import!` statements (so a caller can pre-read them). */
+declare function collectImports(src: string): string[];
+/** An oracle assertion passes iff its query evaluates to exactly the unit atom `()`. */
+declare function isOraclePass(r: QueryResult): boolean;
+/** Run a test file and report pass/fail counts and the failing queries. */
+declare function oracleReport(src: string, fuel?: number, imports?: Map<string, Atom[]>): {
+    total: number;
+    passed: number;
+    failures: string[];
+};
+
+/** The `concurrency` module: timing/concurrency extensions (transaction, and later par/race/mutex). */
+declare const CONCURRENCY_MODULE_SRC = "\n  (: transaction (-> Atom %Undefined%))\n";
+/** The `curry` module: PeTTa-style partial application. Importing it sets the engine's curry flag (see
+ *  the import! handler), so a symbol-headed call applied to fewer arguments than the function's arity
+ *  reduces to `(partial fn (args))`. This module supplies the rules that *apply* such a closure (append
+ *  the new arguments and re-evaluate the now-fuller call, which re-curries if still short), plus the
+ *  same under-application handling for |-> lambdas, whose head is an expression and so is not reached by
+ *  the symbol-headed hook. Off unless imported, so the Hyperon oracle baseline is untouched. */
+declare const CURRY_MODULE_SRC = "\n  (: partial (-> Atom Expression Atom))\n\n  ; Apply a closure to further arguments: append them to the bound list, rebuild the call, evaluate it.\n  ; append is forced through its own let (cons-atom would otherwise take it as a literal subexpression),\n  ; and the rebuilt call is fully reduced with metta (eval is a single step), which re-curries if still\n  ; under-applied.\n  (= ((partial $f $bound) $a)\n     (let $args (append $bound ($a))\n       (let $call (cons-atom $f $args) (metta $call %Undefined% &self))))\n  (= ((partial $f $bound) $a $b)\n     (let $args (append $bound ($a $b))\n       (let $call (cons-atom $f $args) (metta $call %Undefined% &self))))\n\n  ; An under-applied |-> lambda (head is an expression, so the core hook does not see it) becomes a\n  ; partial closure over the lambda value; applying it later rebuilds the full application.\n  (= ((|-> ($p1 $p2) $body) $a1)\n     (partial (|-> ($p1 $p2) $body) ($a1)))\n  (= ((|-> ($p1 $p2 $p3) $body) $a1)\n     (partial (|-> ($p1 $p2 $p3) $body) ($a1)))\n  (= ((|-> ($p1 $p2 $p3) $body) $a1 $a2)\n     (partial (|-> ($p1 $p2 $p3) $body) ($a1 $a2)))\n";
+/** The built-in extension modules, by the name used in `(import! &self <name>)`. */
+declare function builtinModules(): Map<string, Atom[]>;
+/** A fresh imports map seeded with the built-in extension modules, optionally merged with caller
+ *  imports. Built-ins are only applied when a program actually `(import! ...)`s them, so this never
+ *  affects the Hyperon oracle baseline. Built-in module names are reserved: a caller-supplied module of
+ *  the same name does NOT override the built-in (otherwise a disk file that happens to share a name, e.g.
+ *  a corpus `curry.metta` that itself does `(import! &self curry)`, would shadow the built-in rules). */
+declare function withBuiltinModules(extra?: Map<string, Atom[]>): Map<string, Atom[]>;
+
+declare const STDLIB_SRC = "\n  ; ---- Types of the grounded ops (math, bool, atom). Hyperon's grounded atoms carry their type\n  ; intrinsically and `get-type` reads it; @metta-ts grounds these as host functions in builtins.ts,\n  ; so the type signature is declared here to match. Values from hyperon-experimental math.rs/atom.rs\n  ; (math ops are f64-valued, so e.g. pow-math/sqrt-math return Number; min-atom/max-atom take any\n  ; expression, typed %Undefined% -> Number). The core arithmetic and comparison ops (+ - < == \u2026) are\n  ; already declared in the prelude.\n  (: pow-math (-> Number Number Number))\n  (: sqrt-math (-> Number Number))\n  (: abs-math (-> Number Number))\n  (: log-math (-> Number Number Number))\n  (: trunc-math (-> Number Number))\n  (: ceil-math (-> Number Number))\n  (: floor-math (-> Number Number))\n  (: round-math (-> Number Number))\n  (: sin-math (-> Number Number))\n  (: asin-math (-> Number Number))\n  (: cos-math (-> Number Number))\n  (: acos-math (-> Number Number))\n  (: tan-math (-> Number Number))\n  (: atan-math (-> Number Number))\n  (: isnan-math (-> Number Bool))\n  (: isinf-math (-> Number Bool))\n  (: min-atom (-> %Undefined% Number))\n  (: max-atom (-> %Undefined% Number))\n  (: and (-> Bool Bool Bool))\n  (: or (-> Bool Bool Bool))\n  (: not (-> Bool Bool))\n  (: xor (-> Bool Bool Bool))\n\n  ; sealed alpha-renames the variables of its second argument. That argument is Atom-typed so the\n  ; body reaches sealed unevaluated (hyperon-experimental core.rs: (-> Expression Atom Atom)); without\n  ; this the reduce loop would evaluate the body first, e.g. collapsing (== 1 $e) before renaming.\n  (: sealed (-> Expression Atom Atom))\n\n  ; ---- IO (host primitives grounded in builtins.ts) ----\n  (: println! (-> %Undefined% (->)))\n  (: print! (-> %Undefined% (->)))\n  (: format-args (-> String Expression String))\n  ; repr renders an atom's textual form. The argument is Atom-typed (not evaluated) so repr shows the\n  ; atom as written; to repr a reduced form, evaluate it first (e.g. bind it with let).\n  (: repr (-> Atom String))\n\n  ; trace! prints its first argument and returns the (evaluated) second.\n  (: trace! (-> %Undefined% %Undefined% %Undefined%))\n  (= (trace! $msg $ret) (let $unit (println! $msg) $ret))\n\n  ; include = import a module's contents into the current space.\n  (: include (-> Atom %Undefined%))\n  (= (include $module) (import! &self $module))\n\n  ; ---- Error system ----\n  (: ErrorType Type)\n  (: ErrorDescription Type)\n  (: IncorrectNumberOfArguments ErrorDescription)\n  (: BadType (-> Type Type ErrorDescription))\n  (: BadArgType (-> Number Type Type ErrorDescription))\n\n  ; ---- Module system (minimal: @metta-ts resolves modules via import! into a space) ----\n  (: module-space-no-deps (-> SpaceType SpaceType))\n  (= (module-space-no-deps $s) $s)\n  (: print-mods! (-> (->)))\n  (= (print-mods!) ())\n  (: git-module! (-> Atom (->)))\n  (= (git-module! $url) (Error (git-module! $url) \"git-module! is not supported in @metta-ts\"))\n\n  ; ---- Documentation system (ported from hyperon stdlib.metta) ----\n  (: DocDescription Type)\n  (: DocInformal Type)\n  (: DocFormal Type)\n  (: DocItem Type)\n  (: DocKindFunction Type)\n  (: DocKindAtom Type)\n  (: DocType Type)\n  (: DocParameters Type)\n  (: DocParameter Type)\n  (: DocParameterInformal Type)\n  (: DocReturn Type)\n  (: DocReturnInformal Type)\n  (: @doc (-> Atom DocDescription DocParameters DocReturnInformal DocInformal))\n  (: @desc (-> String DocDescription))\n  (: @param (-> DocType DocDescription DocParameter))\n  (: @return (-> DocType DocDescription DocReturn))\n  (: @doc-formal (-> DocItem DocKindFunction DocType DocDescription DocParameters DocReturn DocFormal))\n  (: @item (-> Atom DocItem))\n  (: @kind (-> Atom DocKindFunction))\n  (: @type (-> Type DocType))\n  (: @params (-> Expression DocParameters))\n\n  (= (get-doc-single-atom $space $atom)\n    (let $type (get-type-space $space $atom)\n      (if (is-function $type)\n        (get-doc-function $space $atom $type)\n        (get-doc-atom $space $atom) )))\n  (= (get-doc-function $space $name $type)\n    (unify $space (@doc $name $desc (@params $params) $ret)\n      (let $type' (if (== $type %Undefined%) (undefined-doc-function-type $params) (cdr-atom $type))\n      (let ($params' $ret') (get-doc-params $params $ret $type')\n        (@doc-formal (@item $name) (@kind function) (@type $type) $desc (@params $params') $ret')))\n      Empty ))\n  (= (get-doc-atom $space $atom)\n    (let $type (get-type-space $space $atom)\n      (unify $space (@doc $atom $desc)\n        (@doc-formal (@item $atom) (@kind atom) (@type $type) $desc)\n        (unify $space (@doc $atom $desc' (@params $params) $ret)\n          (get-doc-function $space $atom %Undefined%)\n          Empty ))))\n  (= (get-doc-params $params $ret $types)\n    (let $head-type (car-atom $types)\n    (let $tail-types (cdr-atom $types)\n      (if (== () $params)\n        (let (@return $ret-desc) $ret\n          (() (@return (@type $head-type) (@desc $ret-desc))) )\n        (let (@param $param-desc) (car-atom $params)\n          (let $tail-params (cdr-atom $params)\n          (let ($params' $result-ret) (get-doc-params $tail-params $ret $tail-types)\n          (let $result-params (cons-atom (@param (@type $head-type) (@desc $param-desc)) $params')\n            ($result-params $result-ret) ))))))))\n  (= (undefined-doc-function-type $params)\n    (if (== () $params) (%Undefined%)\n      (let $params-tail (cdr-atom $params)\n      (let $tail (undefined-doc-function-type $params-tail)\n        (cons-atom %Undefined% $tail) ))))\n  (= (help-param! $param)\n    (let (@param (@type $type) (@desc $desc)) $param\n      (println! (format-args \"  {} {}\" ((type $type) $desc))) ))\n  (: help-space! (-> SpaceType (->)))\n  (= (help-space! $space)\n    (let $_ (collapse\n      (unify $space (@doc $name (@desc $desc) $params $ret)\n        (let () (println! (format-args \"{} {}\" ($name $desc))) Empty)\n        Empty )) ()))\n\n  ; mod-space! loads a module into a fresh space and returns it.\n  (: mod-space! (-> Atom SpaceType))\n  (= (mod-space! $module) (let $s (new-space) (let $u (import! $s $module) $s)))\n";
+/** The standard-library atoms (parsed once and cached). Always loaded by the runner. */
+declare function stdlibAtoms(): Atom[];
+
+declare const TAG_ARITY = 0;
+declare const TAG_SYMBOL = 1;
+declare const TAG_NEWVAR = 2;
+declare const TAG_VARREF = 3;
+/** Interns symbols and grounded values to dense integer ids, with a reverse map so a flat atom decodes
+ *  back exactly. Symbols and grounds share the id space (a ground's id reconstructs the ground). */
+declare class Interner {
+    private readonly byKey;
+    private readonly entries;
+    private add;
+    internSym(name: string): number;
+    internGround(value: Ground): number;
+    /** The id for a symbol/ground if already interned, else undefined (a pattern symbol absent from the
+     *  KB can never match, so its lookup short-circuits). */
+    lookupSym(name: string): number | undefined;
+    lookupGround(value: Ground): number | undefined;
+    /** Reconstruct the atom for a leaf id. */
+    decodeLeaf(id: number): Atom;
+    get size(): number;
+}
+/** Encode an atom into the token array `out`, interning leaves. `varMap` assigns de Bruijn indices to
+ *  variable names (shared across one atom so repeated variables become VARREF). */
+declare function encodeInto(a: Atom, out: number[], it: Interner, varMap: Map<string, number>): void;
+/** Encode a single atom to a token array. */
+declare function encodeAtom(a: Atom, it: Interner): number[];
+/** Decode the token at `pos`, returning the atom and the position after it. Variables are reconstructed
+ *  with de Bruijn names `$0`, `$1`, … (so a decoded atom is alpha-equivalent to the original). */
+declare function decodeAt(tokens: Int32Array | number[], pos: number, it: Interner): [Atom, number];
+/** Decode a full token array to an atom. */
+declare function decodeAtom(tokens: Int32Array | number[], it: Interner): Atom;
+/** The number of tokens in the subterm starting at `pos`. */
+declare function subtermLen(tokens: Int32Array | number[], pos: number): number;
+/** Encode a query pattern using lookup (not interning): returns the tokens and the variable names in de
+ *  Bruijn order, or `null` if a pattern symbol/ground is absent from the interner (fast fail; it can
+ *  never match any stored fact). */
+declare function encodePattern(a: Atom, it: Interner): {
+    tokens: number[];
+    varNames: string[];
+} | null;
+/** One-sided match of an encoded pattern against an encoded ground fact in a (possibly shared) token
+ *  array. Returns the variable bindings (de Bruijn index -> the matched fact subterm's [start, end)
+ *  token range), or `null` on mismatch. Pure integer work over the token array, so a worker can run it
+ *  against a `SharedArrayBuffer`-backed `Int32Array` with no copying. */
+declare function matchFlatAt(pat: ArrayLike<number>, fact: Int32Array | number[], factStart: number): Map<number, [number, number]> | null;
+/** A flat, interned knowledge base: facts are appended as token runs into one array, indexed by head
+ *  functor id, and matched against an encoded pattern by integer scan. */
+declare class FlatKB {
+    readonly interner: Interner;
+    private readonly tokens;
+    private readonly byFunctor;
+    private readonly other;
+    private readonly offsets;
+    /** The token array (for packing into a SharedArrayBuffer). */
+    get tokenArray(): readonly number[];
+    /** Every fact's start offset, in insertion order (for sharding across workers). */
+    get factOffsets(): readonly number[];
+    /** Add a (typically ground) atom to the KB. */
+    add(a: Atom): void;
+    /** Candidate fact offsets for a pattern, using the functor index when the pattern head is a known
+     *  symbol; otherwise every fact. */
+    private candidates;
+    /** Match `pattern` against the KB, returning a binding map (variable name -> matched atom) per match. */
+    match(pattern: Atom): Array<Map<string, Atom>>;
+    get size(): number;
+}
+declare const _internals: {
+    tok: (tag: number, payload?: number) => number;
+    tagOf: (tok: number) => number;
+    payloadOf: (tok: number) => number;
+    subtermLen: typeof subtermLen;
+};
+
+/** A frequent subpattern and its compression economics. */
+interface HeavyPattern {
+    /** The repeated subpattern (decoded for inspection). */
+    readonly pattern: Atom;
+    /** How many times it occurs across the KB. */
+    readonly count: number;
+    /** Its size in tokens. */
+    readonly len: number;
+    /** Tokens saved by factoring it: `(count - 1) * len - count * refCost`. */
+    readonly gain: number;
+}
+/**
+ * The top-`k` heaviest repeated subpatterns in `kb`, by compression gain. `refCost` is the token cost of
+ * a reference to a factored definition (MORK starts at ~4–8). Only subpatterns occurring ≥2 times with
+ * positive gain are returned (single symbols never pay to factor). Brute-force and exact; the oracle
+ * for any future output-sensitive index.
+ */
+declare function williamTopK(kb: FlatKB, k: number, refCost?: number): HeavyPattern[];
+
+declare class Trail {
+    private readonly binds;
+    private readonly trail;
+    /** A restore point: the current trail length. */
+    mark(): number;
+    /** Undo every binding made since `m`. */
+    undo(m: number): void;
+    /** Bind `$name` to `a` and record it on the trail. The caller guarantees `$name` is currently unbound. */
+    bind(name: string, a: Atom): void;
+    /** Follow variable bindings to the representative: a non-variable, or an unbound variable. */
+    deref(a: Atom): Atom;
+    /** Resolve `a` against the current bindings, one pass (the same discipline as the immutable
+     *  `instantiate`/`applySubst`): a variable becomes its bound value as-is; the value's own variables are
+     *  not re-resolved, and an expression's children are resolved. This matches the evaluator exactly,
+     *  including that a cyclic binding (`$y = (.. $y ..)`, which `matchAtoms` produces and `hasLoop` does not
+     *  reject) terminates instead of looping. A new term is built only where a child changed. */
+    resolve(a: Atom): Atom;
+}
+/** Unify two atoms against the trail, binding variables in place; returns whether they unify. On failure
+ *  the trail may hold partial bindings, so callers undo to a mark. Mirrors the immutable matcher: a
+ *  variable binds to the other side (no occurs check; `matchAtoms` admits cyclic bindings and the
+ *  evaluator's one-pass `resolve` handles them, so adding one here would diverge), two symbols/grounded
+ *  values must be equal, two expressions must have equal arity and unify pointwise. */
+declare function unifyTrail(tr: Trail, l0: Atom, r0: Atom): boolean;
+
+export { type AsyncGroundFn, AsyncInSyncError, type Atom, BAIL, type BindingRel, type Bindings, CONCURRENCY_MODULE_SRC, CURRY_MODULE_SRC, type CompiledFns, type CompiledHolder, DEFAULT_FUEL, type EqRel, type ExprAtom, FlatKB, type Frame, type GndAtom, type Ground, type GroundFn, type GroundMatcher, type GroundedExec, type GroundedMatch, type GroundingTable, type HeavyPattern, IMPURE_OPS, InMemorySpace, type IntVal, Interner, type Item, type MetaType, type MinEnv, type QueryResult, type ReduceResult, type Relation, type Ret, type RunOptions, STDLIB_SRC, type Space, type St, type Stack, type StackCons, type Subst, type SymAtom, TAG_ARITY, TAG_NEWVAR, TAG_SYMBOL, TAG_VARREF, type TokenConstructor, Tokenizer, type TopAtom, Trail, type ValRel, type VarAtom, type World, _internals, addAtomToEnv, addEqRaw, addInt, addValRaw, addVarBinding, addVarEquality, alphaEq, analyzePurity, applySubst, atomEq, atomSize, atomVars, baseTable, bindingsToSubst, buildEnv, builtinModules, callGrounded, canonInt, cmpIntVal, collectImports, collectVars, compileEnv, decodeAt, decodeAtom, emptyBindings, emptyEnv, emptyExpr, emptySubst, encodeAtom, encodeInto, encodePattern, eraseSubst, evalAtom, evalSequential, expr, extendSubst, format, freshenRule, gbool, getTypes, gfloat, gint, gnd, groundEq, groundType, gstr, gunit, hasLoop, hashOf, initSt, instantiate, intAbs, intDiv, intMod, isErrorAtom, isExpr, isGnd, isOraclePass, isSym, isVar, isZero, keyWellFormed, lookupSubst, lookupVal, matchAtoms, matchAtomsScoped, matchAtomsWith, matchFlatAt, merge, metaType, mettaEval, mettaEvalAsync, mulInt, occurs, oracleReport, parse, parseAll, pettaOpNames, preludeAtoms, removeVal, runCompiled, runProgram, runProgramAsync, setOutputSink, setRawSink, standardTokenizer, stdTable, stdlibAtoms, subInt, sym, tableKey, toF64, unifiable, unifyTop, unifyTrail, variable, wcoJoin, williamTopK, withBuiltinModules };