@metta-ts/hyperon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MesTTo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# @metta-ts/hyperon
+
+A TypeScript class API for MeTTa atoms, spaces, and a runner, modeled on Hyperon's `hyperon.atoms`
+and `hyperon.base`. Where the Python package wraps a Rust core over FFI, this one wraps the immutable
+terms of [`@metta-ts/core`](../core) in classes. It runs anywhere TypeScript runs, with no native
+addon and no WASM.
+
+Hyperon's Python method names are kept as aliases next to the idiomatic TypeScript ones, so code
+ported from `hyperon` reads naturally: `get_name()` sits beside `name()`, `get_children()` beside
+`children()`, `add_atom()` beside `addAtom()`.
+
+## Atoms
+
+You build atoms with the short constructors `S`, `V`, `E`, `G`, and `ValueAtom`:
+
+```ts
+import { S, V, E, ValueAtom } from "@metta-ts/hyperon";
+
+S("parent");                       // a symbol
+V("x");                            // a variable, prints as $x
+E(S("parent"), S("tom"), V("c"));  // an expression (parent tom $c)
+ValueAtom(42);                     // a grounded number
+ValueAtom("hi");                   // a grounded string, prints as "hi"
+```
+
+Every atom answers `metatype()`, `equals(other)`, `toString()`, `iterate()` (depth-first), and
+`matchAtom(other)`. The kinds are `SymbolAtom`, `VariableAtom`, `ExpressionAtom`, and `GroundedAtom`;
+`SymbolAtom.name()` and `ExpressionAtom.children()` read the parts.
+
+## Matching and bindings
+
+`matchAtom` returns a `BindingsSet`, a set of binding frames. An empty set means no match.
+
+```ts
+import { S, V, E, ValueAtom } from "@metta-ts/hyperon";
+
+const set = E(S("point"), V("x"), V("y"))
+  .matchAtom(E(S("point"), ValueAtom(1), ValueAtom(2)));
+
+const frame = set.frames[0];
+frame.resolve(V("x"))?.toString(); // "1"
+frame.resolve(V("y"))?.toString(); // "2"
+```
+
+A `Bindings` frame records associations with `addVarBinding(v, atom)`, reads them with
+`resolve(v)` and `pairs()`, and combines with another frame via `merge`.
+
+## Spaces
+
+A `GroundingSpace` holds atoms. You add, query, and substitute:
+
+```ts
+import { GroundingSpace, S, V, E } from "@metta-ts/hyperon";
+
+const sp = new GroundingSpace();
+sp.addAtom(E(S("parent"), S("tom"), S("bob")));
+sp.addAtom(E(S("parent"), S("tom"), S("liz")));
+
+sp.subst(E(S("parent"), S("tom"), V("c")), V("c"))
+  .map((a) => a.toString());       // ["bob", "liz"]
+```
+
+For a Distributed AtomSpace backend, see [`@metta-ts/das-client`](../das-client), whose `DasLiveSpace`
+is the async analogue (a remote query is a network round-trip).
+
+## Running MeTTa
+
+The `MeTTa` runner evaluates programs and keeps its knowledge base across `run` calls.
+Non-bang atoms extend the knowledge base; each `!`-query returns its results.
+
+```ts
+import { MeTTa } from "@metta-ts/hyperon";
+
+const m = new MeTTa();
+m.run("(= (color) red)\n(= (color) green)");
+m.run("!(color)")[0].map((a) => a.toString()); // ["red", "green"]
+m.run("!(+ 1 2)")[0].map((a) => a.toString());  // ["3"]
+```
+
+`registerOperation(name, fn)` adds a grounded operation callable from
+MeTTa source; the function takes the argument atoms and returns the result atoms:
+
+```ts
+import { MeTTa, ValueAtom, GroundedAtom } from "@metta-ts/hyperon";
+
+const m = new MeTTa();
+m.registerOperation("double", (args) => {
+  const n = (args[0] as GroundedAtom).object().content as number;
+  return [ValueAtom(n * 2)];
+});
+m.run("!(double 21)")[0].map((a) => a.toString()); // ["42"]
+```
+
+`registerToken(regex, constr)` registers a custom token, `space()` exposes the knowledge base, and
+`getAtomTypes(atom)` returns the types the runner infers for an atom.
+
+The runner's `space()` is live: an atom added through it reaches the evaluator
+exactly as a non-bang atom in `run` does, querying it sees what the evaluator sees, and removing an
+atom retracts it from evaluation.
+
+```ts
+const m = new MeTTa();
+m.space().addAtom(parseRule("(= (greeting) hello)")); // reaches evaluation
+m.run("!(greeting)")[0].map((a) => a.toString());     // ["hello"]
+```
+
+## Grounded objects
+
+`ValueObject`, `OperationObject`, and `MatchableObject` wrap a JS value, a function, or a
+custom-matching value. `ValueAtom` converts primitives for you (`number` to Number, `string` to
+String, `boolean` to Bool); `G(obj, type?)` wraps any `GroundedObject`, and `GroundedAtom.object()`
+recovers it.
+
+Wrapping a non-primitive object registers it in a process-global table (the core's grounded value
+carries only an id, and the object must outlive any single wrapper). A long-running host that creates
+many grounded objects can reclaim that memory with `clearGroundedObjects()` once no grounded `ext`
+atom is still in use.
+
+## Optional modules
+
+Two grounded-operation modules from hyperon-experimental ship as opt-in registrations on a runner.
+
+The JSON module gives you `dict-space`, `get-keys`, `get-value`, `json-decode`, and `json-encode`:
+
+```ts
+import { MeTTa, registerJsonModule } from "@metta-ts/hyperon";
+
+const m = new MeTTa();
+registerJsonModule(m);
+m.run('!(json-decode "[1, 2, 3]")')[0].map((a) => a.toString());          // ["(1 2 3)"]
+m.run('(= (d) (dict-space ((a 1) (b 2))))');
+m.run("!(get-value (d) a)")[0].map((a) => a.toString());                  // ["1"]
+```
+
+The module catalog gives you `catalog-clear!`, `catalog-list!`, and `catalog-update!` over a
+`ModuleCatalog` you populate yourself (the dependency-free analogue of Hyperon's remote catalogs):
+
+```ts
+import { MeTTa, ModuleCatalog, registerCatalogModule } from "@metta-ts/hyperon";
+
+const m = new MeTTa();
+const catalog = new ModuleCatalog();
+catalog.register("local", ["mod-a", "mod-b"]);
+registerCatalogModule(m, catalog);
+m.run("!(catalog-list! all)");   // returns (); records into catalog.listing
+```
+
+## JavaScript interop
+
+Hyperon's Python binding has `py-atom`/`py-dot` to call Python from MeTTa, bridged over FFI. Here the
+engine is TypeScript, so there is no bridge: a grounded atom can hold a JS function and the interpreter
+runs it directly. `registerJsInterop(m)` exposes that (opt-in, since it can call arbitrary global JS):
+
+```ts
+import { MeTTa, registerJsInterop } from "@metta-ts/hyperon";
+
+const m = new MeTTa();
+registerJsInterop(m);
+m.run(`!((js-atom "Math.abs") -5)`)[0];                    // 5
+m.run(`!((js-atom "Math.max") 3 7 2)`)[0];                 // 7
+m.run(`!((js-dot "hello world" "toUpperCase"))`)[0];       // "HELLO WORLD"
+m.run(`!((js-dot (js-list (5 1 3)) "join") "-")`)[0];      // "5-1-3"
+m.run(`!(js-dot (js-dict (("a" 1) ("b" 2))) "b")`)[0];     // 2
+```
+
+`js-atom` resolves a dotted path from `globalThis` into a grounded atom (an executable one if it is a
+function); `js-dot` reads a property or method (methods come back bound to their object); `js-list` and
+`js-dict` build a JS array or object from MeTTa atoms.
+
+An `OperationAtom` that heads an expression is run by the interpreter, so a JS function wrapped as an
+atom is callable in-language. That is also what makes `registerAtom` with an `OperationAtom` work like
+Python's `bind! abs (py-atom ...)`:
+
+```ts
+m.registerAtom("dbl", OperationAtom("dbl", (a) =>
+  [ValueAtom((a as GroundedAtom).object().content as number * 2)]));
+m.run("!(dbl 21)")[0];                                     // 42
+```
+
+A grounded operation that throws surfaces as a MeTTa `(Error ...)` atom (an error the program can
+still inspect) rather than crashing the run. `evaluateAtom(atom)` evaluates a single constructed atom
+(the atom-level counterpart of `run`).
+
+## Docs
+
+API docs are generated with TypeDoc from the TSDoc comments: `pnpm --filter @metta-ts/hyperon docs`.

package/dist/index.d.ts

@@ -0,0 +1,436 @@
+import * as core from '@metta-ts/core';
+
+/**
+ * Variable bindings, modeled on Hyperon's `Bindings` and `BindingsSet`. A {@link Bindings} is one
+ * variable-to-atom frame; a {@link BindingsSet} is the set of frames produced by a match. They wrap the
+ * core's immutable binding relations behind a small mutable API.
+ */
+
+/** One frame of variable-to-atom associations. */
+declare class Bindings {
+    private rels;
+    /** The underlying immutable core relations. Replaced (not mutated) by the mutating methods. */
+    constructor(rels?: core.Bindings);
+    /** The core relations backing this frame. */
+    raw(): core.Bindings;
+    /** The atom bound to a variable, if any. */
+    resolve(variable: VariableAtom): Atom | undefined;
+    /** Bind a variable to an atom; returns `true` (the binding is recorded). */
+    addVarBinding(variable: VariableAtom, atom: Atom): boolean;
+    /** Python alias of {@link addVarBinding}. */
+    add_var_binding(variable: VariableAtom, atom: Atom): boolean;
+    /** Assert that two variables are equal (`$a = $b`); returns `true`. */
+    addVarEquality(a: VariableAtom, b: VariableAtom): boolean;
+    /** Python alias of {@link addVarEquality}. */
+    add_var_equality(a: VariableAtom, b: VariableAtom): boolean;
+    /** True when this frame has no associations. */
+    isEmpty(): boolean;
+    /** Python alias of {@link isEmpty}. */
+    is_empty(): boolean;
+    /** The variable-atom pairs in this frame. */
+    pairs(): [VariableAtom, Atom][];
+    /** Python alias of {@link pairs}. */
+    iterator(): [VariableAtom, Atom][];
+    /** Keep only the associations for the given variables. */
+    narrowVars(vars: VariableAtom[]): Bindings;
+    /** Python alias of {@link narrowVars}. */
+    narrow_vars(vars: VariableAtom[]): Bindings;
+    /** Merge with another frame, yielding the consistent combinations as a {@link BindingsSet}. */
+    merge(other: Bindings): BindingsSet;
+    /** A copy of this frame (the core relations are immutable, so the copy is independent). */
+    clone(): Bindings;
+    equals(other: Bindings): boolean;
+    toString(): string;
+}
+/** A set of binding frames; the result of a match. An empty set means no match; a set with one
+ *  empty frame means a match that binds nothing (variables may take any value). */
+declare class BindingsSet {
+    readonly frames: Bindings[];
+    constructor(frames?: Bindings[]);
+    /** A set with no frames (no valid match). */
+    static empty(): BindingsSet;
+    /** A set with a single empty frame (a match binding nothing). */
+    static single(): BindingsSet;
+    /** True when there are no frames. */
+    isEmpty(): boolean;
+    /** Python alias of {@link isEmpty}. */
+    is_empty(): boolean;
+    /** True when there is exactly one frame and it binds nothing. */
+    isSingle(): boolean;
+    /** Python alias of {@link isSingle}. */
+    is_single(): boolean;
+    /** The frame at an index. */
+    get(index: number): Bindings | undefined;
+    /** Iterate the frames. */
+    iterator(): Bindings[];
+    /** Add a frame to the set. */
+    push(bindings: Bindings): void;
+    /** Bind a variable to an atom in every frame; returns `true`. */
+    addVarBinding(variable: VariableAtom, value: Atom): boolean;
+    /** Python alias of {@link addVarBinding}. */
+    add_var_binding(variable: VariableAtom, value: Atom): boolean;
+    /** Assert that two variables are equal in every frame; returns `true`. */
+    addVarEquality(a: VariableAtom, b: VariableAtom): boolean;
+    /** Python alias of {@link addVarEquality}. */
+    add_var_equality(a: VariableAtom, b: VariableAtom): boolean;
+    /** Merge another set (or frame) into this one (cartesian merge of frames). */
+    mergeInto(input: BindingsSet | Bindings): void;
+    /** Python alias of {@link mergeInto}. */
+    merge_into(input: BindingsSet | Bindings): void;
+    /** A copy of this set. */
+    clone(): BindingsSet;
+    toString(): string;
+}
+
+/**
+ * Atom API: a TypeScript class surface over the functional `@metta-ts/core` term model, modeled on
+ * Hyperon's `hyperon.atoms`. It wraps immutable core atoms in classes; it does not bridge Python, Rust,
+ * or FFI. Python aliases (`get_name`, `get_metatype`, ...) sit beside idiomatic names (`name`,
+ * `metatype`, ...) for ported code.
+ */
+
+/** The kind of an atom: `Symbol`, `Variable`, `Expression`, or `Grounded`. */
+type MetaType = core.MetaType;
+/**
+ * Base class for every atom. Wraps one immutable core atom (`catom`) and exposes shared operations:
+ * metatype, structural equality, rendering, depth-first iteration, and matching.
+ */
+declare abstract class Atom {
+    readonly catom: core.Atom;
+    protected constructor(catom: core.Atom);
+    /** Wrap a core atom in the matching subclass. */
+    static fromCAtom(c: core.Atom): Atom;
+    /** The metatype (kind) of this atom. */
+    metatype(): MetaType;
+    /** Python alias of {@link metatype}. */
+    get_metatype(): MetaType;
+    /** Structural equality with another atom. */
+    equals(other: Atom): boolean;
+    /** MeTTa source rendering. */
+    toString(): string;
+    /** This atom and all descendants, depth-first (Hyperon `iterate`). */
+    iterate(): Atom[];
+    /** Match this atom against another, returning every resulting binding frame. */
+    matchAtom(other: Atom): BindingsSet;
+    /** Python alias of {@link matchAtom}. */
+    match_atom(other: Atom): BindingsSet;
+}
+/** A symbol: a single named concept. Symbols with the same name are the same atom. */
+declare class SymbolAtom extends Atom {
+    /** Wrap a core symbol atom. */
+    constructor(catom: core.Atom);
+    /** The symbol's name. */
+    name(): string;
+    /** Python alias of {@link name}. */
+    get_name(): string;
+}
+/** A variable: a placeholder that can be bound during matching. */
+declare class VariableAtom extends Atom {
+    /** Wrap a core variable atom. */
+    constructor(catom: core.Atom);
+    /** The variable's name (without the leading `$`). */
+    name(): string;
+    /** Python alias of {@link name}. */
+    get_name(): string;
+    /** Construct a variable from a name (Hyperon `parse_name`). */
+    static parseName(name: string): VariableAtom;
+}
+/** An expression: an ordered tuple of child atoms. */
+declare class ExpressionAtom extends Atom {
+    /** Wrap a core expression atom. */
+    constructor(catom: core.Atom);
+    /** The child atoms, in order. */
+    children(): Atom[];
+    /** Python alias of {@link children}. */
+    get_children(): Atom[];
+}
+/** Wraps arbitrary content inside a grounded atom, optionally with a display id. */
+declare class GroundedObject {
+    readonly content: unknown;
+    readonly id?: string | undefined;
+    constructor(content: unknown, id?: string | undefined);
+    toString(): string;
+    /** A copy of this object (content is shared). */
+    copy(): GroundedObject;
+}
+/** A grounded object compared by the equality of its content. */
+declare class ValueObject extends GroundedObject {
+    /** The wrapped value. */
+    get value(): unknown;
+    equals(other: ValueObject): boolean;
+}
+/** A value object that can define custom matching against an atom (Hyperon `MatchableObject`). */
+declare class MatchableObject extends ValueObject {
+    /** Override to define matching behavior. Throws by default. */
+    match_(atom: Atom): unknown[];
+}
+/** A grounded operation: a named function callable as a grounded atom. */
+declare class OperationObject extends GroundedObject {
+    readonly opName: string;
+    readonly op: (...args: Atom[]) => Atom[];
+    readonly unwrap: boolean;
+    constructor(opName: string, op: (...args: Atom[]) => Atom[], unwrap?: boolean);
+    /** Run the operation over the argument atoms. */
+    execute(...args: Atom[]): Atom[];
+}
+/** Drop every registered grounded object. Call only when no grounded `ext` atom is still in use;
+ *  afterwards `GroundedAtom.object()` on a cleared atom degrades to a `ValueObject` over its string id. */
+declare function clearGroundedObjects(): void;
+/** A grounded atom: value, space, or operation content wrapped as an atom. */
+declare class GroundedAtom extends Atom {
+    private obj;
+    /** Wrap a core grounded atom, optionally remembering the JS object behind it. */
+    constructor(catom: core.Atom, obj?: GroundedObject);
+    /** The wrapped object: the original `GroundedObject` if known, otherwise a `ValueObject` over the
+     *  grounded value. The result is cached so repeated calls return the same instance. */
+    object(): GroundedObject;
+    /** Python alias of {@link object}. */
+    get_object(): GroundedObject;
+    /** The plain JS value behind this grounded atom, typed as `T`. */
+    jsValue<T = unknown>(): T;
+    /** The grounded type atom. */
+    groundedType(): Atom;
+    /** Python alias of {@link groundedType}. */
+    get_grounded_type(): Atom;
+}
+/** The plain JS value behind a core ground (numbers, strings, booleans; `undefined` for unit). */
+declare function groundToJs(g: core.Ground): unknown;
+/** Construct a {@link SymbolAtom}. */
+declare const S: (name: string) => SymbolAtom;
+/** Construct a {@link VariableAtom}. */
+declare const V: (name: string) => VariableAtom;
+/** Construct an {@link ExpressionAtom} from child atoms. */
+declare const E: (...children: Atom[]) => ExpressionAtom;
+/** Construct a {@link GroundedAtom} from a grounded object, optionally typed. An `OperationObject`
+ *  becomes executable: when it heads `(<atom> arg...)`, the interpreter runs its operation. */
+declare function G(obj: GroundedObject, type?: Atom): GroundedAtom;
+/**
+ * Wrap a JS value in a grounded atom. Without `typeName`, primitives become MeTTa primitives
+ * (`number` -> Number, `string` -> String, `boolean` -> Bool) and anything else is wrapped in a
+ * {@link ValueObject}. With `typeName`, the value is always wrapped in a `ValueObject` carrying that
+ * type, so the requested type is honored for primitives too.
+ */
+declare function ValueAtom(value: unknown, typeName?: string): GroundedAtom;
+/** Construct a grounded operation atom (Hyperon `OperationAtom`). The operation runs over atoms;
+ *  register it in a {@link MeTTa} runner's tokenizer/grounding to call it from MeTTa source. */
+declare function OperationAtom(name: string, op: (...args: Atom[]) => Atom[], unwrap?: boolean): GroundedAtom;
+/** The built-in type atoms (Hyperon `AtomType`). */
+declare const AtomType: {
+    /** `%Undefined%`. */
+    readonly UNDEFINED: SymbolAtom;
+    /** `Type`. */
+    readonly TYPE: SymbolAtom;
+    /** `Atom`. */
+    readonly ATOM: SymbolAtom;
+    /** `Symbol`. */
+    readonly SYMBOL: SymbolAtom;
+    /** `Variable`. */
+    readonly VARIABLE: SymbolAtom;
+    /** `Expression`. */
+    readonly EXPRESSION: SymbolAtom;
+    /** `Grounded`. */
+    readonly GROUNDED: SymbolAtom;
+    /** `Number`. */
+    readonly NUMBER: SymbolAtom;
+    /** `Bool`. */
+    readonly BOOL: SymbolAtom;
+    /** `String`. */
+    readonly STRING: SymbolAtom;
+};
+/** Display type name for an atom, for use in error messages (e.g. `Number`, `String`,
+ *  `Symbol`, `Expression`). Grounded atoms report their value type rather than just `Grounded`. */
+declare function friendlyTypeName(atom: Atom): string;
+/** True when an atom is an `(Error ...)` expression. */
+declare function atomIsError(atom: Atom): boolean;
+/** True when two atoms are alpha-equivalent (equal up to consistent variable renaming). */
+declare function atomsAreEquivalent(first: Atom, second: Atom): boolean;
+
+/**
+ * Runtime API: spaces, tokenizer, parser, and MeTTa runner, modeled on Hyperon's `hyperon.base` and
+ * `hyperon.runner`. TypeScript surface over `@metta-ts/core`.
+ */
+
+/** A reference to a Space: a store of atoms that can be added to, queried, and substituted over. */
+declare class SpaceRef {
+    readonly space: core.Space;
+    constructor(space: core.Space);
+    /** Add an atom to the space. */
+    addAtom(atom: Atom): void;
+    /** Python alias of {@link addAtom}. */
+    add_atom(atom: Atom): void;
+    /** Remove an atom from the space; returns whether one was removed. */
+    removeAtom(atom: Atom): boolean;
+    /** Python alias of {@link removeAtom}. */
+    remove_atom(atom: Atom): boolean;
+    /** Every atom in the space. */
+    getAtoms(): Atom[];
+    /** Python alias of {@link getAtoms}. */
+    get_atoms(): Atom[];
+    /** The number of atoms in the space. */
+    atomCount(): number;
+    /** Python alias of {@link atomCount}. */
+    atom_count(): number;
+    /** Match a pattern against the space, returning the binding frames. */
+    query(pattern: Atom): BindingsSet;
+    /** Match `pattern`, then instantiate `template` under each resulting binding. */
+    subst(pattern: Atom, template: Atom): Atom[];
+}
+/** A space implemented in memory (Hyperon `GroundingSpace`). */
+declare class GroundingSpace extends SpaceRef {
+    constructor();
+}
+/** Turns words and string literals into atoms via registered `(regex, constructor)` pairs. */
+declare class Tokenizer {
+    readonly ctok: core.Tokenizer;
+    constructor(ctok?: core.Tokenizer);
+    /** Register a token: text matching `regex` becomes the atom built by `constr`. */
+    registerToken(regex: RegExp, constr: (token: string) => Atom): void;
+    /** Python alias of {@link registerToken}. */
+    register_token(regex: RegExp, constr: (token: string) => Atom): void;
+}
+/** Parses S-expression MeTTa text into atoms, using a {@link Tokenizer} for leaf tokens. */
+declare class SExprParser {
+    private readonly text;
+    constructor(text: string);
+    /** Parse the first atom (Hyperon `parse`). */
+    parse(tokenizer: Tokenizer): Atom | undefined;
+    /** Parse every top-level atom. */
+    parseAll(tokenizer: Tokenizer): Atom[];
+}
+/**
+ * MeTTa runner. Evaluates programs while preserving a knowledge base and grounding across calls
+ * (REPL-style). Build it, `run` source, register tokens and grounded operations.
+ */
+declare class MeTTa {
+    private readonly gt;
+    private readonly tok;
+    private env;
+    private st;
+    private readonly kb;
+    private readonly _space;
+    constructor();
+    private addToKb;
+    private removeFromKb;
+    /** Run MeTTa source. Non-bang atoms extend the knowledge base; each `!`-query yields its results.
+     *  Returns one atom list per `!`-query, in order. */
+    run(program: string, fuel?: number): Atom[][];
+    /** Run MeTTa source asynchronously, awaiting any async grounded operations (registered with
+     *  {@link registerAsyncOperation}). Identical to {@link run} for a program with no async ops. */
+    runAsync(program: string, fuel?: number): Promise<Atom[][]>;
+    /** Register an async grounded operation callable from MeTTa source by `name` (resolved by the async
+     *  runner). The function receives argument atoms and resolves to result atoms. A rejection becomes a
+     *  MeTTa `(Error ...)` atom. Use it for I/O: fetch, a DAS query, a timer. */
+    registerAsyncOperation(name: string, op: (args: Atom[]) => Promise<Atom[]>): void;
+    /** Parse every top-level atom of a program. */
+    parseAll(program: string): Atom[];
+    /** Parse the first atom of a program. */
+    parseSingle(program: string): Atom | undefined;
+    /** Evaluate a single atom against the runner's knowledge base (Hyperon `evaluate_atom`); returns its
+     *  results. Unlike `run`, it takes an atom rather than source text. */
+    evaluateAtom(atom: Atom, fuel?: number): Atom[];
+    /** Python alias of {@link evaluateAtom}. */
+    evaluate_atom(atom: Atom, fuel?: number): Atom[];
+    /** Evaluate a single atom, awaiting any async grounded operations reached during evaluation (those
+     *  registered with {@link registerAsyncOperation}). Identical to {@link evaluateAtom} when no async op
+     *  is reached. */
+    evaluateAtomAsync(atom: Atom, fuel?: number): Promise<Atom[]>;
+    /** The runner's top-level space. Atoms added through it reach the evaluator's knowledge base
+     *  (same as a non-bang atom in `run`), and querying it sees what the evaluator sees. Removing an
+     *  atom retracts it from evaluation too. */
+    space(): SpaceRef;
+    /** The runner's tokenizer. */
+    tokenizer(): Tokenizer;
+    /** Register a custom token (text matching `regex` becomes `constr`'s atom). */
+    registerToken(regex: RegExp, constr: (token: string) => Atom): void;
+    /** Register a symbol as a token that produces a fixed atom. */
+    registerAtom(name: string, atom: Atom): void;
+    /** Register a grounded operation callable from MeTTa source by `name`. The function receives argument
+     *  atoms and returns result atoms. A thrown error becomes a MeTTa `(Error ...)` atom instead of
+     *  crashing the run. Throw {@link IncorrectArgumentError} to leave the expression unevaluated so other
+     *  rewrite rules can try (MeTTa's multiple dispatch on a type mismatch). */
+    registerOperation(name: string, op: (args: Atom[]) => Atom[]): void;
+    /** Every type the runner infers for an atom (Hyperon `get_atom_types`). */
+    getAtomTypes(atom: Atom): Atom[];
+    /** Python alias of {@link getAtomTypes}. */
+    get_atom_types(atom: Atom): Atom[];
+}
+/** Throw this from a {@link MeTTa.registerOperation} handler to signal wrong arguments and leave the
+ *  expression unevaluated for other rules (the core's `incorrectArgument`) instead of producing a hard
+ *  `(Error ...)` atom. */
+declare class IncorrectArgumentError extends Error {
+}
+/** The MeTTa standard tokenizer as a wrapped {@link Tokenizer} (integers, floats, `True`/`False`). */
+declare function standardTokenizer(): Tokenizer;
+
+/**
+ * JSON module, modeled on hyperon-experimental's `hyperon.stdlib` JSON operations. Register it on a
+ * {@link MeTTa} runner to make these grounded operations callable from MeTTa source:
+ *
+ * - `dict-space`  `(-> Expression Grounded)`: build a Space of `(key value)` pairs.
+ * - `get-keys`    `(-> Grounded Atom)`: every key in a dict-space (one result per key).
+ * - `get-value`   `(-> Grounded Atom %Undefined%)`: the value tied to a key (empty if absent).
+ * - `json-decode` `(-> String Atom)`: JSON text to MeTTa (array to expression, object to dict-space,
+ *   string to String, number to Number, bool to Bool, null to `null`).
+ * - `json-encode` `(-> Atom String)`: MeTTa to JSON text (the inverse).
+ */
+
+/** A grounded value wrapping a Space, so a dict-space round-trips through grounded atoms. */
+declare class SpaceValue extends ValueObject {
+    readonly space: GroundingSpace;
+    constructor(space: GroundingSpace);
+    toString(): string;
+}
+/** Register the JSON module's operations on a runner. */
+declare function registerJsonModule(m: MeTTa): void;
+
+/** An in-memory registry of named module catalogs. */
+declare class ModuleCatalog {
+    private readonly catalogs;
+    /** One line per `catalog-list!` call, so tests and UIs can observe the side effect. */
+    readonly listing: string[];
+    /** The names of catalogs updated by `catalog-update!`. */
+    readonly updated: string[];
+    /** Add or replace a named catalog's module list. */
+    register(name: string, modules: string[]): void;
+    /** The module names in a catalog. */
+    modules(name: string): string[];
+    /** The catalog names, in insertion order. */
+    names(): string[];
+    private targets;
+    /** Clear one catalog (or `all`). */
+    clear(target: string): void;
+    /** Record the contents of one catalog (or `all`) into {@link listing}. */
+    list(target: string): void;
+    /** Mark one catalog (or `all`) updated. */
+    update(target: string): void;
+}
+/** Register the catalog operations on a runner, backed by the given catalog. */
+declare function registerCatalogModule(m: MeTTa, catalog: ModuleCatalog): void;
+
+/**
+ * JavaScript interop, the TypeScript analogue of Hyperon's Python interop (py-atom/py-dot/py-list/
+ * py-dict). The MeTTa engine runs in TypeScript, so a grounded atom can hold a JS function and the
+ * interpreter executes it directly (see GroundedAtom exec wiring). Register with `registerJsInterop(m)`;
+ * opt-in because it can resolve and call arbitrary global JS.
+ *
+ * - `js-atom`  `(js-atom "Math.abs")`: resolve a dotted path from `globalThis` into a grounded atom
+ *   (an executable one if it is a function), e.g. `((js-atom "Math.abs") -5)` -> 5.
+ * - `js-dot`   `(js-dot <obj> "prop")`: read a property/method of a wrapped JS object; a method is
+ *   returned bound to the object so `((js-dot <s> "toUpperCase"))` works.
+ * - `js-list`  `(js-list (1 2 3))`: a JS array from the expression's elements.
+ * - `js-dict`  `(js-dict (("a" 1) ("b" 2)))`: a JS object from (key value) pairs.
+ */
+
+/** Marks a grounded atom that wraps an arbitrary JS value (object/array), for round-tripping. */
+declare class JsValue extends ValueObject {
+}
+/** The plain JS value behind an atom: wrapped JS values unwrap to themselves, grounded primitives to
+ *  their content, symbols to their name, expressions to arrays; everything else to its text. */
+declare function atomToJs(atom: Atom): unknown;
+/** Wrap a JS value as an atom: functions become executable operation atoms, primitives become grounded
+ *  primitives, everything else is wrapped in a {@link JsValue} grounded atom. */
+declare function jsToAtom(value: unknown): Atom;
+/** Register the JS interop operations on a runner. */
+declare function registerJsInterop(m: MeTTa): void;
+
+export { Atom, AtomType, Bindings, BindingsSet, E, ExpressionAtom, G, GroundedAtom, GroundedObject, GroundingSpace, IncorrectArgumentError, JsValue, MatchableObject, MeTTa, type MetaType, ModuleCatalog, OperationAtom, OperationObject, S, SExprParser, SpaceRef, SpaceValue, SymbolAtom, Tokenizer, V, ValueAtom, ValueObject, VariableAtom, atomIsError, atomToJs, atomsAreEquivalent, clearGroundedObjects, friendlyTypeName, groundToJs, jsToAtom, registerCatalogModule, registerJsInterop, registerJsonModule, standardTokenizer };