@mettascript/node 2.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,56 @@
+# @mettascript/node
+
+Node.js entry for [MeTTaScript](https://github.com/MesTTo/MeTTaScript): the `metta` command-line interface, file-based `import!`, and a `SharedArrayBuffer` worker-thread parallel matcher. Re-exports everything from [`@mettascript/core`](https://github.com/MesTTo/MeTTaScript/tree/main/packages/core).
+
+## Install
+
+```bash
+npm install @mettascript/node
+# for the CLI on your PATH:
+npm install -g @mettascript/node
+```
+
+## CLI
+
+`metta` is a single command with subcommands:
+
+```bash
+metta run program.metta       # run a program (metta program.metta is shorthand)
+metta check program.metta     # static analysis (--json, --undefined-symbols)
+metta debug --file program.metta why '(main)'   # engine debugger (why/eval/run)
+metta graph program.metta -o out.gif            # render the reduction as an animated GIF
+metta --version
+```
+
+Without a global install: `npx -p @mettascript/node metta run program.metta`.
+
+Host runtimes are explicit and lazy:
+
+```bash
+metta run --py program.metta       # Python through pythonia
+metta run --prolog program.metta   # Prolog through a local swipl executable
+```
+
+Without those flags the CLI never loads Python, Prolog, or their optional
+dependencies. `metta graph` similarly loads [`@mettascript/grapher`](https://github.com/MesTTo/MeTTaScript/tree/main/packages/grapher)
+and its renderers only when invoked; install them with `npm install @mettascript/grapher gifenc sharp`.
+
+The earlier `metta-ts` (run) and `metta-debug` (debug) commands remain as aliases,
+so existing scripts keep working.
+
+## Usage
+
+```ts
+import { runFile, ParallelFlatMatcher } from "@mettascript/node";
+
+// Run a .metta file (resolves import! against the file system).
+for (const { query, results } of runFile("program.metta")) {
+  console.log(query, results);
+}
+```
+
+`ParallelFlatMatcher` scans a large flat knowledge base across `worker_threads` over a shared token buffer. It pays off only for a large KB scanned by a non-selective query whose result set is small; a keyed query is already near-constant-time via the in-memory argument index.
+
+## License
+
+[MIT](https://github.com/MesTTo/MeTTaScript/blob/main/LICENSE).

package/dist/check-TCNAUG5Q.js

@@ -0,0 +1,13 @@
+// src/check.ts
+import { readFileSync } from "fs";
+import { analyzeSource, renderAll, DiagnosticSeverity } from "@mettascript/core";
+function checkFile(file, opts) {
+  const src = readFileSync(file, "utf8");
+  const diags = analyzeSource(src, { undefinedSymbols: opts.undefinedSymbols });
+  const hasError = diags.some((d) => d.severity === DiagnosticSeverity.Error);
+  const text = opts.json ? JSON.stringify(diags, null, 2) : diags.length > 0 ? renderAll(src, file, diags) : "";
+  return { text, exitCode: hasError ? 1 : 0 };
+}
+export {
+  checkFile
+};

package/dist/chunk-CWWQ3S7I.js

@@ -0,0 +1,142 @@
+// src/source.ts
+import "@mettascript/libraries";
+import {
+  DEFAULT_FUEL,
+  evalSequential,
+  evalSequentialAllDirectives,
+  parseAll,
+  runProgramAsync,
+  standardTokenizer
+} from "@mettascript/core";
+
+// src/par-hyperpose.ts
+import { Worker } from "worker_threads";
+import { createRequire } from "module";
+var WORKER_SRC = `
+const { workerData } = require("node:worker_threads");
+const { corePath, rulesSrc, branchSrc, sab, base, cap, fuel, hostEffects } = workerData;
+const view = new Int32Array(sab);
+(async () => {
+  try {
+    const m = await import(corePath);
+    if (hostEffects === false && typeof m.setHostEffectsEnabled === "function") {
+      m.setHostEffectsEnabled(false);
+    }
+    const r = m.runProgram(rulesSrc + "\\n!" + branchSrc, fuel);
+    const last = r[r.length - 1];
+    const out = JSON.stringify((last && last.results ? last.results : []).map((a) => m.format(a)));
+    if (out.length > cap) { Atomics.store(view, base, -1); }
+    else {
+      for (let i = 0; i < out.length; i++) view[base + 2 + i] = out.charCodeAt(i);
+      Atomics.store(view, base + 1, out.length);
+      Atomics.store(view, base, 1);
+    }
+  } catch (e) {
+    Atomics.store(view, base, -1); // import failure, fuel exhaustion, anything: this branch bailed
+  } finally {
+    // Always signal completion, even on a caught failure, so the main thread's Atomics.wait cannot block
+    // forever waiting for a branch that already errored.
+    Atomics.add(view, 0, 1);
+    Atomics.notify(view, 0);
+  }
+})();
+`;
+var CAP = 16384;
+function evalBranchesParallel(corePath, rulesSrc, branchSrcs, firstOnly, fuel, options = {}) {
+  const n = branchSrcs.length;
+  const region = 2 + CAP;
+  const sab = new SharedArrayBuffer((1 + n * region) * 4);
+  const view = new Int32Array(sab);
+  const workers = branchSrcs.map(
+    (br, i) => new Worker(WORKER_SRC, {
+      eval: true,
+      workerData: {
+        corePath,
+        rulesSrc,
+        branchSrc: br,
+        sab,
+        base: 1 + i * region,
+        cap: CAP,
+        fuel,
+        hostEffects: options.hostEffects
+      }
+    })
+  );
+  const out = new Array(n).fill(null);
+  const read = (i) => {
+    const base = 1 + i * region;
+    const status = Atomics.load(view, base);
+    if (status === 0) return void 0;
+    if (status === -1) return null;
+    const len = Atomics.load(view, base + 1);
+    let s = "";
+    for (let j = 0; j < len; j++) s += String.fromCharCode(view[base + 2 + j]);
+    return JSON.parse(s);
+  };
+  const WAIT_MS = 6e4;
+  let done = false;
+  while (!done) {
+    const prev = Atomics.load(view, 0);
+    for (let i = 0; i < n; i++) {
+      if (out[i] !== null) continue;
+      const r = read(i);
+      if (r === void 0) continue;
+      out[i] = r;
+      if (firstOnly && r !== null && r.length > 0) {
+        done = true;
+        break;
+      }
+    }
+    if (Atomics.load(view, 0) >= n) done = true;
+    if (!done && Atomics.wait(view, 0, prev, WAIT_MS) === "timed-out" && Atomics.load(view, 0) === prev)
+      break;
+  }
+  for (const w of workers) void w.terminate();
+  return out;
+}
+function makeParEvalImpl(fuel, options = {}) {
+  const corePath = createRequire(import.meta.url).resolve("@mettascript/core");
+  return (rulesSrc, branchSrcs, firstOnly) => evalBranchesParallel(corePath, rulesSrc, branchSrcs, firstOnly, fuel, options);
+}
+
+// src/source.ts
+function withDefaultParallelism(fuel, opts, parOptions) {
+  const base = opts ?? {};
+  return {
+    ...base,
+    tabling: base.tabling ?? true,
+    parEvalImpl: base.parEvalImpl ?? makeParEvalImpl(fuel, parOptions)
+  };
+}
+function runSource(src, fuel = DEFAULT_FUEL, imports = /* @__PURE__ */ new Map(), opts) {
+  return evalSequential(
+    parseAll(src, standardTokenizer()),
+    fuel,
+    imports,
+    withDefaultParallelism(fuel, opts)
+  );
+}
+function runSourceAllDirectives(src, fuel = DEFAULT_FUEL, imports = /* @__PURE__ */ new Map(), opts) {
+  return evalSequentialAllDirectives(
+    parseAll(src, standardTokenizer()),
+    fuel,
+    imports,
+    withDefaultParallelism(fuel, opts)
+  );
+}
+function runSourceAsync(src, asyncOps = /* @__PURE__ */ new Map(), fuel = DEFAULT_FUEL, imports = /* @__PURE__ */ new Map(), opts, parOptions) {
+  return runProgramAsync(
+    src,
+    asyncOps,
+    fuel,
+    imports,
+    withDefaultParallelism(fuel, opts, parOptions)
+  );
+}
+
+export {
+  makeParEvalImpl,
+  runSource,
+  runSourceAllDirectives,
+  runSourceAsync
+};

package/dist/chunk-DHXPSARV.js

@@ -0,0 +1,233 @@
+import {
+  readImports
+} from "./chunk-L4U6ZIAR.js";
+
+// src/run-main.ts
+import { parseArgs } from "util";
+import { existsSync, readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import {
+  atomEq,
+  emptyExpr,
+  format,
+  isErrorAtom,
+  setOutputSink,
+  setRawSink
+} from "@mettascript/core";
+async function reexecWithLargerStack() {
+  const { spawnSync } = await import("child_process");
+  const res = spawnSync(
+    process.execPath,
+    ["--stack-size=8000", process.argv[1] ?? "", ...process.argv.slice(2)],
+    { stdio: "inherit", env: { ...process.env, METTA_TS_STACK: "1" } }
+  );
+  process.exit(res.status ?? 1);
+}
+async function runCliSource(src, fuel, imports, opts, includeNonBang) {
+  const { runSource, runSourceAllDirectives } = await import("./source.js");
+  return includeNonBang ? runSourceAllDirectives(src, fuel, imports, opts) : runSource(src, fuel, imports, opts);
+}
+async function runToBuffer(file, fuel, opts, includeNonBang) {
+  const src = readFileSync(file, "utf8");
+  const fileDir = dirname(resolve(file));
+  const imports = readImports(src, fileDir, dirname(fileDir));
+  const buf = [];
+  const prevOut = setOutputSink((line) => buf.push(line + "\n"));
+  const prevRaw = setRawSink((text) => buf.push(text));
+  try {
+    const results = await runCliSource(src, fuel, imports, opts, includeNonBang);
+    for (const r of results)
+      buf.push(
+        "[" + r.results.map((a) => formatCliResult(a, includeNonBang ? r.query : void 0)).join(", ") + "]\n"
+      );
+    return buf.join("");
+  } finally {
+    setOutputSink(prevOut);
+    setRawSink(prevRaw);
+  }
+}
+function formatCliResult(atom, query) {
+  if (query !== void 0 && isErrorAtom(atom) && atomEq(atom, query) && atom.kind === "expr")
+    return "( " + atom.items.map(format).join(" ") + ")";
+  return format(atom);
+}
+function importName(a) {
+  if (a?.kind === "sym") return a.name;
+  if (a?.kind === "gnd" && a.value.g === "str") return a.value.s;
+  if (a?.kind === "expr" && a.items.length === 2 && a.items[0]?.kind === "sym" && a.items[0].name === "library")
+    return importName(a.items[1]);
+  return void 0;
+}
+function errorMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+function resolveHostPath(fileDir, name) {
+  const fileRelative = resolve(fileDir, name);
+  if (existsSync(fileRelative)) return fileRelative;
+  return resolve(name);
+}
+async function runInteropToBuffer(file, fuel, opts, modes) {
+  const [{ composeHostInterops }, { runSourceAsync }] = await Promise.all([
+    import("@mettascript/core/host"),
+    import("./source.js")
+  ]);
+  const interops = [];
+  const src = readFileSync(file, "utf8");
+  const fileDir = dirname(resolve(file));
+  const resolveImportPath = (p) => resolveHostPath(fileDir, p);
+  if (modes.py) {
+    if (process.env.METTA_TS_FORCE_NO_PYTHONIA === "1")
+      throw new Error("--py needs the pythonia backend; run: npm install pythonia");
+    let python;
+    try {
+      ({ python } = await import("pythonia"));
+    } catch {
+      throw new Error(
+        "--py needs the pythonia backend; run: npm install pythonia (and ensure python3 is on PATH)"
+      );
+    }
+    const [{ pyCoreAsyncOps, PY_METTA_SRC }, { pythoniaBridge }] = await Promise.all([
+      import("@mettascript/py"),
+      import("@mettascript/py/pythonia")
+    ]);
+    const bridge = pythoniaBridge(python);
+    interops.push({
+      name: "pythonia",
+      prelude: PY_METTA_SRC,
+      asyncOps: pyCoreAsyncOps(bridge),
+      hostImport: async (_space, target) => {
+        const name = importName(target);
+        if (!name?.endsWith(".py")) return { tag: "noReduce" };
+        try {
+          await bridge.import(resolveImportPath(name));
+          return { tag: "ok", results: [emptyExpr] };
+        } catch (e) {
+          return { tag: "runtimeError", msg: `import!: ${name}: ${errorMessage(e)}` };
+        }
+      },
+      dispose: () => bridge.dispose()
+    });
+  }
+  if (modes.prolog) {
+    if (process.env.METTA_TS_FORCE_NO_SWIPL === "1")
+      throw new Error("--prolog needs SWI-Prolog on PATH; install swipl");
+    const [{ PROLOG_METTA_SRC, prologCoreAsyncOps }, { swiPrologBridge }] = await Promise.all([
+      import("@mettascript/prolog"),
+      import("@mettascript/prolog/swi-node")
+    ]);
+    const bridge = swiPrologBridge();
+    interops.push({
+      name: "swi-prolog",
+      prelude: PROLOG_METTA_SRC,
+      asyncOps: prologCoreAsyncOps(bridge, {
+        resolvePath: resolveImportPath
+      }),
+      hostImport: async (_space, target) => {
+        const name = importName(target);
+        if (!name?.endsWith(".pl")) return { tag: "noReduce" };
+        try {
+          await bridge.consult(resolveImportPath(name));
+          return { tag: "ok", results: [emptyExpr] };
+        } catch (e) {
+          return { tag: "runtimeError", msg: `import!: ${name}: ${errorMessage(e)}` };
+        }
+      },
+      dispose: () => bridge.dispose()
+    });
+  }
+  const host = composeHostInterops(interops);
+  const buf = [];
+  const prevOut = setOutputSink((line) => buf.push(line + "\n"));
+  const prevRaw = setRawSink((text) => buf.push(text));
+  try {
+    const results = await runSourceAsync(
+      host.prelude === void 0 ? src : `${host.prelude}
+${src}`,
+      new Map(host.asyncOps ?? []),
+      fuel,
+      readImports(src, fileDir, dirname(fileDir)),
+      {
+        ...opts ?? {},
+        ...host.hostImport !== void 0 ? { hostImport: host.hostImport } : {}
+      }
+    );
+    for (const r of results) buf.push("[" + r.results.map(format).join(", ") + "]\n");
+    return buf.join("");
+  } finally {
+    setOutputSink(prevOut);
+    setRawSink(prevRaw);
+    await host.dispose?.();
+  }
+}
+async function runCliMain(argv, prog = "metta run") {
+  const { positionals, values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      "max-steps": { type: "string" },
+      "max-stack-depth": { type: "string" },
+      "hash-cons": { type: "boolean" },
+      "flat-atomspace": { type: "boolean" },
+      check: { type: "boolean" },
+      json: { type: "boolean" },
+      "undefined-symbols": { type: "boolean" },
+      py: { type: "boolean" },
+      prolog: { type: "boolean" },
+      conformance: { type: "boolean" }
+    }
+  });
+  const file = positionals[0];
+  if (file === void 0) {
+    process.stderr.write(
+      `usage: ${prog} [--check [--json] [--undefined-symbols]] [--py] [--prolog] [--conformance] [--max-steps=N] [--max-stack-depth=N] [--hash-cons] <file.metta>
+`
+    );
+    process.exit(2);
+  }
+  if (values.check === true) {
+    const { checkFile } = await import("./check-TCNAUG5Q.js");
+    const { text, exitCode } = checkFile(file, {
+      json: values.json === true,
+      undefinedSymbols: values["undefined-symbols"] === true
+    });
+    if (text.length > 0) {
+      (values.json === true ? process.stdout : process.stderr).write(text + "\n");
+    }
+    process.exit(exitCode);
+  }
+  const fuel = values["max-steps"] !== void 0 ? Number(values["max-steps"]) : void 0;
+  const maxStackDepth = values["max-stack-depth"] !== void 0 ? Number(values["max-stack-depth"]) : void 0;
+  const hashCons = values["hash-cons"] === true || process.env.METTA_TS_HASHCONS === "1" || process.env.METTA_TS_HASHCONS === "true";
+  const flatAtomspace = values["flat-atomspace"] === true || process.env.METTA_TS_FLAT_ATOMSPACE === "1" || process.env.METTA_TS_FLAT_ATOMSPACE === "true";
+  const opts = maxStackDepth !== void 0 || hashCons || flatAtomspace ? {
+    ...maxStackDepth !== void 0 ? { maxStackDepth } : {},
+    ...hashCons || flatAtomspace ? {
+      experimental: {
+        ...hashCons ? { hashCons: true } : {},
+        ...flatAtomspace ? { flatAtomspace: true } : {}
+      }
+    } : {}
+  } : void 0;
+  if (values.py === true || values.prolog === true) {
+    const output = await runInteropToBuffer(file, fuel, opts, {
+      py: values.py === true,
+      prolog: values.prolog === true
+    });
+    process.stdout.write(output);
+    return;
+  }
+  if (process.env.METTA_TS_STACK !== void 0) {
+    process.stdout.write(await runToBuffer(file, fuel, opts, values.conformance === true));
+    return;
+  }
+  try {
+    process.stdout.write(await runToBuffer(file, fuel, opts, values.conformance === true));
+  } catch (e) {
+    if (!(e instanceof RangeError)) throw e;
+    await reexecWithLargerStack();
+  }
+}
+
+export {
+  runCliMain
+};

package/dist/chunk-ELBXIFJR.js

@@ -0,0 +1,126 @@
+import {
+  runSource
+} from "./chunk-CWWQ3S7I.js";
+import {
+  readImports
+} from "./chunk-L4U6ZIAR.js";
+
+// src/debug-main.ts
+import { parseArgs } from "util";
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { format, setOutputSink, setRawSink } from "@mettascript/core";
+import { assembleQuery, explainCall } from "@mettascript/debug";
+function loadProgram(source, file) {
+  if (file !== void 0) {
+    const p = resolve(file);
+    if (!existsSync(p)) throw new Error(`file not found: ${p}`);
+    return { src: readFileSync(p, "utf8"), baseDir: dirname(p) };
+  }
+  if (source !== void 0) return { src: source, baseDir: process.cwd() };
+  throw new Error("provide --source '<metta>' or --file <path>");
+}
+function runQuery(loaded, call, fuel) {
+  setOutputSink(() => {
+  });
+  setRawSink(() => {
+  });
+  const program = assembleQuery(loaded.src, call);
+  const imports = readImports(program, loaded.baseDir, dirname(loaded.baseDir));
+  return explainCall(runSource, loaded.src, call, { fuel, imports });
+}
+function printHuman(obj) {
+  for (const [k, v] of Object.entries(obj)) {
+    if (Array.isArray(v)) {
+      if (v.length === 0) continue;
+      process.stdout.write(`${k}:
+`);
+      for (const item of v) process.stdout.write(`  ${String(item)}
+`);
+    } else if (v !== null && typeof v === "object") {
+      const entries = Object.entries(v);
+      if (entries.length === 0) continue;
+      process.stdout.write(`${k}:
+`);
+      for (const [ik, iv] of entries) process.stdout.write(`  ${ik}: ${String(iv)}
+`);
+    } else {
+      process.stdout.write(`${k}: ${String(v)}
+`);
+    }
+  }
+}
+function emit(llm, obj) {
+  if (llm) process.stdout.write(`${JSON.stringify(obj, null, 2)}
+`);
+  else printHuman(obj);
+}
+function usage(prog) {
+  return `${prog} \u2014 headless MeTTa engine debugger
+
+usage:
+  ${prog} (--source '<metta>' | --file <path>) why '(<call>)' [--llm] [--max-steps N]
+  ${prog} (--source '<metta>' | --file <path>) eval '(<expr>)' [--llm] [--max-steps N]
+  ${prog} (--source '<metta>' | --file <path>) run [--llm] [--max-steps N]
+
+commands:
+  why    run the call with the trace bus and report which grounded reducer fired, any higher-order
+         specialization, any stack-overflow cut point, the reduction count, and the result.
+  eval   evaluate one expression and print its result.
+  run    run the whole program and print each !-query's results.`;
+}
+function runDebugMain(argv, prog = "metta debug") {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: {
+      source: { type: "string" },
+      file: { type: "string" },
+      "max-steps": { type: "string" },
+      llm: { type: "boolean", default: false },
+      help: { type: "boolean", default: false }
+    },
+    allowPositionals: true
+  });
+  const cmd = positionals[0];
+  if (values.help === true || cmd === void 0) {
+    process.stdout.write(`${usage(prog)}
+`);
+    return;
+  }
+  const fuel = values["max-steps"] !== void 0 ? Number(values["max-steps"]) : void 0;
+  const loaded = loadProgram(values.source, values.file);
+  const llm = values.llm === true;
+  if (cmd === "why") {
+    const call = positionals[1];
+    if (call === void 0) throw new Error(`usage: ${prog} why '(<call>)'`);
+    const { result, summary: s } = runQuery(loaded, call, fuel);
+    emit(llm, {
+      call,
+      result,
+      grounded: s.grounded,
+      specialized: s.specialized,
+      overflow: s.overflow,
+      reductions: s.reductions
+    });
+    return;
+  }
+  if (cmd === "eval") {
+    const expr = positionals[1];
+    if (expr === void 0) throw new Error(`usage: ${prog} eval '(<expr>)'`);
+    emit(llm, { result: runQuery(loaded, expr, fuel).result });
+    return;
+  }
+  if (cmd === "run") {
+    const imports = readImports(loaded.src, loaded.baseDir, dirname(loaded.baseDir));
+    const results = runSource(loaded.src, fuel, imports).map((g) => g.results.map(format));
+    emit(llm, { results });
+    return;
+  }
+  throw new Error(`unknown command '${cmd}'
+
+${usage(prog)}`);
+}
+
+export {
+  runDebugMain
+};

