MeTTa TS 1.2.0

Author: MesTTo

README.md

@@ -1,3 +1,90 @@
+# MeTTa TS 1.2.0
+
+MeTTa TS 1.2.0 adds eight importable standard libraries and makes the core list
+operations run in linear time. Both changes keep the conformance oracle
+byte-identical: the libraries stay off the prelude, and the faster list
+operations return results equal to the prelude recursion up to variable renaming.
+
+## Standard libraries
+
+Eight libraries from the PeTTa distribution are now importable modules. Load one
+with `(import! &self <name>)`. They are kept off the prelude, so a program that
+imports none of them behaves exactly as before and the oracle is unchanged.
+
+- `vector`, `roman`, `combinatorics`, `patrick`, `datastructures`, and `spaces`
+  port the corresponding PeTTa utilities.
+- `nars` is a Non-Axiomatic Reasoning System belief engine.
+- `pln` is a Probabilistic Logic Networks reasoner with truth-value revision,
+  negation, and deduction, reached through a `PLN.Query` entry point.
+
+The ports follow Hyperon semantics rather than PeTTa's cons-cell representation:
+list construction uses `decons-atom`/`cons-atom`, `collapse` yields a comma
+tuple, and `foldl`/`msort` map to `foldl-atom`/`sort`.
+
+## Linear-time list operations
+
+`size-atom`, `map-atom`, `filter-atom`, and `foldl-atom` over a literal list of
+N elements now run in O(N) time on a constant native stack. The prelude
+recursion was quadratic to cubic and overflowed the stack before reaching a
+million elements.
+
+`size-atom` gains a fast path that returns a ground tuple of inert data without
+threading each element through the interpreter. `map-atom`, `filter-atom`, and
+`foldl-atom` evaluate as grounded operations, and when the per-element function
+is compiled they call it directly on the compiled path. Every result is equal to
+the prelude recursion up to variable renaming, checked by an on/off differential.
+
+A five-run minimum-time subprocess benchmark against PeTTa on SWI-Prolog, at
+N=100000 and including process startup, with a one-clause user function per
+element:
+
+| Operation     |  PeTTa | MeTTa TS | Speedup |
+| ------------- | -----: | -------: | ------: |
+| `size-atom`   | 887 ms |   170 ms |   5.23x |
+| `map-atom`    | 999 ms |   348 ms |   2.87x |
+| `filter-atom` | 966 ms |   360 ms |   2.68x |
+| `foldl-atom`  | 999 ms |   346 ms |   2.89x |
+
+## Trace bus and metta-debug
+
+The core exposes an optional trace bus: pass a `trace` sink to a run and the
+evaluator reports its reduce, rule-selection, grounded-dispatch, and
+specialization decisions, with no cost when no sink is set. The `@metta-ts/node`
+package adds a `metta-debug` command that runs a call under that sink and prints
+those decisions, so a depth or dispatch question is a one-command diagnosis.
+
+## Fixes
+
+A function that returns a control form such as `let` or `if` under
+`{tabling: true}` now reduces it fully instead of leaving it partially reduced.
+
+## Verification
+
+Checked on Linux with Node and pnpm.
+
+- Build, type check, lint, and format checks pass across all ten packages.
+- `pnpm test` passes: 1,208 tests across 123 files, with 38 optional live
+  integration tests (7 files) skipped.
+- The checked oracle passes all 23 corpus files. It is byte-identical to 1.1.7:
+  the new libraries are opt-in and off the prelude, and the faster list
+  operations equal the prelude recursion up to variable renaming.
+
+## Packages
+
+All public packages use version `1.2.0`:
+
+```bash
+npm install @metta-ts/core@1.2.0
+npm install -g @metta-ts/node@1.2.0
+```
+
+Optional host packages use the same version:
+
+```bash
+npm install @metta-ts/py@1.2.0 pythonia
+npm install @metta-ts/prolog@1.2.0
+```
+
 # MeTTa TS 1.1.7
 
 MeTTa TS 1.1.7 fixes a unification soundness bug in grounded substitution.

RELEASE_NOTES.md

@@ -20,7 +20,7 @@ const last = async (src: string): Promise<string[]> =>
   (await runProgramAsync(src, new Map([["aw", aw]]))).at(-1)!.results.map(format);
 
 // par: three branches run concurrently; collapse gathers the union.
-console.log("par:", await last("!(collapse (par (aw 3) (aw 4) (aw 2)))")); // [ '(3 4 2)' ]
+console.log("par:", await last("!(collapse (par (aw 3) (aw 4) (aw 2)))")); // [ '(, 3 4 2)' ]
 
 // race: the fast branch (3ms) wins over the slow one (40ms).
 console.log("race:", await last("!(race (aw 40) (aw 3))")); // [ '3' ]

examples/concurrency.ts

@@ -30,5 +30,5 @@ for (const { query, results: rs } of results) {
 }
 // !(bin)                       => [ '0', '1' ]
 // !(superpose (red green blue))=> [ 'red', 'green', 'blue' ]
-// !(collapse (bin))            => [ '(0 1)' ]
+// !(collapse (bin))            => [ '(, 0 1)' ]
 // !(double (superpose (1 2 3)))=> [ '2', '4', '6' ]

examples/nondeterminism.ts

@@ -13,6 +13,7 @@
     "matching": "tsx matching.ts",
     "nondeterminism": "tsx nondeterminism.ts",
     "stdlib": "tsx stdlib.ts",
