@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/client/ipc.d.ts

@@ -0,0 +1,81 @@
+import type { ActionFailure, ActionSessionFacts, ClientSessionFacts } from '../action-contracts.js';
+import type { ActionCatalog } from '../api/catalog.js';
+import type { ActionDispatcher } from '../api/dispatch.js';
+import type { JudgmentAccess } from '../knowledge/judgments.js';
+/** Frames larger than this are refused rather than buffered. */
+export declare const IPC_MAX_FRAME_BYTES: number;
+export interface IpcRequest {
+    /** Wire-level correlation id; distinct from operationId, which is the semantic command id. */
+    requestId: string;
+    kind: 'call' | 'describe';
+    /** Opaque session credential — the server maps it to access; input never grants access. */
+    credential?: string;
+    /** kind === 'describe': one contract name; absent lists the whole surface. */
+    name?: string;
+    /** kind === 'call': */
+    action?: string;
+    input?: unknown;
+    operationId?: string;
+    session?: ClientSessionFacts;
+}
+export type IpcResponse = {
+    requestId: string;
+    ok: true;
+    result: unknown;
+} | {
+    requestId: string;
+    ok: false;
+    error: ActionFailure;
+};
+/**
+ * A transport break. `connect` means the request provably never reached the
+ * runtime — the call can be reported `failed`. `exchange` means it may have
+ * been delivered — the honest status is `unknown` until operation.get or a
+ * same-id resend settles it.
+ */
+export declare class IpcTransportError extends Error {
+    readonly phase: 'connect' | 'exchange';
+    constructor(phase: 'connect' | 'exchange', message: string);
+}
+export declare function encodeFrame(payload: unknown): Buffer;
+/** One request over one connection — matches the short-lived CLI/MCP caller lifecycle. */
+export declare function sendIpcRequest(socketPath: string, request: IpcRequest, options?: {
+    timeoutMs?: number;
+}): Promise<IpcResponse>;
+export interface ActionIpcServerOptions {
+    socketPath: string;
+    catalog: ActionCatalog;
+    dispatch: ActionDispatcher;
+    /**
+     * Maps the wire credential to call authority. A credential that cannot be
+     * resolved is denied — the throw never reaches the action.
+     */
+    resolveAccess: (credential: string | undefined) => JudgmentAccess;
+    /**
+     * Host-stated call-site facts for calls on this socket — composed from the
+     * resolved authority and the request, never from caller input. A fact the
+     * socket cannot truthfully state (per-turn run, batch, channel) stays
+     * absent.
+     */
+    sessionFacts?: (access: JudgmentAccess, request: IpcRequest) => ActionSessionFacts | undefined;
+    maxFrameBytes?: number;
+    /**
+     * When the socket path already exists: probe it. A live socket is an error —
+     * a dead file left by a crashed process is unlinked and reclaimed.
+     */
+    reclaimStaleSocket?: boolean;
+}
+/** True when the path exists but nothing answers — a dead file, safe to replace. */
+export declare function staleSocketFile(socketPath: string): Promise<boolean>;
+export interface ActionIpcServer {
+    socketPath: string;
+    close(): Promise<void>;
+}
+/**
+ * The server half of the IPC contract — the piece `runtime.start` mounts when
+ * it opens the socket. One connection per caller, frames handled in order.
+ */
+export declare function createActionIpcServer(options: ActionIpcServerOptions): Promise<ActionIpcServer>;
+/** Convenience for callers that only need a correlation id for the wire. */
+export declare function newRequestId(): string;
+//# sourceMappingURL=ipc.d.ts.map

package/dist/client/ipc.js

