@maadb/core 0.0.1 → 0.7.9

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

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/mcp/notifications.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAI7D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,IAAI,CAEtE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAwBD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBrF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,0BAA0B,EAAE,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,CAAC,UAAU,CAAC,GAAG,qBAAqB,CA+C7F"}

package/dist/mcp/notifications.js

@@ -0,0 +1,154 @@
+// ============================================================================
+// Live notifications — 0.6.11 (fup-2026-035)
+//
+// Per-session notifier registry + filtered fan-out for `maad_subscribe`. Each
+// connected MCP session registers one notifier closure that wraps its
+// McpServer's `sendResourceUpdated`. On a durable write (CommitOutcome =
+// 'committed'), the MCP tool handler calls `notifyWrite(ctx, event)`, which
+// walks every session with an active subscription, matches the filter, and
+// fires the notifier.
+//
+// Durability gate: the write-tool handler skips this call when
+// `writeDurable === false` or the underlying commit was a noop. Subscribers
+// never see events for non-durable or no-op writes — the whole point of
+// shipping 0.6.10 durability first.
+//
+// Zero-overhead path: `notifyWrite` early-returns when no session has a
+// subscription. Cheap Map iteration with a single boolean check per session.
+// Sessions without subscriptions pay nothing for the notification path.
+// ============================================================================
+import { logger } from '../engine/logger.js';
+const notifiers = new Map();
+/**
+ * Register a notifier for a session. Called by the transport once the
+ * per-session McpServer is connected and ready to emit. Overwrites any
+ * prior registration for the same sessionId (transport reconnect path).
+ */
+export function registerNotifier(sessionId, fn) {
+    notifiers.set(sessionId, fn);
+}
+/**
+ * Remove a notifier. Called when a session is destroyed (SessionRegistry
+ * close handler fans this out). Safe to call with an unknown sessionId.
+ */
+export function unregisterNotifier(sessionId) {
+    notifiers.delete(sessionId);
+}
+/**
+ * Current count of registered notifiers. Used by maad_health telemetry and
+ * by zero-overhead fast-path detection in `notifyWrite`.
+ */
+export function notifierCount() {
+    return notifiers.size;
+}
+/**
+ * Test hook — drops every registered notifier. Production code never calls
+ * this; vitest suites that reuse the process need it between cases.
+ */
+export function __resetNotifiers() {
+    notifiers.clear();
+}
+/**
+ * Does this session's subscription filter match the event? Null filter
+ * fields mean "accept any." In single-mode sessions, if the subscription's
+ * `project` is null, it implicitly matches the session's activeProject.
+ * In multi-mode, null matches any project in the whitelist.
+ */
+function matchesSubscription(state, event) {
+    const sub = state.subscription;
+    if (!sub)
+        return false;
+    if (sub.docTypes !== null && !sub.docTypes.includes(event.docType))
+        return false;
+    if (sub.project !== null) {
+        if (sub.project !== event.project)
+            return false;
+    }
+    else {
+        // Null project: match the session's visible project scope.
+        if (state.mode === 'single' && state.activeProject !== event.project)
+            return false;
+        if (state.mode === 'multi' && !(state.whitelist ?? []).includes(event.project))
+            return false;
+    }
+    return true;
+}
+/**
+ * Fan-out entry point called by MCP write tool handlers after a successful
+ * durable commit. Iterates sessions with subscriptions, matches the filter,
+ * and invokes each session's notifier. Zero overhead when no session has a
+ * subscription (the count check bypasses the iteration).
+ *
+ * Caller MUST only invoke this when `writeDurable === true` on the engine
+ * result — the durability gate is upstream, not here. Delete operations
+ * should pass `action: 'delete'` and the docType recorded before deletion.
+ */
+export async function notifyWrite(ctx, event) {
+    if (notifiers.size === 0)
+        return; // fast path: nobody listening
+    for (const state of ctx.sessions.snapshot()) {
+        if (!matchesSubscription(state, event))
+            continue;
+        const fn = notifiers.get(state.sessionId);
+        if (!fn)
+            continue;
+        try {
+            await fn(event);
+        }
+        catch (e) {
+            // Notifier delivery failure is non-fatal to the write. Log so
+            // operators can spot broken transports (disconnected SSE, stale
+            // McpServer) — but never propagate the error back to the writer.
+            logger.bestEffort('notify', 'deliver', `Notifier failed for session ${state.sessionId}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+}
+export function collectSubscriptions(sessions) {
+    const subscriptions = [];
+    const byProject = {};
+    const byDocType = {};
+    for (const state of sessions.snapshot()) {
+        if (!state.subscription)
+            continue;
+        subscriptions.push({
+            sessionId: state.sessionId,
+            mode: state.mode,
+            activeProject: state.activeProject ?? null,
+            whitelist: state.whitelist ?? null,
+            subscription: {
+                docTypes: state.subscription.docTypes,
+                project: state.subscription.project,
+                createdAt: state.subscription.createdAt.toISOString(),
+            },
+            bindingSource: state.bindingSource,
+            lastActivityAt: state.lastActivityAt.toISOString(),
+        });
+        const explicitProject = state.subscription.project;
+        if (explicitProject !== null) {
+            byProject[explicitProject] = (byProject[explicitProject] ?? 0) + 1;
+        }
+        else if (state.mode === 'single' && state.activeProject) {
+            byProject[state.activeProject] = (byProject[state.activeProject] ?? 0) + 1;
+        }
+        else if (state.mode === 'multi' && state.whitelist) {
+            for (const p of state.whitelist) {
+                byProject[p] = (byProject[p] ?? 0) + 1;
+            }
+        }
+        if (state.subscription.docTypes === null) {
+            byDocType['*'] = (byDocType['*'] ?? 0) + 1;
+        }
+        else {
+            for (const t of state.subscription.docTypes) {
+                byDocType[t] = (byDocType[t] ?? 0) + 1;
+            }
+        }
+    }
+    return {
+        totalSubscriptions: subscriptions.length,
+        subscriptions,
+        byProject,
+        byDocType,
+    };
+}
+//# sourceMappingURL=notifications.js.map

package/dist/mcp/notifications.js.map

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

package/dist/mcp/query-depth.d.ts

@@ -0,0 +1,28 @@
+import type { DocId } from '../types.js';
+import type { DocumentMatch } from '../types.js';
+import type { GetResult, GetFullResult } from '../engine/types.js';
+import type { Result } from '../errors.js';
+export type QueryDepth = 'hot' | 'cold' | 'full';
+export interface HydrationEngine {
+    getDocument(id: DocId, depth: 'cold'): Promise<Result<GetResult>>;
+    getDocumentFull(id: DocId): Promise<Result<GetFullResult>>;
+}
+export interface HydrationOptions {
+    depth: QueryDepth;
+    depthMaxResults?: number;
+}
+export interface HydratedRow extends DocumentMatch {
+    body?: string;
+    composite?: GetFullResult;
+    _hydrationError?: string;
+}
+export interface HydrationOutcome {
+    rows: HydratedRow[];
+    meta: {
+        depth: QueryDepth;
+        hydrated: number;
+        capped?: boolean;
+    } | null;
+}
+export declare function hydrateQueryRows(engine: HydrationEngine, rows: DocumentMatch[], opts: HydrationOptions): Promise<HydrationOutcome>;
+//# sourceMappingURL=query-depth.d.ts.map

package/dist/mcp/query-depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-depth.d.ts","sourceRoot":"","sources":["../../src/mcp/query-depth.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAClE,eAAe,CAAC,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,UAAU,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,IAAI,EAAE;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACxE;AAKD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,aAAa,EAAE,EACrB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,gBAAgB,CAAC,CA0B3B"}

package/dist/mcp/query-depth.js

@@ -0,0 +1,43 @@
+// ============================================================================
+// 0.7.3 (fup-2026-079[a]) — maad_query depth hydration helper.
+//
+// Composite that kills the query-then-N-gets agent pattern. After the engine
+// finds matching pointer rows, the handler optionally hydrates each row with
+// body content (depth=cold) or full composite (depth=full).
+//
+// Sequential per-row to keep memory bounded and to mirror per-doc error
+// surfaces; one failure does not abort the batch — failed rows omit
+// body/composite and stamp `_hydrationError` so callers see the partial.
+//
+// Hard cap on hydration count (default 50, max 100) keeps response payloads
+// from blowing past the response-size guard. Beyond cap, remaining rows
+// return at hot depth.
+// ============================================================================
+const HARD_CAP = 100;
+const DEFAULT_CAP = 50;
+export async function hydrateQueryRows(engine, rows, opts) {
+    if (opts.depth === 'hot') {
+        return { rows, meta: null };
+    }
+    const requested = opts.depthMaxResults ?? DEFAULT_CAP;
+    const cap = Math.min(Math.max(1, requested), HARD_CAP);
+    const toHydrate = Math.min(rows.length, cap);
+    const hydrated = await Promise.all(rows.slice(0, toHydrate).map(async (row) => {
+        if (opts.depth === 'cold') {
+            const r = await engine.getDocument(row.docId, 'cold');
+            if (r.ok)
+                return { ...row, body: r.value.body ?? '' };
+            return { ...row, _hydrationError: r.errors[0]?.code ?? 'UNKNOWN' };
+        }
+        const r = await engine.getDocumentFull(row.docId);
+        if (r.ok)
+            return { ...row, composite: r.value };
+        return { ...row, _hydrationError: r.errors[0]?.code ?? 'UNKNOWN' };
+    }));
+    const merged = [...hydrated, ...rows.slice(toHydrate)];
+    const meta = { depth: opts.depth, hydrated: toHydrate };
+    if (rows.length > cap)
+        meta.capped = true;
+    return { rows: merged, meta };
+}
+//# sourceMappingURL=query-depth.js.map

package/dist/mcp/query-depth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-depth.js","sourceRoot":"","sources":["../../src/mcp/query-depth.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+DAA+D;AAC/D,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,4DAA4D;AAC5D,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,yEAAyE;AACzE,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,uBAAuB;AACvB,+EAA+E;AA8B/E,MAAM,QAAQ,GAAG,GAAG,CAAC;AACrB,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAuB,EACvB,IAAqB,EACrB,IAAsB;IAEtB,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,IAAI,WAAW,CAAC;IACtD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE7C,MAAM,QAAQ,GAAkB,MAAM,OAAO,CAAC,GAAG,CAC/C,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAwB,EAAE;QAC/D,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACtD,IAAI,CAAC,CAAC,EAAE;gBAAE,OAAO,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;YACtD,OAAO,EAAE,GAAG,GAAG,EAAE,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,SAAS,EAAE,CAAC;QACrE,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,CAAC,CAAC,EAAE;YAAE,OAAO,EAAE,GAAG,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;QAChD,OAAO,EAAE,GAAG,GAAG,EAAE,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,SAAS,EAAE,CAAC;IACrE,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,MAAM,GAAkB,CAAC,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IACtE,MAAM,IAAI,GAA6B,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IAClF,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG;QAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAChC,CAAC"}

package/dist/mcp/rate-limit.d.ts

@@ -0,0 +1,60 @@
+export interface RateLimitConfig {
+    writesPerSec: number;
+    writesPerMin: number;
+    concurrent: number;
+    payloadBytes: number;
+    disabled: boolean;
+    now: () => number;
+}
+export declare function readRateLimitEnv(): Partial<RateLimitConfig>;
+export type RateLimitReason = 'writes_per_sec' | 'writes_per_min' | 'concurrent' | 'payload_too_large';
+export interface RateLimitRejection {
+    reason: RateLimitReason;
+    limit: number;
+    retryAfterMs: number | null;
+}
+export declare function isMutatingTool(toolName: string): boolean;
+export declare class SessionRateLimiter {
+    private config;
+    private writesSec;
+    private writesMin;
+    private inFlight;
+    constructor(opts?: Partial<RateLimitConfig>);
+    /**
+     * 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: number): RateLimitRejection | 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: string): {
+        ok: true;
+        release: () => void;
+    } | {
+        ok: false;
+        rejection: RateLimitRejection;
+    };
+    /**
+     * 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: string): RateLimitRejection | null;
+    /**
+     * Total in-flight requests across all sessions. Used by the H7 graceful
+     * shutdown drain loop.
+     */
+    totalInFlight(): number;
+    /** Discard all per-session state for `sessionId`. Called on disconnect. */
+    disposeSession(sessionId: string): void;
+    /** Test helper — peek at in-flight count for a single session. */
+    inFlightFor(sessionId: string): number;
+    /** Test helper — peek at current config (for assertions). */
+    getConfig(): Readonly<RateLimitConfig>;
+}
+export declare function initRateLimiter(opts: Partial<RateLimitConfig>): void;
+export declare function getRateLimiter(): SessionRateLimiter;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/mcp/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/mcp/rate-limit.ts"],"names":[],"mappings":"AA+CA,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAUD,wBAAgB,gBAAgB,IAAI,OAAO,CAAC,eAAe,CAAC,CAU3D;AAID,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAEvG,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAeD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD;AAID,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,QAAQ,CAA6B;gBAEjC,IAAI,GAAE,OAAO,CAAC,eAAe,CAAM;IAQ/C;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAU1D;;;OAGG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,kBAAkB,CAAA;KAAE;IAqBzH;;;;OAIG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAsC7D;;;OAGG;IACH,aAAa,IAAI,MAAM;IAMvB,2EAA2E;IAC3E,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAMvC,kEAAkE;IAClE,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAItC,6DAA6D;IAC7D,SAAS,IAAI,QAAQ,CAAC,eAAe,CAAC;CAGvC;AAMD,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAEpE;AAED,wBAAgB,cAAc,IAAI,kBAAkB,CAEnD"}

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"}