+    "standard-libraries": "metta-ts standard-libraries.metta",
     "types": "tsx types.ts",
     "js-interop": "tsx js-interop.ts",
     "python-interop": "tsx python-interop.ts",
@@ -25,6 +26,7 @@
     "transactions": "tsx transactions.ts",
     "scaling": "tsx scaling.ts",
     "parallel-matcher": "tsx parallel-matcher.ts",
+    "grapher": "tsx grapher.ts",
     "grapher-gif": "tsx grapher-gif.ts",
     "typecheck": "tsc --noEmit"
   },

examples/package.json

@@ -0,0 +1,34 @@
+; SPDX-FileCopyrightText: 2026 MesTTo
+; SPDX-License-Identifier: MIT
+
+; The 1.2.0 importable libraries are opt-in. Each import adds its functions to &self.
+; Run it after building packages:
+;   pnpm --filter @metta-ts/examples standard-libraries
+
+!(import! &self vector)
+!(dot (1.0 2.0 3.0) (4.0 5.0 6.0))          ; [32.0]
+
+!(import! &self combinatorics)
+!(collapse (range 1 4))                     ; [(, 1 2 3)]
+
+!(import! &self roman)
+(= (double $x) (* $x 2))
+!(map-flat double (1 2 3))                  ; [(2 4 6)]
+
+!(import! &self patrick)
+(= (inc $x) (+ $x 1))
+!(compose (double inc) (5))                 ; [12]
+
+!(import! &self datastructures)
+!(dequeue (enqueue b (enqueue a (empty-queue)))) ; [(Pair a (queue () (b) 1))]
+
+!(import! &self spaces)
+!(add-atom &warehouse (box 1))
+!(migrateAtoms &warehouse &shipped (box $n))
+!(collapse (match &shipped $x $x))          ; [(, (box 1))]
+
+!(import! &self nars)
+!(Truth_Expectation (stv 0.8 0.9))          ; [0.77]
+
+!(import! &self pln)
+!(Truth_ModusPonens (stv 0.8 0.9) (stv 0.7 0.6)) ; [(stv 0.564 0.54)]

examples/standard-libraries.metta

@@ -19,7 +19,7 @@ console.log(
     !(transaction (add-atom &self (cnt 7)))
     !(collapse (match &self (cnt $v) $v))
   `),
-); // [ '(5 7)' ]
+); // [ '(, 5 7)' ]
 
 // Rollback: the body adds (cnt 6) then produces zero results, so the add is undone.
 console.log(
@@ -30,4 +30,4 @@ console.log(
     !(transaction (let $u (add-atom &self (cnt 6)) (superpose ())))
     !(collapse (match &self (cnt $v) $v))
   `),
-); // [ '(5)' ]
+); // [ '(, 5)' ]

examples/transactions.ts

@@ -74,53 +74,6 @@ await runner.dispose();
 See `examples/browser-interop` for a runnable smoke check and a bundle isolation
 check.
 
-For embedders that already resolved imports, `@metta-ts/browser/source` exposes source runners:
-
-```ts
-import { runSourceAsync } from "@metta-ts/browser/source";
-
-const results = await runSourceAsync(`
-  !(import! &self concurrency)
-  !(par (+ 1 1) (+ 2 2))
-`);
-```
-
-The async runner supports MeTTa's async forms (`par`, `race`, `with-mutex`) and uses Web Workers for
-`(once (hyperpose ...))` when the browser host provides them.
-
-## Host Interop
-
-`@metta-ts/browser/host` composes optional host runtimes such as Pyodide and
-SWI-Prolog WASM. The base browser package stays pure TypeScript. Import a host
-adapter only when the page needs it.
-
-```ts
-import { createBrowserRunner, createBrowserTextLoader } from "@metta-ts/browser/host";
-import { createPyodideInterop } from "@metta-ts/py/pyodide";
-import { createSwiWasmInterop } from "@metta-ts/prolog/swi-wasm";
-
-const files = new Map([
-  ["math.py", "def add(a, b):\n    return a + b\n"],
-  ["facts.pl", "edge(alice, bob).\n"],
-]);
-const loadText = createBrowserTextLoader({ files, baseUrl: import.meta.url });
-const py = await createPyodideInterop({ loadText });
-const prolog = await createSwiWasmInterop({ loadText });
-const runner = createBrowserRunner({ files, interops: [py, prolog] });
-
-const results = await runner.run(`
-  !(import! &self "math.py")
-  !(py-call (math.add 40 2))
-  !(import! &self "facts.pl")
-  !(prolog-call (edge alice $x))
-`);
-
-await runner.dispose();
-```
-
-See `examples/browser-interop` for a runnable smoke check and a bundle isolation
-check.
-
 ## License
 
 [MIT](https://github.com/MesTTo/MeTTa-TS/blob/main/LICENSE).

packages/browser/README.md

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

packages/browser/package.json

@@ -28,6 +28,8 @@ for (const { query, results: rs } of results) {
 
 `runProgram` parses the source, adds every non-bang atom to the knowledge base, evaluates each `!`-query, and returns one result group per query. For a higher-level class API modeled on Python's `hyperon`, see [`@metta-ts/hyperon`](https://github.com/MesTTo/MeTTa-TS/tree/main/packages/hyperon).
 
+The experimental line adds a pull-based streaming grounded-operation protocol on the `experimental` npm tag; see [Experimental features](https://mestto.github.io/MeTTa-TS/guide/experimental).
+
 ## License
 
 [MIT](https://github.com/MesTTo/MeTTa-TS/blob/main/LICENSE).