feat(das): DasSpace + transport (mock-tested) + browser gateway wire; integration boundary documented

Author: MesTTo

packages/das-client/README.md

@@ -0,0 +1,24 @@
+# @metta-ts/das-client
+
+Distributed AtomSpace (DAS) as a pluggable `Space` backend for MeTTa TS.
+
+## What ships here
+
+- **`DasTransport`** — the network boundary interface (`query`/`add`/`remove`/`atoms`).
+- **`DasSpace`** — implements the kernel's `Space` interface over a transport, so a DAS is just another Space backend (drops in wherever `InMemorySpace` does). Mock-tested.
+- **`MockTransport`** — an in-process transport that exercises the exact `DasSpace` code paths, for tests and offline development.
+- **`das.metta`** — the vendored DAS module type declarations (`new-das!`, `das-evolution!`, `das-link-creation!`, …) from hyperon-experimental.
+
+## What does not ship (the remaining integration)
+
+The **live bus client** is deliberately not shipped as unverified code. DAS's distributed layer is gRPC (`singnet/das-proto`: `DistributedAlgorithmNode.execute_message`, `attention_broker`) plus a peer-to-peer streaming choreography. Completing it means:
+
+1. Generate gRPC stubs from `das-proto` (ts-proto + `@grpc/grpc-js`).
+2. Port the choreography from the Python reference `hyperon_das` (~2.8k LOC): service bus, proxy, port pool, distributed-algorithm bus node, pattern-matching + atomdb clients, and atom-handle hashing (capture parity vectors from the Python client first).
+3. Validate against a live DAS (`das-toolbox`) in an integration test.
+
+This is **Node-only**: a participant must host an inbound bus node, which a browser cannot do — the browser reaches DAS through [`@metta-ts/das-gateway`](../das-gateway). Per the project's correctness-first principle, this lands behind a live-DAS differential test rather than as untested wire-protocol code.
+
+## Kernel integration note
+
+`DasSpace` implements the same `Space` interface as `InMemorySpace`. Wiring a named DAS-backed space into the interpreter's `World` (so `match`/`add-atom`/`get-atoms` over a `new-das!` handle dispatch to a `DasSpace`) is a small generalization of `World.spaces` from `Atom[]` lists to `Space` backends — the seam is already the `Space` interface.

packages/das-client/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@metta-ts/das-client",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist"],
+  "scripts": { "build": "tsup src/index.ts --format esm --dts --clean" },
+  "dependencies": { "@metta-ts/core": "workspace:*" }
+}

packages/das-client/src/das-space.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+import { sym, variable, expr, instantiate, atomEq } from "@metta-ts/core";
+import { DasSpace } from "./das-space";
+import { MockTransport } from "./transport";
+
+describe("DasSpace (over a mock transport)", () => {
+  it("implements the Space interface: add, query, remove", () => {
+    const space = new DasSpace(new MockTransport());
+    space.add(expr([sym("Similarity"), sym("human"), sym("chimp")]));
+    space.add(expr([sym("Similarity"), sym("human"), sym("monkey")]));
+
+    const res = space.query(expr([sym("Similarity"), sym("human"), variable("s")]));
+    expect(res.length).toBe(2);
+    const got = res.map((b) => instantiate(b, variable("s")));
+    expect(got.some((a) => atomEq(a, sym("chimp")))).toBe(true);
+    expect(got.some((a) => atomEq(a, sym("monkey")))).toBe(true);
+
+    expect(space.remove(expr([sym("Similarity"), sym("human"), sym("chimp")]))).toBe(true);
+    expect(space.query(expr([sym("Similarity"), sym("human"), variable("s")])).length).toBe(1);
+  });
+});

packages/das-client/src/das-space.ts

