@mneme-ai/matrix 2.167.0

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * `mneme-matrix` — serve the Matrix Rail gRPC wire server on 127.0.0.1, or self-test.
+ *   mneme-matrix serve [--port 50561]
+ *   mneme-matrix selftest
+ */
+import { createMatrixServer } from "./server.js";
+import { grpcGauntlet } from "./gauntlet.js";
+async function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0] ?? "serve";
+    if (cmd === "selftest") {
+        const g = await grpcGauntlet();
+        process.stdout.write(`🛰 MATRIX gRPC self-test — ${g.score}/100\n`);
+        for (const c of g.checks)
+            process.stdout.write(`  ${c.pass ? "✓" : "✗"} ${c.name} — ${c.detail}\n`);
+        process.stdout.write(`  metrics: health ${g.metrics.healthMs}ms · ping ${g.metrics.pingMs}ms · ${(g.metrics.largePayloadBytes / 1e6).toFixed(1)}MB round-trip ${g.metrics.roundTripMs}ms\n`);
+        process.exit(g.score === 100 ? 0 : 2);
+    }
+    if (cmd === "serve") {
+        const pIdx = args.indexOf("--port");
+        const port = pIdx >= 0 ? parseInt(args[pIdx + 1] ?? "0", 10) : 50561;
+        const srv = await createMatrixServer({ port });
+        process.stdout.write(`🛰 Matrix Rail gRPC on 127.0.0.1:${srv.port} (loopback only · proof-carrying · chunked pipe). Ctrl-C to stop.\n`);
+        process.on("SIGINT", () => { srv.stop().then(() => process.exit(0)); });
+        process.on("SIGTERM", () => { srv.stop().then(() => process.exit(0)); });
+        return;
+    }
+    process.stderr.write(`unknown command: ${cmd}\nusage: mneme-matrix serve [--port N] | selftest\n`);
+    process.exit(1);
+}
+main().catch((e) => { process.stderr.write(`matrix error: ${e.message}\n`); process.exit(1); });
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC;IAE/B,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,MAAM,YAAY,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;QACpE,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;QACpG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,QAAQ,aAAa,CAAC,CAAC,OAAO,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,iBAAiB,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,OAAO,CAAC,WAAW,MAAM,CAAC,CAAC;QAC7L,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACrE,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,GAAG,CAAC,IAAI,qEAAqE,CAAC,CAAC;QACxI,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzE,OAAO;IACT,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,GAAG,qDAAqD,CAAC,CAAC;IACnG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAkB,CAAW,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Matrix Rail gRPC client helpers — used by tests, the gauntlet, the CLI, and as
+ * the reference any-language agents follow. Unary Invoke + chunked Pipe.
+ */
+import * as grpc from "@grpc/grpc-js";
+export interface MatrixClient {
+    _c: grpc.Client;
+    close: () => void;
+}
+export interface ToolReply {
+    ok: boolean;
+    data_json: string;
+    wisdom: string;
+    proof_json: string;
+    error: string;
+}
+export declare function connect(addr: string): MatrixClient;
+export declare function health(client: MatrixClient): Promise<{
+    ok: boolean;
+    version: string;
+    tools: number;
+    note: string;
+}>;
+/** Unary Invoke — the typed door to any tool. */
+export declare function invoke(client: MatrixClient, tool: string, argsJson?: string, heldRoot?: string): Promise<ToolReply>;
+/**
+ * Pipe-invoke: send the request through the CHUNKED bidi pipe (any size, integrity-
+ * checked) and reassemble the reply. Proves a large payload flows past the 4MB cap.
+ */
+export declare function pipeInvoke(client: MatrixClient, tool: string, argsJson?: string, heldRoot?: string): Promise<ToolReply>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAgBtC,MAAM,WAAW,YAAY;IAAG,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE;AACpE,MAAM,WAAW,SAAS;IAAG,EAAE,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAEhH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAOlD;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAGnH;AAED,iDAAiD;AACjD,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAO,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAG7G;AAMD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAO,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAkBjH"}

package/dist/client.js

