@maadb/core 0.0.1 → 0.7.9

package/dist/mcp/shutdown.d.ts

@@ -0,0 +1,32 @@
+import type { EnginePool } from '../instance/pool.js';
+import type { SessionRateLimiter } from './rate-limit.js';
+export type ShutdownState = 'running' | 'draining' | 'exiting';
+export interface DrainTarget {
+    pool: EnginePool;
+    rateLimiter: SessionRateLimiter;
+}
+export interface ShutdownOptions {
+    shutdownTimeoutMs?: number;
+    exit?: (code: number) => void;
+    installHandlers?: boolean;
+    finalCleanup?: () => Promise<void>;
+}
+export declare function getShutdownState(): ShutdownState;
+export declare function isShuttingDown(): boolean;
+/**
+ * Test hook — resets module state. NEVER call from production code.
+ */
+export declare function __resetShutdownState(): void;
+/**
+ * Begin shutdown. First call flips state to 'draining' and starts the drain
+ * loop. Second call short-circuits the wait and accelerates to exiting.
+ * Third+ calls are ignored.
+ */
+export declare function beginShutdown(target: DrainTarget, opts?: ShutdownOptions): Promise<void>;
+/**
+ * Install SIGTERM / SIGINT handlers that call beginShutdown on first hit and
+ * accelerate on the second. Call once from server startup. Tests bypass this
+ * by installing their own handlers or calling beginShutdown directly.
+ */
+export declare function installSignalHandlers(target: DrainTarget, opts?: ShutdownOptions): void;
+//# sourceMappingURL=shutdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/mcp/shutdown.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG1D,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAG3B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9B,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AASD,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CA6Ef;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE,eAAoB,GAAG,IAAI,CAQ3F"}

package/dist/mcp/shutdown.js