@@ -0,0 +1,21 @@
+// A Space backed by a Distributed AtomSpace. It implements the same `Space` interface the kernel
+// already injects (so it drops in wherever `InMemorySpace` does), delegating every operation to a
+// `DasTransport`. This is how DAS becomes "just another Space backend".
+import { type Atom, type Bindings, type Space } from "@metta-ts/core";
+import { type DasTransport } from "./transport";
+
+export class DasSpace implements Space {
+  constructor(private readonly transport: DasTransport) {}
+  add(atom: Atom): void {
+    this.transport.add(atom);
+  }
+  remove(atom: Atom): boolean {
+    return this.transport.remove(atom);
+  }
+  query(pattern: Atom): Bindings[] {
+    return this.transport.query(pattern);
+  }
+  atoms(): readonly Atom[] {
+    return this.transport.atoms();
+  }
+}

packages/das-client/src/das.metta

@@ -0,0 +1,61 @@
+(@doc new-das!
+  (@desc "Creates a new Distributed AtomSpace (DAS) instance with specified server and known peer endpoints")
+  (@params (
+    (@param "Server endpoint with port range (e.g., 0.0.0.0:42000-42999 or localhost:52000-52099)")
+    (@param "Known peer endpoint (e.g., 0.0.0.0:40002 or localhost:40002)")))
+  (@return "A Space instance representing the DAS"))
+
+(@doc das-join-network!
+  (@desc "(re)Joins the DAS network using the configured parameters")
+  (@params ())
+  (@return "Unit atom"))
+
+(@doc das-services!
+  (@desc "Prints information about available DAS services")
+  (@params ())
+  (@return "Unit atom"))
+
+(@doc das-service-status!
+  (@desc "Checks the status of a specific DAS service by name")
+  (@params (
+    (@param "Service name (string)")))
+  (@return "String: 'ServiceAvailable: <name>' if available, or error if not available or not registered"))
+
+(@doc das-set-param!
+  (@desc "Sets a DAS parameter value. The parameter must exist in the DAS configuration")
+  (@params (
+    (@param "Expression containing key-value pair, e.g., (max_answers 100)")))
+  (@return "String: 'DAS Param Updated: <param_name>' or error"))
+
+(@doc das-get-params!
+  (@desc "Prints all current DAS parameters")
+  (@params ())
+  (@return "Unit atom"))
+
+(@doc das-create-context!
+  (@desc "Creates a context in the DAS with specified query, determiner schema, and stimulus schema")
+  (@params (
+    (@param "Context name (string)")
+    (@param "ExpressionAtom containing schemas: ( (query) (determiner_schema) (stimulus_schema) )")))
+  (@return "Result atom from context creation"))
+
+(@doc das-evolution!
+  (@desc "Performs DAS evolution operation with query, fitness function, correlation queries, replacements, and mappings")
+  (@params (
+    (@param "ExpressionAtom containing evolution configuration: ( (query) (fitness-function) (correlation-queries) (correlation-replacements) (correlation-mappings) )")
+    (@param "Template atom to be filled with evolution results")))
+  (@return "Non-deterministic result: template with bindings from evolution"))
+
+(@doc das-link-creation!
+  (@desc "Creates links in the DAS based on a query pattern and one or more templates")
+  (@params (
+    (@param "Query atom to match against")
+    (@param "Template atoms (one or more) for link creation")))
+  (@return "Result atom from link creation"))
+
+(@doc das-helpers!
+  (@desc "Executes helper functions for DAS operations. Currently supports 'sleep' helper")
+  (@params (
+    (@param "Helper function name (string), e.g., 'sleep'")
+    (@param "Argument for the helper function (string), e.g., '5' for sleep duration in seconds")))
+  (@return "Unit atom"))

packages/das-client/src/index.ts

@@ -0,0 +1,14 @@
+// @metta-ts/das-client — Distributed AtomSpace as a pluggable Space backend for MeTTa TS.
+//
+// Architecture (shipped, mock-tested): `DasTransport` is the network boundary; `DasSpace`
+// implements the kernel's `Space` interface over a transport, so DAS is just another Space backend.
+//
+// Live bus client (the remaining integration — NOT shipped unverified): generate gRPC stubs from
+// `singnet/das-proto` (`DistributedAlgorithmNode.execute_message`, `attention_broker`), then port
+// the choreography from the Python reference `hyperon_das` (service bus, proxy, port pool, bus node,
+// pattern-matching/atomdb clients, atom-handle hashing). That requires a running DAS to validate, so
+// per the project's correctness-first principle it lands behind a live-DAS integration test, not as
+// unverified code. Node-only (a browser cannot host an inbound bus node; the browser reaches DAS via
+// @metta-ts/das-gateway). See README.
+export { type DasTransport, MockTransport } from "./transport";
+export { DasSpace } from "./das-space";

