MeTTaScript 2.2.0

MesTTo · MesTTo · commit 3d37a2e2d439 · 2026-07-23T09:02:52.000+10:00
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,3 +1,22 @@
+# MeTTaScript 2.2.0
+
+Exposes the import resolver as a reusable, host-agnostic function. The transitive, cycle-safe import
+resolution that 2.1.0 added is now a core primitive that any host can drive with its own module reader.
+Behavior is unchanged: every terminating program produces the same output as 2.1.0, validated byte-identical
+across the full corpus, so upgrading is safe.
+
+## `resolveImportGraph`
+
+`@mettascript/core` now exports `resolveImportGraph(entrySrc, resolveModule, contextId?)`, the transitive,
+cycle-safe import-graph walk, decoupled from the filesystem. The caller supplies a `resolveModule` callback
+that maps an import name and a context to a module identity and, when the module is loadable, its source. The
+function returns the same import graph the runtime consumes.
+
+`@metta-ts/node`'s `readImports` is now a thin wrapper that supplies a filesystem `resolveModule`, so its
+behavior is identical. A tool that resolves modules from somewhere other than the filesystem, such as an
+editor working over in-memory workspace files, can build the exact same import graph the runtime uses by
+supplying its own reader, rather than reimplementing the resolution.
+
 # MeTTaScript 2.1.0
 
 Imports are now transitive, deduplicated, and cycle-safe. A module you import can itself import other
