@maadb/core 0.0.1 → 0.7.10-rc.3

package/dist/mcp/rate-limit.js

@@ -0,0 +1,203 @@
+// ============================================================================
+// SessionRateLimiter — per-session token buckets + payload cap.
+//
+// Three independent buckets per session:
+//   writes/sec   capacity=10, refill=10 tokens/sec  (mutating tools only)
+//   writes/min   capacity=60, refill=60 tokens/60s  (mutating tools only)
+//   concurrent   semaphore, cap=5                   (any tool in flight)
+//
+// Plus one per-request cap:
+//   payload_too_large  ≥ 1 MiB serialized args
+//
+// Read-only tools are exempt from the write buckets but still count against
+// `concurrent` and `payload`. Refill is lazy (computed on tryAcquire*), no
+// background timers. All knobs env-tunable (MAAD_RL_*). Kill switch:
+// MAAD_RL_DISABLE=1.
+// ============================================================================
+function newBucket(capacity, refillPerSec, nowMs) {
+    return { capacity, refillPerSec, tokens: capacity, lastRefillMs: nowMs };
+}
+function refill(bucket, nowMs) {
+    const elapsedSec = (nowMs - bucket.lastRefillMs) / 1000;
+    if (elapsedSec <= 0)
+        return;
+    const added = elapsedSec * bucket.refillPerSec;
+    bucket.tokens = Math.min(bucket.capacity, bucket.tokens + added);
+    bucket.lastRefillMs = nowMs;
+}
+function msUntilOneToken(bucket, nowMs) {
+    refill(bucket, nowMs);
+    if (bucket.tokens >= 1)
+        return 0;
+    const deficit = 1 - bucket.tokens;
+    return Math.ceil((deficit / bucket.refillPerSec) * 1000);
+}
+const DEFAULTS = {
+    writesPerSec: 10,
+    writesPerMin: 60,
+    concurrent: 5,
+    payloadBytes: 1_048_576,
+    disabled: false,
+};
+export function readRateLimitEnv() {
+    const env = process.env;
+    const out = {};
+    const num = (s) => (s && !Number.isNaN(Number(s)) ? Number(s) : undefined);
+    const wps = num(env.MAAD_RL_WRITES_PER_SEC);
+    if (wps !== undefined)
+        out.writesPerSec = wps;
+    const wpm = num(env.MAAD_RL_WRITES_PER_MIN);
+    if (wpm !== undefined)
+        out.writesPerMin = wpm;
+    const conc = num(env.MAAD_RL_CONCURRENT);
+    if (conc !== undefined)
+        out.concurrent = conc;
+    const pb = num(env.MAAD_RL_PAYLOAD_BYTES);
+    if (pb !== undefined)
+        out.payloadBytes = pb;
+    if (env.MAAD_RL_DISABLE === '1')
+        out.disabled = true;
+    return out;
+}
+// ---- Mutating tool registry ------------------------------------------------
+const MUTATING_TOOLS = new Set([
+    'maad_create',
+    'maad_update',
+    'maad_bulk_create',
+    'maad_bulk_update',
+    // Note: maad_delete is an engine operation, not currently an MCP tool.
+    // Indexing ops (reindex, indexAll) are admin tools; they ARE mutating but
+    // are gated by role; we count them against the write bucket for consistency.
+    'maad_reindex',
+]);
+export function isMutatingTool(toolName) {
+    return MUTATING_TOOLS.has(toolName);
+}
+// ---- Limiter class ---------------------------------------------------------
+export class SessionRateLimiter {
+    config;
+    writesSec = new Map();
+    writesMin = new Map();
+    inFlight = new Map();
+    constructor(opts = {}) {
+        this.config = {
+            ...DEFAULTS,
+            now: () => Date.now(),
+            ...opts,
+        };
+    }
+    /**
+     * Per-request payload size gate. Returns null on success or a rejection
+     * describing the breach. Runs before anything else — oversize args waste
+     * compute.
+     */
+    checkPayloadSize(bytes) {
+        if (this.config.disabled)
+            return null;
+        if (bytes <= this.config.payloadBytes)
+            return null;
+        return {
+            reason: 'payload_too_large',
+            limit: this.config.payloadBytes,
+            retryAfterMs: null,
+        };
+    }
+    /**
+     * Acquire a concurrent-in-flight slot. Returns { release } on success or
+     * a rejection. ALL tool calls (reads and writes) use this cap.
+     */
+    tryAcquireConcurrent(sessionId) {
+        if (this.config.disabled)
+            return { ok: true, release: () => { } };
+        const current = this.inFlight.get(sessionId) ?? 0;
+        if (current >= this.config.concurrent) {
+            return {
+                ok: false,
+                rejection: { reason: 'concurrent', limit: this.config.concurrent, retryAfterMs: null },
+            };
+        }
+        this.inFlight.set(sessionId, current + 1);
+        return {
+            ok: true,
+            release: () => {
+                const c = this.inFlight.get(sessionId) ?? 0;
+                if (c <= 1)
+                    this.inFlight.delete(sessionId);
+                else
+                    this.inFlight.set(sessionId, c - 1);
+            },
+        };
+    }
+    /**
+     * Consume one token each from writes/sec and writes/min. Only called for
+     * mutating tools. Returns null on success or a rejection identifying which
+     * bucket failed.
+     */
+    tryAcquireWrite(sessionId) {
+        if (this.config.disabled)
+            return null;
+        const nowMs = this.config.now();
+        let wps = this.writesSec.get(sessionId);
+        if (!wps) {
+            wps = newBucket(this.config.writesPerSec, this.config.writesPerSec, nowMs);
+            this.writesSec.set(sessionId, wps);
+        }
+        refill(wps, nowMs);
+        let wpm = this.writesMin.get(sessionId);
+        if (!wpm) {
+            wpm = newBucket(this.config.writesPerMin, this.config.writesPerMin / 60, nowMs);
+            this.writesMin.set(sessionId, wpm);
+        }
+        refill(wpm, nowMs);
+        if (wps.tokens < 1) {
+            return {
+                reason: 'writes_per_sec',
+                limit: this.config.writesPerSec,
+                retryAfterMs: msUntilOneToken(wps, nowMs),
+            };
+        }
+        if (wpm.tokens < 1) {
+            return {
+                reason: 'writes_per_min',
+                limit: this.config.writesPerMin,
+                retryAfterMs: msUntilOneToken(wpm, nowMs),
+            };
+        }
+        wps.tokens -= 1;
+        wpm.tokens -= 1;
+        return null;
+    }
+    /**
+     * Total in-flight requests across all sessions. Used by the H7 graceful
+     * shutdown drain loop.
+     */
+    totalInFlight() {
+        let total = 0;
+        for (const n of this.inFlight.values())
+            total += n;
+        return total;
+    }
+    /** Discard all per-session state for `sessionId`. Called on disconnect. */
+    disposeSession(sessionId) {
+        this.writesSec.delete(sessionId);
+        this.writesMin.delete(sessionId);
+        this.inFlight.delete(sessionId);
+    }
+    /** Test helper — peek at in-flight count for a single session. */
+    inFlightFor(sessionId) {
+        return this.inFlight.get(sessionId) ?? 0;
+    }
+    /** Test helper — peek at current config (for assertions). */
+    getConfig() {
+        return this.config;
+    }
+}
+// ---- Module-level singleton -------------------------------------------------
+let limiter = new SessionRateLimiter();
+export function initRateLimiter(opts) {
+    limiter = new SessionRateLimiter(opts);
+}
+export function getRateLimiter() {
+    return limiter;
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/mcp/rate-limit.js.map

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

package/dist/mcp/reload-signal.d.ts

@@ -0,0 +1,13 @@
+import type { InstanceCtx } from './ctx.js';
+/**
+ * Install a SIGHUP listener that triggers performInstanceReload. Safe to call
+ * once at startup. Windows returns early (no SIGHUP on that platform). Tests
+ * skip this — they invoke performInstanceReload directly.
+ */
+export declare function installReloadSignalHandler(ctx: InstanceCtx): void;
+/**
+ * Remove the SIGHUP listener. Used by tests between cases and by graceful
+ * shutdown to prevent late signals from firing after teardown.
+ */
+export declare function uninstallReloadSignalHandler(): void;
+//# sourceMappingURL=reload-signal.d.ts.map

package/dist/mcp/reload-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reload-signal.d.ts","sourceRoot":"","sources":["../../src/mcp/reload-signal.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAM5C;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CA+CjE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAKnD"}

package/dist/mcp/reload-signal.js

@@ -0,0 +1,68 @@
+// ============================================================================
+// SIGHUP reload signal handler — triggers a full instance reload on POSIX
+// systems (systemctl reload, kill -HUP, etc.). Windows has no SIGHUP concept
+// at the OS level, so installation is a no-op there — operators on Windows
+// use the `maad_instance_reload` MCP tool instead.
+//
+// The handler defers to `performInstanceReload` with source="sighup". Errors
+// are logged to the ops channel but do not crash the process — a failed
+// reload leaves the prior instance state intact.
+// ============================================================================
+import { performInstanceReload } from './instance-reload.js';
+import { getOpsLog } from '../logging.js';
+let signalHandler = null;
+/**
+ * Install a SIGHUP listener that triggers performInstanceReload. Safe to call
+ * once at startup. Windows returns early (no SIGHUP on that platform). Tests
+ * skip this — they invoke performInstanceReload directly.
+ */
+export function installReloadSignalHandler(ctx) {
+    if (process.platform === 'win32') {
+        // No SIGHUP on Windows. Document in the deploy guides that Windows
+        // operators must use the maad_instance_reload MCP tool.
+        return;
+    }
+    if (signalHandler) {
+        // Already installed — idempotent for test helpers that reinit.
+        return;
+    }
+    signalHandler = () => {
+        // Fire-and-forget — the signal handler itself must return synchronously.
+        // Errors land on the ops log via performInstanceReload's internal logging.
+        void (async () => {
+            const instanceResult = await performInstanceReload(ctx, 'sighup');
+            if (!instanceResult.ok) {
+                const first = instanceResult.errors[0];
+                getOpsLog().warn({ event: 'sighup_reload_failed', code: first?.code, message: first?.message }, 'sighup_reload_failed');
+            }
+            // 0.7.0 — reload tokens.yaml too. Independent of instance reload; a
+            // failure here doesn't roll back the instance reload. Captures of
+            // ctx.tokens elsewhere (the HTTP transport closure) stay valid because
+            // TokenStore.reload mutates the existing instance in-place.
+            // Loose null check (`!= null`) catches both null and undefined — test
+            // harnesses sometimes pass partial ctx objects without a tokens field.
+            if (ctx.tokens != null) {
+                const tokensResult = await ctx.tokens.reload();
+                if (!tokensResult.ok) {
+                    const first = tokensResult.errors[0];
+                    getOpsLog().warn({ event: 'sighup_tokens_reload_failed', code: first?.code, message: first?.message }, 'sighup_tokens_reload_failed');
+                }
+                else {
+                    getOpsLog().info({ event: 'tokens_reload', total: tokensResult.value.total, active: tokensResult.value.active }, 'tokens_reload');
+                }
+            }
+        })();
+    };
+    process.on('SIGHUP', signalHandler);
+}
+/**
+ * Remove the SIGHUP listener. Used by tests between cases and by graceful
+ * shutdown to prevent late signals from firing after teardown.
+ */
+export function uninstallReloadSignalHandler() {
+    if (signalHandler && process.platform !== 'win32') {
+        process.off('SIGHUP', signalHandler);
+    }
+    signalHandler = null;
+}
+//# sourceMappingURL=reload-signal.js.map

package/dist/mcp/reload-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reload-signal.js","sourceRoot":"","sources":["../../src/mcp/reload-signal.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,0EAA0E;AAC1E,6EAA6E;AAC7E,2EAA2E;AAC3E,mDAAmD;AACnD,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,iDAAiD;AACjD,+EAA+E;AAG/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,IAAI,aAAa,GAAkC,IAAI,CAAC;AAExD;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAgB;IACzD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,mEAAmE;QACnE,wDAAwD;QACxD,OAAO;IACT,CAAC;IACD,IAAI,aAAa,EAAE,CAAC;QAClB,+DAA+D;QAC/D,OAAO;IACT,CAAC;IAED,aAAa,GAAG,GAAG,EAAE;QACnB,yEAAyE;QACzE,2EAA2E;QAC3E,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,MAAM,cAAc,GAAG,MAAM,qBAAqB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAClE,IAAI,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC;gBACvB,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBACvC,SAAS,EAAE,CAAC,IAAI,CACd,EAAE,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAC7E,sBAAsB,CACvB,CAAC;YACJ,CAAC;YACD,oEAAoE;YACpE,kEAAkE;YAClE,uEAAuE;YACvE,4DAA4D;YAC5D,sEAAsE;YACtE,uEAAuE;YACvE,IAAI,GAAG,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;gBACvB,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC/C,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;oBACrB,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;oBACrC,SAAS,EAAE,CAAC,IAAI,CACd,EAAE,KAAK,EAAE,6BAA6B,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EACpF,6BAA6B,CAC9B,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,SAAS,EAAE,CAAC,IAAI,CACd,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,EAC9F,eAAe,CAChB,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B;IAC1C,IAAI,aAAa,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IACvC,CAAC;IACD,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC"}

package/dist/mcp/response.d.ts

@@ -0,0 +1,109 @@
+import type { Result, MaadError } from '../errors.js';
+import type { ValidationWarning } from '../types.js';
+import type { ProvenanceMode } from './config.js';
+export declare function setProvenanceMode(mode: ProvenanceMode): void;
+export declare function getProvenanceMode(): ProvenanceMode;
+export declare function successResponse(data: unknown, toolName?: string): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export declare function errorResponse(errors: MaadError[]): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export declare function resultToResponse<T>(result: Result<T>, toolName?: string): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * 0.7.1 (R3) — Projected-size guard for list-returning tools. Computes the
+ * byte size of the serialized response before returning; rejects with
+ * RESPONSE_TOO_LARGE when over cap. Prevents silent truncation when the MCP
+ * client's tool-output harness caps the response (~80KB in Claude Code).
+ *
+ * Cap is read lazily from MAAD_RESPONSE_MAX_BYTES each call so tests can
+ * flip it via env without re-importing the module. Default 64KB gives
+ * headroom below the observed Claude Code ceiling.
+ *
+ * Only applies to success responses — error responses are small and
+ * stamping them risks hiding the original error. Returns the input
+ * unchanged for errors or when under cap.
+ */
+export declare function responseMaxBytes(): number;
+export declare function guardResponseSize(response: {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}, context: {
+    tool: string;
+    hint?: string;
+}): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * Attach or merge fields into `_meta` on an already-serialized tool response.
+ * Used by the MCP wrapper to stamp request_id onto every response so clients
+ * can quote it in bug reports. Non-breaking (MCP allows extra fields).
+ */
+export declare function attachMeta(response: {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}, meta: Record<string, unknown>): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * Attach validation warnings to `_meta.warnings[]`. No-op when the input is
+ * empty or undefined — avoids polluting responses for writes that produced
+ * no warnings. Used by write-tool handlers (maad_create / maad_update /
+ * maad_bulk_*) after a successful engine call.
+ */
+export declare function attachWarnings(response: {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}, warnings: ValidationWarning[] | undefined): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * 0.6.10 — Stamp commit-durability signals onto a write response. Always
+ * attaches `write_durable`. When the commit failed (write landed on disk
+ * but the git commit didn't), also attaches `commit_failure` with the
+ * action / code / message so the client can log forensics or retry.
+ * `write_durable: true` attaches nothing else — existing clients that
+ * ignore `_meta` see zero behavioral change.
+ */
+export declare function attachDurability(response: {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}, writeDurable: boolean, commitFailure: {
+    code: string;
+    message: string;
+    action: 'create' | 'update' | 'delete';
+} | undefined): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+//# sourceMappingURL=response.d.ts.map

package/dist/mcp/response.d.ts.map

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

package/dist/mcp/response.js

@@ -0,0 +1,132 @@
+// ============================================================================
+// MCP Response Contract — standard { ok, data|errors } shape for all tools
+// Provenance mode injects _source metadata when enabled.
+// ============================================================================
+let provenanceMode = 'off';
+export function setProvenanceMode(mode) {
+    provenanceMode = mode;
+}
+export function getProvenanceMode() {
+    return provenanceMode;
+}
+export function successResponse(data, toolName) {
+    const response = { ok: true, data };
+    if (provenanceMode !== 'off' && toolName) {
+        response._source = toolName;
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(response) }] };
+}
+export function errorResponse(errors) {
+    const response = {
+        ok: false,
+        errors: errors.map(e => {
+            const base = {
+                code: e.code,
+                message: e.message,
+            };
+            if (e.details !== undefined)
+                base.details = e.details;
+            return base;
+        }),
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(response) }] };
+}
+export function resultToResponse(result, toolName) {
+    if (result.ok)
+        return successResponse(result.value, toolName);
+    return errorResponse(result.errors);
+}
+/**
+ * 0.7.1 (R3) — Projected-size guard for list-returning tools. Computes the
+ * byte size of the serialized response before returning; rejects with
+ * RESPONSE_TOO_LARGE when over cap. Prevents silent truncation when the MCP
+ * client's tool-output harness caps the response (~80KB in Claude Code).
+ *
+ * Cap is read lazily from MAAD_RESPONSE_MAX_BYTES each call so tests can
+ * flip it via env without re-importing the module. Default 64KB gives
+ * headroom below the observed Claude Code ceiling.
+ *
+ * Only applies to success responses — error responses are small and
+ * stamping them risks hiding the original error. Returns the input
+ * unchanged for errors or when under cap.
+ */
+export function responseMaxBytes() {
+    const raw = process.env['MAAD_RESPONSE_MAX_BYTES'];
+    if (!raw)
+        return 65536;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 65536;
+}
+export function guardResponseSize(response, context) {
+    const first = response.content[0];
+    if (!first || first.type !== 'text')
+        return response;
+    const cap = responseMaxBytes();
+    const bytes = Buffer.byteLength(first.text, 'utf8');
+    if (bytes <= cap)
+        return response;
+    // Only reject success responses — error responses are small and should pass through.
+    let parsed;
+    try {
+        parsed = JSON.parse(first.text);
+    }
+    catch {
+        return response;
+    }
+    if (parsed.ok === false)
+        return response;
+    const hint = context.hint ?? 'Narrow field projection, add filters, or paginate with cursor';
+    return errorResponse([{
+            code: 'RESPONSE_TOO_LARGE',
+            message: `Projected response (${bytes} bytes) exceeds cap (${cap} bytes)`,
+            details: { projectedBytes: bytes, capBytes: cap, hint, tool: context.tool },
+        }]);
+}
+/**
+ * Attach or merge fields into `_meta` on an already-serialized tool response.
+ * Used by the MCP wrapper to stamp request_id onto every response so clients
+ * can quote it in bug reports. Non-breaking (MCP allows extra fields).
+ */
+export function attachMeta(response, meta) {
+    const first = response.content[0];
+    if (!first || first.type !== 'text')
+        return response;
+    let parsed;
+    try {
+        parsed = JSON.parse(first.text);
+    }
+    catch {
+        return response;
+    }
+    const existing = parsed._meta ?? {};
+    parsed._meta = { ...existing, ...meta };
+    return { content: [{ type: 'text', text: JSON.stringify(parsed) }] };
+}
+/**
+ * Attach validation warnings to `_meta.warnings[]`. No-op when the input is
+ * empty or undefined — avoids polluting responses for writes that produced
+ * no warnings. Used by write-tool handlers (maad_create / maad_update /
+ * maad_bulk_*) after a successful engine call.
+ */
+export function attachWarnings(response, warnings) {
+    if (!warnings || warnings.length === 0)
+        return response;
+    return attachMeta(response, { warnings });
+}
+/**
+ * 0.6.10 — Stamp commit-durability signals onto a write response. Always
+ * attaches `write_durable`. When the commit failed (write landed on disk
+ * but the git commit didn't), also attaches `commit_failure` with the
+ * action / code / message so the client can log forensics or retry.
+ * `write_durable: true` attaches nothing else — existing clients that
+ * ignore `_meta` see zero behavioral change.
+ */
+export function attachDurability(response, writeDurable, commitFailure) {
+    if (writeDurable)
+        return attachMeta(response, { write_durable: true });
+    const meta = { write_durable: false };
+    if (commitFailure)
+        meta['commit_failure'] = commitFailure;
+    return attachMeta(response, meta);
+}
+//# sourceMappingURL=response.js.map