packages/das-client/src/transport.ts

@@ -0,0 +1,40 @@
+// The DAS transport boundary. A `DasTransport` speaks to a Distributed AtomSpace; the concrete
+// bus implementation (gRPC generated from `das-proto`, choreography ported from the Python
+// `hyperon_das` reference) plugs in here. This package ships the architecture + a deterministic
+// `MockTransport` for tests; the live bus client is the remaining integration (it needs a running
+// DAS service to validate, so it is not shipped unverified — see README).
+import { type Atom, type Bindings, matchAtoms } from "@metta-ts/core";
+
+export interface DasTransport {
+  /** Pattern-matching query against the remote space; returns binding sets (DAS `query`). */
+  query(pattern: Atom): Bindings[];
+  /** Create/insert an atom (DAS `add_link` / atomdb write). */
+  add(atom: Atom): void;
+  /** Remove an atom. */
+  remove(atom: Atom): boolean;
+  /** Enumerate atoms (where the backend supports it). */
+  atoms(): readonly Atom[];
+}
+
+/** An in-process transport over a local atom list, for tests and offline development. It exercises
+ *  the exact `DasSpace`/grounded-op code paths a real bus client would, minus the network. */
+export class MockTransport implements DasTransport {
+  constructor(private readonly store: Atom[] = []) {}
+  query(pattern: Atom): Bindings[] {
+    const out: Bindings[] = [];
+    for (const a of this.store) for (const b of matchAtoms(pattern, a)) out.push(b);
+    return out;
+  }
+  add(atom: Atom): void {
+    this.store.push(atom);
+  }
+  remove(atom: Atom): boolean {
+    const i = this.store.findIndex((a) => JSON.stringify(a) === JSON.stringify(atom));
+    if (i < 0) return false;
+    this.store.splice(i, 1);
+    return true;
+  }
+  atoms(): readonly Atom[] {
+    return this.store;
+  }
+}

packages/das-client/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"],
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" }
+}

packages/das-gateway/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@metta-ts/das-gateway",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist"],
+  "scripts": { "build": "tsup src/index.ts --format esm --dts --clean" },
+  "dependencies": { "@metta-ts/core": "workspace:*", "@metta-ts/das-client": "workspace:*" }
+}

packages/das-gateway/src/index.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { sym, variable, expr, format, instantiate, atomEq } from "@metta-ts/core";
+import { encodePattern, decodeBindings, queryDas, type GatewayTransport } from "./index";
+
+describe("das-gateway wire format", () => {
+  it("encodes a pattern and decodes binding solutions round-trip", async () => {
+    // A stub gateway that "answers" $s = chimp / monkey for any pattern.
+    const transport: GatewayTransport = {
+      query: () =>
+        Promise.resolve({
+          bindings: [
+            [["s", "chimp"]],
+            [["s", "monkey"]],
+          ],
+        }),
+    };
+    const pattern = expr([sym("Similarity"), sym("human"), variable("s")]);
+    expect(encodePattern(pattern)).toBe("(Similarity human $s)");
+
+    const sols = await queryDas(transport, "&das", pattern);
+    const got = sols.map((b) => format(instantiate(b, variable("s"))));
+    expect(got).toEqual(["chimp", "monkey"]);
+    expect(decodeBindings({ bindings: [[["s", "chimp"]]] }).length).toBe(1);
+    expect(atomEq(instantiate(decodeBindings({ bindings: [[["s", "chimp"]]] })[0]!, variable("s")), sym("chimp"))).toBe(true);
+  });
+});