MeTTa TS 1.1.3

Author: MesTTo

README.md

@@ -302,6 +302,21 @@ A representative slice (wall-clock, subprocess including startup; `speedup` = Pe
 
 The full per-program table is in [`RESULTS-corpus.md`](packages/node/bench/RESULTS-corpus.md).
 
+Patrick Hammer also supplied four adversarial nondeterministic programs that were slow or exhausted memory in an older build. [`packages/node/bench/nondeterminism.mjs`](packages/node/bench/nondeterminism.mjs) keeps those query shapes as a separate checked benchmark. Five-run subprocess medians, including startup:
+
+| Program                          |     PeTTa |  MeTTa TS |   Speedup |
+| -------------------------------- | --------: | --------: | --------: |
+| filtered `matespacefast` matches | 5738.1 ms | 3344.2 ms | **1.72x** |
+| 22^4 `superpose` cross product   |  388.7 ms |  148.5 ms | **2.62x** |
+| nondeterministic tabled `fib(7)` |  180.1 ms |   99.6 ms | **1.81x** |
+| duplicate-heavy `TupleConcat`    |  178.8 ms |  101.1 ms | **1.77x** |
+
+The benchmark validates all 234,256 cross-product results, all 196 distinct Fibonacci answers, the exact `TupleConcat` result, and the embedded matespace assertion. MeTTa TS uses the same default evaluator as the CLI. No benchmark, PeTTa, curry, or tabling mode is selected.
+
+Automatic tabling does not memoize every recursive function. Admission requires transitive purity and a recursive strongly connected component that branches back into itself at least twice. Linear recursion such as factorial stays on the compiled path. Custom host operations and space, state, file, random, time, import, and output operations are excluded.
+
+Completed and active tables share hard entry, answer, retained-cell, per-entry, and interner limits. Completed entries are LRU-evictable. Active entries cannot be evicted while their producer runs, so a call that cannot fit returns `TableResourceLimit` instead of continuing toward process exhaustion. See [Scaling to millions of atoms](website/advanced/scaling.md#automatic-tabling) for the current limits and completion policy.
+
 That speed comes from general engine work:
 
 - an O(1)-stack reduce-loop trampoline;
@@ -310,7 +325,10 @@ That speed comes from general engine work:
 - an O(1)-stack worklist for nondeterminism;
 - ground-atom type memoisation;
 - an exact-match ground-fact index;
-- bounded automatic tabling of pure overlapping-recursive functions, with structural token keys and runtime rule-versioned entries;
+- nested argument-functor indexing for ground runtime facts such as `(num (M $x))`;
+- bounded automatic tabling of pure overlapping-recursive functions, with structural token keys, runtime rule-versioned entries, and one shared budget for completed and active tables;
+- consumer-directed distinct memoization and streaming choice deduplication only where `unique-atom(collapse(...))` makes duplicate derivations unobservable, while ordinary `collapse` keeps its exact ordered bag;
+- a slot-based evaluator for closed pure `let` and `superpose` products that preserves result order and multiplicity without allocating general binding frames;
 - a native-code compiler for the pure deterministic int/bool/tuple subset, with tail-recursion compiled to loops and PeTTa-style **higher-order specialisation** so a function passed as an argument (e.g. `iterate`'s `$step`) is bound and compiled rather than interpreted;
 - a compiler for **nondeterministic `let*`-chain functions** (the backward-chainer class): a multi-equation function whose clause bodies chain space matches and recursive calls compiles to a clause-major depth-first search, the same fragment PeTTa hands to Prolog's clause alternatives;
 - a compiler for **add-atom saturation loops**: the add-if-absent idiom becomes one exact-membership probe plus append, and a single-branch `case` over a space match becomes a snapshot-and-thread loop with Empty-pruned branches.

RELEASE_NOTES.md

@@ -1,148 +1,152 @@
-# MeTTa TS 1.1.2
+# MeTTa TS 1.1.3
 
-A pure-TypeScript implementation of [MeTTa](https://metta-lang.dev), the
-OpenCog Hyperon language. The core engine runs in the browser, Node, Deno, Bun,
-edge runtimes, and TypeScript-based agents with no native addon and no required
-WASM. Optional host adapters can load Python or Prolog runtimes when a program
-asks for them.
+MeTTa TS 1.1.3 improves nondeterministic evaluation and bounds every automatic
+table allocation. The default evaluator is faster than PeTTa on the four
+reported nondeterministic workloads while preserving Hyperon semantics. There
+is no benchmark mode, PeTTa mode, curry mode, or manually selected fast path.
 
 ## Tested on Linux
 
 This release is prepared on Linux with Node 22 and pnpm 11. The release gate
 builds every package, typechecks the workspace, runs the full Vitest suite,
-builds the GitHub Pages documentation, runs the oracle checks, and runs the
-benchmark suite before tagging. Optional Python, Pyodide, SWI-Prolog, and
-SWI-WASM adapters are built and covered by their available tests, with live
-runtime checks depending on the host tools installed in the release
-environment.
-
-The current conformance rerun reports Core/ST at 431 passed, 77 failed, 60
-expected failures, and 0 skipped. Full/ST with `fileio,json,random` reports 470
-passed, 174 failed, 4 expected failures, and 26 skipped. The remaining gaps are
-the tracked parser/directive, kernel, typing, stdlib, feature, and concurrency
-divergences, so this release should not be described as full Hyperon
-conformance.
-
-## What's new
-
-### Integrated host interop release train
-
-This release includes the full local host-interop train that followed 1.1.0:
-browser host adapters, Python and Prolog runtime splits, SWI-WASM, Pyodide,
-source runners, async effects, CLI checks, and the eDSL host builders.
-
-### Browser Python and Prolog
-
-`@metta-ts/browser/host` composes optional host runtimes into the browser
-runner. A browser app can now run the same `.metta` program shape as Node:
-
-```metta
-!(import! &self "math.py")
-!(py-call (math.add 40 2))
-
-!(import! &self "facts.pl")
-!(prolog-call (edge alice $x))
-```
-
-Python runs through `@metta-ts/py/pyodide`. Prolog runs through
-`@metta-ts/prolog/swi-wasm`. The base `@metta-ts/browser` package stays
-runtime-agnostic; Pyodide and SWI-WASM are only included when their adapter
-subpaths are imported.
-
-### Prolog interop package
-
-`@metta-ts/prolog` is now part of the release. The root package contains the
-generic bridge and MeTTa-side helper source. Runtime adapters live on subpaths:
-
-- `@metta-ts/prolog/swi-node` talks to a local `swipl` executable.
-- `@metta-ts/prolog/swi-wasm` runs through `swipl-wasm`.
-
-The supported surface follows PeTTa where the operation is a host Prolog bridge:
-`Predicate`, `callPredicate`, `assertaPredicate`, `assertzPredicate`,
-`retractPredicate`, `prolog-call`, `prolog-consult`, and
-`import_prolog_function`.
-
-MeTTa TS keeps Hyperon-style evaluation. There is no PeTTa mode and no curry
-mode. Plain `.pl` imports and predicate calls are host capabilities, not a
-second evaluator.
+builds the GitHub Pages documentation, runs the Hyperon oracle, runs the scale
+proof, and runs the benchmark suite before tagging.
 
-### Runtime adapter split
+The final suite passed 109 test files and 1,063 tests, with 38 optional live
+integration tests skipped. The checked 270-assertion oracle passed all 23
+corpus files.
 
-The Python and Prolog roots no longer import runtime backends from their package
-roots. Node-specific adapters are explicit subpaths:
-
-- `@metta-ts/py/pythonia`
-- `@metta-ts/prolog/swi-node`
-
-Browser adapters are explicit subpaths:
-
-- `@metta-ts/py/pyodide`
-- `@metta-ts/prolog/swi-wasm`
-
-That keeps default imports browser-clean and leaves optional dependencies behind
-their adapter subpaths.
-
-### eDSL host helpers
-
-`@metta-ts/edsl/py` and `@metta-ts/edsl/prolog` provide dependency-free builders
-for the host interop forms. They build ordinary atoms such as `py-call`,
-`py-atom`, `prolog-call`, `Predicate`, and `import_prolog_function`. They do
-not load Python, Prolog, Pyodide, SWI-WASM, or Node adapters.
-
-```ts
-import { vars } from "@metta-ts/edsl";
-import { pyCall } from "@metta-ts/edsl/py";
-import { prologCall } from "@metta-ts/edsl/prolog";
-
-const { x } = vars();
-
-pyCall("math.add", 40, 2); // (py-call (math.add 40 2))
-prologCall(["edge", "alice", x]); // (prolog-call (edge alice $x))
-```
-
-### Bounded structural tabling
-
-Automatic tabling now uses structural token keys and a bounded table space
-instead of recursive printed-form keys. Pure overlapping-recursive calls can be
-memoized without table growth being unbounded:
-
-- completed pure entries are capped and LRU-evictable;
-- interner resets invalidate old opaque table keys;
-- runtime rules are version-keyed;
-- impure, meta, state, import, `match`, `collapse`, and concurrency paths stay
-  outside the table cache;
-- direct active variant recursion uses local-linear completion for finite answer
-  sets;
-- non-cyclic calls keep exact ordered-bag memoization.
+The external Core/ST conformance result is unchanged from the untouched 1.1.2
+baseline: 431 passed, 77 failed, 60 manifest expected failures, and 0 skipped.
+The remaining failures are existing parser, directive, kernel, typing, and
+stdlib contract differences. This release does not claim full specification
+conformance.
 
-The stale-key path reported during release review is covered by a regression:
-old tail-call pending keys cannot write into a new interner generation after a
-table-space reset.
+## Nondeterministic execution
+
+The new checked benchmark keeps four query shapes reported by Patrick Hammer
+as ordinary `.metta` files. Five-run subprocess medians include startup:
+
+| Program                          |     PeTTa |  MeTTa TS | Speedup |
+| -------------------------------- | --------: | --------: | ------: |
+| filtered `matespacefast` matches | 5738.1 ms | 3344.2 ms |   1.72x |
+| 22^4 `superpose` cross product   |  388.7 ms |  148.5 ms |   2.62x |
+| nondeterministic tabled `fib(7)` |  180.1 ms |   99.6 ms |   1.81x |
+| duplicate-heavy `TupleConcat`    |  178.8 ms |  101.1 ms |   1.77x |
+
+The harness validates 234,256 cross-product results, 196 distinct Fibonacci
+answers, the exact `TupleConcat` sequence, and the embedded matespace
+assertion. Run it with `pnpm bench:nondeterminism`.
+
+A slot-based choice evaluator handles closed pure `let`, `let*`, `superpose`,
+integer arithmetic, comparisons, `if`, and constructor tuples. Unsupported,
+redefined, ill-typed, async, or executable-grounded forms stay on the normal
+interpreter path. Result order and multiplicity are unchanged.
+
+`unique-atom(collapse(call))` can evaluate a supported static pure integer
+recurrence as a first-seen answer set. Closed pure choice products also retain
+first-seen answers as they emit instead of materializing a duplicate bag first.
+An ordinary `collapse(call)` still returns its exact ordered bag with duplicate
+derivations. Ground answer deduplication uses structural hashes with equality
+checks instead of a quadratic scan.
+
+## Bounded automatic tabling
+
+Automatic table admission remains conservative. The whole rule dependency
+graph must be pure, the call key must be safe, and the recursive component must
+branch back into itself at least twice. Linear recursion stays on the normal
+compiled path.
+
+The policy does not assume that every recursive program is safe to memoize and
+does not let admitted tables grow until the process runs out of memory. It
+combines the static overlap test with one global runtime budget. Exceeding the
+active-state budget returns `TableResourceLimit`; it does not continue toward
+an out-of-memory failure.
+
+Completed and active tables now share these default ceilings:
+
+- 50,000 entries
+- 1,000,000 answers
+- 1,000,000 retained atom cells
+- 100,000 cells in one entry
+- 250,000 interned leaves
+
+Completed tables are removed in least-recently-used order. Active tables are
+not evicted while their producer runs, so they return `TableResourceLimit` when
+the shared budget cannot fit more state. The consumer-directed recurrence memo
+uses the same entry, answer, cell, and per-entry limits. Interner generations
+prevent stale tail-call keys from writing after a reset.
+
+Direct active variant recursion still uses local-linear fixed-point completion.
+Non-cyclic calls preserve exact ordered bags. The evaluator does not infer
+Picat-style `min` or `max` answer subsumption.
+
+## Matching and scale
+
+Ground runtime facts now have a nested argument-functor index. A pattern such
+as `(num (M $x))` selects the `M` bucket instead of scanning every `num` fact.
+The matcher falls back to complete candidates when a non-ground fact could
+unify.
+
+A finite in-memory match whose result is discarded by a standard
+`let ... (empty)` is removed before enumeration. The optimization declines for
+custom grounded matchers, mutable state handles, changed standard forms, and
+non-memory spaces.
+
+The 30,000-fact scale gate also runs larger actual MeTTa workloads:
+
+| Program                    |                  Checked result |     Time |
+| -------------------------- | ------------------------------: | -------: |
+| 24^4 pure choice product   |                 331,776 answers |  81.2 ms |
+| duplicate tuple product    | 50 values from 500,000 branches |  30.8 ms |
+| nondeterministic `fib(10)` |          2,817 distinct answers |  73.4 ms |
+| nested runtime match       |                  30,000 answers | 647.3 ms |
+
+## Correctness fixes
+
+- `superpose` in the choice evaluator now strips a collapsed bag's leading
+  comma marker. The recursive `supercollapse` corpus case remains empty as
+  Hyperon requires.
+- Choice planning now respects application type errors, expression-headed
+  rewrite rules, and replaced sync or async grounded operations.
+- Nested indexing no longer changes candidate enumeration when a pattern has
+  no nested-head constraint.
+- Active table entries and answers count against the same global resource
+  budget as completed entries.
+- The purity firewall now treats custom sync and async grounded operations as
+  effectful unless they are the unchanged implementation of a known-pure
+  built-in. File, catalog, random, time, output, fresh-identity, and host calls
+  cannot enter automatic tables transitively.
+- File handles can be closed immediately with `file-close!` and are also closed
+  when their grounded atom is collected. Dictionary spaces and file records use
+  weak-key storage instead of lifetime-unbounded global maps. Grounded behavior
+  and non-default grounded types remain on the lossless atomspace path.
+- Grounded-operation registration invalidates evaluated terms, table analyses,
+  and compiled closures that may encode the previous dispatch behavior.
+- DAS gateway binding responses must contain exactly one MeTTa atom per value.
+  Malformed or multi-atom wire values now fail at the decode boundary.
+- Git imports pass an end-of-options marker before the repository path.
+- The unused `streamEmit`, `tableBackchain`, and `trieSpace` experimental
+  options have been removed. They never selected an implementation.
 
 ## Install
 
 ```bash
-npm install @metta-ts/core
-npm install -g @metta-ts/node
-npm install @metta-ts/py pythonia
-npm install @metta-ts/prolog
+npm install @metta-ts/core@1.1.3
+npm install -g @metta-ts/node@1.1.3
 ```
 
-Browser projects that use optional host runtimes should also install the runtime
-adapter they import:
+Optional host packages use the same version:
 
 ```bash
-npm install pyodide swipl-wasm
+npm install @metta-ts/py@1.1.3 pythonia
+npm install @metta-ts/prolog@1.1.3
 ```
 
 ## Provenance
 
 - Semantics: [hyperon-experimental](https://github.com/trueagi-io/hyperon-experimental).
-- Python interop surface: PeTTa's `py-call` and Hyperon's
-  [`py-atom`](https://trueagi-io.github.io/hyperon-experimental/reference/atoms/)
-  family.
-- Prolog interop surface: PeTTa-compatible predicate bridge forms where they do
-  not depend on PeTTa's evaluator.
-- Verified spec and differential oracle:
-  [LeaTTa](https://github.com/MesTTo/LeaTTa).
+- Verified differential semantics: [LeaTTa](https://github.com/MesTTo/LeaTTa).
+- Host compatibility: PeTTa-compatible Python and Prolog bridge forms where
+  they do not depend on PeTTa's evaluator.
 - License: [MIT](LICENSE).

package.json

@@ -16,7 +16,8 @@
     "format": "prettier --write \"packages/*/src/**/*.ts\" \"*.{json,md}\"",
     "format:check": "prettier --check \"packages/*/src/**/*.ts\" \"*.{json,md}\"",
     "oracle": "vitest run packages/core/src/oracle.test.ts",
-    "bench": "pnpm -r --filter @metta-ts/core --filter @metta-ts/node --filter @metta-ts/browser build && node packages/node/bench/suite.mjs && node packages/node/bench/concurrency.mjs && node packages/browser/bench/concurrency.mjs",
+    "bench": "pnpm -r --filter @metta-ts/core --filter @metta-ts/node --filter @metta-ts/browser build && node packages/node/bench/suite.mjs && node packages/node/bench/nondeterminism.mjs --engine=ts --runs=1 && node packages/node/bench/concurrency.mjs && node packages/browser/bench/concurrency.mjs",
+    "bench:nondeterminism": "pnpm -r --filter @metta-ts/core --filter @metta-ts/node build && node packages/node/bench/nondeterminism.mjs",
     "bench:scale": "pnpm -r --filter @metta-ts/core --filter @metta-ts/node build && node packages/node/bench/scale-proof.mjs",
     "bench:prolog": "pnpm -r --filter @metta-ts/core --filter @metta-ts/hyperon --filter @metta-ts/prolog --filter @metta-ts/node build && node packages/node/bench/prolog.mjs"
   },

packages/browser/package.json

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

packages/core/package.json

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

packages/core/src/atom-set.test.ts

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+//
+// SPDX-License-Identifier: MIT
+
+import fc from "fast-check";
+import { describe, expect, it } from "vitest";
+import { alphaEq } from "./alpha";
+import { type Atom, expr, gfloat, gint, sym, variable } from "./atom";
+import { dedupAlphaStable, dedupExact } from "./atom-set";
+import { format } from "./parser";
+
+const atomArb: fc.Arbitrary<Atom> = fc.letrec<{ atom: Atom }>((tie) => ({
+  atom: fc.oneof(
+    { depthSize: "small", withCrossShrink: true },
+    fc.constantFrom("a", "b", "c", "pair").map(sym),
+    fc.constantFrom("x", "y", "z").map(variable),
+    fc.integer({ min: -20, max: 20 }).map(gint),
+    fc.integer({ min: -20, max: 20 }).map(gfloat),
+    fc.array(tie("atom"), { maxLength: 4 }).map(expr),
+  ),
+})).atom;
+
+function naiveAlphaDedup(atoms: readonly Atom[]): Atom[] {
+  const out: Atom[] = [];
+  for (const atom of atoms) if (!out.some((candidate) => alphaEq(candidate, atom))) out.push(atom);
+  return out;
+}
+
+describe("stable atom sets", () => {
+  it("matches a quadratic alpha-equivalence oracle over random atoms", () => {
+    fc.assert(
+      fc.property(fc.array(atomArb, { maxLength: 80 }), (atoms) => {
+        const expected = naiveAlphaDedup(atoms).map(format);
+        const actual = dedupAlphaStable(atoms).map(format);
+        return JSON.stringify(actual) === JSON.stringify(expected);
+      }),
+      { numRuns: 500 },
+    );
+  });
+
+  it("keeps the first alpha-equivalent variable pattern", () => {
+    const first = expr([sym("pair"), variable("x"), variable("x")]);
+    const renamed = expr([sym("pair"), variable("y"), variable("y")]);
+    const distinct = expr([sym("pair"), variable("y"), variable("z")]);
+
+    expect(dedupAlphaStable([first, renamed, distinct]).map(format)).toEqual([
+      "(pair $x $x)",
+      "(pair $y $z)",
+    ]);
+  });
+
+  it("uses the evaluator's numeric equality for exact grounded atoms", () => {
+    expect(dedupExact([gint(3), gfloat(3), gint(4)]).map(format)).toEqual(["3", "4"]);
+  });
+});