@@ -0,0 +1,314 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IpcTransportError = exports.IPC_MAX_FRAME_BYTES = void 0;
+exports.encodeFrame = encodeFrame;
+exports.sendIpcRequest = sendIpcRequest;
+exports.staleSocketFile = staleSocketFile;
+exports.createActionIpcServer = createActionIpcServer;
+exports.newRequestId = newRequestId;
+/**
+ * IPC — the private Unix-socket wire between CLI/MCP clients and the runtime.
+ *
+ * §4.3: the socket carries requestId, action, input and the current session
+ * credential. Frames are length-prefixed JSON; partial reads, oversized frames
+ * and disconnects are handled explicitly. A lost answer is never an empty
+ * result — whether a mutation landed is settled through operation.get, not by
+ * guessing from a broken socket.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_net_1 = require("node:net");
+/** Frames larger than this are refused rather than buffered. */
+exports.IPC_MAX_FRAME_BYTES = 32 * 1024 * 1024;
+const FRAME_HEADER_BYTES = 4;
+/**
+ * A transport break. `connect` means the request provably never reached the
+ * runtime — the call can be reported `failed`. `exchange` means it may have
+ * been delivered — the honest status is `unknown` until operation.get or a
+ * same-id resend settles it.
+ */
+class IpcTransportError extends Error {
+    phase;
+    constructor(phase, message) {
+        super(message);
+        this.name = 'IpcTransportError';
+        this.phase = phase;
+    }
+}
+exports.IpcTransportError = IpcTransportError;
+function encodeFrame(payload) {
+    const body = Buffer.from(JSON.stringify(payload), 'utf8');
+    if (body.length > exports.IPC_MAX_FRAME_BYTES) {
+        throw new IpcTransportError('exchange', `frame of ${body.length} bytes exceeds the ${exports.IPC_MAX_FRAME_BYTES}-byte cap`);
+    }
+    const frame = Buffer.alloc(FRAME_HEADER_BYTES + body.length);
+    frame.writeUInt32BE(body.length, 0);
+    body.copy(frame, FRAME_HEADER_BYTES);
+    return frame;
+}
+/** Reassembles a byte stream into whole frame bodies; partial tails stay buffered. */
+class FrameReader {
+    maxFrameBytes;
+    buffered = Buffer.alloc(0);
+    constructor(maxFrameBytes) {
+        this.maxFrameBytes = maxFrameBytes;
+    }
+    push(chunk) {
+        this.buffered = this.buffered.length === 0 ? chunk : Buffer.concat([this.buffered, chunk]);
+        const frames = [];
+        while (this.buffered.length >= FRAME_HEADER_BYTES) {
+            const length = this.buffered.readUInt32BE(0);
+            if (length > this.maxFrameBytes) {
+                throw new Error(`frame length ${length} exceeds the ${this.maxFrameBytes}-byte cap`);
+            }
+            if (this.buffered.length < FRAME_HEADER_BYTES + length) {
+                return frames;
+            }
+            frames.push(this.buffered.subarray(FRAME_HEADER_BYTES, FRAME_HEADER_BYTES + length));
+            this.buffered = this.buffered.subarray(FRAME_HEADER_BYTES + length);
+        }
+        return frames;
+    }
+}
+/** One request over one connection — matches the short-lived CLI/MCP caller lifecycle. */
+function sendIpcRequest(socketPath, request, options = {}) {
+    return new Promise((resolve, reject) => {
+        let frame;
+        try {
+            frame = encodeFrame(request);
+        }
+        catch (error) {
+            reject(new IpcTransportError('connect', `ipc encode failed: ${error instanceof Error ? error.message : String(error)}`));
+            return;
+        }
+        let connected = false;
+        let settled = false;
+        const socket = (0, node_net_1.createConnection)(socketPath);
+        const reader = new FrameReader(exports.IPC_MAX_FRAME_BYTES);
+        const settle = (complete) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            complete();
+        };
+        const timer = options.timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                settle(() => reject(new IpcTransportError(connected ? 'exchange' : 'connect', `ipc request timed out after ${options.timeoutMs}ms`)));
+            }, options.timeoutMs);
+        socket.once('connect', () => {
+            connected = true;
+            socket.write(frame, (error) => {
+                if (error) {
+                    settle(() => reject(new IpcTransportError('exchange', `ipc write failed: ${error.message}`)));
+                }
+            });
+        });
+        socket.on('data', (chunk) => {
+            let bodies;
+            try {
+                bodies = reader.push(chunk);
+            }
+            catch (error) {
+                settle(() => reject(new IpcTransportError('exchange', `malformed response stream: ${error instanceof Error ? error.message : String(error)}`)));
+                return;
+            }
+            for (const body of bodies) {
+                let response;
+                try {
+                    response = JSON.parse(body.toString('utf8'));
+                }
+                catch {
+                    settle(() => reject(new IpcTransportError('exchange', 'response frame is not JSON')));
+                    return;
+                }
+                if (response.requestId !== request.requestId) {
+                    settle(() => reject(new IpcTransportError('exchange', `response requestId ${response.requestId} does not match request ${request.requestId}`)));
+                    return;
+                }
+                settle(() => resolve(response));
+                return;
+            }
+        });
+        socket.once('error', (error) => {
+            settle(() => reject(new IpcTransportError(connected ? 'exchange' : 'connect', `ipc socket error: ${error.message}`)));
+        });
+        socket.once('close', () => {
+            settle(() => reject(new IpcTransportError(connected ? 'exchange' : 'connect', 'ipc socket closed before a complete response frame')));
+        });
+    });
+}
+/** True when the path exists but nothing answers — a dead file, safe to replace. */
+function staleSocketFile(socketPath) {
+    if (!(0, node_fs_1.existsSync)(socketPath)) {
+        return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+        const probe = (0, node_net_1.createConnection)(socketPath);
+        probe.once('connect', () => {
+            probe.destroy();
+            resolve(false);
+        });
+        probe.once('error', () => resolve(true));
+    });
+}
+async function handleFrame(socket, options, body) {
+    let request;
+    try {
+        request = JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        socket.write(encodeFrame({
+            requestId: '',
+            ok: false,
+            error: {
+                kind: 'invalid_input',
+                code: 'malformed_frame',
+                message: 'request frame is not JSON',
+            },
+        }));
+        return;
+    }
+    const reply = (response) => {
+        socket.write(encodeFrame(response));
+    };
+    let access;
+    try {
+        access = options.resolveAccess(request.credential);
+    }
+    catch (error) {
+        reply({
+            requestId: request.requestId,
+            ok: false,
+            error: {
+                kind: 'denied',
+                code: 'access_denied',
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return;
+    }
+    try {
+        let result;
+        if (request.kind === 'describe') {
+            result =
+                request.name === undefined
+                    ? options.catalog.list()
+                    : options.catalog.describe(request.name);
+        }
+        else if (request.kind === 'call') {
+            if (typeof request.action !== 'string' || request.action.length === 0) {
+                reply({
+                    requestId: request.requestId,
+                    ok: false,
+                    error: {
+                        kind: 'invalid_input',
+                        code: 'missing_action',
+                        message: 'call request requires action',
+                    },
+                });
+                return;
+            }
+            const session = options.sessionFacts?.(access, request);
+            result = await options.dispatch({ action: request.action, input: request.input, operationId: request.operationId }, session === undefined ? { access } : { access, session });
+        }
+        else {
+            reply({
+                requestId: request.requestId,
+                ok: false,
+                error: {
+                    kind: 'invalid_input',
+                    code: 'unknown_request_kind',
+                    message: `unknown request kind ${String(request.kind)}`,
+                },
+            });
+            return;
+        }
+        reply({ requestId: request.requestId, ok: true, result });
+    }
+    catch (error) {
+        reply({
+            requestId: request.requestId,
+            ok: false,
+            error: {
+                kind: 'internal',
+                code: error instanceof Error ? error.name : 'internal_error',
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+/**
+ * The server half of the IPC contract — the piece `runtime.start` mounts when
+ * it opens the socket. One connection per caller, frames handled in order.
+ */
+function createActionIpcServer(options) {
+    const maxFrameBytes = options.maxFrameBytes ?? exports.IPC_MAX_FRAME_BYTES;
+    const sockets = new Set();
+    const server = (0, node_net_1.createServer)((socket) => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+        socket.on('error', () => socket.destroy());
+        const reader = new FrameReader(maxFrameBytes);
+        socket.on('data', (chunk) => {
+            let bodies;
+            try {
+                bodies = reader.push(chunk);
+            }
+            catch (error) {
+                socket.write(encodeFrame({
+                    requestId: '',
+                    ok: false,
+                    error: {
+                        kind: 'invalid_input',
+                        code: 'frame_too_large',
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                }));
+                socket.end();
+                return;
+            }
+            for (const body of bodies) {
+                void handleFrame(socket, options, body);
+            }
+        });
+    });
+    return new Promise((resolve, reject) => {
+        const handle = {
+            socketPath: options.socketPath,
+            close: () => new Promise((done) => {
+                for (const socket of sockets) {
+                    socket.destroy();
+                }
+                server.close(() => {
+                    (0, node_fs_1.rmSync)(options.socketPath, { force: true });
+                    done();
+                });
+            }),
+        };
+        const listen = () => {
+            server.once('error', reject);
+            server.listen(options.socketPath, () => resolve(handle));
+        };
+        if (!options.reclaimStaleSocket || !(0, node_fs_1.existsSync)(options.socketPath)) {
+            listen();
+            return;
+        }
+        void staleSocketFile(options.socketPath).then((stale) => {
+            if (!stale) {
+                reject(new Error(`ipc socket already served by a live runtime: ${options.socketPath}`));
+                return;
+            }
+            (0, node_fs_1.rmSync)(options.socketPath, { force: true });
+            listen();
+        });
+    });
+}
+/** Convenience for callers that only need a correlation id for the wire. */
+function newRequestId() {
+    return `req_${(0, node_crypto_1.randomUUID)()}`;
+}
+//# sourceMappingURL=ipc.js.map

package/dist/db-adapter/base-adapter.d.ts

@@ -1,6 +1,10 @@
 /**
- * Base Database Adapter Interface
- * All adapters must implement these methods
+ * Row shapes the SQLite drivers share.
+ *
+ * There used to be an abstract class here declaring the adapter's methods, which made
+ * two definitions of the same port: this one and the DatabaseInstance interface in
+ * db-manager. A driver now says which interface it satisfies rather than inheriting a
+ * second copy of the contract.
  */
 import type { Statement, RunResult } from './statement.js';
 export type { Statement, RunResult };
@@ -9,68 +13,4 @@ export interface VectorSearchResult {
     similarity?: number;
     distance?: number;
 }
-export declare abstract class DatabaseAdapter {
-    /**
-     * Connect to database
-     * @returns Database connection
-     */
-    abstract connect(): unknown;
-    /**
-     * Disconnect from database
-     */
-    abstract disconnect(): void;
-    /**
-     * Check if connected
-     * @returns Connection status
-     */
-    abstract isConnected(): boolean;
-    /**
-     * Prepare a SQL statement
-     * @param sql - SQL query
-     * @returns Prepared statement
-     */
-    abstract prepare(sql: string): Statement;
-    /**
-     * Execute raw SQL
-     * @param sql - SQL to execute
-     */
-    abstract exec(sql: string): void;
-    /**
-     * Execute function in transaction
-     * @param fn - Function to execute
-     * @returns Function return value
-     */
-    abstract transaction<T>(fn: () => T): T;
-    /**
-     * Vector similarity search
-     * @param embedding - Query embedding (1024-dim)
-     * @param limit - Max results
-     * @returns Search results with distance
-     */
-    abstract vectorSearch(embedding: Float32Array | number[], limit: number, topicPrefix?: string): VectorSearchResult[] | null;
-    /**
-     * Insert vector embedding
-     * @param rowid - Decision rowid
-     * @param embedding - Embedding vector
-     */
-    abstract insertEmbedding(rowid: number, embedding: Float32Array | number[]): RunResult | null;
-    /**
-     * Get last inserted row ID
-     * @returns Last rowid
-     */
-    abstract getLastInsertRowid(): number;
-    /**
-     * Run migrations
-     * @param migrationsDir - Path to migrations directory
-     */
-    abstract runMigrations(migrationsDir: string): void;
-    /**
-     * Check if vector search is enabled
-     */
-    abstract get vectorSearchEnabled(): boolean;
-    /**
-     * Get database path
-     */
-    abstract getDbPath(): string;
-}
 //# sourceMappingURL=base-adapter.d.ts.map

package/dist/db-adapter/base-adapter.js

@@ -1,11 +1,11 @@
 "use strict";
 /**
- * Base Database Adapter Interface
- * All adapters must implement these methods
+ * Row shapes the SQLite drivers share.
+ *
+ * There used to be an abstract class here declaring the adapter's methods, which made
+ * two definitions of the same port: this one and the DatabaseInstance interface in
+ * db-manager. A driver now says which interface it satisfies rather than inheriting a
+ * second copy of the contract.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DatabaseAdapter = void 0;
-class DatabaseAdapter {
-}
-exports.DatabaseAdapter = DatabaseAdapter;
 //# sourceMappingURL=base-adapter.js.map

package/dist/db-adapter/index.d.ts

@@ -1,16 +1,16 @@
 /**
  * Database Adapter Factory (SQLite-only)
  *
- * MAMA Plugin uses SQLite exclusively for local storage.
- * PostgreSQL support is only available in the legacy mcp-server.
+ * SQLite only. There is no PostgreSQL adapter here.
  *
  * @module db-adapter
  */
 import { SQLiteAdapter } from './sqlite-adapter.js';
 import { NodeSQLiteAdapter } from './node-sqlite-adapter.js';
-import { DatabaseAdapter, type VectorSearchResult, type RunResult } from './base-adapter.js';
+import type { VectorSearchResult, RunResult } from './base-adapter.js';
+import type { DatabaseInstance } from '../db-manager.js';
 import type { Statement } from './statement.js';
-export { DatabaseAdapter, SQLiteAdapter, NodeSQLiteAdapter };
+export { SQLiteAdapter, NodeSQLiteAdapter };
 export type { Statement, VectorSearchResult, RunResult };
 export interface AdapterConfig {
     dbPath?: string;
@@ -21,5 +21,5 @@ export interface AdapterConfig {
  * @param config - Database configuration
  * @returns Configured SQLite adapter instance
  */
-export declare function createAdapter(config?: AdapterConfig): DatabaseAdapter;
+export declare function createAdapter(config?: AdapterConfig): DatabaseInstance;
 //# sourceMappingURL=index.d.ts.map

package/dist/db-adapter/index.js

@@ -2,21 +2,18 @@
 /**
  * Database Adapter Factory (SQLite-only)
  *
- * MAMA Plugin uses SQLite exclusively for local storage.
- * PostgreSQL support is only available in the legacy mcp-server.
+ * SQLite only. There is no PostgreSQL adapter here.
  *
  * @module db-adapter
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NodeSQLiteAdapter = exports.SQLiteAdapter = exports.DatabaseAdapter = void 0;
+exports.NodeSQLiteAdapter = exports.SQLiteAdapter = void 0;
 exports.createAdapter = createAdapter;
 const debug_logger_js_1 = require("../debug-logger.js");
 const sqlite_adapter_js_1 = require("./sqlite-adapter.js");
 Object.defineProperty(exports, "SQLiteAdapter", { enumerable: true, get: function () { return sqlite_adapter_js_1.SQLiteAdapter; } });
 const node_sqlite_adapter_js_1 = require("./node-sqlite-adapter.js");
 Object.defineProperty(exports, "NodeSQLiteAdapter", { enumerable: true, get: function () { return node_sqlite_adapter_js_1.NodeSQLiteAdapter; } });
-const base_adapter_js_1 = require("./base-adapter.js");
-Object.defineProperty(exports, "DatabaseAdapter", { enumerable: true, get: function () { return base_adapter_js_1.DatabaseAdapter; } });
 /**
  * Create SQLite database adapter
  *