@metta-ts/debug 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MesTTo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+<!--
+SPDX-FileCopyrightText: 2026 MesTTo
+SPDX-License-Identifier: MIT
+-->
+
+# @metta-ts/debug
+
+`@metta-ts/debug` contains the host-free debugger engine used by `metta-debug`
+and embedders such as language servers.
+
+The package does not read files, register global output sinks, or import Node
+APIs. Callers provide the exact runner they already use.
+
+```ts
+import { explainCall } from "@metta-ts/debug";
+import { runProgram } from "@metta-ts/core";
+
+const report = explainCall(runProgram, "(= (double $x) (* $x 2))", "(double 21)");
+
+console.log(report.result); // ["42"]
+```
+
+Use `collectTrace` when the caller already has an assembled program and only
+needs the raw trace event stream. Use `summarize` when the caller already
+collected events and needs the grouped `metta-debug why` counters.

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { TraceEvent, Atom, RunOptions, QueryResult } from '@metta-ts/core';
+export { TraceEvent } from '@metta-ts/core';
+
+interface TraceSummary {
+    readonly grounded: Record<string, number>;
+    readonly specialized: string[];
+    readonly overflow: string[];
+    readonly reductions: number;
+}
+type TraceRunner = (program: string, fuel: number | undefined, imports: Map<string, Atom[]>, opts?: RunOptions) => QueryResult[];
+interface DebugRunOptions {
+    readonly fuel?: number | undefined;
+    readonly imports?: Map<string, Atom[]> | undefined;
+    readonly runOptions?: Omit<RunOptions, "trace"> | undefined;
+}
+interface CallExplanation {
+    readonly result: string[];
+    readonly trace: TraceEvent[];
+    readonly summary: TraceSummary;
+}
+declare function summarize(events: readonly TraceEvent[]): TraceSummary;
+declare function assembleQuery(source: string, call: string): string;
+declare function collectTrace(runner: TraceRunner, program: string, opts?: DebugRunOptions): TraceEvent[];
+declare function explainCall(runner: TraceRunner, source: string, call: string, opts?: DebugRunOptions): CallExplanation;
+
+export { type CallExplanation, type DebugRunOptions, type TraceRunner, type TraceSummary, assembleQuery, collectTrace, explainCall, summarize };

package/dist/index.js

@@ -0,0 +1,49 @@
+// src/index.ts
+import {
+  format
+} from "@metta-ts/core";
+function summarize(events) {
+  const grounded = {};
+  const specialized = /* @__PURE__ */ new Set();
+  const overflow = [];
+  let reductions = 0;
+  for (const e of events) {
+    if (e.kind === "grounded") grounded[e.op] = (grounded[e.op] ?? 0) + 1;
+    else if (e.kind === "specialize") specialized.add(`${e.from} -> ${e.to}`);
+    else if (e.kind === "overflow") overflow.push(e.atom);
+    else reductions++;
+  }
+  return { grounded, specialized: [...specialized], overflow, reductions };
+}
+function assembleQuery(source, call) {
+  const trimmed = call.trim();
+  const q = trimmed.startsWith("!") ? trimmed : `!${trimmed}`;
+  return `${source}
+${q}`;
+}
+function runWithTrace(runner, program, opts = {}) {
+  const trace = [];
+  const runOptions = {
+    ...opts.runOptions ?? {},
+    trace: (e) => trace.push(e)
+  };
+  const groups = runner(program, opts.fuel, opts.imports ?? /* @__PURE__ */ new Map(), runOptions);
+  return { groups, trace };
+}
+function collectTrace(runner, program, opts) {
+  return runWithTrace(runner, program, opts).trace;
+}
+function explainCall(runner, source, call, opts) {
+  const { groups, trace } = runWithTrace(runner, assembleQuery(source, call), opts);
+  return {
+    result: groups.at(-1)?.results.map(format) ?? [],
+    trace,
+    summary: summarize(trace)
+  };
+}
+export {
+  assembleQuery,
+  collectTrace,
+  explainCall,
+  summarize
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@metta-ts/debug",
+  "version": "1.3.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@metta-ts/core": "1.3.0"
+  },
+  "author": "MesTTo",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Host-free trace collection and explanation helpers for MeTTa TS debuggers.",
+  "keywords": [
+    "metta",
+    "hyperon",
+    "debug",
+    "trace",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MesTTo/MeTTa-TS.git",
+    "directory": "packages/debug"
+  },
+  "homepage": "https://github.com/MesTTo/MeTTa-TS#readme",
+  "bugs": {
+    "url": "https://github.com/MesTTo/MeTTa-TS/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean"
+  }
+}