package/dist/mcp/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/mcp/response.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,yDAAyD;AACzD,+EAA+E;AAM/E,IAAI,cAAc,GAAmB,KAAK,CAAC;AAE3C,MAAM,UAAU,iBAAiB,CAAC,IAAoB;IACpD,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC;AACxB,CAAC;AAiBD,MAAM,UAAU,eAAe,CAAC,IAAa,EAAE,QAAiB;IAC9D,MAAM,QAAQ,GAAgB,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACjD,IAAI,cAAc,KAAK,KAAK,IAAI,QAAQ,EAAE,CAAC;QACzC,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC;IAC9B,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAmB;IAC/C,MAAM,QAAQ,GAAgB;QAC5B,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;YACrB,MAAM,IAAI,GAAyE;gBACjF,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAC;YACF,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS;gBAAE,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;YACtD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;KACH,CAAC;IACF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAI,MAAiB,EAAE,QAAiB;IACtE,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9D,OAAO,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IACnD,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,QAA4D,EAC5D,OAAwC;IAExC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,QAAQ,CAAC;IAErD,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpD,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,QAAQ,CAAC;IAElC,qFAAqF;IACrF,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,EAAE,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IAEzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,+DAA+D,CAAC;IAC7F,OAAO,aAAa,CAAC,CAAC;YACpB,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,uBAAuB,KAAK,wBAAwB,GAAG,SAAS;YACzE,OAAO,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;SAC5E,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,QAA4D,EAC5D,IAA6B;IAE7B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,QAAQ,CAAC;IAErD,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,QAAQ,GAAI,MAAM,CAAC,KAA6C,IAAI,EAAE,CAAC;IAC7E,MAAM,CAAC,KAAK,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAC;IACxC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;AACvE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,QAA4D,EAC5D,QAAyC;IAEzC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACxD,OAAO,UAAU,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA4D,EAC5D,YAAqB,EACrB,aAAoG;IAEpG,IAAI,YAAY;QAAE,OAAO,UAAU,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,MAAM,IAAI,GAA4B,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;IAC/D,IAAI,aAAa;QAAE,IAAI,CAAC,gBAAgB,CAAC,GAAG,aAAa,CAAC;IAC1D,OAAO,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC"}