package/dist/chunk-L4U6ZIAR.js

@@ -0,0 +1,24 @@
+// src/file-imports.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve, sep } from "path";
+import { collectImports, parseAll, standardTokenizer } from "@mettascript/core";
+function readImports(src, baseDir, importRoot = baseDir) {
+  const imports = /* @__PURE__ */ new Map();
+  if (!src.includes("import!")) return imports;
+  const base = resolve(baseDir);
+  const root = resolve(importRoot);
+  for (const name of collectImports(src)) {
+    const path = resolve(base, name.endsWith(".metta") ? name : name + ".metta");
+    if (path !== root && !path.startsWith(root + sep)) continue;
+    if (existsSync(path))
+      imports.set(
+        name,
+        parseAll(readFileSync(path, "utf8"), standardTokenizer()).filter((top) => !top.bang).map((top) => top.atom)
+      );
+  }
+  return imports;
+}
+
+export {
+  readImports
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import {
+  runCliMain
+} from "./chunk-DHXPSARV.js";
+import "./chunk-L4U6ZIAR.js";
+
+// src/cli.ts
+runCliMain(process.argv.slice(2), "metta-ts").catch((e) => {
+  process.stderr.write((e instanceof Error ? e.message : String(e)) + "\n");
+  process.exit(1);
+});

package/dist/debug-cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/debug-cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import {
+  runDebugMain
+} from "./chunk-ELBXIFJR.js";
+import "./chunk-CWWQ3S7I.js";
+import "./chunk-L4U6ZIAR.js";
+
+// src/debug-cli.ts
+try {
+  runDebugMain(process.argv.slice(2), "metta-debug");
+} catch (e) {
+  process.stderr.write(`${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(2);
+}

package/dist/debug-main-Y254S5BG.js

@@ -0,0 +1,8 @@
+import {
+  runDebugMain
+} from "./chunk-ELBXIFJR.js";
+import "./chunk-CWWQ3S7I.js";
+import "./chunk-L4U6ZIAR.js";
+export {
+  runDebugMain
+};

package/dist/graph-main-WRL2UUTS.js

@@ -0,0 +1,51 @@
+// src/graph-main.ts
+import { parseArgs } from "util";
+import { readFileSync, writeFileSync } from "fs";
+import { basename, extname, resolve } from "path";
+function parseView(value) {
+  if (value === void 0) return void 0;
+  if (value === "blocks" || value === "graph" || value === "side-by-side") return value;
+  throw new Error(`--view must be blocks, graph, or side-by-side, got ${value}`);
+}
+async function runGraphMain(argv) {
+  const { positionals, values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      out: { type: "string", short: "o" },
+      view: { type: "string" },
+      width: { type: "string" },
+      "max-steps": { type: "string" }
+    }
+  });
+  const file = positionals[0];
+  if (file === void 0) {
+    process.stderr.write(
+      "usage: metta graph <file.metta> [-o out.gif] [--view blocks|graph|side-by-side] [--width N] [--max-steps N]\n"
+    );
+    process.exit(2);
+  }
+  const view = parseView(values.view);
+  const src = readFileSync(resolve(file), "utf8");
+  let renderReductionGif;
+  try {
+    ({ renderReductionGif } = await import("@mettascript/grapher/node"));
+  } catch (e) {
+    throw new Error(
+      "metta graph needs @mettascript/grapher and its renderers; install them with: npm install @mettascript/grapher gifenc sharp",
+      { cause: e }
+    );
+  }
+  const gif = await renderReductionGif(src, {
+    ...view !== void 0 ? { view } : {},
+    ...values.width !== void 0 ? { width: Number(values.width) } : {},
+    ...values["max-steps"] !== void 0 ? { maxSteps: Number(values["max-steps"]) } : {}
+  });
+  const out = values.out ?? `${basename(file, extname(file))}.gif`;
+  writeFileSync(out, gif);
+  process.stdout.write(`wrote ${out} (${gif.byteLength} bytes)
+`);
+}
+export {
+  runGraphMain
+};

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { Atom, FlatKB, RunOptions, QueryResult } from '@mettascript/core';
+export * from '@mettascript/core';
+export { ParEvalOptions, makeParEvalImpl, runSource, runSourceAllDirectives, runSourceAsync } from './source.js';
+
+/** Pre-read every `import!` target referenced in `src`, resolving names against `baseDir`. */
+declare function readImports(src: string, baseDir: string, importRoot?: string): Map<string, Atom[]>;
+
+/** A worker-pool, SharedArrayBuffer-backed parallel matcher over a {@link FlatKB}. Build it once from a
+ *  KB, reuse the warm pool across queries, and `close()` when done. */
+declare class ParallelFlatMatcher {
+    private readonly kb;
+    private readonly tokens;
+    private readonly counter;
+    private readonly numFacts;
+    private readonly workers;
+    private queue;
+    constructor(kb: FlatKB, workerCount?: number);
+    /** Match `pattern` across the KB in parallel. Returns one binding map (variable name -> atom) per
+     *  match, identical (up to order) to the single-threaded `FlatKB.match`. Concurrent calls are
+     *  serialized internally (the workers share one counter), so it is safe to call without awaiting. */
+    match(pattern: Atom): Promise<Array<Map<string, Atom>>>;
+    private matchOne;
+    /** Terminate the worker pool. */
+    close(): Promise<void>;
+}
+
+/** Run a `.metta` file from disk, resolving `import!` relative to the file's directory. `fuel` is the step
+ *  ceiling; `opts` carries interpreter settings such as the initial `maxStackDepth`. */
+declare function runFile(path: string, fuel?: number, opts?: RunOptions): QueryResult[];
+/** Run a file and return one result entry for every top-level directive. */
+declare function runFileAllDirectives(path: string, fuel?: number, opts?: RunOptions): QueryResult[];
+
+export { ParallelFlatMatcher, readImports, runFile, runFileAllDirectives };

package/dist/index.js

@@ -0,0 +1,160 @@
+import {
+  makeParEvalImpl,
+  runSource,
+  runSourceAllDirectives,
+  runSourceAsync
+} from "./chunk-CWWQ3S7I.js";
+import {
+  readImports
+} from "./chunk-L4U6ZIAR.js";
+
+// src/index.ts
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import "@mettascript/core";
+export * from "@mettascript/core";
+
+// src/flat-parallel.ts
+import { Worker } from "worker_threads";
+import { availableParallelism } from "os";
+import { encodePattern, decodeAt } from "@mettascript/core";
+var WORKER_SRC = `
+const { parentPort, workerData } = require("node:worker_threads");
+const tokens = new Int32Array(workerData.tokensSAB);
+const offsets = new Int32Array(workerData.offsetsSAB);
+const counter = new Int32Array(workerData.counterSAB);
+const numFacts = workerData.numFacts;
+const T_ARITY = 0, T_SYMBOL = 1, T_NEWVAR = 2, T_VARREF = 3;
+const tg = (t) => (t >>> 28) & 0xf, pl = (t) => t & 0x0fffffff;
+function subLen(tk, pos) {
+  const t = tk[pos];
+  if (tg(t) === T_ARITY) { let l = 1, p = pos + 1; for (let i = 0; i < pl(t); i++) { const x = subLen(tk, p); l += x; p += x; } return l; }
+  return 1;
+}
+function rangeEq(tk, as, bs) {
+  const l = subLen(tk, as); if (l !== subLen(tk, bs)) return false;
+  for (let i = 0; i < l; i++) if (tk[as + i] !== tk[bs + i]) return false; return true;
+}
+function matchAt(pat, fact, fs) {
+  const binds = []; let vc = 0, pp = 0, fp = fs;
+  function go() {
+    const pt = pat[pp], ptag = tg(pt);
+    if (ptag === T_NEWVAR) { const l = subLen(fact, fp); binds[vc++] = [fp, fp + l]; pp++; fp += l; return true; }
+    if (ptag === T_VARREF) { const ref = binds[pl(pt)]; if (!ref) return false; if (!rangeEq(fact, ref[0], fp)) return false; pp++; fp += subLen(fact, fp); return true; }
+    if (ptag === T_SYMBOL) { if (fact[fp] !== pt) return false; pp++; fp++; return true; }
+    if (fact[fp] !== pt) return false; const n = pl(pt); pp++; fp++;
+    for (let i = 0; i < n; i++) if (!go()) return false; return true;
+  }
+  return go() ? binds : null;
+}
+parentPort.on("message", (pat) => {
+  const out = [];
+  for (;;) {
+    const idx = Atomics.add(counter, 0, 1);
+    if (idx >= numFacts) break;
+    const binds = matchAt(pat, tokens, offsets[idx]);
+    if (binds) out.push(binds);   // binds: array indexed by de Bruijn id -> [start, end)
+  }
+  parentPort.postMessage(out);
+});
+`;
+var ParallelFlatMatcher = class {
+  kb;
+  tokens;
+  counter;
+  numFacts;
+  workers;
+  // All workers share one work-stealing counter, so calls must not overlap; serialize them on a queue.
+  queue = Promise.resolve();
+  constructor(kb, workerCount = Math.max(1, availableParallelism() - 1)) {
+    this.kb = kb;
+    const toks = kb.tokenArray;
+    const offs = kb.factOffsets;
+    this.numFacts = offs.length;
+    const tokensSAB = new SharedArrayBuffer(toks.length * 4);
+    this.tokens = new Int32Array(tokensSAB);
+    this.tokens.set(toks);
+    const offsetsSAB = new SharedArrayBuffer(Math.max(1, offs.length) * 4);
+    new Int32Array(offsetsSAB).set(offs);
+    const counterSAB = new SharedArrayBuffer(4);
+    this.counter = new Int32Array(counterSAB);
+    this.workers = Array.from(
+      { length: Math.max(1, workerCount) },
+      () => new Worker(WORKER_SRC, {
+        eval: true,
+        workerData: { tokensSAB, offsetsSAB, counterSAB, numFacts: this.numFacts }
+      })
+    );
+  }
+  /** Match `pattern` across the KB in parallel. Returns one binding map (variable name -> atom) per
+   *  match, identical (up to order) to the single-threaded `FlatKB.match`. Concurrent calls are
+   *  serialized internally (the workers share one counter), so it is safe to call without awaiting. */
+  async match(pattern) {
+    const run = this.queue.then(() => this.matchOne(pattern));
+    this.queue = run.catch(() => void 0);
+    return run;
+  }
+  async matchOne(pattern) {
+    const enc = encodePattern(pattern, this.kb.interner);
+    if (enc === null) return [];
+    Atomics.store(this.counter, 0, 0);
+    const replies = this.workers.map(
+      (w) => (
+        // Reject on worker error or early exit, so a crashing worker fails the match instead of leaving
+        // `Promise.all` and the serialized queue hung forever. Remove all listeners when any fires so a
+        // long-lived worker does not accumulate them across calls.
+        new Promise((res, rej) => {
+          const onMsg = (m) => (cleanup(), res(m));
+          const onErr = (e) => (cleanup(), rej(e));
+          const onExit = (code) => (cleanup(), rej(new Error(`match worker exited (${code})`)));
+          const cleanup = () => {
+            w.off("message", onMsg);
+            w.off("error", onErr);
+            w.off("exit", onExit);
+          };
+          w.on("message", onMsg);
+          w.on("error", onErr);
+          w.on("exit", onExit);
+        })
+      )
+    );
+    for (const w of this.workers) w.postMessage(enc.tokens);
+    const perWorker = await Promise.all(replies);
+    const out = [];
+    for (const matches of perWorker)
+      for (const ranges of matches) {
+        const m = /* @__PURE__ */ new Map();
+        ranges.forEach(
+          (r, idx) => m.set(enc.varNames[idx], decodeAt(this.tokens, r[0], this.kb.interner)[0])
+        );
+        out.push(m);
+      }
+    return out;
+  }
+  /** Terminate the worker pool. */
+  async close() {
+    await Promise.all(this.workers.map((w) => w.terminate()));
+  }
+};
+
+// src/index.ts
+function runFile(path, fuel, opts) {
+  const src = readFileSync(path, "utf8");
+  const fileDir = dirname(resolve(path));
+  return runSource(src, fuel, readImports(src, fileDir, dirname(fileDir)), opts);
+}
+function runFileAllDirectives(path, fuel, opts) {
+  const src = readFileSync(path, "utf8");
+  const fileDir = dirname(resolve(path));
+  return runSourceAllDirectives(src, fuel, readImports(src, fileDir, dirname(fileDir)), opts);
+}
+export {
+  ParallelFlatMatcher,
+  makeParEvalImpl,
+  readImports,
+  runFile,
+  runFileAllDirectives,
+  runSource,
+  runSourceAllDirectives,
+  runSourceAsync
+};

package/dist/metta-cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/metta-cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+// src/metta-cli.ts
+import { createRequire } from "module";
+function version() {
+  const require2 = createRequire(import.meta.url);
+  return require2("../package.json").version;
+}
+var HELP = `metta \u2014 MeTTaScript command-line interface
+
+usage:
+  metta <file.metta> [options]         run a program (shorthand for "metta run")
+  metta run <file.metta> [options]     run a program, printing each !-query's results
+  metta check <file.metta> [options]   statically analyze a program (--json, --undefined-symbols)
+  metta debug (--file <p> | --source '<m>') <why|eval|run> [--llm]   debug the engine
+  metta graph <file.metta> [-o out.gif] [--view blocks|graph|side-by-side]   render a reduction GIF
+  metta --version | --help
+
+Run "metta run --help" style is not needed; each subcommand prints its own usage on a missing argument.
+"metta-ts" and "metta-debug" remain as aliases.`;
+async function main() {
+  const args = process.argv.slice(2);
+  const first = args[0];
+  if (first === void 0 || first === "--help" || first === "-h" || first === "help") {
+    process.stdout.write(`${HELP}
+`);
+    return;
+  }
+  if (first === "--version" || first === "-v") {
+    process.stdout.write(`${version()}
+`);
+    return;
+  }
+  const rest = args.slice(1);
+  switch (first) {
+    case "run": {
+      const { runCliMain } = await import("./run-main-MK6LUIIS.js");
+      await runCliMain(rest, "metta run");
+      return;
+    }
+    case "check": {
+      const { runCliMain } = await import("./run-main-MK6LUIIS.js");
+      await runCliMain(["--check", ...rest], "metta check");
+      return;
+    }
+    case "debug": {
+      const { runDebugMain } = await import("./debug-main-Y254S5BG.js");
+      runDebugMain(rest, "metta debug");
+      return;
+    }
+    case "graph": {
+      const { runGraphMain } = await import("./graph-main-WRL2UUTS.js");
+      await runGraphMain(rest);
+      return;
+    }
+    default: {
+      const { runCliMain } = await import("./run-main-MK6LUIIS.js");
+      await runCliMain(args, "metta");
+      return;
+    }
+  }
+}
+main().catch((e) => {
+  process.stderr.write(`${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(1);
+});

package/dist/run-main-MK6LUIIS.js

@@ -0,0 +1,7 @@
+import {
+  runCliMain
+} from "./chunk-DHXPSARV.js";
+import "./chunk-L4U6ZIAR.js";
+export {
+  runCliMain
+};

package/dist/source.d.ts

@@ -0,0 +1,17 @@
+import { Atom, RunOptions, QueryResult, AsyncGroundFn } from '@mettascript/core';
+
+interface ParEvalOptions {
+    readonly hostEffects?: boolean;
+}
+/** Build the `RunOptions.parEvalImpl` hook the core runner calls for `(once (hyperpose …))`. Resolves the
+ *  built `@metta-ts/core` entry once (the worker re-imports it) and binds the step ceiling. */
+declare function makeParEvalImpl(fuel: number, options?: ParEvalOptions): (rulesSrc: string, branchSrcs: string[], firstOnly: boolean) => (string[] | null)[];
+
+/** Run a MeTTa source string with an in-memory import map and Node's worker-thread hyperpose hook. */
+declare function runSource(src: string, fuel?: number, imports?: Map<string, Atom[]>, opts?: RunOptions): QueryResult[];
+/** Run a source string and return one result entry for every top-level directive. */
+declare function runSourceAllDirectives(src: string, fuel?: number, imports?: Map<string, Atom[]>, opts?: RunOptions): QueryResult[];
+/** Async source runner for embedders that register async grounded operations. */
+declare function runSourceAsync(src: string, asyncOps?: Map<string, AsyncGroundFn>, fuel?: number, imports?: Map<string, Atom[]>, opts?: RunOptions, parOptions?: ParEvalOptions): Promise<QueryResult[]>;
+
+export { type ParEvalOptions, makeParEvalImpl, runSource, runSourceAllDirectives, runSourceAsync };

package/dist/source.js

@@ -0,0 +1,12 @@
+import {
+  makeParEvalImpl,
+  runSource,
+  runSourceAllDirectives,
+  runSourceAsync
+} from "./chunk-CWWQ3S7I.js";
+export {
+  makeParEvalImpl,
+  runSource,
+  runSourceAllDirectives,
+  runSourceAsync
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@mettascript/node",
+  "version": "2.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "metta": "./dist/metta-cli.js",
+    "metta-ts": "./dist/cli.js",
+    "metta-debug": "./dist/debug-cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./source": {
+      "types": "./dist/source.d.ts",
+      "default": "./dist/source.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@mettascript/core": "2.0.0",
+    "@mettascript/py": "2.0.0",
+    "@mettascript/debug": "2.0.0",
+    "@mettascript/prolog": "2.0.0",
+    "@mettascript/libraries": "2.0.0"
+  },
+  "author": "MesTTo",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Node.js entry for MeTTaScript: the metta-ts CLI, file import!, optional Python/Prolog interop, and a worker-thread parallel matcher.",
+  "keywords": [
+    "metta",
+    "hyperon",
+    "cli",
+    "atomspace",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MesTTo/MeTTaScript.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://github.com/MesTTo/MeTTaScript#readme",
+  "bugs": {
+    "url": "https://github.com/MesTTo/MeTTaScript/issues"
+  },
+  "devDependencies": {
+    "pythonia": "^1.2.6",
+    "ws": "^7.5.10",
+    "@mettascript/grapher": "2.0.0"
+  },
+  "peerDependencies": {
+    "pythonia": "^1.2.6",
+    "@mettascript/grapher": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@mettascript/grapher": {
+      "optional": true
+    },
+    "pythonia": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts src/debug-cli.ts src/metta-cli.ts src/source.ts --format esm --dts --clean"
+  }
+}