@@ -0,0 +1,69 @@
+/**
+ * Matrix Rail gRPC client helpers — used by tests, the gauntlet, the CLI, and as
+ * the reference any-language agents follow. Unary Invoke + chunked Pipe.
+ */
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { matrix } from "@mneme-ai/core";
+const PROTO_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "proto", "mneme.proto");
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function MatrixClientCtor() {
+    const def = protoLoader.loadSync(PROTO_PATH, { keepCase: true, longs: Number, enums: String, defaults: true, oneofs: true });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pkg = grpc.loadPackageDefinition(def);
+    return pkg.mneme.Matrix;
+}
+export function connect(addr) {
+    const Ctor = MatrixClientCtor();
+    const c = new Ctor(addr, grpc.credentials.createInsecure(), {
+        "grpc.max_receive_message_length": 8 * 1024 * 1024,
+        "grpc.max_send_message_length": 8 * 1024 * 1024,
+    });
+    return { _c: c, close: () => c.close() };
+}
+export function health(client) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new Promise((resolve, reject) => client._c.Health({}, (e, r) => (e ? reject(e) : resolve(r))));
+}
+/** Unary Invoke — the typed door to any tool. */
+export function invoke(client, tool, argsJson = "{}", heldRoot = "") {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new Promise((resolve, reject) => client._c.Invoke({ tool, args_json: argsJson, held_root: heldRoot }, (e, r) => (e ? reject(e) : resolve(r))));
+}
+const toWire = (f) => ({ id: f.id, seq: f.seq, total: f.total, orig_bytes: f.origBytes, gz: f.gz, data: Buffer.from(f.data) });
+const fromWire = (w) => ({ id: String(w.id), seq: Number(w.seq), total: Number(w.total), origBytes: Number(w.orig_bytes), gz: !!w.gz, data: w.data instanceof Uint8Array ? w.data : Uint8Array.from(w.data ?? []) });
+/**
+ * Pipe-invoke: send the request through the CHUNKED bidi pipe (any size, integrity-
+ * checked) and reassemble the reply. Proves a large payload flows past the 4MB cap.
+ */
+export function pipeInvoke(client, tool, argsJson = "{}", heldRoot = "") {
+    return new Promise((resolve, reject) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const call = client._c.Pipe();
+        const replyFrames = [];
+        call.on("data", (w) => { try {
+            replyFrames.push(fromWire(w));
+        }
+        catch { /* */ } });
+        call.on("error", (e) => reject(e));
+        call.on("end", () => {
+            const asm = matrix.reassemble(replyFrames);
+            if (!asm.ok)
+                return reject(new Error(`reply pipe integrity: ${asm.reason}`));
+            try {
+                resolve(JSON.parse(new TextDecoder().decode(asm.payload)));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        // stream the request as frames
+        const reqBytes = new TextEncoder().encode(JSON.stringify({ tool, argsJson, heldRoot }));
+        for (const f of matrix.chunkFrame(reqBytes))
+            call.write(toWire(f));
+        call.end();
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/gauntlet.d.ts

@@ -0,0 +1,17 @@
+export interface GrpcGauntlet {
+    score: number;
+    metrics: {
+        healthMs: number;
+        pingMs: number;
+        largePayloadBytes: number;
+        framesOverWire: number;
+        roundTripMs: number;
+    };
+    checks: Array<{
+        name: string;
+        pass: boolean;
+        detail: string;
+    }>;
+}
+export declare function grpcGauntlet(): Promise<GrpcGauntlet>;
+//# sourceMappingURL=gauntlet.d.ts.map

package/dist/gauntlet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gauntlet.d.ts","sourceRoot":"","sources":["../src/gauntlet.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IACtH,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,CA4C1D"}

package/dist/gauntlet.js

@@ -0,0 +1,61 @@
+/**
+ * grpcGauntlet — the LIVE, measured proof that the Matrix wire works: start a
+ * server on an ephemeral loopback port, run real round-trips, MEASURE, shut down.
+ * Honest numbers, not adjectives.
+ */
+import { createMatrixServer } from "./server.js";
+import { connect, health, invoke, pipeInvoke } from "./client.js";
+import { createHash } from "node:crypto";
+function entropy(n, seed = 1) {
+    const out = new Uint8Array(n);
+    let off = 0, ctr = 0;
+    while (off < n) {
+        const b = createHash("sha256").update(`${seed}:${ctr++}`).digest();
+        const t = Math.min(b.length, n - off);
+        out.set(b.subarray(0, t), off);
+        off += t;
+    }
+    return out;
+}
+export async function grpcGauntlet() {
+    const checks = [];
+    const metrics = { healthMs: 0, pingMs: 0, largePayloadBytes: 0, framesOverWire: 0, roundTripMs: 0 };
+    const srv = await createMatrixServer({ port: 0 });
+    const client = connect(`127.0.0.1:${srv.port}`);
+    try {
+        // 1) Health — the server is up on loopback + advertises the tool surface
+        let t = Date.now();
+        const h = await health(client);
+        metrics.healthMs = Date.now() - t;
+        checks.push({ name: "health round-trips on 127.0.0.1", pass: h.ok === true && h.tools > 0, detail: `tools=${h.tools} v=${h.version} ${metrics.healthMs}ms` });
+        // 2) Unary Invoke (ping) — the typed door works
+        t = Date.now();
+        const p = await invoke(client, "matrix.ping");
+        metrics.pingMs = Date.now() - t;
+        checks.push({ name: "unary Invoke works", pass: p.ok === true && JSON.parse(p.data_json).pong === true, detail: `${metrics.pingMs}ms` });
+        // 3) THE BIG ONE — a 5MB payload flows through the chunked Pipe byte-identical
+        //    (past gRPC's 4MB cap, which would reject a single message).
+        const big = entropy(5_000_000, 42);
+        const bigStr = Buffer.from(big).toString("base64"); // ~6.7MB string, well over 4MB
+        metrics.largePayloadBytes = bigStr.length;
+        t = Date.now();
+        const echoed = await pipeInvoke(client, "matrix.echo", JSON.stringify({ payload: bigStr }));
+        metrics.roundTripMs = Date.now() - t;
+        const back = echoed.ok ? JSON.parse(echoed.data_json).payload : "";
+        checks.push({ name: "5MB+ payload flows through chunked Pipe byte-identical", pass: back === bigStr, detail: `${(bigStr.length / 1e6).toFixed(1)}MB round-trip ${metrics.roundTripMs}ms (4MB cap bypassed)` });
+        // 4) pipe integrity surfaces on a real wire (a real tool via Pipe carries a proof)
+        const real = await pipeInvoke(client, "matrix.ping");
+        checks.push({ name: "Pipe carries a real call end-to-end", pass: real.ok === true, detail: "request frames in → reply frames out" });
+        // 5) unknown tool fails cleanly (server stays up — fail-open)
+        const bad = await invoke(client, "no.such.tool");
+        const stillUp = await health(client);
+        checks.push({ name: "unknown tool fails cleanly, server stays up", pass: bad.ok === false && stillUp.ok === true, detail: bad.error.slice(0, 40) });
+        const pass = checks.every((c) => c.pass);
+        return { score: pass ? 100 : 0, metrics, checks };
+    }
+    finally {
+        client.close();
+        await srv.stop();
+    }
+}
+//# sourceMappingURL=gauntlet.js.map

package/dist/gauntlet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gauntlet.js","sourceRoot":"","sources":["../src/gauntlet.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @mneme-ai/matrix — THE MATRIX RAIL gRPC wire server (local-first).
+ * One typed, signed, streaming pipe any AI agent (any language) crosses to reach
+ * every Mneme function. Wraps @mneme-ai/core's pipe core. See docs/MATRIX.md.
+ */
+export { createMatrixServer, buildImpl, type ServeOptions, type RunningServer } from "./server.js";
+export { connect, health, invoke, pipeInvoke, type MatrixClient, type ToolReply } from "./client.js";
+export { grpcGauntlet, type GrpcGauntlet } from "./gauntlet.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AACrG,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @mneme-ai/matrix — THE MATRIX RAIL gRPC wire server (local-first).
+ * One typed, signed, streaming pipe any AI agent (any language) crosses to reach
+ * every Mneme function. Wraps @mneme-ai/core's pipe core. See docs/MATRIX.md.
+ */
+export { createMatrixServer, buildImpl } from "./server.js";
+export { connect, health, invoke, pipeInvoke } from "./client.js";
+export { grpcGauntlet } from "./gauntlet.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAyC,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAqC,MAAM,aAAa,CAAC;AACrG,OAAO,EAAE,YAAY,EAAqB,MAAM,eAAe,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,43 @@
+/**
+ * THE MATRIX RAIL — gRPC wire server (local-first).
+ *
+ * The wire shell around @mneme-ai/core's pipe core. Any AI agent, any language,
+ * connects over HTTP/2 + Protobuf to reach EVERY Mneme function through one typed
+ * door — and a chunked bidi pipe so any-size payload flows byte-identical.
+ *
+ * Molecules of intelligence at every joint:
+ *   • binds 127.0.0.1 ONLY (insecure creds are fine on loopback — no network, air-gap intact)
+ *   • Invoke bridges to the SAME tool registry the MCP server uses (buildRuntime +
+ *     buildToolMap) → all ~960 tools, zero logic duplication, seamless
+ *   • every Invoke response carries a TRUSTLESS Ed25519 `_proof` (verify offline)
+ *   • Pipe reassembles with the core's full integrity check (dropped/reordered/
+ *     tampered chunk caught) and re-chunks the reply → the 4MB cap is never hit
+ *   • every handler is TOTAL — a thrown tool never crashes the server
+ *   • fail-open: if a tool/runtime is unavailable, the call returns ok:false, the
+ *     server stays up, and the agent can fall back to MCP/CLI
+ */
+import * as grpc from "@grpc/grpc-js";
+/** The discovery file any agent reads to find the running rail (zero-command wiring). */
+export declare function discoveryPath(cwd: string): string;
+export interface ServeOptions {
+    cwd?: string;
+    host?: string;
+    port?: number;
+    idleMs?: number;
+}
+export interface RunningServer {
+    server: grpc.Server;
+    port: number;
+    host: string;
+    stop: () => Promise<void>;
+}
+/** Build the gRPC service implementation bound to a repo root. Pure of network.
+ *  `touch` is called on every request so the server can self-reap when idle. */
+export declare function buildImpl(cwd: string, touch?: () => void): {
+    Invoke: (call: any, cb: any) => void;
+    Health: (_call: any, cb: any) => void;
+    Pipe: (call: any) => void;
+};
+/** Start the Matrix gRPC server on loopback. Resolves with the bound port. */
+export declare function createMatrixServer(opts?: ServeOptions): Promise<RunningServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAStC,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAA+C;AAcjG,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAOD;gFACgF;AAChF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,IAAe;mBAuChD,GAAG,MAAM,GAAG;oBAOX,GAAG,MAAM,GAAG;iBAGf,GAAG;EAsBnB;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAyClF"}

package/dist/server.js

@@ -0,0 +1,213 @@
+/**
+ * THE MATRIX RAIL — gRPC wire server (local-first).
+ *
+ * The wire shell around @mneme-ai/core's pipe core. Any AI agent, any language,
+ * connects over HTTP/2 + Protobuf to reach EVERY Mneme function through one typed
+ * door — and a chunked bidi pipe so any-size payload flows byte-identical.
+ *
+ * Molecules of intelligence at every joint:
+ *   • binds 127.0.0.1 ONLY (insecure creds are fine on loopback — no network, air-gap intact)
+ *   • Invoke bridges to the SAME tool registry the MCP server uses (buildRuntime +
+ *     buildToolMap) → all ~960 tools, zero logic duplication, seamless
+ *   • every Invoke response carries a TRUSTLESS Ed25519 `_proof` (verify offline)
+ *   • Pipe reassembles with the core's full integrity check (dropped/reordered/
+ *     tampered chunk caught) and re-chunks the reply → the 4MB cap is never hit
+ *   • every handler is TOTAL — a thrown tool never crashes the server
+ *   • fail-open: if a tool/runtime is unavailable, the call returns ok:false, the
+ *     server stays up, and the agent can fall back to MCP/CLI
+ */
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { trustless, matrix } from "@mneme-ai/core";
+import { buildRuntime, buildToolMap } from "@mneme-ai/mcp";
+import { createRequire } from "node:module";
+import { writeFileSync, rmSync, mkdirSync, existsSync } from "node:fs";
+/** The discovery file any agent reads to find the running rail (zero-command wiring). */
+export function discoveryPath(cwd) { return join(cwd, ".mneme", "matrix.json"); }
+const PROTO_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "proto", "mneme.proto");
+const req = createRequire(import.meta.url);
+function version() { try {
+    return req("../package.json").version ?? "0.0.0";
+}
+catch {
+    return "0.0.0";
+} }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function loadMatrixService() {
+    const def = protoLoader.loadSync(PROTO_PATH, { keepCase: true, longs: Number, enums: String, defaults: true, oneofs: true });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pkg = grpc.loadPackageDefinition(def);
+    return pkg.mneme.Matrix.service;
+}
+const toWire = (f) => ({ id: f.id, seq: f.seq, total: f.total, orig_bytes: f.origBytes, gz: f.gz, data: Buffer.from(f.data) });
+const fromWire = (w) => ({ id: String(w.id), seq: Number(w.seq), total: Number(w.total), origBytes: Number(w.orig_bytes), gz: !!w.gz, data: w.data instanceof Uint8Array ? w.data : Uint8Array.from(w.data ?? []) });
+/** Build the gRPC service implementation bound to a repo root. Pure of network.
+ *  `touch` is called on every request so the server can self-reap when idle. */
+export function buildImpl(cwd, touch = () => { }) {
+    const toolMap = buildToolMap();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let runtime = null;
+    let runtimeErr = "";
+    async function getRuntime() {
+        if (runtime)
+            return runtime;
+        if (runtimeErr)
+            return null;
+        try {
+            runtime = await buildRuntime(cwd);
+            return runtime;
+        }
+        catch (e) {
+            runtimeErr = e.message;
+            return null;
+        }
+    }
+    /** The bridge: a tool name + JSON args → a proof-carrying ToolResponse. Total. */
+    async function invoke(tool, argsJson, _heldRoot) {
+        try {
+            // infra self-test fast-paths — no runtime, no registry (so the wire can be
+            // proven for any-size data without building the heavy store/embedder).
+            if (tool === "matrix.ping")
+                return { ok: true, data_json: JSON.stringify({ pong: true, version: version() }), wisdom: "pong", proof_json: "", error: "" };
+            if (tool === "matrix.echo")
+                return { ok: true, data_json: argsJson || "{}", wisdom: "echo", proof_json: "", error: "" };
+            const t = toolMap.get(tool);
+            if (!t)
+                return { ok: false, data_json: "{}", wisdom: "", proof_json: "", error: `unknown tool: ${tool}` };
+            const rt = await getRuntime();
+            if (!rt)
+                return { ok: false, data_json: "{}", wisdom: "", proof_json: "", error: `runtime unavailable: ${runtimeErr}` };
+            let args = {};
+            try {
+                args = argsJson ? JSON.parse(argsJson) : {};
+            }
+            catch {
+                return { ok: false, data_json: "{}", wisdom: "", proof_json: "", error: "args_json is not valid JSON" };
+            }
+            const resp = await t.handler(rt, args);
+            const data = (resp?.data ?? {});
+            // proof-per-message: bind the response data to an offline-verifiable Ed25519 receipt
+            const wrapped = trustless.proofWrap(cwd, `matrix:${tool}`, typeof data === "object" && data ? data : { value: data });
+            const proof = wrapped["_proof"];
+            return { ok: true, data_json: JSON.stringify(data), wisdom: String(resp?.wisdom ?? ""), proof_json: JSON.stringify(proof ?? null), error: "" };
+        }
+        catch (e) {
+            return { ok: false, data_json: "{}", wisdom: "", proof_json: "", error: e.message };
+        }
+    }
+    return {
+        // unary
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        Invoke: (call, cb) => {
+            touch();
+            const r = call.request ?? {};
+            invoke(String(r.tool ?? ""), String(r.args_json ?? ""), r.held_root).then((res) => cb(null, res)).catch((e) => cb(null, { ok: false, data_json: "{}", wisdom: "", proof_json: "", error: e.message }));
+        },
+        // unary
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        Health: (_call, cb) => { touch(); cb(null, { ok: true, version: version(), tools: toolMap.size, note: "Matrix Rail — 127.0.0.1, proof-carrying, chunked pipe" }); },
+        // bidi stream: client streams request frames → reassemble → invoke → stream reply frames
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        Pipe: (call) => {
+            touch();
+            const frames = [];
+            call.on("data", (w) => { touch(); try {
+                frames.push(fromWire(w));
+            }
+            catch { /* skip bad frame */ } });
+            call.on("error", () => { try {
+                call.end();
+            }
+            catch { /* */ } });
+            call.on("end", () => {
+                (async () => {
+                    try {
+                        const asm = matrix.reassemble(frames);
+                        if (!asm.ok) {
+                            for (const f of matrix.chunkFrame(JSON.stringify({ ok: false, error: `pipe integrity: ${asm.reason}` })))
+                                call.write(toWire(f));
+                            call.end();
+                            return;
+                        }
+                        const reqMsg = matrix.decodeRequest(asm.payload);
+                        if (!reqMsg) {
+                            for (const f of matrix.chunkFrame(JSON.stringify({ ok: false, error: "pipe payload is not a ToolRequest" })))
+                                call.write(toWire(f));
+                            call.end();
+                            return;
+                        }
+                        const res = await invoke(reqMsg.tool, reqMsg.argsJson, reqMsg.heldRoot);
+                        for (const f of matrix.chunkFrame(JSON.stringify(res)))
+                            call.write(toWire(f));
+                        call.end();
+                    }
+                    catch (e) {
+                        try {
+                            for (const f of matrix.chunkFrame(JSON.stringify({ ok: false, error: e.message })))
+                                call.write(toWire(f));
+                            call.end();
+                        }
+                        catch { /* */ }
+                    }
+                })();
+            });
+        },
+    };
+}
+/** Start the Matrix gRPC server on loopback. Resolves with the bound port. */
+export function createMatrixServer(opts = {}) {
+    const host = opts.host ?? "127.0.0.1";
+    const port = opts.port ?? 0;
+    const cwd = opts.cwd ?? process.cwd();
+    // SELF-REAPING: the rail shuts itself down after `idleMs` with no requests, so a
+    // demand-spawned rail never lingers as an orphan (0 = never reap; tests pass 0).
+    const idleMs = opts.idleMs ?? 900_000; // 15 min default
+    let lastActivity = Date.now();
+    const touch = () => { lastActivity = Date.now(); };
+    const server = new grpc.Server({
+        // we CHUNK, so we never need to raise the cap — but keep it explicit + sane.
+        "grpc.max_receive_message_length": 8 * 1024 * 1024,
+        "grpc.max_send_message_length": 8 * 1024 * 1024,
+    });
+    server.addService(loadMatrixService(), buildImpl(cwd, touch));
+    return new Promise((resolve, reject) => {
+        server.bindAsync(`${host}:${port}`, grpc.ServerCredentials.createInsecure(), (err, boundPort) => {
+            if (err)
+                return reject(err);
+            // write the discovery file so any agent (any language) finds the rail with
+            // NO user command. Best-effort + only for the default loopback serve (skip
+            // ephemeral test ports so parallel tests don't fight over the file).
+            const disc = discoveryPath(cwd);
+            const writeDiscovery = host === "127.0.0.1" && (opts.port ?? 0) !== 0;
+            if (writeDiscovery) {
+                try {
+                    mkdirSync(join(cwd, ".mneme"), { recursive: true });
+                    writeFileSync(disc, JSON.stringify({ host, port: boundPort, pid: process.pid, version: version(), proto: PROTO_PATH, idleMs, at: new Date().toISOString() }));
+                }
+                catch { /* best-effort */ }
+            }
+            const cleanup = () => { if (writeDiscovery) {
+                try {
+                    if (existsSync(disc))
+                        rmSync(disc);
+                }
+                catch { /* */ }
+            } };
+            const stop = () => new Promise((res) => { if (reaper)
+                clearInterval(reaper); server.tryShutdown(() => { cleanup(); res(); }); });
+            // the idle reaper — unref'd so it never keeps the process alive on its own.
+            let reaper = null;
+            if (idleMs > 0) {
+                reaper = setInterval(() => { if (Date.now() - lastActivity > idleMs) {
+                    void stop();
+                } }, Math.min(60_000, Math.max(1_000, Math.floor(idleMs / 5))));
+                if (typeof reaper.unref === "function")
+                    reaper.unref();
+            }
+            resolve({ server, port: boundPort, host, stop });
+        });
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mneme-ai/matrix",
+  "version": "2.167.0",
+  "description": "THE MATRIX RAIL — the local-first gRPC wire server for Mneme. Any AI agent (any language) connects over HTTP/2 + Protobuf to reach every Mneme function through one typed, signed, streaming pipe. Invoke (unary, proof-carrying) + Pipe (bidi, chunked → any-size data flows byte-identical, past gRPC's 4MB cap). Binds 127.0.0.1 only; fail-open; wraps @mneme-ai/core's pipe core.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mneme-matrix": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./proto": "./proto/mneme.proto"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/patsa2561-art/mneme-ai.git",
+    "directory": "packages/matrix"
+  },
+  "homepage": "https://github.com/patsa2561-art/mneme-ai#readme",
+  "bugs": {
+    "url": "https://github.com/patsa2561-art/mneme-ai/issues"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "proto",
+    "README.md"
+  ],
+  "dependencies": {
+    "@grpc/grpc-js": "^1.12.5",
+    "@grpc/proto-loader": "^0.7.13",
+    "@mneme-ai/core": "2.167.0",
+    "@mneme-ai/mcp": "2.167.0"
+  }
+}

package/proto/mneme.proto

@@ -0,0 +1,35 @@
+// THE MATRIX RAIL — Mneme's local-first gRPC contract.
+// One typed door (Invoke) to every Mneme function + one chunked bidi pipe (Pipe)
+// so ANY-size payload flows byte-identical, past gRPC's 4MB message cap.
+syntax = "proto3";
+package mneme;
+
+service Matrix {
+  // Generic gateway — maps 1:1 to the tool registry. Every current AND future
+  // tool is reachable here with no schema change. Response carries a TRUSTLESS proof.
+  rpc Invoke (ToolRequest) returns (ToolResponse);
+
+  // The chunked bidi pipe: a client streams the request as ordered, manifested
+  // frames; the server reassembles (full integrity check), processes, and streams
+  // the response back as frames. Each frame is small (<256KB) so the 4MB cap is
+  // never hit, regardless of total payload size.
+  rpc Pipe (stream Frame) returns (stream Frame);
+
+  rpc Health (HealthRequest) returns (HealthReply);
+}
+
+message ToolRequest  { string tool = 1; string args_json = 2; string held_root = 3; }
+message ToolResponse { bool ok = 1; string data_json = 2; string wisdom = 3; string proof_json = 4; string error = 5; }
+
+// One frame of the Matrix pipe (mirrors @mneme-ai/core matrix.Frame).
+message Frame {
+  string id = 1;          // sha256 of the whole ORIGINAL payload (== integrity manifest)
+  uint32 seq = 2;         // 0-based order
+  uint32 total = 3;       // total frame count
+  uint32 orig_bytes = 4;  // original (decompressed) length
+  bool gz = 5;            // data is gzip-compressed
+  bytes data = 6;         // the (possibly compressed) slice
+}
+
+message HealthRequest {}
+message HealthReply { bool ok = 1; string version = 2; uint32 tools = 3; string note = 4; }