@maadb/core 0.0.1 → 0.7.10-rc.3

package/dist/mcp/memory-pressure.js

@@ -0,0 +1,179 @@
+// ============================================================================
+// Memory Pressure Watcher — periodic V8 heap-usage sampler.
+//
+// Samples process.memoryUsage().heapUsed against v8.getHeapStatistics()
+// heap_size_limit on an interval and emits a degraded-severity log event
+// when the ratio passes a configured threshold. Pure observability — never
+// mutates engine state, never throws, never blocks shutdown.
+//
+// Background: cgroup-capped deployments (e.g. 512 MiB container on Node 24)
+// trip V8's auto-calibrated old-space cap at ~253 MB heap_size_limit. Without
+// this surface, the only signal that a process is approaching the cap is
+// post-mortem (exitCode=134 with "Reached heap limit"). The watcher gives
+// operators a pre-OOM warning + a counter in maad_health.
+//
+// Disabled when intervalMs <= 0 (set MAAD_MEMORY_PRESSURE_INTERVAL_MS=0).
+// Cooldown prevents log spam under sustained pressure — one fire per
+// cooldown window while the ratio stays above threshold; the first sample
+// below threshold re-arms the edge trigger.
+// ============================================================================
+import v8 from 'node:v8';
+import { logger } from '../engine/logger.js';
+const DEFAULT_INTERVAL_MS = 60_000;
+const DEFAULT_THRESHOLD_RATIO = 0.8;
+const DEFAULT_COOLDOWN_MS = 5 * 60_000;
+const defaultSampler = () => {
+    const stats = v8.getHeapStatistics();
+    return {
+        heapUsedBytes: stats.used_heap_size,
+        heapCapBytes: stats.heap_size_limit,
+    };
+};
+const state = {
+    intervalMs: 0,
+    thresholdRatio: DEFAULT_THRESHOLD_RATIO,
+    cooldownMs: DEFAULT_COOLDOWN_MS,
+    sampler: defaultSampler,
+    now: () => Date.now(),
+    timer: null,
+    lastSampleAtMs: null,
+    heapUsedBytes: null,
+    heapCapBytes: null,
+    inPressure: false,
+    lastPressureAtMs: null,
+    lastFireAtMs: null,
+    pressureFiresTotal: 0,
+};
+export function readMemoryPressureEnv() {
+    const intervalMs = parseNumericEnv(process.env.MAAD_MEMORY_PRESSURE_INTERVAL_MS, DEFAULT_INTERVAL_MS);
+    const rawThreshold = parseNumericEnv(process.env.MAAD_MEMORY_PRESSURE_RATIO, DEFAULT_THRESHOLD_RATIO);
+    const cooldownMs = parseNumericEnv(process.env.MAAD_MEMORY_PRESSURE_COOLDOWN_MS, DEFAULT_COOLDOWN_MS);
+    const thresholdRatio = clamp(rawThreshold, 0, 1);
+    return { intervalMs, thresholdRatio, cooldownMs };
+}
+function parseNumericEnv(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+export function initMemoryPressureWatcher(opts) {
+    stopMemoryPressureWatcher();
+    state.intervalMs = opts.intervalMs;
+    state.thresholdRatio = clamp(opts.thresholdRatio, 0, 1);
+    state.cooldownMs = Math.max(0, opts.cooldownMs);
+    state.sampler = opts.sampler ?? defaultSampler;
+    state.now = opts.now ?? (() => Date.now());
+    state.lastSampleAtMs = null;
+    state.heapUsedBytes = null;
+    state.heapCapBytes = null;
+    state.inPressure = false;
+    state.lastPressureAtMs = null;
+    state.lastFireAtMs = null;
+    state.pressureFiresTotal = 0;
+    if (opts.intervalMs <= 0)
+        return;
+    const timer = setInterval(sampleOnce, opts.intervalMs);
+    timer.unref();
+    state.timer = timer;
+}
+export function stopMemoryPressureWatcher() {
+    if (state.timer) {
+        clearInterval(state.timer);
+        state.timer = null;
+    }
+}
+/**
+ * Run one sample. Public so tests and shutdown paths can probe without
+ * waiting for the interval to fire. Never throws.
+ */
+export function sampleOnce() {
+    let sample;
+    try {
+        sample = state.sampler();
+    }
+    catch {
+        return;
+    }
+    const nowMs = state.now();
+    state.lastSampleAtMs = nowMs;
+    state.heapUsedBytes = sample.heapUsedBytes;
+    state.heapCapBytes = sample.heapCapBytes;
+    if (sample.heapCapBytes <= 0)
+        return;
+    const ratio = sample.heapUsedBytes / sample.heapCapBytes;
+    if (ratio >= state.thresholdRatio) {
+        const cooldownPassed = state.lastFireAtMs === null
+            || (nowMs - state.lastFireAtMs) >= state.cooldownMs;
+        const edgeTrigger = !state.inPressure;
+        if (edgeTrigger || cooldownPassed) {
+            logger.degraded('engine', 'memory_pressure', `V8 heap at ${formatPct(ratio)}% of cap (${bytesToMb(sample.heapUsedBytes)}MB / ${bytesToMb(sample.heapCapBytes)}MB)`, {
+                heap_used_mb: bytesToMb(sample.heapUsedBytes),
+                heap_cap_mb: bytesToMb(sample.heapCapBytes),
+                ratio: round3(ratio),
+                threshold_ratio: state.thresholdRatio,
+                edge: edgeTrigger,
+            });
+            state.pressureFiresTotal++;
+            state.lastFireAtMs = nowMs;
+            state.lastPressureAtMs = nowMs;
+        }
+        state.inPressure = true;
+    }
+    else {
+        state.inPressure = false;
+    }
+}
+export function getMemoryPressureSnapshot() {
+    const heapUsed = state.heapUsedBytes;
+    const heapCap = state.heapCapBytes;
+    const ratio = heapUsed !== null && heapCap !== null && heapCap > 0
+        ? round3(heapUsed / heapCap) : null;
+    return {
+        enabled: state.intervalMs > 0,
+        intervalMs: state.intervalMs,
+        thresholdRatio: state.thresholdRatio,
+        lastSampleAt: state.lastSampleAtMs !== null ? new Date(state.lastSampleAtMs).toISOString() : null,
+        heapUsedMb: heapUsed !== null ? bytesToMb(heapUsed) : null,
+        heapCapMb: heapCap !== null ? bytesToMb(heapCap) : null,
+        ratio,
+        inPressure: state.inPressure,
+        lastPressureAt: state.lastPressureAtMs !== null ? new Date(state.lastPressureAtMs).toISOString() : null,
+        pressureFiresTotal: state.pressureFiresTotal,
+    };
+}
+/**
+ * Test hook — resets module state. Never call from production code.
+ */
+export function __resetMemoryPressureForTests() {
+    stopMemoryPressureWatcher();
+    state.intervalMs = 0;
+    state.thresholdRatio = DEFAULT_THRESHOLD_RATIO;
+    state.cooldownMs = DEFAULT_COOLDOWN_MS;
+    state.sampler = defaultSampler;
+    state.now = () => Date.now();
+    state.lastSampleAtMs = null;
+    state.heapUsedBytes = null;
+    state.heapCapBytes = null;
+    state.inPressure = false;
+    state.lastPressureAtMs = null;
+    state.lastFireAtMs = null;
+    state.pressureFiresTotal = 0;
+}
+function bytesToMb(b) {
+    return Math.round((b / 1024 / 1024) * 10) / 10;
+}
+function round3(n) {
+    return Math.round(n * 1000) / 1000;
+}
+function formatPct(ratio) {
+    return (ratio * 100).toFixed(1);
+}
+function clamp(n, lo, hi) {
+    if (n < lo)
+        return lo;
+    if (n > hi)
+        return hi;
+    return n;
+}
+//# sourceMappingURL=memory-pressure.js.map

package/dist/mcp/memory-pressure.js.map

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

package/dist/mcp/notifications.d.ts

@@ -0,0 +1,87 @@
+import type { InstanceCtx } from './ctx.js';
+/**
+ * Event shape emitted on durable writes. Used both as the payload mapped into
+ * MCP's `notifications/resources/updated` and as the match target for
+ * per-session filters.
+ */
+export interface ChangeEvent {
+    action: 'create' | 'update' | 'delete';
+    docId: string;
+    docType: string;
+    project: string;
+    updatedAt: string;
+}
+/**
+ * Callback that pushes a ChangeEvent to a single MCP session's client. The
+ * transport layer (HTTP or stdio) registers this closure when it builds the
+ * per-session McpServer. Failures are logged but never thrown — a broken
+ * notifier channel must not kill the write that triggered it.
+ */
+export type Notifier = (event: ChangeEvent) => Promise<void>;
+/**
+ * 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 declare function registerNotifier(sessionId: string, fn: Notifier): void;
+/**
+ * Remove a notifier. Called when a session is destroyed (SessionRegistry
+ * close handler fans this out). Safe to call with an unknown sessionId.
+ */
+export declare function unregisterNotifier(sessionId: string): void;
+/**
+ * Current count of registered notifiers. Used by maad_health telemetry and
+ * by zero-overhead fast-path detection in `notifyWrite`.
+ */
+export declare function notifierCount(): number;
+/**
+ * Test hook — drops every registered notifier. Production code never calls
+ * this; vitest suites that reuse the process need it between cases.
+ */
+export declare function __resetNotifiers(): void;
+/**
+ * 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 declare function notifyWrite(ctx: InstanceCtx, event: ChangeEvent): Promise<void>;
+/**
+ * 0.6.12 — Inventory of active subscriptions across an instance. Produced
+ * by `maad_subscriptions` (admin-only). Extracted here so the aggregation
+ * logic is unit-testable without spinning up a full MCP server.
+ *
+ * `byProject` reflects "who would receive an event for project X": single-mode
+ * sessions bin under their activeProject; multi-mode sessions without an
+ * explicit project filter bin under every whitelisted project; sessions with
+ * an explicit filter bin only under that project.
+ *
+ * `byDocType` uses `*` as the any-type bucket (subscribers that omitted the
+ * docTypes filter) so admins can tell at a glance how many "firehose" vs
+ * "type-narrowed" subscribers are active.
+ */
+export interface SubscriptionInventoryEntry {
+    sessionId: string;
+    mode: string | null;
+    activeProject: string | null;
+    whitelist: string[] | null;
+    subscription: {
+        docTypes: string[] | null;
+        project: string | null;
+        createdAt: string;
+    };
+    bindingSource: string | null;
+    lastActivityAt: string;
+}
+export interface SubscriptionInventory {
+    totalSubscriptions: number;
+    subscriptions: SubscriptionInventoryEntry[];
+    byProject: Record<string, number>;
+    byDocType: Record<string, number>;
+}
+export declare function collectSubscriptions(sessions: InstanceCtx['sessions']): SubscriptionInventory;
+//# sourceMappingURL=notifications.d.ts.map

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":"AAAA,+EAA+E;AAC/E,6CAA6C;AAC7C,EAAE;AACF,8EAA8E;AAC9E,sEAAsE;AACtE,yEAAyE;AACzE,4EAA4E;AAC5E,2EAA2E;AAC3E,sBAAsB;AACtB,EAAE;AACF,+DAA+D;AAC/D,4EAA4E;AAC5E,wEAAwE;AACxE,oCAAoC;AACpC,EAAE;AACF,wEAAwE;AACxE,6EAA6E;AAC7E,wEAAwE;AACxE,+EAA+E;AAI/E,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAuB7C,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;AAE9C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,EAAY;IAC9D,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,SAAS,CAAC,IAAI,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,KAAmB,EAAE,KAAkB;IAClE,MAAM,GAAG,GAAG,KAAK,CAAC,YAAY,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IAEvB,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAEjF,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;IAClD,CAAC;SAAM,CAAC;QACN,2DAA2D;QAC3D,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,aAAa,KAAK,KAAK,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QACnF,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;IAC/F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAgB,EAAE,KAAkB;IACpE,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,8BAA8B;IAEhE,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;QAC5C,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC;YAAE,SAAS;QACjD,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,CAAC,EAAE;YAAE,SAAS;QAClB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,8DAA8D;YAC9D,gEAAgE;YAChE,iEAAiE;YACjE,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,EACnC,+BAA+B,KAAK,CAAC,SAAS,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACrG,CAAC;IACH,CAAC;AACH,CAAC;AAiCD,MAAM,UAAU,oBAAoB,CAAC,QAAiC;IACpE,MAAM,aAAa,GAAiC,EAAE,CAAC;IACvD,MAAM,SAAS,GAA2B,EAAE,CAAC;IAC7C,MAAM,SAAS,GAA2B,EAAE,CAAC;IAE7C,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,YAAY;YAAE,SAAS;QAClC,aAAa,CAAC,IAAI,CAAC;YACjB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;YAC1C,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;YAClC,YAAY,EAAE;gBACZ,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC,QAAQ;gBACrC,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,OAAO;gBACnC,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,WAAW,EAAE;aACtD;YACD,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC,WAAW,EAAE;SACnD,CAAC,CAAC;QAEH,MAAM,eAAe,GAAG,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC;QACnD,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;YAC7B,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACrE,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YAC1D,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7E,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YACrD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBAChC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QAED,IAAI,KAAK,CAAC,YAAY,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YACzC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;gBAC5C,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,kBAAkB,EAAE,aAAa,CAAC,MAAM;QACxC,aAAa;QACb,SAAS;QACT,SAAS;KACV,CAAC;AACJ,CAAC"}

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