MeTTa TS 1.0.8

Author: MesTTo

RELEASE_NOTES.md

@@ -1,32 +1,33 @@
-# MeTTa TS 1.0.7
+# MeTTa TS 1.0.8
 
 A pure-TypeScript implementation of [MeTTa](https://metta-lang.dev) (Meta Type Talk), the OpenCog Hyperon language. It runs anywhere TypeScript runs: the browser, Node, Deno, Bun, and edge or serverless functions. No native addons, no WASM, no Rust.
 
 ## Tested on Linux
 
 This release is tested on Linux (Node 20, the CI matrix): lint, format, typecheck, the full test suite, and the build all run there. Because the engine is pure TypeScript with no native addon and no WASM, it is meant to be cross-platform and should run unchanged on any JavaScript runtime. Other operating systems are not yet part of the tested matrix.
 
-## What's new: the proof-size-bounded backward chainer, from losing to winning
+## What's new: a static analyzer and `metta-ts --check`
 
-Nil Geisweiller's [`bfc-xp`](https://github.com/ngeiswei/chaining) benchmark searches a Łukasiewicz propositional calculus for a proof of a target formula under a fixed size bound, backtracking through modus ponens and three axiom schemes. It is a real nondeterministic search, not a lookup, and it was the one place PeTTa still beat MeTTa TS. This release closes that gap by compiling the search itself, not just the terms it searches over.
+This release adds a static analyzer that catches mistakes before a program runs and reports them the way a modern compiler does: the exact source span underlined, an error code, a message, and a suggested fix. It ships in `@metta-ts/core` as a library and on the `metta-ts` CLI as `--check`.
 
-A match-free nondeterministic group (no clause queries a space, only recursion, `if`-guards, and integer arithmetic) now compiles in two steps. First, every clause becomes a skeleton: a tree of constant subtrees, clause-variable slots, and structured nodes, computed once per group rather than copied per call. Second, the skeleton compiles to specialized JavaScript, one function per functor, generated once via `new Function` and shared by every run: head unification becomes read/write-mode code that fails at the first mismatch with no allocation, and body arguments and templates become direct constructor expressions with integer arithmetic unboxed. Underneath both steps, search variables are cell variables: a binding lives in a mutable slot on the variable itself, so dereferencing is pointer-chasing and undoing a failed branch is popping a trail array, no string-keyed map anywhere. Every bind carries an occurs check, so a would-be cyclic binding fails the search instead of looping, exactly the discipline `hasLoop` enforces on the interpreter's own immutable bindings and SWI-Prolog enforces under `occurs_check(true)`. A model in [`spec/loop_reject.als`](spec/loop_reject.als) proves the two mechanisms reject exactly the same binding sets, in every possible bind order. An environment that forbids dynamic code (a CSP without `unsafe-eval`) falls back to running the skeleton directly, still far faster than the plain interpreter; a group that does query a space (like `nilbc`, MeTTa TS's dependently-typed backward chainer) is unaffected and keeps running on the original interpreter-backed search.
+The analyzer reads the interpreter's own signature table, so it flags exactly the calls the interpreter itself would reject. A builtin called with the wrong number of arguments is checked against the same `(-> ...)` declaration the evaluator uses at run time, not against a second copy of the arity rules that could drift from it:
 
-The result, measured with `hyperfine` (mean ± σ, wall clock, engine startup included, each row from one `hyperfine` invocation so the two columns are directly comparable):
+```
+error[arity-mismatch]: prog.metta:1:2
+  |
+1 | !(car-atom 1 2)
+  |  ^^^^^^^^^^^^^^ car-atom expects 1 argument, got 2
+```
 
-| benchmark                                           |           MeTTa TS |              PeTTa |
-| --------------------------------------------------- | -----------------: | -----------------: |
-| `jarr` (size 13)                                    |  124.8 ms ± 4.2 ms | 182.9 ms ± 10.6 ms |
-| `pm2.27` (size 13)                                  |  121.6 ms ± 1.3 ms |  183.0 ms ± 8.3 ms |
-| `imim1` (size 15)                                   |  152.2 ms ± 4.1 ms |  212.3 ms ± 3.9 ms |
-| `jarr` (size 17), PeTTa with `occurs_check(true)`   | 455.5 ms ± 69.5 ms | 476.0 ms ± 11.8 ms |
-| `loowoz` (size 19), PeTTa with `occurs_check(true)` |  2.092 s ± 0.063 s |  2.501 s ± 0.003 s |
+An opt-in `--undefined-symbols` pass adds a "did you mean" on an unknown head, suggesting the closest defined name by edit distance. It is off by default because MeTTa's add-mode makes an unknown head legal: `(foo 1 2)` with no rule for `foo` is data added to the space, not a typo. With the flag on, `(fibonaci 10)` next to a defined `fibonacci` becomes a warning that carries the fix, never an error.
 