package/dist/mcp/roles.d.ts

@@ -0,0 +1,7 @@
+export type Role = 'reader' | 'writer' | 'admin';
+export declare function getToolsForRole(role: Role): ReadonlySet<string>;
+export declare function parseRole(raw: string | undefined): Role;
+export declare function roleSatisfies(have: Role, need: Role): boolean;
+export declare function minRole(a: Role, b: Role): Role;
+export declare function getMinRoleForTool(toolName: string): Role | null;
+//# sourceMappingURL=roles.d.ts.map

package/dist/mcp/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/mcp/roles.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AA+BjD,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAE/D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGvD;AAKD,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAE7D;AAGD,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,CAE9C;AAID,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAK/D"}

package/dist/mcp/roles.js

@@ -0,0 +1,57 @@
+// ============================================================================
+// MCP Roles — role definitions and tool filtering
+// ============================================================================
+const READER_TOOLS = [
+    'maad_scan', 'maad_summary', 'maad_describe',
+    'maad_get', 'maad_query', 'maad_search', 'maad_related', 'maad_schema', 'maad_aggregate', 'maad_join',
+    'maad_verify', 'maad_find_orphans', 'maad_changes_since',
+    'maad_history', 'maad_audit',
+    'maad_subscribe', 'maad_unsubscribe',
+];
+const WRITER_TOOLS = [
+    ...READER_TOOLS,
+    'maad_create', 'maad_update', 'maad_validate', 'maad_bulk_create', 'maad_bulk_update',
+];
+const ADMIN_TOOLS = [
+    ...WRITER_TOOLS,
+    'maad_delete', 'maad_reindex', 'maad_reload', 'maad_health',
+    'maad_instance_reload',
+    'maad_subscriptions',
+    'maad_issue_token', 'maad_revoke_token', 'maad_rotate_token',
+    'maad_list_tokens', 'maad_show_token',
+    'maad_backup',
+];
+const ROLE_TOOLS = {
+    reader: READER_TOOLS,
+    writer: WRITER_TOOLS,
+    admin: ADMIN_TOOLS,
+};
+export function getToolsForRole(role) {
+    return new Set(ROLE_TOOLS[role]);
+}
+export function parseRole(raw) {
+    if (raw === 'reader' || raw === 'writer' || raw === 'admin')
+        return raw;
+    return 'reader'; // default: least privilege
+}
+const ROLE_RANK = { reader: 0, writer: 1, admin: 2 };
+// Returns true if `have` satisfies at least the level of `need`.
+export function roleSatisfies(have, need) {
+    return ROLE_RANK[have] >= ROLE_RANK[need];
+}
+// Returns the more restrictive of two roles.
+export function minRole(a, b) {
+    return ROLE_RANK[a] <= ROLE_RANK[b] ? a : b;
+}
+// Inverse of getToolsForRole: for a given tool name, what's the minimum role
+// that can call it? Returns null for unknown tools.
+export function getMinRoleForTool(toolName) {
+    if (READER_TOOLS.includes(toolName))
+        return 'reader';
+    if (WRITER_TOOLS.includes(toolName))
+        return 'writer';
+    if (ADMIN_TOOLS.includes(toolName))
+        return 'admin';
+    return null;
+}
+//# sourceMappingURL=roles.js.map

