@metta-ts/core 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -96,11 +96,22 @@ 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;
+declare function canInternExprItems(items: readonly Atom[]): 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;
+interface InternTable {
+    readonly buckets: Map<number, Atom | Atom[]>;
+    readonly variables: Map<string, VarAtom>;
+    readonly expressions: WeakSet<ExprAtom>;
+    readonly hasUnsafeGrounded: WeakMap<ExprAtom, boolean>;
+}
+declare function createInternTable(): InternTable;
+declare function internAtom(table: InternTable | undefined, a: Atom): Atom;
+declare function internExpr(table: InternTable | undefined, a: ExprAtom): ExprAtom;
+declare function internBuiltExpr(table: InternTable | undefined, a: ExprAtom): 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;
@@ -111,6 +122,8 @@ declare const gstr: (s: string) => GndAtom;
 declare const gbool: (b: boolean) => GndAtom;
 declare const gunit: GndAtom;
 declare function metaType(a: Atom): MetaType;
+declare const mixHash: (h: number, x: number) => number;
+declare const strHash: (s: string) => number;
 /** 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;
@@ -156,40 +169,61 @@ declare function removeVal(b: Bindings, x: string): Bindings;
 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;
+/** Prepend `$x ← a` when the caller has already proved `$x` has no direct value binding. */
+declare function prependValRaw(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;
+/** Build a single value relation. The canonical `ValRel` constructor for callers outside this module. */
+declare function makeValRel(x: string, a: Atom): ValRel;
+/** Build a binding set from an explicit list of relations (newest-first). */
+declare function fromRelations(rels: readonly BindingRel[]): Bindings;
+/** Number of relations in the set. */
+declare function size(b: Bindings): number;
+/** Whether the set has no relations. */
+declare function isEmpty(b: Bindings): boolean;
+/** Every relation, newest-first (the order `merge` folds them in). */
+declare function relations(b: Bindings): Iterable<BindingRel>;
+/** Each current value binding as `[var, atom]`. */
+declare function valEntries(b: Bindings): Iterable<readonly [string, Atom]>;
+/** Whether any value binding satisfies `pred`. */
+declare function someVal(b: Bindings, pred: (x: string, a: Atom) => boolean): boolean;
+/** Whether the set carries any `eq` alias. */
+declare function hasEq(b: Bindings): boolean;
+/** Each `eq` alias relation, newest-first. */
+declare function eqRelations(b: Bindings): Iterable<EqRel>;
 
-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;
 
+declare function canCompactAtom(a: Atom): boolean;
+declare class FlatAtomSpace {
+    private readonly table;
+    private readonly ranges;
+    private readonly dead;
+    readonly liveCount: number;
+    readonly nonGroundCount: number;
+    private constructor();
+    static empty(): FlatAtomSpace;
+    static fromAtoms(atoms: readonly Atom[]): FlatAtomSpace | undefined;
+    get size(): number;
+    appendAll(atoms: readonly Atom[]): FlatAtomSpace;
+    removeOne(atom: Atom): FlatAtomSpace;
+    exactCount(atom: Atom): number;
+    candidatesFor(patternHead: string | undefined): Iterable<Atom>;
+    toArray(): Atom[];
+    roundTrip(atom: Atom): Atom;
+    private decodeFact;
+    private visibleFactIds;
+    private factVisible;
+}
+
 type ReduceResult = {
     readonly tag: "ok";
     readonly results: readonly Atom[];
@@ -228,23 +262,61 @@ declare class Tup {
     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
+type Ty = "int" | "bool" | "sym" | `tuple${number}` | `symtuple${number}`;
+/** A compiled pure function. `run` is filled after the whole dependency group is compiled, so mutual
  *  recursion resolves through the holder object. */
-interface CompiledHolder {
+interface FunctionalHolder {
+    kind: "functional";
     arity: number;
     retType: Ty;
     paramTypes: Ty[];
     run: (vals: FrameVal[]) => FrameVal | boolean;
 }
+interface CompiledAtomResult {
+    readonly atom: Atom;
+    readonly bnd: Bindings;
+}
+interface CompiledRunResult {
+    readonly results: readonly CompiledAtomResult[];
+    readonly counterDelta: number;
+    readonly state?: St;
+}
+interface RewriteHolder {
+    kind: "rewrite";
+    arity: number;
+    retType: Ty;
+    paramTypes: Ty[];
+    ruleCount: number;
+    run: (partAtoms: readonly Atom[]) => CompiledRunResult | undefined;
+}
+interface SymbolicHolder {
+    kind: "symbolic";
+    arity: number;
+    clauseCount: number;
+    run: (partAtoms: readonly Atom[], counter: number) => CompiledRunResult | undefined;
+}
+interface CompiledImpureOps {
+    readonly addAtom: (env: MinEnv, st: St, space: Atom, atom: Atom) => St | undefined;
+}
+type ImpEval = {
+    readonly value: Atom;
+    readonly st: St;
+} | typeof BAIL;
+interface ImperativeHolder {
+    kind: "imperative";
+    arity: number;
+    clauseCount: number;
+    run: (partAtoms: readonly Atom[], st: St, ops: CompiledImpureOps, discard?: boolean) => ImpEval;
+}
+type CompiledHolder = FunctionalHolder | RewriteHolder | SymbolicHolder | ImperativeHolder;
 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;
+/** Run a compiled function, returning an ordered result bag, or `undefined` to fall back to the interpreter
+ *  when the call falls outside the proven subset. */
+declare function runCompiled(env: MinEnv, op: string, partAtoms: readonly Atom[], st: St, ops?: CompiledImpureOps, discard?: boolean): CompiledRunResult | undefined;
 
 /** A grounded operation that runs asynchronously, for the async runner. */
 type AsyncGroundFn = (args: readonly Atom[]) => Promise<ReduceResult>;
@@ -271,6 +343,7 @@ interface Item {
 interface MinEnv {
     ruleIndex: Map<string, Array<[Atom, Atom]>>;
     varRules: Array<[Atom, Atom]>;
+    varRulesVar: Array<[Atom, Atom]>;
     sigs: Map<string, Atom[]>;
     gt: GroundingTable;
     atoms: Atom[];
@@ -281,6 +354,10 @@ interface MinEnv {
     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>>;
+    /** Optional per-run hash-cons table for immutable terms. */
+    intern?: InternTable;
+    /** Ground expressions already observed to reduce to themselves for the current rule set. */
+    evaluatedAtoms: WeakSet<Atom>;
     factIndex: Map<string, Atom[]>;
     argIndex: Map<string, Atom[]>;
     nonGroundAtPos: Map<string, Atom[]>;
@@ -301,13 +378,21 @@ interface MinEnv {
      *  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;
+    compiled?: CompiledFns | undefined;
     /** Set when an equation changed, so the compiler re-runs before the next query. */
-    compileDirty?: boolean;
+    compileDirty?: boolean | undefined;
     /** 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;
+    /** Opt-in trail-based matching (`experimental.trail`): the conjunctive `match` enumerates on a WAM-style
+     *  trail (zero per-solution allocation) instead of the immutable `Bindings`/`merge` threading. Off by
+     *  default; byte-identical to the reference matcher (differential-gated), falling back to it per query for
+     *  cases the trail cannot reproduce (custom grounded matchers). */
+    useTrail?: boolean;
+    /** Opt-in compact runtime `&self` atomspace. Off by default; when on, runtime additions are stored as flat
+     *  term ids and decoded only when a query or observable operation needs tree atoms. */
+    useFlatAtomspace?: boolean;
 }
 /** An empty environment for grounding table `gt`. Grow it with `addAtomToEnv`. */
 declare function emptyEnv(gt: GroundingTable): MinEnv;
@@ -316,11 +401,13 @@ declare function emptyEnv(gt: GroundingTable): MinEnv;
  *  gated by the 270/270 oracle. */
 declare function addAtomToEnv(env: MinEnv, x: Atom): void;
 declare function buildEnv(atoms: Atom[], gt: GroundingTable): MinEnv;
+type NamedSpace = AtomLog;
 interface World {
-    spaces: Map<string, Atom[]>;
+    spaces: Map<string, NamedSpace>;
     store: Map<number, Atom>;
     tokens: Map<string, Atom>;
     selfExtra: AtomLog;
+    flatSelfExtra: FlatAtomSpace | undefined;
     selfRules: Map<string, Array<[Atom, Atom]>>;
     selfVarRules: ReadonlyArray<[Atom, Atom]>;
     maxStackDepth: number;
@@ -358,11 +445,23 @@ 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). */
+/** Hooks for streaming the join: `onDescend`/`onAscend` bracket each variable binding as the search descends
+ *  and backtracks, and `onLeaf` fires at each full solution. The caller keeps whatever state it needs (a
+ *  partial map, or a trail synced to the descent) so the join itself never materializes the answer set. */
+interface WcoFoldHooks<V> {
+    onDescend(variable: string, value: V): void;
+    onAscend(variable: string): void;
+    onLeaf(): void;
+}
+/** The worst-case-optimal join (generic join / leapfrog-triejoin family) as a streaming fold: it drives the
+ *  same trie-cursor intersection as the textbook join but, instead of collecting binding maps, brackets each
+ *  variable binding with `onDescend`/`onAscend` and calls `onLeaf` per solution. 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. A consumer that only needs an aggregate (COUNT/EXISTS) keeps a trail
+ *  synced to the descent and never materializes the answer set (MORK's `trie_join_count` kernel). `key` maps
+ *  a value to a comparable string; pass `varOrder` to fix the elimination order (first-seen otherwise). */
+declare function wcoJoinFold<V>(rels: ReadonlyArray<Relation<V>>, key: (v: V) => string, hooks: WcoFoldHooks<V>, varOrder?: readonly string[]): void;
+/** Collect every join solution as a fresh binding map: a thin materializing wrapper over `wcoJoinFold`. */
 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. */
@@ -414,7 +513,7 @@ declare function bindingsToSubst(b: Bindings): Subst;
  *  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 instantiate(b: Bindings, a: Atom, suffix?: string, intern?: InternTable): Atom;
 
 declare function alphaEq(a: Atom, b: Atom): boolean;
 
@@ -466,6 +565,14 @@ interface QueryResult {
 declare const DEFAULT_FUEL = 100000;
 interface RunOptions {
     readonly tabling?: boolean;
+    readonly experimental?: {
+        readonly hashCons?: boolean;
+        readonly streamEmit?: boolean;
+        readonly tableBackchain?: boolean;
+        readonly trieSpace?: boolean;
+        readonly flatAtomspace?: boolean;
+        readonly trail?: boolean;
+    };
     readonly maxStackDepth?: number;
     readonly parEvalImpl?: (rulesSrc: string, branchSrcs: string[], firstOnly: boolean) => (string[] | null)[];
 }
@@ -479,7 +586,7 @@ declare function runProgram(src: string, fuel?: number, imports?: Map<string, At
 /** 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[]>;
+declare function runProgramAsync(src: string, asyncOps?: Map<string, AsyncGroundFn>, fuel?: number, imports?: Map<string, Atom[]>, opts?: RunOptions): 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 `()`. */
@@ -615,6 +722,8 @@ declare class Trail {
     bind(name: string, a: Atom): void;
     /** Follow variable bindings to the representative: a non-variable, or an unbound variable. */
     deref(a: Atom): Atom;
+    /** The atom currently bound to `$name`, if any (the direct binding, not dereferenced). */
+    get(name: string): Atom | undefined;
     /** 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,
@@ -629,4 +738,4 @@ declare class Trail {
  *  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 };
+export { type AsyncGroundFn, AsyncInSyncError, type Atom, BAIL, type BindingRel, type Bindings, CONCURRENCY_MODULE_SRC, CURRY_MODULE_SRC, type CompiledFns, type CompiledHolder, type CompiledImpureOps, type CompiledRunResult, DEFAULT_FUEL, type EqRel, type ExprAtom, FlatAtomSpace, FlatKB, type Frame, type GndAtom, type Ground, type GroundFn, type GroundMatcher, type GroundedExec, type GroundedMatch, type GroundingTable, type HeavyPattern, IMPURE_OPS, InMemorySpace, type IntVal, type InternTable, 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 WcoFoldHooks, type World, _internals, addAtomToEnv, addEqRaw, addInt, addValRaw, addVarBinding, addVarEquality, alphaEq, analyzePurity, applySubst, atomEq, atomSize, atomVars, baseTable, bindingsToSubst, buildEnv, builtinModules, callGrounded, canCompactAtom, canInternExprItems, canonInt, cmpIntVal, collectImports, collectVars, compileEnv, createInternTable, decodeAt, decodeAtom, emptyBindings, emptyEnv, emptyExpr, emptySubst, encodeAtom, encodeInto, encodePattern, eqRelations, eraseSubst, evalAtom, evalSequential, expr, extendSubst, format, freshenRule, fromRelations, gbool, getTypes, gfloat, gint, gnd, groundEq, groundType, gstr, gunit, hasEq, hasLoop, hashOf, initSt, instantiate, intAbs, intDiv, intMod, internAtom, internBuiltExpr, internExpr, isEmpty, isErrorAtom, isExpr, isGnd, isOraclePass, isSym, isVar, isZero, keyWellFormed, lookupSubst, lookupVal, makeValRel, matchAtoms, matchAtomsScoped, matchAtomsWith, matchFlatAt, merge, metaType, mettaEval, mettaEvalAsync, mixHash, mulInt, occurs, oracleReport, parse, parseAll, pettaOpNames, preludeAtoms, prependValRaw, relations, removeVal, runCompiled, runProgram, runProgramAsync, setOutputSink, setRawSink, size, someVal, standardTokenizer, stdTable, stdlibAtoms, strHash, subInt, sym, tableKey, toF64, unifiable, unifyTop, unifyTrail, valEntries, variable, wcoJoin, wcoJoinFold, williamTopK, withBuiltinModules };