@maadb/core 0.0.1 → 0.7.9

package/dist/mcp/tools/instance.js

@@ -0,0 +1,207 @@
+// ============================================================================
+// Instance tools — maad_projects, maad_use_project, maad_use_projects,
+//                  maad_current_session
+//
+// These four tools operate at the instance level (no project binding required).
+// They let clients discover and bind to projects served by this MCP instance.
+// ============================================================================
+import { z } from 'zod';
+import { successResponse, errorResponse } from '../response.js';
+import { resolveSessionId } from '../../instance/session.js';
+import { performInstanceReload } from '../instance-reload.js';
+import { roleSatisfies } from '../roles.js';
+import { maadError } from '../../errors.js';
+import { collectSubscriptions } from '../notifications.js';
+const ROLE_ENUM = z.enum(['reader', 'writer', 'admin']);
+export function register(server, ctx) {
+    server.registerTool('maad_projects', {
+        description: 'Lists projects declared in this MCP instance. Returns name, description, configured role, and whether the current session has access. Call this before maad_use_project.',
+        inputSchema: z.object({}),
+    }, async (_args, extra) => {
+        const sessionId = resolveSessionId(extra);
+        const state = ctx.sessions.get(sessionId);
+        const projects = ctx.instance.projects.map((p) => ({
+            name: p.name,
+            description: p.description ?? null,
+            role: p.role,
+            accessible: state?.mode === null || !state
+                ? null
+                : state.mode === 'single'
+                    ? state.activeProject === p.name
+                    : (state.whitelist ?? []).includes(p.name),
+        }));
+        return successResponse({
+            instance: ctx.instance.name,
+            source: ctx.instance.source,
+            projects,
+            sessionBound: state?.mode !== null && state !== undefined,
+        }, 'maad_projects');
+    });
+    server.registerTool('maad_use_project', {
+        description: 'Binds the current session to a single project. Every subsequent tool call routes to this project. Optional `as` downgrades the session role below the project\'s configured role (e.g. bind an admin project in reader mode for safety). Once bound, a session cannot rebind — disconnect and reconnect instead.',
+        inputSchema: z.object({
+            name: z.string().describe('Project name (from maad_projects)'),
+            as: ROLE_ENUM.optional().describe('Optional role downgrade. Cannot exceed the project\'s configured role.'),
+        }),
+    }, async (args, extra) => {
+        const sessionId = resolveSessionId(extra);
+        if (!ctx.sessions.get(sessionId))
+            ctx.sessions.create(sessionId);
+        const opts = args.as ? { as: args.as } : {};
+        const result = ctx.sessions.bindSingle(sessionId, args.name, opts);
+        if (!result.ok)
+            return errorResponse(result.errors);
+        const state = result.value;
+        return successResponse({
+            mode: state.mode,
+            activeProject: state.activeProject,
+            effectiveRole: state.effectiveRoles.get(args.name),
+        }, 'maad_use_project');
+    });
+    server.registerTool('maad_use_projects', {
+        description: 'Binds the current session to a whitelist of projects (multi-project mode). Every subsequent tool call must pass `project=<name>` to pick one. Optional `as` downgrades the role uniformly across all listed projects. Once bound, a session cannot rebind.',
+        inputSchema: z.object({
+            names: z.array(z.string()).min(1).describe('Project names from maad_projects'),
+            as: ROLE_ENUM.optional().describe('Optional role downgrade. Cannot exceed any project\'s configured role.'),
+        }),
+    }, async (args, extra) => {
+        const sessionId = resolveSessionId(extra);
+        if (!ctx.sessions.get(sessionId))
+            ctx.sessions.create(sessionId);
+        const opts = args.as ? { as: args.as } : {};
+        const result = ctx.sessions.bindMulti(sessionId, args.names, opts);
+        if (!result.ok)
+            return errorResponse(result.errors);
+        const state = result.value;
+        const effectiveRoles = {};
+        for (const [name, role] of state.effectiveRoles)
+            effectiveRoles[name] = role;
+        return successResponse({
+            mode: state.mode,
+            whitelist: state.whitelist,
+            effectiveRoles,
+        }, 'maad_use_projects');
+    });
+    server.registerTool('maad_current_session', {
+        description: 'Returns the current session state: mode, bound project(s), effective role per project, and binding_source (how the session was bound — client_tool or gateway_pin). Useful for debugging routing issues and detecting pinned sessions.',
+        inputSchema: z.object({}),
+    }, async (_args, extra) => {
+        const sessionId = resolveSessionId(extra);
+        const state = ctx.sessions.get(sessionId);
+        if (!state) {
+            return successResponse({ sessionId, mode: null, binding_source: null, note: 'no session registered yet' }, 'maad_current_session');
+        }
+        const effectiveRoles = {};
+        for (const [name, role] of state.effectiveRoles)
+            effectiveRoles[name] = role;
+        return successResponse({
+            sessionId: state.sessionId,
+            mode: state.mode,
+            activeProject: state.activeProject ?? null,
+            whitelist: state.whitelist ?? null,
+            effectiveRoles,
+            binding_source: state.bindingSource,
+            createdAt: state.createdAt.toISOString(),
+            lastActivityAt: state.lastActivityAt.toISOString(),
+            subscription: state.subscription
+                ? { docTypes: state.subscription.docTypes, project: state.subscription.project, createdAt: state.subscription.createdAt.toISOString() }
+                : null,
+        }, 'maad_current_session');
+    });
+    server.registerTool('maad_subscribe', {
+        description: 'Subscribe the current session to live notifications on durable writes. Optional filters: docTypes (array), project (string). Emits notifications/resources/updated with uri=maad://records/<docId> + extra params. One subscription per session; re-subscribe to replace filter.',
+        inputSchema: z.object({
+            docTypes: z.array(z.string()).optional().describe('Allowlist of doc types; omit for all types'),
+            project: z.string().optional().describe('Restrict to one project; defaults to session\'s bound scope'),
+        }),
+    }, async (args, extra) => {
+        const sessionId = resolveSessionId(extra);
+        if (!ctx.sessions.get(sessionId))
+            ctx.sessions.create(sessionId);
+        const state = ctx.sessions.get(sessionId);
+        const docTypes = (args.docTypes && args.docTypes.length > 0) ? args.docTypes : null;
+        const project = args.project ?? null;
+        state.subscription = { docTypes, project, createdAt: new Date() };
+        return successResponse({
+            subscribed: true,
+            filter: { docTypes, project },
+            note: 'Notifications fire only on durable commits. Use maad_changes_since for historical catch-up on reconnect.',
+        }, 'maad_subscribe');
+    });
+    server.registerTool('maad_unsubscribe', {
+        description: 'Releases the current session\'s live-update subscription. No-op if not subscribed.',
+        inputSchema: z.object({}),
+    }, async (_args, extra) => {
+        const sessionId = resolveSessionId(extra);
+        const state = ctx.sessions.get(sessionId);
+        const wasSubscribed = state?.subscription !== undefined;
+        if (state)
+            delete state.subscription;
+        return successResponse({ subscribed: false, wasSubscribed }, 'maad_unsubscribe');
+    });
+    return 6;
+}
+/**
+ * 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 function registerReload(server, ctx) {
+    server.registerTool('maad_instance_reload', {
+        description: 'Reloads instance.yaml from disk. Picks up added projects, evicts removed, cancels bound sessions. Admin on every bound project required. Path/role mutations rejected until 0.9.0.',
+        inputSchema: z.object({}),
+    }, async (_args, extra) => {
+        const sessionId = resolveSessionId(extra);
+        const state = ctx.sessions.get(sessionId);
+        // Session must be bound before an admin check makes sense.
+        if (!state || state.mode === null) {
+            return errorResponse([maadError('SESSION_UNBOUND', 'Session is not bound to any project. Call maad_use_project(s) before maad_instance_reload.')]);
+        }
+        // Admin on EVERY project in the binding. In single mode that's one project;
+        // in multi mode it's the whole whitelist. Prevents an operator who only
+        // has admin on one subproject from reloading the whole instance and
+        // affecting other tenants.
+        for (const [projectName, role] of state.effectiveRoles) {
+            if (!roleSatisfies(role, 'admin')) {
+                return errorResponse([maadError('INSUFFICIENT_ROLE', `maad_instance_reload requires admin on every project in the session binding; session has "${role}" on "${projectName}".`)]);
+            }
+        }
+        const result = await performInstanceReload(ctx, 'tool');
+        if (!result.ok)
+            return errorResponse(result.errors);
+        return successResponse({
+            source: result.value.source,
+            projectsAdded: result.value.projectsAdded,
+            projectsRemoved: result.value.projectsRemoved,
+            sessionsCancelled: result.value.sessionsCancelled.length,
+            sessionsPruned: result.value.sessionsPruned.length,
+            durationMs: result.value.durationMs,
+        }, 'maad_instance_reload');
+    });
+    server.registerTool('maad_subscriptions', {
+        description: 'Admin tool: returns live-subscription inventory across all sessions as { totalSubscriptions, subscriptions[], byProject, byDocType }. Requires admin on every project in the session binding.',
+        inputSchema: z.object({}),
+    }, async (_args, extra) => {
+        const sessionId = resolveSessionId(extra);
+        const callerState = ctx.sessions.get(sessionId);
+        if (!callerState || callerState.mode === null) {
+            return errorResponse([maadError('SESSION_UNBOUND', 'Session is not bound to any project. Call maad_use_project(s) before maad_subscriptions.')]);
+        }
+        // Admin on EVERY project in the binding — same model as maad_instance_reload.
+        // The tool leaks instance-wide state, so require admin across the caller's full scope.
+        for (const [projectName, role] of callerState.effectiveRoles) {
+            if (!roleSatisfies(role, 'admin')) {
+                return errorResponse([maadError('INSUFFICIENT_ROLE', `maad_subscriptions requires admin on every project in the session binding; session has "${role}" on "${projectName}".`)]);
+            }
+        }
+        const inventory = collectSubscriptions(ctx.sessions);
+        return successResponse(inventory, 'maad_subscriptions');
+    });
+    return 2;
+}
+//# sourceMappingURL=instance.js.map

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

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

package/dist/mcp/tools/maintain.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=maintain.d.ts.map

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

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

package/dist/mcp/tools/maintain.js

@@ -0,0 +1,118 @@
+// ============================================================================
+// Maintain tools — maad_delete, maad_reindex, maad_reload, maad_health
+// ============================================================================
+import { z } from 'zod';
+import { docId } from '../../types.js';
+import { resultToResponse, successResponse, getProvenanceMode, attachDurability } from '../response.js';
+import { notifyWrite } from '../notifications.js';
+import { isDryRun, dryRunResponse, auditToolCall } from '../guardrails.js';
+import { withEngine } from '../with-session.js';
+import { getTransportSnapshot, isInitialized as telemetryInitialized } from '../transport/telemetry.js';
+export function register(server, ctx) {
+    server.registerTool('maad_delete', {
+        description: 'Deletes a record. Soft: renames file with _deleted prefix. Hard: removes file entirely.',
+        inputSchema: z.object({
+            docId: z.string().describe('Document ID to delete'),
+            mode: z.enum(['soft', 'hard']).default('soft').describe('soft=rename, hard=remove file'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_delete', args, async ({ engine, projectName }) => {
+        auditToolCall('maad_delete', args);
+        if (isDryRun())
+            return dryRunResponse('maad_delete', args);
+        const result = await engine.deleteDocument(docId(args.docId), args.mode);
+        const response = resultToResponse(result);
+        if (!result.ok)
+            return response;
+        const value = result.value;
+        if (value.writeDurable) {
+            await notifyWrite(ctx, {
+                action: 'delete',
+                docId: String(value.docId),
+                docType: String(value.docType),
+                project: projectName,
+                updatedAt: new Date().toISOString(),
+            });
+        }
+        return attachDurability(response, value.writeDurable, value.commitFailure);
+    }));
+    server.registerTool('maad_reindex', {
+        description: 'Rebuilds the SQLite index from markdown files. Use after external file changes or to recover from stale state. Auto-detects per-type schema-index changes and rebuilds affected types even when files are byte-identical (rebuiltTypes lists them in the response).',
+        inputSchema: z.object({
+            force: z.boolean().optional().default(false).describe('Force full rebuild (skip both hash check and the schema-fingerprint shortcut). Rarely needed since 0.7.4 — the engine now auto-rebuilds types whose indexed-field set changed.'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_reindex', args, async ({ engine }) => {
+        return resultToResponse(await engine.reindex({ force: args.force }));
+    }));
+    server.registerTool('maad_reload', {
+        description: 'Reloads the engine — picks up new registry, schemas, and type directories without restarting the server. Use after changing _registry/ or _schema/ files.',
+        inputSchema: z.object({
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_reload', args, async ({ engine }) => {
+        auditToolCall('maad_reload', {});
+        return resultToResponse(await engine.reload());
+    }));
+    server.registerTool('maad_health', {
+        description: 'Engine health + transport + session telemetry + instance reload stats. sessions block: {active, pinned, subscribed, byProject: {<project>:{<role>:count}}, byIdentity: {<agent_id|anonymous>:count}, ...lifecycle counters}. instance block: {source, configPath?, projectCount, reload counters}.',
+        inputSchema: z.object({
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_health', args, ({ engine }) => {
+        const health = engine.health();
+        const provMode = getProvenanceMode();
+        // Telemetry may be uninitialized in test contexts that build an engine
+        // without going through startServer. Fall back gracefully so maad_health
+        // stays useful in those environments.
+        const pinnedCount = ctx.sessions.snapshot().filter(s => s.bindingSource === 'gateway_pin').length;
+        const telemetry = telemetryInitialized()
+            ? getTransportSnapshot(ctx.sessions.size(), pinnedCount)
+            : null;
+        // 0.6.12 — subscribed-session counter for cheap observability. Admins
+        // grep `subscribed > 0` to confirm push-based delivery is in use at all;
+        // full inventory is the admin-only maad_subscriptions tool.
+        const subscribedCount = ctx.sessions.snapshot().filter(s => s.subscription !== undefined).length;
+        // 0.7.0 — byProject + byIdentity aggregates (spec v2 fix #4: byProject
+        // replaces the ambiguous flat byRole because multi-project sessions
+        // carry different roles per project). byProject counts session×project
+        // pairs grouped by role so the inner sums can exceed `active` when
+        // multi-mode sessions exist. byIdentity counts DISTINCT sessions per
+        // agent_id; sessions with no token bucket under 'anonymous'.
+        const byProject = {};
+        const byIdentity = {};
+        for (const state of ctx.sessions.snapshot()) {
+            for (const [projectName, role] of state.effectiveRoles) {
+                const bucket = byProject[projectName] ?? (byProject[projectName] = {});
+                bucket[role] = (bucket[role] ?? 0) + 1;
+            }
+            const ident = state.token?.agentId ?? 'anonymous';
+            byIdentity[ident] = (byIdentity[ident] ?? 0) + 1;
+        }
+        // 0.6.9 — instance reload stats, always included. Operators watching
+        // hot-reload behavior (cohort expansion, tenant churn) filter on this
+        // block to verify their last reload landed + projectCount is current.
+        const reloadStats = ctx.pool.reloadStats();
+        const instanceBlock = {
+            name: ctx.instance.name,
+            source: ctx.instance.source,
+            configPath: ctx.instance.configPath ?? null,
+            projectCount: ctx.instance.projects.length,
+            lastReloadAt: reloadStats.lastReloadAt ? reloadStats.lastReloadAt.toISOString() : null,
+            reloadsAttempted: reloadStats.reloadsAttempted,
+            reloadsSucceeded: reloadStats.reloadsSucceeded,
+            reloadsFailed: reloadStats.reloadsFailed,
+            projectsAdded: reloadStats.projectsAdded,
+            projectsRemoved: reloadStats.projectsRemoved,
+        };
+        const sessionsBlock = telemetry
+            ? { ...telemetry.sessions, subscribed: subscribedCount, byProject, byIdentity }
+            : { subscribed: subscribedCount, byProject, byIdentity };
+        const payload = telemetry
+            ? { ...health, provenance: provMode, transport: telemetry.transport, sessions: sessionsBlock, instance: instanceBlock }
+            : { ...health, provenance: provMode, sessions: sessionsBlock, instance: instanceBlock };
+        return successResponse(payload, 'maad_health');
+    }));
+    return 4;
+}
+//# sourceMappingURL=maintain.js.map

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

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

package/dist/mcp/tools/read.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=read.d.ts.map

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

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

package/dist/mcp/tools/read.js

@@ -0,0 +1,260 @@
+// ============================================================================
+// Read tools — maad_get, maad_query, maad_search, maad_related, maad_schema,
+//              maad_aggregate, maad_verify, maad_join
+// ============================================================================
+import { z } from 'zod';
+import { docId, docType } from '../../types.js';
+import { resultToResponse, attachMeta, guardResponseSize } from '../response.js';
+import { withEngine } from '../with-session.js';
+import { hydrateQueryRows } from '../query-depth.js';
+export function register(server, ctx) {
+    server.registerTool('maad_get', {
+        description: 'Reads a markdown-backed record at increasing depth: hot (frontmatter), warm (+block), cold (full body), full (resolved refs+objects+related, provisional composite).',
+        inputSchema: z.object({
+            docId: z.string().describe('Document ID to read'),
+            depth: z.enum(['hot', 'warm', 'cold', 'full']).default('hot')
+                .describe('hot=frontmatter, warm=+block, cold=full body, full=resolved refs+objects+related'),
+            block: z.string().optional().describe('Block ID or heading (warm depth only)'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_get', args, async ({ engine }) => {
+        if (args.depth === 'full') {
+            return resultToResponse(await engine.getDocumentFull(docId(args.docId)), 'maad_get');
+        }
+        return resultToResponse(await engine.getDocument(docId(args.docId), args.depth, args.block ?? undefined), 'maad_get');
+    }));
+    server.registerTool('maad_query', {
+        description: 'Finds documents by type with optional field filters and projection. Filters support shorthand eq, single-op, between shortcut, and array-of-ops (AND semantics). Use fields to return frontmatter values inline instead of chasing IDs. Set depth=cold to return record bodies inline (kills query-then-N-gets pattern), depth=full to return full composite (refs+objects+related) per row.',
+        inputSchema: z.object({
+            docType: z.string().describe('Document type to query'),
+            filters: z.any().optional().describe('Field filters. Shorthand: { status: "active" }. Single op: { opened_at: { op: "gte", value: "2026-01-01" } }. Range shortcut: { opened_at: { op: "between", value: ["2026-03-01", "2026-03-31"] } }. Array-of-ops (AND): { opened_at: [{op: "gte", value: "2026-03-01"}, {op: "lte", value: "2026-03-31"}] }. Ops: eq, neq, gt, gte, lt, lte, in, contains, between.'),
+            fields: z.array(z.string()).optional().describe('Field names to return inline (e.g. ["name", "status"]). Indexed fields only.'),
+            sortBy: z.string().optional().describe('Indexed field to sort by'),
+            sortOrder: z.enum(['asc', 'desc']).optional().describe('Sort direction (default desc)'),
+            limit: z.number().optional().describe('Max results (default 50, capped at 500). Over-requests are clamped silently with _meta.limit_clamped set.'),
+            offset: z.number().optional().describe('Skip first N results'),
+            depth: z.enum(['hot', 'cold', 'full']).optional().describe('hot (default) = pointer + projected fields only; cold = adds body to each row; full = adds resolved composite (refs+objects+related). cold/full bound by depth_max_results (default 50, capped at 100) to prevent payload blowups.'),
+            depthMaxResults: z.number().optional().describe('When depth=cold|full, hydrate at most N rows (default 50, capped at 100). Beyond cap, remaining rows return at hot depth.'),
+            includeFilePath: z.boolean().optional().describe('Include filePath in each result row (default false — omitted to trim response size)'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_query', args, async ({ engine }) => {
+        const query = { docType: docType(args.docType) };
+        if (args.filters !== undefined)
+            query.filters = args.filters;
+        if (args.fields !== undefined)
+            query.fields = args.fields;
+        if (args.sortBy !== undefined)
+            query.sortBy = args.sortBy;
+        if (args.sortOrder !== undefined)
+            query.sortOrder = args.sortOrder;
+        if (args.limit !== undefined)
+            query.limit = args.limit;
+        if (args.offset !== undefined)
+            query.offset = args.offset;
+        const result = engine.findDocuments(query);
+        // 0.7.0 — default-strip filePath to trim response size. Clients that
+        // need the on-disk path opt in via includeFilePath:true. Backend still
+        // produces the field; we drop it at the MCP boundary.
+        let effective = result;
+        if (result.ok && args.includeFilePath !== true) {
+            const stripped = result.value.results.map(r => {
+                const { filePath, ...rest } = r;
+                void filePath;
+                return rest;
+            });
+            const newValue = {
+                total: result.value.total,
+                results: stripped,
+            };
+            if (result.value.limitClamped)
+                newValue.limitClamped = result.value.limitClamped;
+            effective = { ok: true, value: newValue };
+        }
+        // 0.7.3 (fup-2026-079[a]) — depth hydration. Composite that kills the
+        // query-then-N-gets agent pattern.
+        let depthMeta = null;
+        if (effective.ok && (args.depth === 'cold' || args.depth === 'full')) {
+            const hydrateOpts = { depth: args.depth };
+            if (args.depthMaxResults !== undefined)
+                hydrateOpts.depthMaxResults = args.depthMaxResults;
+            const outcome = await hydrateQueryRows(engine, effective.value.results, hydrateOpts);
+            const newValue = {
+                total: effective.value.total,
+                results: outcome.rows,
+            };
+            if (effective.value.limitClamped)
+                newValue.limitClamped = effective.value.limitClamped;
+            effective = { ok: true, value: newValue };
+            depthMeta = outcome.meta;
+        }
+        let response = resultToResponse(effective, 'maad_query');
+        // 0.7.1 — surface engine limit-clamping in _meta, then guard response size.
+        if (effective.ok && effective.value.limitClamped) {
+            response = attachMeta(response, { limit_clamped: effective.value.limitClamped });
+        }
+        if (depthMeta) {
+            response = attachMeta(response, { depth: depthMeta });
+        }
+        return guardResponseSize(response, { tool: 'maad_query' });
+    }));
+    server.registerTool('maad_search', {
+        description: 'Searches extracted objects across all documents. Filter by primitive + optional subtype, then narrow with query (substring) or value (exact). Without query or value, returns ALL objects matching primitive/subtype.',
+        inputSchema: z.object({
+            primitive: z.string().describe('Extraction primitive (entity, date, amount, etc.)'),
+            subtype: z.string().optional().describe('Subtype filter (person, org, attorney, etc.)'),
+            query: z.string().optional().describe('Substring match on values (e.g. "Attorney" matches "Lead Attorney")'),
+            value: z.string().optional().describe('Exact value match (must match the full extracted value)'),
+            contains: z.string().optional().describe('Alias for query — substring match on values'),
+            docId: z.string().optional().describe('Scope search to a single document'),
+            limit: z.number().optional().describe('Max results (default 50)'),
+            offset: z.number().optional().describe('Skip first N results'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_search', args, ({ engine }) => {
+        const query = { primitive: args.primitive };
+        if (args.subtype !== undefined)
+            query.subtype = args.subtype;
+        if (args.value !== undefined)
+            query.value = args.value;
+        const containsValue = args.query ?? args.contains;
+        if (containsValue !== undefined)
+            query.contains = containsValue;
+        if (args.docId !== undefined)
+            query.docId = docId(args.docId);
+        if (args.limit !== undefined)
+            query.limit = args.limit;
+        if (args.offset !== undefined)
+            query.offset = args.offset;
+        return resultToResponse(engine.searchObjects(query), 'maad_search');
+    }));
+    server.registerTool('maad_related', {
+        description: 'Returns documents connected to a given doc via ref fields.',
+        inputSchema: z.object({
+            docId: z.string().describe('Document ID'),
+            direction: z.enum(['outgoing', 'incoming', 'both']).default('both')
+                .describe('outgoing=docs this references, incoming=docs that reference this, both=all'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_related', args, ({ engine }) => {
+        return resultToResponse(engine.listRelated(docId(args.docId), args.direction), 'maad_related');
+    }));
+    server.registerTool('maad_schema', {
+        description: 'Returns field definitions, required fields, enum values, ID prefix, and format hints for a type. Use before create/update to know what fields to pass and how to format values.',
+        inputSchema: z.object({
+            docType: z.string().describe('Document type'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_schema', args, ({ engine }) => {
+        return resultToResponse(engine.schemaInfo(docType(args.docType)), 'maad_schema');
+    }));
+    server.registerTool('maad_aggregate', {
+        description: 'Groups documents by a field and optionally computes a metric (count/sum/avg/min/max) on another field. Supports multi-hop ref chains in groupBy (e.g. "client->industry") for cross-doctype aggregates — resolves refs at query time, merges groups that collapse to the same leaf value. Use instead of iterating records for totals.',
+        inputSchema: z.object({
+            docType: z.string().optional().describe('Document type to scope (optional; required for ref-chain groupBy)'),
+            groupBy: z.string().describe('Field name or ref chain to group by. Single field: "status". Multi-hop chain: "client_id->industry" or "case_id->account_id->name". Each non-leaf segment must be a ref field on its parent type.'),
+            metric: z.object({
+                field: z.string().describe('Field to aggregate (must be indexed, numeric for sum/avg/min/max)'),
+                op: z.enum(['count', 'sum', 'avg', 'min', 'max']).describe('Aggregation operation'),
+            }).optional().describe('Optional metric to compute per group. Without this, returns count per group value.'),
+            filters: z.any().optional().describe('Field filters (same format as maad_query — shorthand, single-op, between shortcut, array-of-ops with AND semantics).'),
+            limit: z.number().optional().describe('Max groups to return (default 50, capped at 2000). Over-requests are clamped silently with _meta.limit_clamped set.'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_aggregate', args, ({ engine }) => {
+        const query = {
+            groupBy: args.groupBy,
+        };
+        if (args.docType !== undefined)
+            query.docType = docType(args.docType);
+        if (args.metric !== undefined)
+            query.metric = args.metric;
+        if (args.filters !== undefined)
+            query.filters = args.filters;
+        if (args.limit !== undefined)
+            query.limit = args.limit;
+        const result = engine.aggregate(query);
+        let response = resultToResponse(result, 'maad_aggregate');
+        // 0.7.1 — surface engine limit-clamping in _meta, then guard response size.
+        if (result.ok && result.value.limitClamped) {
+            response = attachMeta(response, { limit_clamped: result.value.limitClamped });
+        }
+        return guardResponseSize(response, { tool: 'maad_aggregate' });
+    }));
+    server.registerTool('maad_verify', {
+        description: 'Fact-check a claim against the database. Two modes: (1) field — verify a specific field value on a document, (2) count — verify a document count for a type with optional filters. Use this BEFORE stating any number, date, amount, or count as fact.',
+        inputSchema: z.object({
+            mode: z.enum(['field', 'count']).describe('Verification mode'),
+            docId: z.string().optional().describe('Document ID (required for field mode)'),
+            field: z.string().optional().describe('Field name to verify (required for field mode)'),
+            expected: z.any().optional().describe('Expected value for the field (required for field mode)'),
+            docType: z.string().optional().describe('Document type (required for count mode)'),
+            expectedCount: z.number().optional().describe('Expected document count (required for count mode)'),
+            filters: z.any().optional().describe('Field filters for count mode (same format as maad_query)'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_verify', args, async ({ engine }) => {
+        if (args.mode === 'field') {
+            if (!args.docId || !args.field || args.expected === undefined) {
+                return resultToResponse({ ok: false, errors: [{ code: 'INVALID_ARGS', message: 'field mode requires docId, field, and expected' }] }, 'maad_verify');
+            }
+            return resultToResponse(await engine.verifyField(docId(args.docId), args.field, args.expected), 'maad_verify');
+        }
+        if (args.mode === 'count') {
+            if (!args.docType || args.expectedCount === undefined) {
+                return resultToResponse({ ok: false, errors: [{ code: 'INVALID_ARGS', message: 'count mode requires docType and expectedCount' }] }, 'maad_verify');
+            }
+            return resultToResponse(engine.verifyCount(docType(args.docType), args.expectedCount, args.filters), 'maad_verify');
+        }
+        return resultToResponse({ ok: false, errors: [{ code: 'INVALID_ARGS', message: 'mode must be "field" or "count"' }] }, 'maad_verify');
+    }));
+    server.registerTool('maad_join', {
+        description: 'Queries documents and follows ref fields to return projected fields from both source and target records in one call. Eliminates N+1 round-trips. Example: all cases with their client name and attorney name.',
+        inputSchema: z.object({
+            docType: z.string().describe('Source document type to query'),
+            refs: z.array(z.string()).describe('Ref field names to follow (e.g. ["client", "assigned_attorney"])'),
+            fields: z.array(z.string()).optional().describe('Fields to return from source documents'),
+            refFields: z.record(z.string(), z.array(z.string())).optional().describe('Fields to return from each ref target: { "client": ["name", "industry"], "assigned_attorney": ["first_name"] }'),
+            filters: z.any().optional().describe('Field filters on source documents (same format as maad_query)'),
+            limit: z.number().optional().describe('Max results (default 50)'),
+            offset: z.number().optional().describe('Skip first N results'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_join', args, ({ engine }) => {
+        const query = {
+            docType: docType(args.docType),
+            refs: args.refs,
+        };
+        if (args.fields !== undefined)
+            query.fields = args.fields;
+        if (args.refFields !== undefined)
+            query.refFields = args.refFields;
+        if (args.filters !== undefined)
+            query.filters = args.filters;
+        if (args.limit !== undefined)
+            query.limit = args.limit;
+        if (args.offset !== undefined)
+            query.offset = args.offset;
+        return resultToResponse(engine.join(query), 'maad_join');
+    }));
+    server.registerTool('maad_changes_since', {
+        description: 'Polling delta. Returns records with updated_at > cursor, ordered (updated_at ASC, doc_id ASC). Omit cursor to start. Pass nextCursor back verbatim to paginate; hasMore signals more pages. Operation: create | update (deletes not emitted).',
+        inputSchema: z.object({
+            cursor: z.string().optional().describe('Opaque cursor from a previous response. Omit on first call.'),
+            limit: z.number().int().positive().optional().describe('Max changes per page (default 100, max 1000).'),
+            docTypes: z.array(z.string()).optional().describe('Filter to these document types only.'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_changes_since', args, ({ engine }) => {
+        const q = {};
+        if (args.cursor !== undefined)
+            q.cursor = args.cursor;
+        if (args.limit !== undefined)
+            q.limit = args.limit;
+        if (args.docTypes !== undefined)
+            q.docTypes = args.docTypes;
+        return resultToResponse(engine.changesSince(q), 'maad_changes_since');
+    }));
+    return 9;
+}
+//# sourceMappingURL=read.js.map