@metta-ts/node 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,36 @@
+# @metta-ts/node
+
+Node.js entry for [MeTTa TS](https://github.com/MesTTo/Meta-TypeScript-Talk): the `metta-ts` command-line runner, file-based `import!`, and a `SharedArrayBuffer` worker-thread parallel matcher. Re-exports everything from [`@metta-ts/core`](https://github.com/MesTTo/Meta-TypeScript-Talk/tree/main/packages/core).
+
+## Install
+
+```bash
+npm install @metta-ts/node
+# for the CLI on your PATH:
+npm install -g @metta-ts/node
+```
+
+## CLI
+
+```bash
+metta-ts path/to/program.metta
+# or without a global install:
+npx -p @metta-ts/node metta-ts path/to/program.metta
+```
+
+## Usage
+
+```ts
+import { runFile, ParallelFlatMatcher } from "@metta-ts/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/Meta-TypeScript-Talk/blob/main/LICENSE).

package/dist/chunk-FIH2Z2UY.js

@@ -0,0 +1,250 @@
+// src/index.ts
+import { readFileSync, existsSync } from "fs";
+import { resolve, dirname, sep } from "path";
+import {
+  parseAll,
+  standardTokenizer,
+  evalSequential,
+  collectImports,
+  DEFAULT_FUEL
+} from "@metta-ts/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 } = workerData;
+const view = new Int32Array(sab);
+(async () => {
+  try {
+    const m = await import(corePath);
+    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) {
+  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
+      }
+    })
+  );
+  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) {
+  const corePath = createRequire(import.meta.url).resolve("@metta-ts/core");
+  return (rulesSrc, branchSrcs, firstOnly) => evalBranchesParallel(corePath, rulesSrc, branchSrcs, firstOnly, fuel);
+}
+
+// src/index.ts
+export * from "@metta-ts/core";
+
+// src/flat-parallel.ts
+import { Worker as Worker2 } from "worker_threads";
+import { availableParallelism } from "os";
+import { encodePattern, decodeAt } from "@metta-ts/core";
+var WORKER_SRC2 = `
+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 Worker2(WORKER_SRC2, {
+        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 readImports(src, baseDir) {
+  const m = /* @__PURE__ */ new Map();
+  const base = resolve(baseDir);
+  for (const name of collectImports(src)) {
+    const p = resolve(base, name.endsWith(".metta") ? name : name + ".metta");
+    if (p !== base && !p.startsWith(base + sep)) continue;
+    if (existsSync(p))
+      m.set(
+        name,
+        parseAll(readFileSync(p, "utf8"), standardTokenizer()).filter((t) => !t.bang).map((t) => t.atom)
+      );
+  }
+  return m;
+}
+function runFile(path, fuel, opts) {
+  const src = readFileSync(path, "utf8");
+  const tops = parseAll(src, standardTokenizer());
+  const withPar = opts?.parEvalImpl === void 0 ? { ...opts, parEvalImpl: makeParEvalImpl(fuel ?? DEFAULT_FUEL) } : opts;
+  return evalSequential(tops, fuel, readImports(src, dirname(resolve(path))), withPar);
+}
+
+export {
+  ParallelFlatMatcher,
+  readImports,
+  runFile
+};

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import {
+  runFile
+} from "./chunk-FIH2Z2UY.js";
+
+// src/cli.ts
+import { parseArgs } from "util";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import { format } from "@metta-ts/core";
+function reexecWithLargerStack() {
+  if (process.env.METTA_TS_STACK !== void 0) return;
+  const res = spawnSync(
+    process.execPath,
+    ["--stack-size=8000", fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+    { stdio: "inherit", env: { ...process.env, METTA_TS_STACK: "1" } }
+  );
+  process.exit(res.status ?? 1);
+}
+function main() {
+  reexecWithLargerStack();
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      "max-steps": { type: "string" },
+      "max-stack-depth": { type: "string" }
+    }
+  });
+  const file = positionals[0];
+  if (file === void 0) {
+    process.stderr.write("usage: metta-ts [--max-steps=N] [--max-stack-depth=N] <file.metta>\n");
+    process.exit(2);
+  }
+  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;
+  for (const r of runFile(
+    file,
+    fuel,
+    maxStackDepth !== void 0 ? { maxStackDepth } : void 0
+  )) {
+    process.stdout.write("[" + r.results.map(format).join(", ") + "]\n");
+  }
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { FlatKB, Atom, RunOptions, QueryResult } from '@metta-ts/core';
+export * from '@metta-ts/core';
+
+/** 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>;
+}
+
+/** Pre-read every `import!` target referenced in `src`, resolving names against `baseDir`. */
+declare function readImports(src: string, baseDir: string): Map<string, Atom[]>;
+/** 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[];
+
+export { ParallelFlatMatcher, readImports, runFile };

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  ParallelFlatMatcher,
+  readImports,
+  runFile
+} from "./chunk-FIH2Z2UY.js";
+export {
+  ParallelFlatMatcher,
+  readImports,
+  runFile
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@metta-ts/node",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "metta-ts": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@metta-ts/core": "1.0.0"
+  },
+  "author": "MesTTo",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Node.js entry for MeTTa TS: the metta-ts CLI, file import!, and a worker-thread parallel matcher.",
+  "keywords": [
+    "metta",
+    "hyperon",
+    "cli",
+    "atomspace",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MesTTo/Meta-TypeScript-Talk.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://github.com/MesTTo/Meta-TypeScript-Talk#readme",
+  "bugs": {
+    "url": "https://github.com/MesTTo/Meta-TypeScript-Talk/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean"
+  }
+}