package/dist/mcp/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../src/mcp/roles.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kDAAkD;AAClD,+EAA+E;AAI/E,MAAM,YAAY,GAAG;IACnB,WAAW,EAAE,cAAc,EAAE,eAAe;IAC5C,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW;IACrG,aAAa,EAAE,mBAAmB,EAAE,oBAAoB;IACxD,cAAc,EAAE,YAAY;IAC5B,gBAAgB,EAAE,kBAAkB;CAC5B,CAAC;AAEX,MAAM,YAAY,GAAG;IACnB,GAAG,YAAY;IACf,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,kBAAkB;CAC7E,CAAC;AAEX,MAAM,WAAW,GAAG;IAClB,GAAG,YAAY;IACf,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa;IAC3D,sBAAsB;IACtB,oBAAoB;IACpB,kBAAkB,EAAE,mBAAmB,EAAE,mBAAmB;IAC5D,kBAAkB,EAAE,iBAAiB;IACrC,aAAa;CACL,CAAC;AAEX,MAAM,UAAU,GAAoC;IAClD,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,WAAW;CACnB,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,IAAU;IACxC,OAAO,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAuB;IAC/C,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,OAAO;QAAE,OAAO,GAAG,CAAC;IACxE,OAAO,QAAQ,CAAC,CAAC,2BAA2B;AAC9C,CAAC;AAED,MAAM,SAAS,GAAyB,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAE3E,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,IAAU,EAAE,IAAU;IAClD,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,OAAO,CAAC,CAAO,EAAE,CAAO;IACtC,OAAO,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,6EAA6E;AAC7E,oDAAoD;AACpD,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,IAAK,YAAkC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC5E,IAAK,YAAkC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC5E,IAAK,WAAiC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC"}