feat: benchmark + RESULTS, README status, runnable examples

Author: MesTTo

README.md

@@ -14,7 +14,16 @@ Performance stays pure TypeScript: staging/partial-evaluation of the eval loop,
 
 ## Status
 
-Pre-implementation. The full, self-contained implementation plan lives in [`docs/superpowers/plans/`](docs/superpowers/plans/).
+The core interpreter is implemented and **passes all 270 assertions** of Hyperon's oracle corpus — the full dependent-type tier (GADTs, dependent types, types-as-propositions), spaces and mutable state, nondeterminism, grounded operations, and documentation — matching the machine-checked LeaTTa result exactly. Pure TypeScript: it builds to a ~72 KB ESM bundle, runs in Node and the browser, with no native addon and no WASM.
+
+```bash
+pnpm install
+pnpm build
+pnpm test          # 270/270 Hyperon oracle gate + unit/property tests
+node packages/node/dist/cli.js examples/factorial.metta
+```
+
+Packages: [`@metta-ts/core`](packages/core) (the interpreter, zero platform deps), [`@metta-ts/node`](packages/node) (CLI + file `import!`), [`@metta-ts/browser`](packages/browser) (web entry + in-memory VFS). The full implementation plan and the binding spec live in [`docs/superpowers/`](docs/superpowers/).
 
 ## Provenance
 

examples/factorial.metta

@@ -0,0 +1,6 @@
+; Factorial via the minimal `unify` instruction (single rule, no divergence).
+; `unify` and the arithmetic ops come from the standard prelude.
+(= (fact $n) (unify $n 0 1 (* $n (fact (- $n 1)))))
+
+!(fact 5)    ; [120]
+!(fact 10)   ; [3628800]

examples/families.metta

@@ -0,0 +1,11 @@
+; A tiny knowledge base queried with `match` over the &self space, plus nondeterminism.
+(Parent Tom Bob)
+(Parent Bob Ann)
+(Parent Bob Pat)
+
+; Grandparent via a conjunctive match.
+(= (grandparent $g $c)
+   (match &self (, (Parent $g $p) (Parent $p $c)) ($g $c)))
+
+!(match &self (Parent Bob $child) $child)   ; [Bob's children: Ann, Pat]
+!(grandparent Tom $who)                     ; [(Tom Ann) (Tom Pat)]

packages/node/bench/RESULTS.md

@@ -0,0 +1,11 @@
+# Benchmark results
+
+Pure TypeScript, no native addon, no WASM. Node v22, single core. Run: `pnpm --filter @metta-ts/core build && node packages/node/bench/bench.mjs`.
+
+| benchmark | time |
+|-----------|------|
+| stdlib parse + load + `(+ 1 2)` (prelude cached) | ~0.07 ms |
+| `fib(18)` naive double-recursion (~10.9k calls) | ~185 ms |
+| full 270-assertion Hyperon oracle (22 files) | ~134 ms |
+
+These are correctness-first numbers (a faithful tree-walker; `buildEnv` is rebuilt per query, no memoization). The Phase-15 roadmap (staging/partial-evaluation, a flat interned atom core, a bytecode VM, a `mnemonist` AtomSpace index) targets the hot paths these expose, each gated by the 270/270 oracle so speed never costs correctness.

packages/node/bench/bench.mjs

@@ -0,0 +1,27 @@
+// Performance benchmark for the MeTTa TS interpreter (pure TypeScript, no native, no WASM).
+// Run after building core: `node packages/node/bench/bench.mjs`
+import { runProgram } from "../../core/dist/index.js";
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+function bench(name, f, iters = 1) {
+  for (let i = 0; i < 3; i++) f(); // warmup
+  const t = performance.now();
+  for (let i = 0; i < iters; i++) f();
+  const ms = (performance.now() - t) / iters;
+  console.log(name.padEnd(40), ms.toFixed(2) + " ms");
+}
+
+bench("stdlib parse+load + (+ 1 2)", () => runProgram("!(+ 1 2)"), 50);
+
+const fib =
+  "(= (fib $n) (unify $n 0 0 (unify $n 1 1 (+ (fib (- $n 1)) (fib (- $n 2))))))\n!(fib 18)";
+bench("fib(18) naive double-recursion", () => runProgram(fib), 5);
+
+const CORPUS = resolve(process.cwd(), "corpus");
+const files = readdirSync(CORPUS).filter((f) => f.endsWith(".metta") && f !== "c2_spaces_kb.metta");
+bench("full 270-assertion oracle (22 files)", () => {
+  for (const f of files) runProgram(readFileSync(resolve(CORPUS, f), "utf8"));
+});
+
+console.log("\nnode " + process.version + " | pure TypeScript, no native, no WASM");