-The last two rows run PeTTa with `occurs_check(true)`, which its SWI-Prolog translation does not set (the flag defaults to off). At these two deeper searches that gap is not just a speed difference: PeTTa as shipped finds 94 answers for `jarr` at size 17 where only 91 exist, and 44 for `loowoz` at size 19 where only 3 exist, the surplus being cyclic-binding artifacts that `occurs_check` is exactly the guard against (the same requirement `bfc-xp`'s own SWI harness documents). Run correctly, PeTTa is a little slower here too. Every MeTTa TS answer above is checked byte-identical to the plain interpreter by a differential oracle that runs the search both ways (`packages/core/src/moded-tabling.test.ts`), and the compiled and interpreted engines' outputs are additionally diffed directly at sizes 17 and 19.
+Precise spans come from a span-tracking parse that reuses the interpreter's own reader primitives, so the analyzer cannot disagree with the real parser about where a token starts or ends. `--json` emits the findings as a Language Server Protocol `Diagnostic[]`, each with a range, a severity, a code, and suggestions that carry an applicability tier, so an editor or a language server can consume them directly.
+
+None of this changes the evaluator. The only edit to existing run-time code is a refactor of the parser that exports the primitives the span parser reuses, and it is guarded by the parser's own tests. So the 270-assertion Hyperon oracle and the corpus benchmark below are byte-identical to 1.0.7, and the analyzer adds no dependency.
 
 ## Corpus benchmark
 
-The existing PeTTa-corpus benchmark (107 shared programs, 97 both engines pass, median 2.01x, geomean 2.06x) is unaffected by this release: none of those programs exercise a match-free nondeterministic group, so they run the same code as before. See [`packages/node/bench/RESULTS-corpus.md`](packages/node/bench/RESULTS-corpus.md) for the full per-program table.
+The engine is unchanged in this release, so the PeTTa-corpus benchmark (107 shared programs, 97 both engines pass, median 2.01x, geomean 2.06x) is identical to 1.0.7. See [`packages/node/bench/RESULTS-corpus.md`](packages/node/bench/RESULTS-corpus.md) for the full per-program table.
 
 ## Major performance gains (since 1.0.0)
 
@@ -39,16 +40,16 @@ The speed comes from general engine work:
 - automatic tabling of pure functions, including ones defined at runtime, and moded (variant) tabling for non-ground pure calls;
 - a native-code compiler for the pure deterministic int/bool/tuple subset, with tail-recursion compiled to loops and higher-order specialisation;
 - worker-thread parallelism: `(once (hyperpose ...))` races branches across CPU cores on Node, and a `SharedArrayBuffer` flat matcher scans large knowledge bases in parallel;
-- the compiled clause-skeleton and JavaScript-codegen search described above, for match-free nondeterministic groups.
+- the compiled clause-skeleton and JavaScript-codegen search for match-free nondeterministic groups, added in 1.0.7.
 
 Every optimisation is verified byte-identical against the 270-assertion Hyperon oracle.
 
 ## What is in this release
 
-- `@metta-ts/core` is the interpreter, parser, type system, pattern matching, and standard library, as a single ESM bundle. It passes all 270 assertions of Hyperon's oracle corpus (the full dependent-type tier, spaces and mutable state, nondeterminism, grounded operations, and documentation), cross-checked against [LeaTTa](https://github.com/MesTTo/LeaTTa), the machine-checked (Lean 4) MeTTa semantics pinned to the same commit.
+- `@metta-ts/core` is the interpreter, parser, type system, pattern matching, and standard library, as a single ESM bundle. It now also carries the static analyzer and its diagnostic model, described above. It passes all 270 assertions of Hyperon's oracle corpus (the full dependent-type tier, spaces and mutable state, nondeterminism, grounded operations, and documentation), cross-checked against [LeaTTa](https://github.com/MesTTo/LeaTTa), the machine-checked (Lean 4) MeTTa semantics pinned to the same commit.
 - `@metta-ts/hyperon` is a TypeScript class API modeled on Python's `hyperon`, with a JavaScript interop layer (`js-atom`, `js-dot`, `js-list`, `js-dict`) that calls into the host runtime directly.
 - `@metta-ts/edsl` is a typed eDSL with term builders, special-form combinators, and a tagged-template surface.
-- `@metta-ts/node` has the `metta-ts` CLI, file `import!`, and the worker-thread parallel matcher.
+- `@metta-ts/node` has the `metta-ts` CLI, now with `--check` for static analysis, plus file `import!` and the worker-thread parallel matcher.
 - `@metta-ts/browser` is a browser entry with an in-memory virtual file system for `import!`.
 - `@metta-ts/grapher` renders a MeTTa reduction as a node graph or a nested-block view, as static SVGs or an animated GIF, with a data-driven stylesheet for node size and colour.
 - `@metta-ts/das-client` and `@metta-ts/das-gateway` are an optional client to SingularityNET's Distributed AtomSpace, run end to end against a live cluster, with atom handles matching the AtomDB byte for byte.
@@ -60,6 +61,14 @@ npm install @metta-ts/core        # the interpreter (works in any JS runtime)
 npm install -g @metta-ts/node     # the metta-ts CLI
 ```
 
+Check a file without running it:
+
+```bash
+metta-ts --check program.metta                       # arity errors, rustc-style
+metta-ts --check --undefined-symbols program.metta   # also "did you mean" on unknown heads
+metta-ts --check --json program.metta                # diagnostics as an LSP Diagnostic[]
+```
+
 ## Provenance
 
 - Semantics: [hyperon-experimental](https://github.com/trueagi-io/hyperon-experimental), pinned to commit `3f76dc4`.

packages/browser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/browser",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/core",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",

packages/core/src/cst.test.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+// SPDX-License-Identifier: MIT
+import { describe, it, expect } from "vitest";
+import { parseAllSpanned } from "./cst";
+import { standardTokenizer } from "./runner";
+import { format } from "./parser";
+
+describe("parseAllSpanned", () => {
+  it("records the span of a nested symbol precisely", () => {
+    const src = "(map (fibonaci 10) $xs)";
+    const [top] = parseAllSpanned(src, standardTokenizer());
+    // top is the whole (map ...) expr
+    expect(src.slice(top!.span.start, top!.span.end)).toBe("(map (fibonaci 10) $xs)");
+    // children[1] is (fibonaci 10); its children[0] is `fibonaci`
+    const fib = top!.children![1]!.children![0]!;
+    expect(src.slice(fib.span.start, fib.span.end)).toBe("fibonaci");
+  });
+
+  it("marks a top-level !-query and spans the form after the bang", () => {
+    const src = "!(car-atom)";
+    const [top] = parseAllSpanned(src, standardTokenizer());
+    expect(top!.bang).toBe(true);
+    expect(src.slice(top!.span.start, top!.span.end)).toBe("(car-atom)");
+  });
+
+  it("produces the same atoms as the plain parser", () => {
+    const src = "(= (f $x) (+ $x 1))\n!(f 2)";
+    const spanned = parseAllSpanned(src, standardTokenizer());
+    expect(spanned.map((n) => format(n.atom))).toEqual(["(= (f $x) (+ $x 1))", "(f 2)"]);
+  });
+
+  it("spans a string literal including its quotes", () => {
+    const src = '(greet "hi")';
+    const [top] = parseAllSpanned(src, standardTokenizer());
+    const strNode = top!.children![1]!;
+    expect(src.slice(strNode.span.start, strNode.span.end)).toBe('"hi"');
+  });
+});

packages/core/src/cst.ts

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+// SPDX-License-Identifier: MIT
+
+// A span-tracking parse: the same atoms `parseAll` produces, plus the source range of every node.
+// Off the `runFile` hot path entirely; only the static analyzer calls it. It reuses parser.ts's
+// char-level primitives so it cannot drift from the real parser.
+import { type Atom, expr } from "./atom";
+import { type Tokenizer } from "./tokenizer";
+import { isDelim, skipTrivia, readStringAt, leafAtom, MAX_DEPTH } from "./parser";
+
+export interface Span {
+  readonly start: number;
+  readonly end: number;
+}
+
+/** One CST node: the atom it parses to, its source range, and (for expressions) its children. The
+ *  top-level marker `bang` is set on a node parsed from a `!`-query. */
+export interface SpannedNode {
+  readonly atom: Atom;
+  readonly span: Span;
+  readonly children?: readonly SpannedNode[];
+  readonly bang?: boolean;
+}
+
+function readSpanned(
+  s: string,
+  pos: number,
+  tk: Tokenizer,
+  depth: number,
+): { node: SpannedNode; end: number } {
+  pos = skipTrivia(s, pos);
+  const start = pos;
+  const ch = s[pos];
+  if (ch === "(") {
+    if (depth >= MAX_DEPTH) throw new Error("MeTTa expression nesting too deep");
+    pos++;
+    const children: SpannedNode[] = [];
+    for (;;) {
+      pos = skipTrivia(s, pos);
+      if (pos >= s.length) throw new Error("unbalanced '(' in MeTTa source");
+      if (s[pos] === ")") {
+        pos++;
+        break;
+      }
+      const r = readSpanned(s, pos, tk, depth + 1);
+      children.push(r.node);
+      pos = r.end;
+    }
+    const atom = expr(children.map((c) => c.atom));
+    return { node: { atom, span: { start, end: pos }, children }, end: pos };
+  }
+  if (ch === '"') {
+    const { atom, end } = readStringAt(s, pos);
+    return { node: { atom, span: { start, end } }, end };
+  }
+  let end = pos;
+  while (end < s.length && !isDelim(s[end]!)) end++;
+  const word = s.slice(pos, end);
+  return { node: { atom: leafAtom(word, tk), span: { start, end } }, end };
+}
+
+/** Parse a whole program into spanned top-level nodes. Mirrors `parseAll`, adding spans and the
+ *  `bang` marker for `!`-queries. */
+export function parseAllSpanned(src: string, tk: Tokenizer): SpannedNode[] {
+  const out: SpannedNode[] = [];
+  let pos = skipTrivia(src, 0);
+  while (pos < src.length) {
+    let bang = false;
+    if (src[pos] === "!") {
+      bang = true;
+      pos = skipTrivia(src, pos + 1);
+    }
+    const r = readSpanned(src, pos, tk, 0);
+    out.push({ ...r.node, bang });
+    pos = skipTrivia(src, r.end);
+  }
+  return out;
+}

packages/core/src/diagnose.test.ts

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+// SPDX-License-Identifier: MIT
+import { describe, it, expect } from "vitest";
+import { analyzeSource } from "./diagnose";
+import { DiagnosticSeverity } from "./diagnostic";
+
+const cfg = { undefinedSymbols: false };
+
+describe("analyzeSource — arity", () => {
+  it("flags too many arguments to a signed builtin", () => {
+    // car-atom : (-> Expression %Undefined%), one parameter
+    const diags = analyzeSource("!(car-atom (a b) (c d))", cfg);
+    expect(diags).toHaveLength(1);
+    expect(diags[0]!.code).toBe("arity-mismatch");
+    expect(diags[0]!.severity).toBe(DiagnosticSeverity.Error);
+    expect(diags[0]!.message).toContain("car-atom");
+    expect(diags[0]!.message).toContain("1 argument");
+    // primary span is the whole call
+    const src = "!(car-atom (a b) (c d))";
+    const r = diags[0]!.range;
+    expect(r.start).toEqual({ line: 0, character: 1 });
+    expect(r.end).toEqual({ line: 0, character: src.length });
+  });
+
+  it("accepts a correct-arity call", () => {
+    expect(analyzeSource("!(car-atom (a b))", cfg)).toEqual([]);
+  });
+
+  it("does not flag an op that has no declared signature", () => {
+    // `foo` is unknown; with undefinedSymbols off, nothing is reported
+    expect(analyzeSource("!(foo 1 2 3)", cfg)).toEqual([]);
+  });
+
+  it("reports every arity error in one pass, sorted by position", () => {
+    const diags = analyzeSource("!(car-atom 1 2)\n!(cdr-atom 1 2)", cfg);
+    expect(diags.map((d) => d.code)).toEqual(["arity-mismatch", "arity-mismatch"]);
+    expect(diags[0]!.range.start.line).toBe(0);
+    expect(diags[1]!.range.start.line).toBe(1);
+  });
+});
+
+describe("analyzeSource — undefined head (gated)", () => {
+  const on = { undefinedSymbols: true };
+
+  it("does not flag an unknown head when the gate is off", () => {
+    expect(analyzeSource("!(fibonaci 10)", { undefinedSymbols: false })).toEqual([]);
+  });
+
+  it("warns on an unknown head with a near-miss to a defined symbol", () => {
+    const src = "(= (fibonacci $n) $n)\n!(fibonaci 10)";
+    const diags = analyzeSource(src, on);
+    const warn = diags.find((d) => d.code === "unknown-symbol");
+    expect(warn).toBeDefined();
+    expect(warn!.severity).toBe(DiagnosticSeverity.Warning);
+    expect(warn!.message).toContain("fibonaci");
+    expect(warn!.suggestions?.[0]?.replacement).toBe("fibonacci");
+    // primary span underlines just the head, not the whole call
+    expect(warn!.range.start.line).toBe(1);
+    expect(warn!.range.start.character).toBe(2); // after "!("
+  });
+
+  it("stays silent for an unknown head with no near match", () => {
+    const diags = analyzeSource("!(totallyunrelated 1)", on);
+    expect(diags.find((d) => d.code === "unknown-symbol")).toBeUndefined();
+  });
+
+  it("does not warn on a known stdlib op", () => {
+    const diags = analyzeSource("!(car-atom (a b))", on);
+    expect(diags.find((d) => d.code === "unknown-symbol")).toBeUndefined();
+  });
+});