@@ -0,0 +1,130 @@
+// ============================================================================
+// Shutdown state machine — running → draining → exiting.
+//
+// SIGTERM / SIGINT trigger DRAINING. New tool calls are rejected at the
+// `withEngine` entry with SHUTTING_DOWN. In-flight writes are given a bounded
+// window to complete (MAAD_SHUTDOWN_TIMEOUT_MS, default 10s). After drain or
+// timeout, EXITING closes engines, flushes audit, and process.exit(code).
+//
+// Second signal during DRAINING skips the wait and force-exits.
+//
+// Cooperative cancellation *inside* engine methods (AbortSignal threaded
+// through stage boundaries) is deferred to 0.8.5 and documented in gaps.md.
+// For 0.4.1: requests already executing run to completion; the drain waits
+// for them; clients see either their response or REQUEST_TIMEOUT if the
+// per-request ceiling was first.
+// ============================================================================
+import { getOpsLog } from '../logging.js';
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+const DRAIN_POLL_MS = 50;
+let state = 'running';
+let shutdownStartedAt = null;
+let shutdownPromise = null;
+export function getShutdownState() {
+    return state;
+}
+export function isShuttingDown() {
+    return state !== 'running';
+}
+/**
+ * Test hook — resets module state. NEVER call from production code.
+ */
+export function __resetShutdownState() {
+    state = 'running';
+    shutdownStartedAt = null;
+    shutdownPromise = null;
+}
+/**
+ * Begin shutdown. First call flips state to 'draining' and starts the drain
+ * loop. Second call short-circuits the wait and accelerates to exiting.
+ * Third+ calls are ignored.
+ */
+export function beginShutdown(target, opts = {}) {
+    const log = getOpsLog();
+    if (state === 'exiting') {
+        // Already on the way out — nothing to do.
+        return shutdownPromise ?? Promise.resolve();
+    }
+    if (state === 'draining') {
+        // Second signal: accelerate.
+        log.warn({ event: 'shutdown_forced' }, 'shutdown_forced');
+        state = 'exiting';
+        // The existing shutdownPromise will observe the state change and finalize.
+        return shutdownPromise ?? Promise.resolve();
+    }
+    // First signal: start draining.
+    state = 'draining';
+    shutdownStartedAt = Date.now();
+    log.info({ event: 'shutdown_start' }, 'shutdown_start');
+    const exitFn = opts.exit ?? ((code) => process.exit(code));
+    const timeoutMs = opts.shutdownTimeoutMs ?? Number(process.env.MAAD_SHUTDOWN_TIMEOUT_MS ?? DEFAULT_SHUTDOWN_TIMEOUT_MS);
+    shutdownPromise = (async () => {
+        let drainTimedOut = false;
+        const deadline = Date.now() + timeoutMs;
+        // Drain loop: wait until no writes are queued AND no requests are in flight
+        // OR the grace window expires, OR a second signal accelerates.
+        while (true) {
+            const queueDepth = target.pool.totalWriteQueueDepth();
+            const inFlight = target.rateLimiter.totalInFlight();
+            if (queueDepth === 0 && inFlight === 0)
+                break;
+            if (state === 'exiting')
+                break; // accelerated by a second signal
+            if (Date.now() >= deadline) {
+                drainTimedOut = true;
+                log.warn({
+                    event: 'shutdown_timeout',
+                    queue_depth: queueDepth,
+                    in_flight: inFlight,
+                    elapsed_ms: Date.now() - (shutdownStartedAt ?? Date.now()),
+                }, 'shutdown_timeout');
+                break;
+            }
+            await sleep(DRAIN_POLL_MS);
+        }
+        state = 'exiting';
+        // EXITING: final cleanup.
+        try {
+            await target.pool.closeAll();
+        }
+        catch {
+            // best-effort
+        }
+        if (opts.finalCleanup) {
+            try {
+                await opts.finalCleanup();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        const elapsedMs = Date.now() - (shutdownStartedAt ?? Date.now());
+        log.info({
+            event: 'shutdown_complete',
+            elapsed_ms: elapsedMs,
+            drain_timed_out: drainTimedOut,
+        }, 'shutdown_complete');
+        // Exit code 1 on timed-out drain; 0 on clean drain. Surfaces to operators
+        // monitoring container exit codes.
+        exitFn(drainTimedOut ? 1 : 0);
+    })();
+    return shutdownPromise;
+}
+/**
+ * Install SIGTERM / SIGINT handlers that call beginShutdown on first hit and
+ * accelerate on the second. Call once from server startup. Tests bypass this
+ * by installing their own handlers or calling beginShutdown directly.
+ */
+export function installSignalHandlers(target, opts = {}) {
+    const onSignal = (sig) => {
+        const log = getOpsLog();
+        log.info({ event: 'signal_received', signal: sig }, 'signal_received');
+        void beginShutdown(target, opts);
+    };
+    process.on('SIGTERM', () => onSignal('SIGTERM'));
+    process.on('SIGINT', () => onSignal('SIGINT'));
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=shutdown.js.map

package/dist/mcp/shutdown.js.map

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

package/dist/mcp/tools/audit.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { InstanceCtx } from '../ctx.js';
+export declare function register(server: McpServer, ctx: InstanceCtx): number;
+//# sourceMappingURL=audit.d.ts.map

package/dist/mcp/tools/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/audit.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAiCpE"}

package/dist/mcp/tools/audit.js

@@ -0,0 +1,45 @@
+// ============================================================================
+// Audit tools — maad_history, maad_audit
+// ============================================================================
+import { z } from 'zod';
+import { docId, docType } from '../../types.js';
+import { resultToResponse } from '../response.js';
+import { withEngine } from '../with-session.js';
+export function register(server, ctx) {
+    server.registerTool('maad_history', {
+        description: 'Returns git commit history for a specific document.',
+        inputSchema: z.object({
+            docId: z.string().describe('Document ID'),
+            limit: z.number().optional().describe('Max commits to return'),
+            since: z.string().optional().describe('Only commits since this date (ISO or git date format)'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_history', args, async ({ engine }) => {
+        const opts = {};
+        if (args.limit !== undefined)
+            opts.limit = args.limit;
+        if (args.since !== undefined)
+            opts.since = args.since;
+        return resultToResponse(await engine.history(docId(args.docId), opts));
+    }));
+    server.registerTool('maad_audit', {
+        description: 'Returns project-wide activity log from git. Shows most recent action per document.',
+        inputSchema: z.object({
+            since: z.string().optional().describe('Activity since date'),
+            until: z.string().optional().describe('Activity until date'),
+            docType: z.string().optional().describe('Filter by document type'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_audit', args, async ({ engine }) => {
+        const opts = {};
+        if (args.since !== undefined)
+            opts.since = args.since;
+        if (args.until !== undefined)
+            opts.until = args.until;
+        if (args.docType !== undefined)
+            opts.docType = docType(args.docType);
+        return resultToResponse(await engine.audit(opts));
+    }));
+    return 2;
+}
+//# sourceMappingURL=audit.js.map

package/dist/mcp/tools/audit.js.map

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

package/dist/mcp/tools/auth.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { InstanceCtx } from '../ctx.js';
+export declare function register(server: McpServer, ctx: InstanceCtx): number;
+//# sourceMappingURL=auth.d.ts.map

package/dist/mcp/tools/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/auth.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AA4C7C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CA0HpE"}

package/dist/mcp/tools/auth.js

@@ -0,0 +1,181 @@
+// ============================================================================
+// Admin MCP auth tools — 0.7.0 Scoped Auth & Identity (P3c)
+//
+//   maad_issue_token    — issue a new token; returns plaintext ONCE + record
+//   maad_revoke_token   — mark a token revoked; returns record
+//   maad_rotate_token   — revoke + reissue with preserved caps; returns plaintext + record
+//   maad_list_tokens    — list registry entries (no hash)
+//   maad_show_token     — fetch one record by id (no hash)
+//
+// All admin-only and engine-less (same pattern as maad_instance_reload and
+// maad_subscriptions). Refuse if the instance has no token registry (stdio
+// / synthetic). Role gate: admin on every project in the session binding.
+// ============================================================================
+import { z } from 'zod';
+import { successResponse, errorResponse } from '../response.js';
+import { resolveSessionId } from '../../instance/session.js';
+import { roleSatisfies } from '../roles.js';
+import { maadError } from '../../errors.js';
+import { tokenId as toTokenId } from '../../auth/types.js';
+const ROLE_ENUM = z.enum(['reader', 'writer', 'admin']);
+/**
+ * Inline admin role check — same pattern as maad_instance_reload. Engine-less
+ * tools bypass withEngine's role gate, so we enforce here. Requires admin
+ * effective role on EVERY project in the session's binding (least privilege,
+ * since token ops affect the instance-wide registry).
+ */
+function requireAdminEverywhere(ctx, sessionId) {
+    const state = ctx.sessions.get(sessionId);
+    if (!state || state.mode === null) {
+        return errorResponse([maadError('SESSION_UNBOUND', 'Session is not bound. Call maad_use_project(s) before admin auth tools.')]);
+    }
+    for (const [projectName, role] of state.effectiveRoles) {
+        if (!roleSatisfies(role, 'admin')) {
+            return errorResponse([maadError('INSUFFICIENT_ROLE', `admin auth tools require admin on every project in the session binding; session has "${role}" on "${projectName}".`)]);
+        }
+    }
+    return null;
+}
+function requireTokenStore(ctx) {
+    if (ctx.tokens === null) {
+        return errorResponse([maadError('TOKENS_FILE_MISSING', 'Token registry is not available — this MCP instance runs in stdio/synthetic mode with no tokens.yaml. Admin auth tools require --instance with a file-mode registry.')]);
+    }
+    return null;
+}
+/** Scrub `hash` from a record before returning to clients — they never need it. */
+function sanitize(record) {
+    const { hash, ...rest } = record;
+    void hash;
+    return rest;
+}
+export function register(server, ctx) {
+    server.registerTool('maad_issue_token', {
+        description: 'Issue a new auth token. Returns plaintext ONCE plus record metadata — plaintext is never recoverable after. Admin on every bound project required.',
+        inputSchema: z.object({
+            role: ROLE_ENUM.describe('Token\'s global role (capped by per-project overrides and instance project ceiling)'),
+            projects: z.array(z.object({
+                name: z.string().describe('Project name or "*" wildcard'),
+                role: ROLE_ENUM.optional().describe('Optional per-project role downgrade (never exceeds global)'),
+            })).describe('Allowlist. Wildcard `*` matches every project at the token\'s global role.'),
+            name: z.string().optional().describe('Human label (e.g. "brain-app-gateway")'),
+            agentId: z.string().optional().describe('Ref -> agent for identity attribution'),
+            userId: z.string().optional().describe('Ref -> user when token represents a human'),
+            expiresAt: z.string().optional().describe('ISO 8601 expiry timestamp'),
+        }),
+    }, async (args, extra) => {
+        const storeErr = requireTokenStore(ctx);
+        if (storeErr)
+            return storeErr;
+        const sid = resolveSessionId(extra);
+        const roleErr = requireAdminEverywhere(ctx, sid);
+        if (roleErr)
+            return roleErr;
+        const spec = {
+            role: args.role,
+            projects: args.projects.map(p => {
+                const cap = { name: p.name };
+                if (p.role !== undefined)
+                    cap.role = p.role;
+                return cap;
+            }),
+        };
+        if (args.name !== undefined)
+            spec.name = args.name;
+        if (args.agentId !== undefined)
+            spec.agentId = args.agentId;
+        if (args.userId !== undefined)
+            spec.userId = args.userId;
+        if (args.expiresAt !== undefined)
+            spec.expiresAt = args.expiresAt;
+        const result = await ctx.tokens.issue(spec);
+        if (!result.ok)
+            return errorResponse(result.errors);
+        return successResponse({
+            plaintext: result.value.plaintext,
+            record: sanitize(result.value.record),
+            warning: 'Store the plaintext now — it will not be returned again.',
+        }, 'maad_issue_token');
+    });
+    server.registerTool('maad_revoke_token', {
+        description: 'Revoke a token by its id. Idempotent. Admin on every bound project required.',
+        inputSchema: z.object({
+            id: z.string().describe('Token id (tok-xxx)'),
+        }),
+    }, async (args, extra) => {
+        const storeErr = requireTokenStore(ctx);
+        if (storeErr)
+            return storeErr;
+        const sid = resolveSessionId(extra);
+        const roleErr = requireAdminEverywhere(ctx, sid);
+        if (roleErr)
+            return roleErr;
+        const result = await ctx.tokens.revoke(toTokenId(args.id));
+        if (!result.ok)
+            return errorResponse(result.errors);
+        return successResponse({ record: sanitize(result.value) }, 'maad_revoke_token');
+    });
+    server.registerTool('maad_rotate_token', {
+        description: 'Revoke an existing token and issue a new one with the same capabilities. Returns new plaintext ONCE. Admin on every bound project required.',
+        inputSchema: z.object({
+            id: z.string().describe('Token id to rotate (tok-xxx)'),
+        }),
+    }, async (args, extra) => {
+        const storeErr = requireTokenStore(ctx);
+        if (storeErr)
+            return storeErr;
+        const sid = resolveSessionId(extra);
+        const roleErr = requireAdminEverywhere(ctx, sid);
+        if (roleErr)
+            return roleErr;
+        const result = await ctx.tokens.rotate(toTokenId(args.id));
+        if (!result.ok)
+            return errorResponse(result.errors);
+        return successResponse({
+            plaintext: result.value.plaintext,
+            record: sanitize(result.value.record),
+            warning: 'Store the new plaintext now — old token revoked, new plaintext will not be returned again.',
+        }, 'maad_rotate_token');
+    });
+    server.registerTool('maad_list_tokens', {
+        description: 'List all tokens in the registry. Active tokens by default; pass includeRevoked:true for full history. Admin on every bound project required.',
+        inputSchema: z.object({
+            includeRevoked: z.boolean().optional().describe('Include revoked tokens in the response'),
+        }),
+    }, async (args, extra) => {
+        const storeErr = requireTokenStore(ctx);
+        if (storeErr)
+            return storeErr;
+        const sid = resolveSessionId(extra);
+        const roleErr = requireAdminEverywhere(ctx, sid);
+        if (roleErr)
+            return roleErr;
+        const all = ctx.tokens.list();
+        const filtered = args.includeRevoked === true ? all : all.filter(r => r.revokedAt === undefined);
+        return successResponse({
+            tokens: filtered.map(sanitize),
+            total: filtered.length,
+            activeCount: ctx.tokens.activeCount(),
+        }, 'maad_list_tokens');
+    });
+    server.registerTool('maad_show_token', {
+        description: 'Fetch a single token record by id. Hash is never returned. Admin on every bound project required.',
+        inputSchema: z.object({
+            id: z.string().describe('Token id (tok-xxx)'),
+        }),
+    }, async (args, extra) => {
+        const storeErr = requireTokenStore(ctx);
+        if (storeErr)
+            return storeErr;
+        const sid = resolveSessionId(extra);
+        const roleErr = requireAdminEverywhere(ctx, sid);
+        if (roleErr)
+            return roleErr;
+        const record = ctx.tokens.lookupById(toTokenId(args.id));
+        if (!record) {
+            return errorResponse([maadError('TOKEN_NOT_FOUND', `No token with id ${args.id}`)]);
+        }
+        return successResponse({ record: sanitize(record) }, 'maad_show_token');
+    });
+    return 5;
+}
+//# sourceMappingURL=auth.js.map

package/dist/mcp/tools/auth.js.map

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

package/dist/mcp/tools/discover.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { InstanceCtx } from '../ctx.js';
+export declare function register(server: McpServer, ctx: InstanceCtx): number;
+//# sourceMappingURL=discover.d.ts.map

package/dist/mcp/tools/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/discover.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CA8EpE"}

package/dist/mcp/tools/discover.js

@@ -0,0 +1,83 @@
+// ============================================================================
+// Discover tools — maad_scan, maad_summary, maad_describe
+// ============================================================================
+import { z } from 'zod';
+import path from 'node:path';
+import { scanFile, scanDirectory } from '../../scanner.js';
+import { successResponse, errorResponse, getProvenanceMode } from '../response.js';
+import { isContainedIn } from '../../engine/pathguard.js';
+import { withEngine } from '../with-session.js';
+export function register(server, ctx) {
+    server.registerTool('maad_scan', {
+        description: 'Analyze raw markdown structure. Works without registry. Use for onboarding new files. Pass a file path for detailed analysis or a directory for corpus-level patterns.',
+        inputSchema: z.object({
+            path: z.string().describe('File or directory path to scan (relative to project root)'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_scan', args, async ({ projectRoot }) => {
+        const absTarget = path.resolve(projectRoot, args.path);
+        if (!isContainedIn(absTarget, projectRoot)) {
+            return errorResponse([{ code: 'PATH_OUTSIDE_PROJECT', message: `Scan path must be within the project root: ${args.path}` }]);
+        }
+        const { statSync } = await import('node:fs');
+        let stat;
+        try {
+            stat = statSync(absTarget);
+        }
+        catch {
+            return errorResponse([{ code: 'PATH_NOT_FOUND', message: `Not found: ${args.path}` }]);
+        }
+        if (stat.isFile()) {
+            return successResponse(await scanFile(absTarget));
+        }
+        else {
+            return successResponse(await scanDirectory(absTarget));
+        }
+    }));
+    server.registerTool('maad_summary', {
+        description: 'Lean project snapshot for session bootstrapping. Returns types, counts, sample IDs, totals, warnings. Call maad_describe for subtype inventory detail.',
+        inputSchema: z.object({
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_summary', args, ({ engine }) => {
+        const summary = engine.summary();
+        const provMode = getProvenanceMode();
+        if (provMode === 'off') {
+            return successResponse(summary, 'maad_summary');
+        }
+        const provenanceInstructions = provMode === 'detail'
+            ? {
+                mode: 'detail',
+                instructions: [
+                    'Tag every data value in your responses with its source:',
+                    '[T:<tool_name>] = from a specific MAAD tool (e.g. [T:maad_get])',
+                    '[R] = from memory/recall (unverified)',
+                    '[R*] = inferred/derived — not directly stated in any source',
+                    'When mixing sources in a table, add a source column.',
+                    'If joins require N+1 calls and you skip them, disclose which values were recalled.',
+                    'Never present recalled data with the same confidence as tool-verified data.',
+                ],
+            }
+            : {
+                mode: 'on',
+                instructions: [
+                    'Tag data sources in responses:',
+                    '[T] = from a MAAD tool call (verified)',
+                    '[R] = from memory/recall (unverified)',
+                    'When mixing sources in a table, add a source column or footnote.',
+                    'Never present recalled data with the same confidence as tool-verified data.',
+                ],
+            };
+        return successResponse({ ...summary, provenance: provenanceInstructions }, 'maad_summary');
+    }));
+    server.registerTool('maad_describe', {
+        description: 'Returns registry types, extraction primitives, document counts, and subtype inventory (deep detail; maad_summary is the lean orientation call).',
+        inputSchema: z.object({
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_describe', args, ({ engine }) => {
+        return successResponse(engine.describe());
+    }));
+    return 3;
+}
+//# sourceMappingURL=discover.js.map

package/dist/mcp/tools/discover.js.map

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

package/dist/mcp/tools/instance.d.ts

@@ -0,0 +1,15 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { InstanceCtx } from '../ctx.js';
+export declare function register(server: McpServer, ctx: InstanceCtx): number;
+/**
+ * Registers the admin-only `maad_instance_reload` tool separately from the
+ * base instance tools. Called regardless of instance source so synthetic
+ * instances can surface a clear INSTANCE_RELOAD_SYNTHETIC error rather than
+ * an opaque "unknown tool" response.
+ *
+ * Role gate lives inside the handler (engine-less tools bypass the `withEngine`
+ * role check). Requires admin effective role on EVERY project in the session's
+ * binding — least privilege, since reload is instance-wide.
+ */
+export declare function registerReload(server: McpServer, ctx: InstanceCtx): number;
+//# sourceMappingURL=instance.d.ts.map

package/dist/mcp/tools/instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/instance.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAQ7C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CA2IpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CA6D1E"}