@metta-ts/hyperon 1.0.0

package/dist/index.js

@@ -0,0 +1,1049 @@
+// src/atoms.ts
+import * as core2 from "@metta-ts/core";
+
+// src/bindings.ts
+import * as core from "@metta-ts/core";
+var Bindings = class _Bindings {
+  /** The underlying immutable core relations. Replaced (not mutated) by the mutating methods. */
+  constructor(rels = core.emptyBindings) {
+    this.rels = rels;
+  }
+  rels;
+  /** The core relations backing this frame. */
+  raw() {
+    return this.rels;
+  }
+  /** The atom bound to a variable, if any. */
+  resolve(variable2) {
+    const a = core.lookupVal(this.rels, variable2.name());
+    return a === void 0 ? void 0 : Atom.fromCAtom(a);
+  }
+  /** Bind a variable to an atom; returns `true` (the binding is recorded). */
+  addVarBinding(variable2, atom) {
+    this.rels = core.addValRaw(this.rels, variable2.name(), atom.catom);
+    return true;
+  }
+  /** Python alias of {@link addVarBinding}. */
+  add_var_binding(variable2, atom) {
+    return this.addVarBinding(variable2, atom);
+  }
+  /** Assert that two variables are equal (`$a = $b`); returns `true`. */
+  addVarEquality(a, b) {
+    this.rels = core.addEqRaw(this.rels, a.name(), b.name());
+    return true;
+  }
+  /** Python alias of {@link addVarEquality}. */
+  add_var_equality(a, b) {
+    return this.addVarEquality(a, b);
+  }
+  /** True when this frame has no associations. */
+  isEmpty() {
+    return this.rels.length === 0;
+  }
+  /** Python alias of {@link isEmpty}. */
+  is_empty() {
+    return this.isEmpty();
+  }
+  /** The variable-atom pairs in this frame. */
+  pairs() {
+    const out = [];
+    for (const r of this.rels) if (r.tag === "val") out.push([V(r.x), Atom.fromCAtom(r.a)]);
+    return out;
+  }
+  /** Python alias of {@link pairs}. */
+  iterator() {
+    return this.pairs();
+  }
+  /** Keep only the associations for the given variables. */
+  narrowVars(vars) {
+    const keep = new Set(vars.map((v) => v.name()));
+    const kept = this.rels.filter((r) => r.tag === "val" && keep.has(r.x));
+    return new _Bindings(kept);
+  }
+  /** Python alias of {@link narrowVars}. */
+  narrow_vars(vars) {
+    return this.narrowVars(vars);
+  }
+  /** Merge with another frame, yielding the consistent combinations as a {@link BindingsSet}. */
+  merge(other) {
+    return new BindingsSet(core.merge(this.rels, other.rels).map((b) => new _Bindings(b)));
+  }
+  /** A copy of this frame (the core relations are immutable, so the copy is independent). */
+  clone() {
+    return new _Bindings(this.rels);
+  }
+  equals(other) {
+    const a = this.pairs();
+    const b = other.pairs();
+    if (a.length !== b.length) return false;
+    return a.every(([v, at]) => {
+      const m = b.find(([v2]) => v2.name() === v.name());
+      return m !== void 0 && core.atomEq(at.catom, m[1].catom);
+    });
+  }
+  toString() {
+    return `{ ${this.pairs().map(([v, a]) => `${v.toString()}: ${a.toString()}`).join(", ")} }`;
+  }
+};
+var BindingsSet = class _BindingsSet {
+  constructor(frames = [new Bindings()]) {
+    this.frames = frames;
+  }
+  frames;
+  /** A set with no frames (no valid match). */
+  static empty() {
+    return new _BindingsSet([]);
+  }
+  /** A set with a single empty frame (a match binding nothing). */
+  static single() {
+    return new _BindingsSet([new Bindings()]);
+  }
+  /** True when there are no frames. */
+  isEmpty() {
+    return this.frames.length === 0;
+  }
+  /** Python alias of {@link isEmpty}. */
+  is_empty() {
+    return this.isEmpty();
+  }
+  /** True when there is exactly one frame and it binds nothing. */
+  isSingle() {
+    return this.frames.length === 1 && this.frames[0].isEmpty();
+  }
+  /** Python alias of {@link isSingle}. */
+  is_single() {
+    return this.isSingle();
+  }
+  /** The frame at an index. */
+  get(index) {
+    return this.frames[index];
+  }
+  /** Iterate the frames. */
+  iterator() {
+    return this.frames;
+  }
+  /** Add a frame to the set. */
+  push(bindings) {
+    this.frames.push(bindings);
+  }
+  /** Bind a variable to an atom in every frame; returns `true`. */
+  addVarBinding(variable2, value) {
+    for (const f of this.frames) f.addVarBinding(variable2, value);
+    return true;
+  }
+  /** Python alias of {@link addVarBinding}. */
+  add_var_binding(variable2, value) {
+    return this.addVarBinding(variable2, value);
+  }
+  /** Assert that two variables are equal in every frame; returns `true`. */
+  addVarEquality(a, b) {
+    for (const f of this.frames) f.addVarEquality(a, b);
+    return true;
+  }
+  /** Python alias of {@link addVarEquality}. */
+  add_var_equality(a, b) {
+    return this.addVarEquality(a, b);
+  }
+  /** Merge another set (or frame) into this one (cartesian merge of frames). */
+  mergeInto(input) {
+    const others = input instanceof _BindingsSet ? input.frames : [input];
+    const merged = [];
+    for (const a of this.frames) for (const b of others) merged.push(...a.merge(b).frames);
+    this.frames.length = 0;
+    this.frames.push(...merged);
+  }
+  /** Python alias of {@link mergeInto}. */
+  merge_into(input) {
+    this.mergeInto(input);
+  }
+  /** A copy of this set. */
+  clone() {
+    return new _BindingsSet(this.frames.map((f) => f.clone()));
+  }
+  toString() {
+    return `[ ${this.frames.map((f) => f.toString()).join(", ")} ]`;
+  }
+};
+
+// src/atoms.ts
+var Atom = class _Atom {
+  constructor(catom) {
+    this.catom = catom;
+  }
+  catom;
+  /** Wrap a core atom in the matching subclass. */
+  static fromCAtom(c) {
+    switch (c.kind) {
+      case "sym":
+        return new SymbolAtom(c);
+      case "var":
+        return new VariableAtom2(c);
+      case "expr":
+        return new ExpressionAtom(c);
+      case "gnd":
+        return new GroundedAtom(c);
+    }
+  }
+  /** The metatype (kind) of this atom. */
+  metatype() {
+    return core2.metaType(this.catom);
+  }
+  /** Python alias of {@link metatype}. */
+  get_metatype() {
+    return this.metatype();
+  }
+  /** Structural equality with another atom. */
+  equals(other) {
+    return core2.atomEq(this.catom, other.catom);
+  }
+  /** MeTTa source rendering. */
+  toString() {
+    return core2.format(this.catom);
+  }
+  /** This atom and all descendants, depth-first (Hyperon `iterate`). */
+  iterate() {
+    const out = [];
+    const go = (c) => {
+      out.push(_Atom.fromCAtom(c));
+      if (c.kind === "expr") for (const it of c.items) go(it);
+    };
+    go(this.catom);
+    return out;
+  }
+  /** Match this atom against another, returning every resulting binding frame. */
+  matchAtom(other) {
+    return new BindingsSet(core2.matchAtoms(this.catom, other.catom).map((b) => new Bindings(b)));
+  }
+  /** Python alias of {@link matchAtom}. */
+  match_atom(other) {
+    return this.matchAtom(other);
+  }
+};
+function assertKind(catom, kind, cls) {
+  if (catom.kind !== kind) throw new Error(`${cls} expects a '${kind}' atom, got '${catom.kind}'`);
+}
+var SymbolAtom = class extends Atom {
+  /** Wrap a core symbol atom. */
+  constructor(catom) {
+    assertKind(catom, "sym", "SymbolAtom");
+    super(catom);
+  }
+  /** The symbol's name. */
+  name() {
+    return this.catom.name;
+  }
+  /** Python alias of {@link name}. */
+  get_name() {
+    return this.name();
+  }
+};
+var VariableAtom2 = class _VariableAtom extends Atom {
+  /** Wrap a core variable atom. */
+  constructor(catom) {
+    assertKind(catom, "var", "VariableAtom");
+    super(catom);
+  }
+  /** The variable's name (without the leading `$`). */
+  name() {
+    return this.catom.name;
+  }
+  /** Python alias of {@link name}. */
+  get_name() {
+    return this.name();
+  }
+  /** Construct a variable from a name (Hyperon `parse_name`). */
+  static parseName(name) {
+    return new _VariableAtom(core2.variable(name));
+  }
+};
+var ExpressionAtom = class extends Atom {
+  /** Wrap a core expression atom. */
+  constructor(catom) {
+    assertKind(catom, "expr", "ExpressionAtom");
+    super(catom);
+  }
+  /** The child atoms, in order. */
+  children() {
+    return this.catom.items.map(Atom.fromCAtom);
+  }
+  /** Python alias of {@link children}. */
+  get_children() {
+    return this.children();
+  }
+};
+var GroundedObject = class {
+  constructor(content, id) {
+    this.content = content;
+    this.id = id;
+  }
+  content;
+  id;
+  toString() {
+    return this.id ?? String(this.content);
+  }
+  /** A copy of this object (content is shared). */
+  copy() {
+    return this;
+  }
+};
+var ValueObject = class extends GroundedObject {
+  /** The wrapped value. */
+  get value() {
+    return this.content;
+  }
+  equals(other) {
+    return this.content === other.content;
+  }
+};
+var MatchableObject = class extends ValueObject {
+  /** Override to define matching behavior. Throws by default. */
+  match_(atom) {
+    throw new Error(`MatchableObject.match_ must be overridden (got ${atom.toString()})`);
+  }
+};
+var OperationObject = class extends GroundedObject {
+  constructor(opName, op, unwrap = true) {
+    super(op, opName);
+    this.opName = opName;
+    this.op = op;
+    this.unwrap = unwrap;
+  }
+  opName;
+  op;
+  unwrap;
+  /** Run the operation over the argument atoms. */
+  execute(...args) {
+    return this.op(...args);
+  }
+};
+var extCounter = 0;
+var EXT_OBJECTS = /* @__PURE__ */ new Map();
+function clearGroundedObjects() {
+  EXT_OBJECTS.clear();
+}
+var GroundedAtom = class extends Atom {
+  obj;
+  /** Wrap a core grounded atom, optionally remembering the JS object behind it. */
+  constructor(catom, obj) {
+    assertKind(catom, "gnd", "GroundedAtom");
+    super(catom);
+    this.obj = obj;
+  }
+  /** 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() {
+    if (this.obj !== void 0) return this.obj;
+    const g = this.catom.value;
+    if (g.g === "ext") {
+      const o = EXT_OBJECTS.get(g.id);
+      if (o !== void 0) {
+        this.obj = o;
+        return o;
+      }
+      this.obj = new ValueObject(g.id);
+      return this.obj;
+    }
+    this.obj = new ValueObject(groundToJs(g));
+    return this.obj;
+  }
+  /** Python alias of {@link object}. */
+  get_object() {
+    return this.object();
+  }
+  /** The plain JS value behind this grounded atom, typed as `T`. */
+  jsValue() {
+    return this.object().content;
+  }
+  /** The grounded type atom. */
+  groundedType() {
+    return Atom.fromCAtom(this.catom.typ);
+  }
+  /** Python alias of {@link groundedType}. */
+  get_grounded_type() {
+    return this.groundedType();
+  }
+};
+function groundToJs(g) {
+  switch (g.g) {
+    case "int":
+    case "float":
+      return g.n;
+    case "str":
+      return g.s;
+    case "bool":
+      return g.b;
+    case "unit":
+      return void 0;
+    case "error":
+      return g.msg;
+    case "ext":
+      return EXT_OBJECTS.get(g.id);
+  }
+}
+var S = (name) => new SymbolAtom(core2.sym(name));
+var V = (name) => new VariableAtom2(core2.variable(name));
+var E = (...children) => new ExpressionAtom(core2.expr(children.map((c) => c.catom)));
+function G(obj, type) {
+  const id = `gnd-${extCounter++}`;
+  EXT_OBJECTS.set(id, obj);
+  const kind = obj instanceof OperationObject ? "operation" : "value";
+  const typ = type?.catom ?? core2.sym("%Undefined%");
+  const exec = obj instanceof OperationObject ? (args) => obj.execute(...args.map(Atom.fromCAtom)).map((a) => a.catom) : void 0;
+  const match = obj instanceof MatchableObject ? (other) => obj.match_(Atom.fromCAtom(other)) : void 0;
+  return new GroundedAtom(core2.gnd({ g: "ext", kind, id }, typ, exec, match), obj);
+}
+function ValueAtom(value, typeName) {
+  if (typeName === void 0) {
+    if (typeof value === "number")
+      return new GroundedAtom(Number.isInteger(value) ? core2.gint(value) : core2.gfloat(value));
+    if (typeof value === "string") return new GroundedAtom(core2.gstr(value));
+    if (typeof value === "boolean") return new GroundedAtom(core2.gbool(value));
+    return G(new ValueObject(value));
+  }
+  return G(new ValueObject(value), Atom.fromCAtom(core2.sym(typeName)));
+}
+function OperationAtom(name, op, unwrap = true) {
+  return G(new OperationObject(name, op, unwrap));
+}
+var AtomType = {
+  /** `%Undefined%`. */
+  UNDEFINED: S("%Undefined%"),
+  /** `Type`. */
+  TYPE: S("Type"),
+  /** `Atom`. */
+  ATOM: S("Atom"),
+  /** `Symbol`. */
+  SYMBOL: S("Symbol"),
+  /** `Variable`. */
+  VARIABLE: S("Variable"),
+  /** `Expression`. */
+  EXPRESSION: S("Expression"),
+  /** `Grounded`. */
+  GROUNDED: S("Grounded"),
+  /** `Number`. */
+  NUMBER: S("Number"),
+  /** `Bool`. */
+  BOOL: S("Bool"),
+  /** `String`. */
+  STRING: S("String")
+};
+function friendlyTypeName(atom) {
+  const c = atom.catom;
+  if (c.kind === "gnd") {
+    switch (c.value.g) {
+      case "int":
+        return "Number (integer)";
+      case "float":
+        return "Number (float)";
+      case "str":
+        return "String";
+      case "bool":
+        return "Bool";
+      case "unit":
+        return "Unit";
+      case "error":
+        return "Error";
+      case "ext":
+        return "Grounded";
+    }
+  }
+  return atom.metatype();
+}
+function atomIsError(atom) {
+  return core2.isErrorAtom(atom.catom);
+}
+function atomsAreEquivalent(first, second) {
+  return core2.alphaEq(first.catom, second.catom);
+}
+
+// src/base.ts
+import * as core3 from "@metta-ts/core";
+var DEFAULT_FUEL = 1e5;
+var SpaceRef = class {
+  constructor(space) {
+    this.space = space;
+  }
+  space;
+  /** Add an atom to the space. */
+  addAtom(atom) {
+    this.space.add(atom.catom);
+  }
+  /** Python alias of {@link addAtom}. */
+  add_atom(atom) {
+    this.addAtom(atom);
+  }
+  /** Remove an atom from the space; returns whether one was removed. */
+  removeAtom(atom) {
+    return this.space.remove(atom.catom);
+  }
+  /** Python alias of {@link removeAtom}. */
+  remove_atom(atom) {
+    return this.removeAtom(atom);
+  }
+  /** Every atom in the space. */
+  getAtoms() {
+    return this.space.atoms().map(Atom.fromCAtom);
+  }
+  /** Python alias of {@link getAtoms}. */
+  get_atoms() {
+    return this.getAtoms();
+  }
+  /** The number of atoms in the space. */
+  atomCount() {
+    return this.space.atoms().length;
+  }
+  /** Python alias of {@link atomCount}. */
+  atom_count() {
+    return this.atomCount();
+  }
+  /** Match a pattern against the space, returning the binding frames. */
+  query(pattern) {
+    return new BindingsSet(this.space.query(pattern.catom).map((b) => new Bindings(b)));
+  }
+  /** Match `pattern`, then instantiate `template` under each resulting binding. */
+  subst(pattern, template) {
+    return this.space.query(pattern.catom).map((b) => Atom.fromCAtom(core3.instantiate(b, template.catom)));
+  }
+};
+var GroundingSpace = class extends SpaceRef {
+  constructor() {
+    super(new core3.InMemorySpace());
+  }
+};
+var RunnerSpace = class {
+  constructor(onAdd, onRemove, list) {
+    this.onAdd = onAdd;
+    this.onRemove = onRemove;
+    this.list = list;
+  }
+  onAdd;
+  onRemove;
+  list;
+  add(atom) {
+    this.onAdd(atom);
+  }
+  remove(atom) {
+    return this.onRemove(atom);
+  }
+  query(pattern, freshen) {
+    const out = [];
+    for (const a of this.list()) {
+      const target2 = freshen ? freshen(a) : a;
+      for (const b of core3.matchAtoms(pattern, target2)) out.push(b);
+    }
+    return out;
+  }
+  atoms() {
+    return this.list();
+  }
+};
+var Tokenizer2 = class {
+  constructor(ctok = new core3.Tokenizer()) {
+    this.ctok = ctok;
+  }
+  ctok;
+  /** Register a token: text matching `regex` becomes the atom built by `constr`. */
+  registerToken(regex, constr) {
+    this.ctok.register(regex, (s) => constr(s).catom);
+  }
+  /** Python alias of {@link registerToken}. */
+  register_token(regex, constr) {
+    this.registerToken(regex, constr);
+  }
+};
+var SExprParser = class {
+  constructor(text) {
+    this.text = text;
+  }
+  text;
+  /** Parse the first atom (Hyperon `parse`). */
+  parse(tokenizer) {
+    const a = core3.parse(this.text, tokenizer.ctok);
+    return a === void 0 ? void 0 : Atom.fromCAtom(a);
+  }
+  /** Parse every top-level atom. */
+  parseAll(tokenizer) {
+    return core3.parseAll(this.text, tokenizer.ctok).map((t) => Atom.fromCAtom(t.atom));
+  }
+};
+var MeTTa = class {
+  gt;
+  tok;
+  env;
+  st;
+  // The single authoritative knowledge base (atoms added after the prelude). Both `run` and
+  // `space()` mutate this, and the interpreter's `env` is kept in lock-step with it.
+  kb = [];
+  _space;
+  constructor() {
+    this.gt = core3.stdTable();
+    this.tok = new Tokenizer2(standardTokenizerC());
+    this.env = core3.buildEnv([...core3.preludeAtoms(), ...core3.stdlibAtoms()], this.gt);
+    this.env.imports = core3.withBuiltinModules();
+    this.st = core3.initSt();
+    this._space = new SpaceRef(
+      new RunnerSpace(
+        (a) => this.addToKb(a),
+        (a) => this.removeFromKb(a),
+        () => this.kb
+      )
+    );
+  }
+  // Add an atom to the KB and the interpreter env together.
+  addToKb(atom) {
+    this.kb.push(atom);
+    core3.addAtomToEnv(this.env, atom);
+  }
+  // Remove an atom from the KB; rebuild env from the prelude + remaining KB so retraction is real
+  // (the env's rule/type indexes are derived, not incrementally removable).
+  removeFromKb(atom) {
+    const i = this.kb.findIndex((a) => core3.atomEq(a, atom));
+    if (i < 0) return false;
+    this.kb.splice(i, 1);
+    this.env = core3.buildEnv([...core3.preludeAtoms(), ...core3.stdlibAtoms(), ...this.kb], this.gt);
+    this.env.imports = core3.withBuiltinModules();
+    return true;
+  }
+  /** 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, fuel = DEFAULT_FUEL) {
+    const parsed = core3.parseAll(program, this.tok.ctok);
+    const out = [];
+    for (const { atom, bang } of parsed) {
+      if (!bang) {
+        this.addToKb(atom);
+        continue;
+      }
+      const [pairs, st2] = core3.mettaEval(this.env, fuel, this.st, [], atom);
+      this.st = st2;
+      out.push(pairs.map((p) => Atom.fromCAtom(p[0])));
+    }
+    return out;
+  }
+  /** Run MeTTa source asynchronously, awaiting any async grounded operations (registered with
+   *  {@link registerAsyncOperation}). Identical to {@link run} for a program with no async ops. */
+  async runAsync(program, fuel = DEFAULT_FUEL) {
+    const parsed = core3.parseAll(program, this.tok.ctok);
+    const out = [];
+    for (const { atom, bang } of parsed) {
+      if (!bang) {
+        this.addToKb(atom);
+        continue;
+      }
+      const [pairs, st2] = await core3.mettaEvalAsync(this.env, fuel, this.st, [], atom);
+      this.st = st2;
+      out.push(pairs.map((p) => Atom.fromCAtom(p[0])));
+    }
+    return out;
+  }
+  /** 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, op) {
+    this.env.agt.set(name, async (args) => {
+      try {
+        const results = await op(args.map(Atom.fromCAtom));
+        return { tag: "ok", results: results.map((a) => a.catom) };
+      } catch (e) {
+        return { tag: "runtimeError", msg: e instanceof Error ? e.message : String(e) };
+      }
+    });
+  }
+  /** Parse every top-level atom of a program. */
+  parseAll(program) {
+    return core3.parseAll(program, this.tok.ctok).map((t) => Atom.fromCAtom(t.atom));
+  }
+  /** Parse the first atom of a program. */
+  parseSingle(program) {
+    const a = core3.parse(program, this.tok.ctok);
+    return a === void 0 ? void 0 : Atom.fromCAtom(a);
+  }
+  /** 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, fuel = DEFAULT_FUEL) {
+    const [pairs, st2] = core3.mettaEval(this.env, fuel, this.st, [], atom.catom);
+    this.st = st2;
+    return pairs.map((p) => Atom.fromCAtom(p[0]));
+  }
+  /** Python alias of {@link evaluateAtom}. */
+  evaluate_atom(atom, fuel = DEFAULT_FUEL) {
+    return this.evaluateAtom(atom, fuel);
+  }
+  /** 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. */
+  async evaluateAtomAsync(atom, fuel = DEFAULT_FUEL) {
+    const [pairs, st2] = await core3.mettaEvalAsync(this.env, fuel, this.st, [], atom.catom);
+    this.st = st2;
+    return pairs.map((p) => Atom.fromCAtom(p[0]));
+  }
+  /** 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() {
+    return this._space;
+  }
+  /** The runner's tokenizer. */
+  tokenizer() {
+    return this.tok;
+  }
+  /** Register a custom token (text matching `regex` becomes `constr`'s atom). */
+  registerToken(regex, constr) {
+    this.tok.registerToken(regex, constr);
+  }
+  /** Register a symbol as a token that produces a fixed atom. */
+  registerAtom(name, atom) {
+    this.tok.registerToken(new RegExp(`^${escapeRegExp(name)}$`), () => atom);
+  }
+  /** 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, op) {
+    this.gt.set(name, (args) => {
+      try {
+        return { tag: "ok", results: op(args.map(Atom.fromCAtom)).map((a) => a.catom) };
+      } catch (e) {
+        if (e instanceof IncorrectArgumentError)
+          return { tag: "incorrectArgument", msg: e.message };
+        return { tag: "runtimeError", msg: e instanceof Error ? e.message : String(e) };
+      }
+    });
+  }
+  /** Every type the runner infers for an atom (Hyperon `get_atom_types`). */
+  getAtomTypes(atom) {
+    return core3.getTypes(this.env, atom.catom).map(Atom.fromCAtom);
+  }
+  /** Python alias of {@link getAtomTypes}. */
+  get_atom_types(atom) {
+    return this.getAtomTypes(atom);
+  }
+};
+var IncorrectArgumentError = class extends Error {
+};
+function standardTokenizer2() {
+  return new Tokenizer2(standardTokenizerC());
+}
+function standardTokenizerC() {
+  return core3.standardTokenizer();
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/modules/json.ts
+var SpaceValue = class extends ValueObject {
+  constructor(space) {
+    super(space);
+    this.space = space;
+  }
+  space;
+  toString() {
+    return "(dict-space)";
+  }
+};
+function spaceOf(atom) {
+  if (!(atom instanceof GroundedAtom)) return void 0;
+  const obj = atom.object();
+  return obj instanceof SpaceValue ? obj.space : void 0;
+}
+function makeDictSpace(pairs) {
+  const space = new GroundingSpace();
+  for (const p of pairs) space.addAtom(p);
+  return G(new SpaceValue(space));
+}
+function jsonToAtom(value) {
+  if (value === null) return S("null");
+  if (Array.isArray(value)) return E(...value.map(jsonToAtom));
+  switch (typeof value) {
+    case "string":
+      return ValueAtom(value);
+    case "number":
+      return ValueAtom(value);
+    case "boolean":
+      return ValueAtom(value);
+    case "object":
+      return makeDictSpace(
+        Object.entries(value).map(
+          ([k, v]) => E(ValueAtom(k), jsonToAtom(v))
+        )
+      );
+    default:
+      return S("null");
+  }
+}
+function atomToJson(atom) {
+  const space = spaceOf(atom);
+  if (space !== void 0) {
+    const obj = {};
+    for (const a of space.getAtoms()) {
+      if (a instanceof ExpressionAtom) {
+        const [k, v] = a.children();
+        if (k !== void 0 && v !== void 0) obj[String(jsonScalar(k))] = atomToJson(v);
+      }
+    }
+    return obj;
+  }
+  if (atom instanceof ExpressionAtom) return atom.children().map(atomToJson);
+  if (atom instanceof GroundedAtom) {
+    const content = atom.object().content;
+    const t = typeof content;
+    if (content !== null && t !== "string" && t !== "number" && t !== "boolean")
+      throw new Error(
+        `json-encode: grounded value of type '${t}' is not JSON-encodable: ${atom.toString()}`
+      );
+    return content;
+  }
+  if (atom instanceof SymbolAtom) return atom.name() === "null" ? null : atom.name();
+  return atom.toString();
+}
+function jsonScalar(atom) {
+  if (atom instanceof GroundedAtom) return atom.object().content;
+  return atom.toString();
+}
+function registerJsonModule(m) {
+  let freshVar = 0;
+  m.registerOperation("dict-space", (args) => {
+    const expr2 = args[0];
+    const pairs = expr2 instanceof ExpressionAtom ? expr2.children() : [];
+    return [makeDictSpace(pairs)];
+  });
+  m.registerOperation("get-keys", (args) => {
+    const space = args[0] === void 0 ? void 0 : spaceOf(args[0]);
+    if (space === void 0)
+      throw new Error(
+        `get-keys: expected a dict-space, got ${args[0]?.toString() ?? "no argument"}`
+      );
+    const keys = [];
+    for (const a of space.getAtoms())
+      if (a instanceof ExpressionAtom) {
+        const k = a.children()[0];
+        if (k !== void 0) keys.push(k);
+      }
+    return keys;
+  });
+  m.registerOperation("get-value", (args) => {
+    const space = args[0] === void 0 ? void 0 : spaceOf(args[0]);
+    const key = args[1];
+    if (space === void 0)
+      throw new Error(
+        `get-value: expected a dict-space, got ${args[0]?.toString() ?? "no argument"}`
+      );
+    if (key === void 0) throw new Error("get-value: missing key argument");
+    const v = V(`__get_value_${freshVar++}`);
+    return space.subst(E(key, v), v);
+  });
+  m.registerOperation("json-decode", (args) => {
+    const a = args[0];
+    if (!(a instanceof GroundedAtom))
+      throw new Error(
+        `json-decode: expected a grounded string, got ${a?.toString() ?? "no argument"}`
+      );
+    const text = a.object().content;
+    if (typeof text !== "string")
+      throw new Error(`json-decode: expected a string value, got ${typeof text}`);
+    return [jsonToAtom(JSON.parse(text))];
+  });
+  m.registerOperation("json-encode", (args) => {
+    const a = args[0];
+    if (a === void 0) throw new Error("json-encode: missing argument");
+    return [ValueAtom(JSON.stringify(atomToJson(a)))];
+  });
+}
+
+// src/modules/catalog.ts
+var ALL = "all";
+var ModuleCatalog = class {
+  catalogs = /* @__PURE__ */ new Map();
+  /** One line per `catalog-list!` call, so tests and UIs can observe the side effect. */
+  listing = [];
+  /** The names of catalogs updated by `catalog-update!`. */
+  updated = [];
+  /** Add or replace a named catalog's module list. */
+  register(name, modules) {
+    this.catalogs.set(name, [...modules]);
+  }
+  /** The module names in a catalog. */
+  modules(name) {
+    return this.catalogs.get(name) ?? [];
+  }
+  /** The catalog names, in insertion order. */
+  names() {
+    return [...this.catalogs.keys()];
+  }
+  targets(target2) {
+    return target2 === ALL ? this.names() : [target2];
+  }
+  /** Clear one catalog (or `all`). */
+  clear(target2) {
+    for (const name of this.targets(target2)) this.catalogs.set(name, []);
+  }
+  /** Record the contents of one catalog (or `all`) into {@link listing}. */
+  list(target2) {
+    for (const name of this.targets(target2))
+      this.listing.push(`${name}: ${this.modules(name).join(", ")}`);
+  }
+  /** Mark one catalog (or `all`) updated. */
+  update(target2) {
+    for (const name of this.targets(target2)) this.updated.push(name);
+  }
+};
+var UNIT = E();
+function target(args) {
+  const a = args[0];
+  return a !== void 0 && a.metatype() === "Symbol" ? a.toString() : ALL;
+}
+function registerCatalogModule(m, catalog) {
+  m.registerOperation("catalog-clear!", (args) => {
+    catalog.clear(target(args));
+    return [UNIT];
+  });
+  m.registerOperation("catalog-list!", (args) => {
+    catalog.list(target(args));
+    return [UNIT];
+  });
+  m.registerOperation("catalog-update!", (args) => {
+    catalog.update(target(args));
+    return [UNIT];
+  });
+}
+
+// src/modules/js.ts
+var JsValue = class extends ValueObject {
+};
+function atomToJs(atom) {
+  if (atom instanceof GroundedAtom) return atom.object().content;
+  if (atom instanceof SymbolAtom) return atom.name();
+  if (atom instanceof VariableAtom2) return atom.name();
+  if (atom instanceof ExpressionAtom) return atom.children().map(atomToJs);
+  return atom.toString();
+}
+function jsToAtom(value) {
+  switch (typeof value) {
+    case "number":
+    case "string":
+    case "boolean":
+      return ValueAtom(value);
+    case "function":
+      return OperationAtom(value.name || "js-fn", (...args) => [
+        jsToAtom(value(...args.map(atomToJs)))
+      ]);
+    case "undefined":
+      return S("()");
+    default:
+      return value === null ? S("null") : G(new JsValue(value));
+  }
+}
+var BLOCKED_SEGMENTS = /* @__PURE__ */ new Set([
+  "eval",
+  "Function",
+  "constructor",
+  "prototype",
+  "__proto__",
+  "process",
+  "require",
+  "Reflect",
+  "globalThis",
+  "global",
+  "module",
+  "import",
+  "child_process"
+]);
+function assertSafePath(path, op) {
+  for (const seg of path.split("."))
+    if (BLOCKED_SEGMENTS.has(seg)) throw new Error(`${op}: access to '${seg}' is blocked`);
+}
+function resolvePath(root, path) {
+  let owner = void 0;
+  let value = root;
+  for (const key of path.split(".")) {
+    if (value == null) return { value: void 0, owner };
+    owner = value;
+    value = value[key];
+  }
+  return { value, owner };
+}
+function asString(atom) {
+  if (atom === void 0) return void 0;
+  const v = atomToJs(atom);
+  return typeof v === "string" ? v : void 0;
+}
+function registerJsInterop(m) {
+  m.registerOperation("js-atom", (args) => {
+    const path = asString(args[0]);
+    if (path === void 0) throw new Error('js-atom: expected a String path (e.g. "Math.abs")');
+    assertSafePath(path, "js-atom");
+    const { value } = resolvePath(globalThis, path);
+    if (value === void 0) throw new Error(`js-atom: '${path}' did not resolve on globalThis`);
+    return [jsToAtom(value)];
+  });
+  m.registerOperation("js-dot", (args) => {
+    const objAtom = args[0];
+    const name = asString(args[1]);
+    if (objAtom === void 0 || name === void 0)
+      throw new Error('js-dot: expected (js-dot <object> "property")');
+    assertSafePath(name, "js-dot");
+    const obj = atomToJs(objAtom);
+    const { value, owner } = resolvePath(obj, name);
+    if (typeof value === "function")
+      return [jsToAtom(value.bind(owner))];
+    return [jsToAtom(value)];
+  });
+  m.registerOperation("js-list", (args) => {
+    const e = args[0];
+    const items = e instanceof ExpressionAtom ? e.children() : [];
+    return [G(new JsValue(items.map(atomToJs)))];
+  });
+  m.registerOperation("js-dict", (args) => {
+    const e = args[0];
+    const out = {};
+    if (e instanceof ExpressionAtom) {
+      for (const pair of e.children())
+        if (pair instanceof ExpressionAtom) {
+          const [k, v] = pair.children();
+          if (k !== void 0 && v !== void 0) out[String(atomToJs(k))] = atomToJs(v);
+        }
+    }
+    return [G(new JsValue(out))];
+  });
+}
+export {
+  Atom,
+  AtomType,
+  Bindings,
+  BindingsSet,
+  E,
+  ExpressionAtom,
+  G,
+  GroundedAtom,
+  GroundedObject,
+  GroundingSpace,
+  IncorrectArgumentError,
+  JsValue,
+  MatchableObject,
+  MeTTa,
+  ModuleCatalog,
+  OperationAtom,
+  OperationObject,
+  S,
+  SExprParser,
+  SpaceRef,
+  SpaceValue,
+  SymbolAtom,
+  Tokenizer2 as Tokenizer,
+  V,
+  ValueAtom,
+  ValueObject,
+  VariableAtom2 as VariableAtom,
+  atomIsError,
+  atomToJs,
+  atomsAreEquivalent,
+  clearGroundedObjects,
+  friendlyTypeName,
+  groundToJs,
+  jsToAtom,
+  registerCatalogModule,
+  registerJsInterop,
+  registerJsonModule,
+  standardTokenizer2 as standardTokenizer
+};