diff --git a/compat/browser/package.json b/compat/browser/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/browser",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/core/package.json b/compat/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/core",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/das-client/package.json b/compat/das-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/das-client",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/das-gateway/package.json b/compat/das-gateway/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/das-gateway",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/debug/package.json b/compat/debug/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/debug",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/edsl/package.json b/compat/edsl/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/edsl",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/grapher/package.json b/compat/grapher/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/grapher",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/hyperon/package.json b/compat/hyperon/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/hyperon",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/libraries/package.json b/compat/libraries/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/libraries",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/node/package.json b/compat/node/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/node",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/prolog/package.json b/compat/prolog/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/prolog",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/compat/py/package.json b/compat/py/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/py",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/browser/package.json b/packages/browser/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/browser",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/core",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/core/src/import-graph.test.ts b/packages/core/src/import-graph.test.ts
@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+//
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { format } from "./parser";
+import { resolveImportGraph, type ResolveModule, type ResolvedModule } from "./import-graph";
+import type { ImportMap, ImportModule } from "./eval";
+
+function moduleAt(imports: ImportMap, name: string): ImportModule {
+  const entry = imports.get(name);
+  if (entry === undefined || Array.isArray(entry)) throw new Error(`missing module ${name}`);
+  return entry;
+}
+
+describe("resolveImportGraph", () => {
+  it("returns an empty map without consulting the host when import! is absent", () => {
+    let called = false;
+    const imports = resolveImportGraph("(= (answer) 42)", () => {
+      called = true;
+      return { id: "unexpected" };
+    });
+
+    expect([...imports]).toEqual([]);
+    expect(called).toBe(false);
+  });
+
+  it("collects a transitive graph once, breaks cycles, and retains unloadable edges", () => {
+    const moduleA: ResolvedModule = {
+      id: "module:a",
+      source: `
+        !(import! &self b)
+        !(import! &self missing)
+        !(ignored-side-effect)
+        (= (a-value) a)
+      `,
+      contextId: "context:a",
+    };
+    const resolutions = new Map<string, ResolvedModule>([
+      ["entry:a", moduleA],
+      ["entry:alias-a", moduleA],
+      ["entry:builtin", { id: "builtin" }],
+      [
+        "context:a:b",
+        {
+          id: "module:b",
+          source: "!(import! &self a)\n(= (b-value) b)",
+          contextId: "context:b",
+        },
+      ],
+      ["context:a:missing", { id: "missing" }],
+      ["context:b:a", moduleA],
+    ]);
+    const calls: Array<readonly [string, string | undefined]> = [];
+    const resolveModule: ResolveModule = (name, fromContextId) => {
+      calls.push([name, fromContextId]);
+      const resolved = resolutions.get(`${fromContextId}:${name}`);
+      if (resolved === undefined) throw new Error(`unexpected resolution ${fromContextId}:${name}`);
+      return resolved;
+    };
+
+    const imports = resolveImportGraph(
+      `
+        !(import! &self a)
+        !(import! &self alias-a)
+        !(import! &self builtin)
+      `,
+      resolveModule,
+      "entry",
+    );
+
+    expect([...imports.keys()]).toEqual(["module:a", "module:b", "a", "alias-a"]);
+    const a = moduleAt(imports, "module:a");
+    const b = moduleAt(imports, "module:b");
+    expect(a.imports).toEqual(["module:b", "missing"]);
+    expect(b.imports).toEqual(["module:a"]);
+    expect(a.defs.map(format)).toEqual(["(= (a-value) a)"]);
+    expect(b.defs.map(format)).toEqual(["(= (b-value) b)"]);
+    expect(imports.get("a")).toBe(a);
+    expect(imports.get("alias-a")).toBe(a);
+    expect(imports.has("builtin")).toBe(false);
+    expect(imports.has("missing")).toBe(false);
+    expect(calls).toEqual([
+      ["a", "entry"],
+      ["b", "context:a"],
+      ["a", "context:b"],
+      ["missing", "context:a"],
+      ["alias-a", "entry"],
+      ["builtin", "entry"],
+    ]);
+  });
+});
diff --git a/packages/core/src/import-graph.ts b/packages/core/src/import-graph.ts
@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+//
+// SPDX-License-Identifier: MIT
+
+import type { Atom } from "./atom";
+import { literalImportTarget, type ImportMap, type ImportModule } from "./eval";
+import { parseAll } from "./parser";
+import { standardTokenizer } from "./runner";
+
+interface ParsedModule {
+  readonly defs: Atom[];
+  readonly imports: string[];
+}
+
+export interface ResolvedModule {
+  /** Canonical identity used for graph edges, deduplication, and cycle detection. */
+  readonly id: string;
+  /** Source text for a readable module. Unloadable modules omit this field. */
+  readonly source?: string;
+  /** Host-defined context used to resolve this module's nested imports. */
+  readonly contextId?: string;
+}
+
+export type ResolveModule = (name: string, fromContextId: string | undefined) => ResolvedModule;
+
+function parseModule(src: string): ParsedModule {
+  const defs: Atom[] = [];
+  const imports: string[] = [];
+  for (const top of parseAll(src, standardTokenizer())) {
+    if (top.bang) {
+      const name = literalImportTarget(top.atom);
+      if (name !== undefined) imports.push(name);
+    } else {
+      defs.push(top.atom);
+    }
+  }
+  return { defs, imports };
+}
+
+/** Resolve the readable transitive import graph without assuming how modules are stored. */
+export function resolveImportGraph(
+  entrySrc: string,
+  resolveModule: ResolveModule,
+  entryContextId?: string,
+): ImportMap {
+  const imports: ImportMap = new Map();
+  if (!entrySrc.includes("import!")) return imports;
+  const visited = new Set<string>();
+
+  const collectModule = (resolved: ResolvedModule): void => {
+    if (resolved.source === undefined || visited.has(resolved.id)) return;
+    visited.add(resolved.id);
+    let parsed: ParsedModule;
+    try {
+      parsed = parseModule(resolved.source);
+    } catch {
+      return;
+    }
+    const nested: string[] = [];
+    const module: ImportModule = { id: resolved.id, defs: parsed.defs, imports: nested };
+    imports.set(resolved.id, module);
+    for (const name of parsed.imports) {
+      const child = resolveModule(name, resolved.contextId);
+      nested.push(child.id);
+      collectModule(child);
+    }
+  };
+
+  for (const name of parseModule(entrySrc).imports) {
+    const resolved = resolveModule(name, entryContextId);
+    if (resolved.source === undefined) continue;
+    collectModule(resolved);
+    const module = imports.get(resolved.id);
+    if (module !== undefined) imports.set(name, module);
+  }
+  return imports;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -22,6 +22,7 @@ export * from "./eval";
 export * from "./eval-depth";
 export * from "./eval-steps";
 export * from "./runner";
+export * from "./import-graph";
 export type { TraceEvent, TraceSink } from "./trace";
 export * from "./host";
 export * from "./extensions";
diff --git a/packages/das-client/package.json b/packages/das-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/das-client",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/das-gateway/package.json b/packages/das-gateway/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/das-gateway",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/debug/package.json b/packages/debug/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/debug",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/edsl/package.json b/packages/edsl/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/edsl",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": "MesTTo",
   "license": "MIT",
   "description": "Ergonomic, typed TypeScript eDSL for MeTTa: term builders, tagged templates, host-interop builders, and auto-grounding of TypeScript values.",
diff --git a/packages/grapher/package.json b/packages/grapher/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/grapher",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": "MesTTo",
   "license": "MIT",
   "description": "MeTTa visual editor and reduction renderer for browser and Node.js, with node-graph and nested-block views.",
diff --git a/packages/hyperon/package.json b/packages/hyperon/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/hyperon",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/libraries/package.json b/packages/libraries/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/libraries",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/node/package.json b/packages/node/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mettascript/node",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/node/src/file-imports.ts b/packages/node/src/file-imports.ts
diff --git a/packages/prolog/package.json b/packages/prolog/package.json
diff --git a/packages/py/package.json b/packages/py/package.json

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/browser",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/core",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/das-client",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/das-gateway",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/debug",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/edsl",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/grapher",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/hyperon",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@metta-ts/libraries",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"license": "MIT",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "./dist/index.js",`