@classytic/arc 2.41.1 → 2.44.0

package/dist/{mcpPlugin-BX5PujI0.mjs → mcpPlugin-srPc7ItN.mjs}

@@ -1,21 +1,29 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { r as evaluatePermissionDecision } from "./authorizationDecision-DawKGoXb.mjs";
-import { p as isArcError, t as ArcError } from "./errors-BH7YU_9O.mjs";
-import { n as requireSingleHeaderValue } from "./headers-BIXWKrzQ.mjs";
-import { b as isElevated, c as getOrgId, g as getUserId, x as isMember } from "./types-CgenB1gv.mjs";
-import { t as BaseController } from "./BaseController-CYEwjyjN.mjs";
-import { a as resolveEffectiveRoles, t as applyFieldReadPermissions } from "./fields-BHrkoF5y.mjs";
-import { t as buildRequestScopeProjection } from "./projection-BzIgzoKZ.mjs";
-import { i as resolvePipelineSteps, t as resolveActionPermission } from "./actionPermissions-BoPGQ5-4.mjs";
-import { t as executePipeline } from "./pipe-FMWNheSO.mjs";
-import { t as pluralize } from "./pluralize-CXWZIzTv.mjs";
-import { t as createIdempotencyResult } from "./interface-YzIbF7Ii.mjs";
-import { r as shouldRejectAdditionalProperties, t as normalizeSchemaIR } from "./schemaIR-CTvPDoPB.mjs";
-import { n as validateAggregations } from "./validate-DrYWnOzI.mjs";
-import { n as executeAggregation } from "./buildHandler-CvxKOc0m.mjs";
-import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { t as arcLog } from "./logger-D4V1zGLI.mjs";
+import { i as NotFoundError, p as isArcError, t as ArcError } from "./errors-CW4anJBy.mjs";
+import { c as BaseController, n as normalizeActionsToRouterConfig, r as resolveActionTargetFence } from "./plugin-DALd9dcF.mjs";
+import { n as requireSingleHeaderValue } from "./headers-DKZQKL-Z.mjs";
+import { b as isElevated, c as getOrgId, g as getUserId, x as isMember } from "./types-fvO6Ovzx.mjs";
+import { a as resolveEffectiveRoles, t as applyFieldReadPermissions } from "./fields-A5crhsJb.mjs";
+import { o as toJsonSchema } from "./schemaConverter-BVjkQ5DD.mjs";
+import { t as buildRequestScopeProjection } from "./projection-wFoLqdss.mjs";
+import { l as resolvePipelineSteps, t as resolveActionPermission } from "./actionPermissions-5N04zBL4.mjs";
+import { a as withoutTenantInjection, r as prepareTenantContext } from "./tenantPreparation-CBvvAcAj.mjs";
+import { r as evaluatePermissionDecision } from "./authorizationDecision-wX3SA9w_.mjs";
+import { n as declareRuntimeCapability } from "./runtimeCapabilities-DIMKMV2G.mjs";
+import { t as executePipeline } from "./pipe-D81zMtWs.mjs";
+import { a as resourceRateLimitWindowMs, i as resolveResourceRateLimiter, t as createMemoryResourceRateLimiter } from "./resourceRateLimit-urWPJxrt.mjs";
+import { n as evictToSize, r as touch, t as assertCapacity } from "./boundedMap-DWiKW7lP.mjs";
+import { t as pluralize } from "./pluralize-COUNYo3d.mjs";
+import { n as createIdempotencyResult, r as operationIdentity, t as resolveIdempotencyTiming } from "./timing-CntavTlR.mjs";
+import { n as acquireIdempotencyKey, r as releaseIdempotencyLock } from "./acquire-BozJ-9yt.mjs";
+import { r as shouldRejectAdditionalProperties, t as normalizeSchemaIR } from "./schemaIR-BA0Hb21Y.mjs";
+import { n as validateAggregations } from "./validate-CWp-lsrm.mjs";
+import { n as executeAggregation } from "./buildHandler-Bswu_vNb.mjs";
+import { ARC_ERROR_CODES, isHttpError, toErrorContract } from "@classytic/repo-core/errors";
 import { createHash, randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
+import { IdempotencyError, fingerprintRequest } from "@classytic/repo-core/idempotency";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
 /**
@@ -222,51 +230,55 @@ function buildRequestContext(input, auth, operation, policyFilters, scopeOverrid
 		},
 		...extras?.server ? { server: extras.server } : {}
 	};
+	const prepared = (ctx) => {
+		prepareTenantContext(ctx, extras?.tenantMiddlewares);
+		return ctx;
+	};
 	switch (operation) {
-		case "list": return {
+		case "list": return prepared({
 			...base,
 			params: {},
 			query: expandOperatorKeys(input),
 			body: void 0
-		};
+		});
 		case "get": {
 			const { id, ...rest } = input;
-			return {
+			return prepared({
 				...base,
 				params: { id: String(id ?? "") },
 				query: expandOperatorKeys(rest),
 				body: void 0
-			};
+			});
 		}
-		case "create": return {
+		case "create": return prepared({
 			...base,
 			params: {},
 			query: {},
 			body: { ...input }
-		};
+		});
 		case "update": {
 			const { id: _id, ...body } = input;
-			return {
+			return prepared({
 				...base,
 				params: { id: String(_id ?? "") },
 				query: {},
 				body
-			};
+			});
 		}
-		case "delete": return {
+		case "delete": return prepared({
 			...base,
 			params: { id: String(input.id ?? "") },
 			query: {},
 			body: void 0
-		};
+		});
 		case "action": {
 			const { id: _actionId, ...actionBody } = input;
-			return {
+			return prepared({
 				...base,
 				params: { id: String(_actionId ?? "") },
 				query: {},
 				body: actionBody
-			};
+			});
 		}
 	}
 }
@@ -563,36 +575,137 @@ function createMcpController(resource) {
 	});
 }
 //#endregion
-//#region src/integrations/mcp/invokeController.ts
+//#region src/integrations/mcp/http-parity.ts
 /**
-* @classytic/arc — Non-HTTP controller invocation for MCP / jobs / workflows.
-*
-* Internal callers (MCP tools, scheduled jobs, workflow steps) need to invoke
-* controller methods without going through Fastify's preHandler chain.
-* Before this module landed, every call site reinvented the same shim:
-* fabricate `params` / `body` / `headers`, project the session into a
-* `RequestScope`, run the permission check by hand, translate thrown errors
-* to the MCP `CallToolResult` shape. The drift across those copies is what
-* the mentora review flagged as the "buildCtx synthetic-context hack."
-*
-* Two public surfaces, layered so callers reach for the smallest piece that
-* does the job:
-*
-*   - {@link invokeController}    full pipeline: permission → context →
-*                                 dispatch → canonical envelope/error
-*                                 conversion. Returns `CallToolResult`.
-*   - {@link mcpHandlerAdapter}   thin try/catch wrapper that turns any
-*                                 async function into a `ToolDefinition`
-*                                 handler with canonical error shape. Use
-*                                 when you want to compose multiple
-*                                 controller calls or weave in custom logic
-*                                 between them.
-*
-* Both honor the same {@link buildRequestContext} primitive — re-exported
-* from this module so authors who want the synthetic context as data (e.g.
-* to pass into `executePipeline`) can grab it without depending on an
-* internal subpath.
+* The gates an HTTP route applies that an MCP tool must apply too, because a tool calls the
+* controller or action handler directly and skips the route: idempotent execution, the
+* key-required refusal, the per-caller rate limit and the action audit record.
 */
+function isIdempotencyStore(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const s = value;
+	return typeof s.get === "function" && typeof s.set === "function" && typeof s.tryLock === "function" && typeof s.unlock === "function";
+}
+/** The wired store, when it is one. */
+function idempotencyStoreOf(store) {
+	return isIdempotencyStore(store) ? store : void 0;
+}
+function isFencedStore(store) {
+	return typeof store.setIfLocked === "function" && store.supportsFencedCompletion !== false;
+}
+/** Refuse an unsafe standalone store; an explicit migration escape is logged at wiring. */
+function assertMcpIdempotencyFencing(wiring) {
+	resolveIdempotencyTiming(wiring?.idempotencyTtlMs, wiring?.idempotencyLockTimeoutMs);
+	const store = idempotencyStoreOf(wiring?.idempotencyStore);
+	if (!store || isFencedStore(store)) return;
+	const message = "[Arc/MCP] Idempotency store must implement atomic setIfLocked completion fencing. Upgrade the store or explicitly allowUnfencedCompletion during migration.";
+	if (wiring?.allowUnfencedCompletion !== true) throw new Error(message);
+	const logger = wiring.log && typeof wiring.log === "object" ? wiring.log : {};
+	const warning = "[Arc/MCP] allowUnfencedCompletion permits an expired worker to overwrite a newer result; migrate the idempotency store to atomic setIfLocked.";
+	if (typeof logger.warn === "function") logger.warn.call(wiring.log, warning);
+	else arcLog("mcp:idempotency").warn(warning);
+}
+/** Same protocol as the HTTP plugin: cached → replay; locked → 409; else lock → run → record. */
+async function runIdempotentTool(args) {
+	const { store, dispatch } = args;
+	const { ttlMs, lockTimeoutMs } = resolveIdempotencyTiming(args.idempotencyTtlMs, args.idempotencyLockTimeoutMs);
+	if (!isFencedStore(store) && args.allowUnfencedCompletion !== true) return toCallToolError({
+		code: ARC_ERROR_CODES.INTERNAL_ERROR,
+		message: "Idempotency store requires atomic setIfLocked completion fencing",
+		status: 500
+	});
+	const fullKey = `${args.key}:${operationIdentity(`${args.resourceName}:${args.operation}`, args.scope ?? buildScope(args.session), void 0, "mcp")}`;
+	let fingerprint;
+	try {
+		fingerprint = fingerprintRequest(args.input);
+	} catch (error) {
+		if (error instanceof IdempotencyError) return toCallToolError({
+			code: ARC_ERROR_CODES.IDEMPOTENCY_BODY_UNFINGERPRINTABLE,
+			message: error.message,
+			status: 400
+		});
+		throw error;
+	}
+	const replay = (cached) => {
+		if (cached) {
+			if (cached.requestFingerprint && cached.requestFingerprint !== fingerprint) return toCallToolError({
+				code: ARC_ERROR_CODES.IDEMPOTENCY_KEY_REUSED,
+				message: "Idempotency key was already used for a different request body. Use a new key for a new request.",
+				status: 422
+			});
+			return cached.body;
+		}
+	};
+	const lockId = randomUUID();
+	const acquisition = await acquireIdempotencyKey(store, fullKey, lockId, lockTimeoutMs);
+	if (acquisition.status === "completed") return replay(acquisition.result);
+	if (acquisition.status === "locked") return toCallToolError({
+		code: ARC_ERROR_CODES.IDEMPOTENCY_CONFLICT,
+		message: "A call with this idempotency key is already in progress",
+		status: 409
+	});
+	let fencedCompletion = false;
+	try {
+		const result = JSON.parse(JSON.stringify(await dispatch()));
+		if (!result.isError) {
+			const completion = createIdempotencyResult(200, result, {}, ttlMs, fingerprint);
+			if (store.setIfLocked && store.supportsFencedCompletion !== false) {
+				if (!await store.setIfLocked(fullKey, lockId, completion)) return toCallToolError({
+					code: ARC_ERROR_CODES.IDEMPOTENCY_CONFLICT,
+					message: "The idempotency completion lease was lost; success could not be recorded",
+					status: 409
+				});
+				fencedCompletion = true;
+			} else await store.set(fullKey, completion);
+		}
+		return result;
+	} finally {
+		await releaseIdempotencyLock(store, fullKey, lockId, fencedCompletion);
+	}
+}
+/** The 400 a keyless call to a key-required route gets over HTTP. */
+function idempotencyKeyRequiredResult(toolName) {
+	return toCallToolError({
+		code: ARC_ERROR_CODES.IDEMPOTENCY_KEY_REQUIRED,
+		message: `'${toolName}' moves money or stock: pass \`_idempotencyKey\` and reuse it on a retry.`,
+		status: 400
+	});
+}
+function createToolRateLimiter(config, resourceName, limiter = createMemoryResourceRateLimiter()) {
+	if (!config) return void 0;
+	resourceRateLimitWindowMs(config.timeWindow);
+	return async (session, scope) => (await limiter.consume(resourceName, config, { scope: scope ?? buildScope(session) })).allowed;
+}
+function rateLimitedResult(toolName) {
+	return toCallToolError({
+		code: "arc.rate_limited",
+		message: `Too many calls to '${toolName}' — retry later.`,
+		status: 429
+	});
+}
+/** `audit.custom(resource, id, action, {}, context)` after a successful action, like the route. */
+async function auditToolAction(audit, args) {
+	if (typeof audit !== "object" || audit === null) return;
+	const logger = audit;
+	if (typeof logger.custom !== "function" || logger._noop === true) return;
+	const { session } = args;
+	const actorId = session?.userId ?? session?.clientId;
+	try {
+		await logger.custom.call(audit, args.resourceName, args.id, args.action, { channel: "mcp" }, {
+			...actorId !== void 0 ? { actorId } : {},
+			...session?.organizationId !== void 0 ? { organizationId: session.organizationId } : {},
+			endpoint: `MCP ${args.toolName}`
+		});
+	} catch (err) {
+		const log = typeof args.log === "object" && args.log !== null ? args.log : void 0;
+		if (typeof log?.error === "function") log.error.call(log, {
+			err,
+			tool: args.toolName
+		}, "[arc/mcp] action audit write failed");
+	}
+}
+//#endregion
+//#region src/integrations/mcp/invokeController.ts
 /**
 * Assemble the {@link McpContextExtras} for a controller invocation from
 * resource-scoped metadata + app-level wiring. Mirrors what
@@ -601,8 +714,9 @@ function createMcpController(resource) {
 */
 function buildContextExtras(options) {
 	const { wiring, resourceName, permissions, fields, schemaOptions, idField } = options;
-	if (!wiring) return void 0;
+	if (!wiring) return { tenantMiddlewares: options.tenantMiddlewares };
 	return {
+		tenantMiddlewares: options.tenantMiddlewares,
 		arc: {
 			resourceName,
 			schemaOptions,
@@ -620,23 +734,6 @@ function buildContextExtras(options) {
 	};
 }
 /**
-* Stable fingerprint of a tool invocation — sorted-key JSON, hashed.
-* Scopes an idempotency key to (resource, action, input, caller) so a
-* reused key with DIFFERENT input is a fresh execution, matching the HTTP
-* plugin's method+url+bodyHash+user fingerprint semantics.
-*/
-function invocationFingerprint(resourceName, actionName, input, session) {
-	const sortKeys = (value) => {
-		if (Array.isArray(value)) return value.map(sortKeys);
-		if (value !== null && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((k) => [k, sortKeys(value[k])]));
-		return value;
-	};
-	return `mcp:${resourceName}:${actionName}:${createHash("sha256").update(JSON.stringify(sortKeys(input))).digest("hex").substring(0, 16)}:u=${session?.userId ?? session?.clientId ?? "anon"}`;
-}
-/** TTLs matching the HTTP idempotency plugin's defaults. */
-const MCP_IDEMPOTENCY_TTL_MS = 864e5;
-const MCP_IDEMPOTENCY_LOCK_MS = 1e4;
-/**
 * Invoke a controller method through the MCP synthetic-context path.
 *
 * Runs the same chain CRUD MCP tools run:
@@ -685,8 +782,9 @@ async function invokeController(controller, op, input, options) {
 			reason: permResult.reason,
 			session
 		});
+		const reqCtx = buildRequestContext(input, session, op, permResult?.policy, permResult?.scope, buildContextExtras(options));
+		if (options.allow && !await options.allow(session, reqCtx.metadata._scope)) return rateLimitedResult(actionName);
 		const dispatch = async () => {
-			const reqCtx = buildRequestContext(input, session, op, permResult?.policy, permResult?.scope, buildContextExtras(options));
 			const response = await method(reqCtx);
 			const data = applyMcpReadMasking(response.data, {
 				fields,
@@ -698,25 +796,20 @@ async function invokeController(controller, op, input, options) {
 				data
 			});
 		};
-		const store = wiring?.idempotencyStore;
-		if (idempotencyKey && store) {
-			const fullKey = `${idempotencyKey}:${invocationFingerprint(resourceName, actionName, input, session)}`;
-			const cached = await store.get(fullKey);
-			if (cached) return cached.body;
-			const lockId = randomUUID();
-			if (!await store.tryLock(fullKey, lockId, MCP_IDEMPOTENCY_LOCK_MS)) return toCallToolError({
-				code: "arc.idempotency_conflict",
-				message: "A call with this idempotency key is already in progress",
-				status: 409
-			});
-			try {
-				const result = await dispatch();
-				if (!result.isError) await store.set(fullKey, createIdempotencyResult(200, result, {}, MCP_IDEMPOTENCY_TTL_MS));
-				return result;
-			} finally {
-				await store.unlock(fullKey, lockId);
-			}
-		}
+		const store = idempotencyStoreOf(wiring?.idempotencyStore);
+		if (idempotencyKey && store) return await runIdempotentTool({
+			store,
+			allowUnfencedCompletion: wiring?.allowUnfencedCompletion,
+			idempotencyTtlMs: wiring?.idempotencyTtlMs,
+			idempotencyLockTimeoutMs: wiring?.idempotencyLockTimeoutMs,
+			key: idempotencyKey,
+			resourceName,
+			operation: actionName,
+			input,
+			session,
+			scope: reqCtx.metadata._scope,
+			dispatch
+		});
 		return await dispatch();
 	} catch (err) {
 		return toCallToolError(err instanceof Error ? err : new Error(String(err)));
@@ -806,7 +899,9 @@ const MUTATING_CRUD_OPS = /* @__PURE__ */ new Set([
 ]);
 function createCrudHandler(op, controller, resourceName, permissions, fields, extras) {
 	const permission = permissions?.[op];
-	return (input, ctx) => {
+	const toolName = extras?.toolName ?? `${op}_${resourceName}`;
+	return async (input, ctx) => {
+		if (extras?.keyRequired && (typeof input._idempotencyKey !== "string" || input._idempotencyKey === "")) return idempotencyKeyRequiredResult(toolName);
 		let idempotencyKey;
 		let payload = input;
 		if ("_idempotencyKey" in input) {
@@ -816,10 +911,12 @@ function createCrudHandler(op, controller, resourceName, permissions, fields, ex
 		}
 		return invokeController(controller, op, payload, {
 			session: ctx.session,
+			allow: extras?.allow,
 			resourceName,
 			permissions: permission,
 			fields,
 			wiring: extras?.wiring,
+			tenantMiddlewares: extras?.tenantMiddlewares,
 			schemaOptions: extras?.schemaOptions,
 			idField: extras?.idField,
 			idempotencyKey
@@ -1082,7 +1179,7 @@ var McpAuthCache = class {
 	maxEntries;
 	constructor(opts) {
 		this.ttlMs = opts?.ttlMs ?? DEFAULT_AUTH_CACHE_TTL_MS;
-		this.maxEntries = opts?.maxEntries ?? DEFAULT_AUTH_CACHE_MAX;
+		this.maxEntries = assertCapacity("McpAuthCache maxEntries", opts?.maxEntries ?? DEFAULT_AUTH_CACHE_MAX);
 	}
 	get(key) {
 		const entry = this.cache.get(key);
@@ -1097,15 +1194,12 @@ var McpAuthCache = class {
 		if (this.cache.size >= this.maxEntries) {
 			const now = Date.now();
 			for (const [k, v] of this.cache) if (now > v.expires) this.cache.delete(k);
-			if (this.cache.size >= this.maxEntries) {
-				const firstKey = this.cache.keys().next().value;
-				if (firstKey) this.cache.delete(firstKey);
-			}
 		}
-		this.cache.set(key, {
+		touch(this.cache, key, {
 			result,
 			expires: Date.now() + this.ttlMs
 		});
+		evictToSize(this.cache, this.maxEntries);
 	}
 };
 /**
@@ -1229,7 +1323,10 @@ function convertActionSchemaToZod(raw) {
 */
 function createActionToolHandler(actionName, handler, permissions, resourceName, _resourcePermissions, rawSchema, idLess = false, fields, extras) {
 	const wiring = extras?.wiring;
+	const parity = extras?.parity;
+	const toolName = parity?.toolName ?? `${actionName}_${resourceName}`;
 	const contextExtras = wiring ? {
+		tenantMiddlewares: extras?.tenantMiddlewares,
 		arc: {
 			resourceName,
 			schemaOptions: extras?.schemaOptions,
@@ -1244,11 +1341,16 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 			audit: wiring.audit,
 			log: wiring.log
 		}
-	} : void 0;
+	} : { tenantMiddlewares: extras?.tenantMiddlewares };
 	const ir = rawSchema ? normalizeSchemaIR(rawSchema) : void 0;
-	const allowedKeys = (ir ? shouldRejectAdditionalProperties(ir) : false) && ir ? /* @__PURE__ */ new Set([...idLess ? [] : ["id"], ...Object.keys(ir.properties)]) : void 0;
-	return async (input, ctx) => {
+	const strict = ir ? shouldRejectAdditionalProperties(ir) : false;
+	const allowedBaseKeys = [...idLess ? [] : ["id"], ...parity?.keyRequired ? ["_idempotencyKey"] : []];
+	const allowedKeys = strict && ir ? /* @__PURE__ */ new Set([...allowedBaseKeys, ...Object.keys(ir.properties)]) : void 0;
+	return async (rawInput, ctx) => {
 		const session = ctx.session;
+		const { _idempotencyKey: rawKey, ...input } = rawInput;
+		const idempotencyKey = typeof rawKey === "string" && rawKey !== "" ? rawKey : void 0;
+		if (parity?.keyRequired && idempotencyKey === void 0) return idempotencyKeyRequiredResult(toolName);
 		if (allowedKeys) {
 			const extras = Object.keys(input).filter((k) => !allowedKeys.has(k));
 			if (extras.length > 0) return toCallToolError({
@@ -1269,18 +1371,62 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 			reason: permResult.reason,
 			session
 		});
-		const reqCtx = buildRequestContext({
-			...input,
-			action: actionName
-		}, session, "action", permResult?.policy, permResult?.scope, contextExtras);
-		const id = idLess ? "" : typeof input.id === "string" ? input.id : "";
-		const { id: _discardId, ...data } = input;
 		try {
-			return toCallToolSuccess(applyMcpReadMasking(await handler(id, data, reqCtx), {
-				fields,
+			const reqCtx = buildRequestContext({
+				...input,
+				action: actionName
+			}, session, "action", permResult?.policy, permResult?.scope, contextExtras);
+			const id = idLess ? "" : typeof input.id === "string" ? input.id : "";
+			const { id: _discardId, ...data } = input;
+			let target;
+			if (!idLess && parity?.fence) {
+				const check = await parity.fence(id, reqCtx);
+				if (!check.visible) throw new NotFoundError(resourceName);
+				target = check.doc;
+			}
+			if (parity?.allow && !await parity.allow(session, reqCtx.metadata._scope)) return rateLimitedResult(toolName);
+			const run = async () => {
+				const withTarget = target === void 0 ? reqCtx : {
+					...reqCtx,
+					arc: {
+						...reqCtx.arc,
+						actionTarget: target
+					}
+				};
+				const req = idempotencyKey === void 0 ? withTarget : {
+					...withTarget,
+					idempotencyKey
+				};
+				const result = await handler(id, data, req);
+				if (parity?.audit) await auditToolAction(wiring?.audit, {
+					resourceName,
+					id,
+					action: actionName,
+					toolName,
+					session,
+					log: wiring?.log
+				});
+				return toCallToolSuccess(applyMcpReadMasking(result, {
+					fields,
+					session,
+					scopeOverride: permResult?.scope
+				}));
+			};
+			const store = idempotencyStoreOf(wiring?.idempotencyStore);
+			if (idempotencyKey !== void 0 && store && !parity?.handlerDedup) return await runIdempotentTool({
+				store,
+				allowUnfencedCompletion: wiring?.allowUnfencedCompletion,
+				idempotencyTtlMs: wiring?.idempotencyTtlMs,
+				idempotencyLockTimeoutMs: wiring?.idempotencyLockTimeoutMs,
+				key: idempotencyKey,
+				resourceName,
+				operation: `action.${actionName}`,
+				input,
 				session,
-				scopeOverride: permResult?.scope
-			}));
+				scope: reqCtx.metadata._scope,
+				dispatch: run
+			});
+			return await run();
 		} catch (err) {
 			return toCallToolError(err instanceof Error ? err : new Error(String(err)));
 		}
@@ -1320,7 +1466,8 @@ function buildAggregationTools(args) {
 				resourceName,
 				repo,
 				buildOptionsFromSession,
-				fields
+				fields,
+				tenantMiddlewares: args.tenantMiddlewares
 			})
 		});
 	}
@@ -1372,14 +1519,24 @@ function createAggregationToolHandler(args) {
 			session: ctx.session
 		});
 		const filterInput = input.filter ?? {};
-		const tenantOptions = buildOptionsFromSession(ctx.session);
+		let prepared;
+		try {
+			prepared = buildRequestContext(filterInput, ctx.session, "list", permResult?.policy, permResult?.scope, { tenantMiddlewares: args.tenantMiddlewares });
+		} catch (error) {
+			return toCallToolError(error instanceof Error ? error : new Error(String(error)));
+		}
+		const meta = prepared.metadata;
+		const tenantOptions = {
+			...buildOptionsFromSession(ctx.session),
+			...meta._tenantFields
+		};
 		const result = await executeAggregation(normalized, {
 			repo,
 			buildOptions: () => tenantOptions
 		}, {
 			query: filterInput,
 			tenantOptions,
-			policyFilter: permResult?.policy
+			policyFilter: meta._policyFilters
 		});
 		if (result.status === 200) {
 			const body = result.body;
@@ -1677,6 +1834,73 @@ function mapJsonSchemaTypeToArcType(jsonType) {
 	}
 }
 //#endregion
+//#region src/integrations/mcp/route-input-schema.ts
+/**
+* Custom-route → MCP tool INPUT schema. The route's own schema is the contract:
+* an input the REST route would refuse must be refused on MCP, never stripped.
+*
+* - A Zod schema that is not a plain object (a union of strict arms) is registered
+*   WHOLE — the MCP SDK validates and advertises a Standard Schema as-is. Flattening
+*   it yields `{}`, and the SDK's `z.object({})` then strips every key the caller sent.
+* - A flat schema declaring `additionalProperties: false` registers as `z.strictObject`,
+*   so an unknown key is an input error instead of a silently dropped filter. So
+*   does a route with NO schema: a key it was sent could never reach the handler.
+* - Any other non-object schema (a JSON Schema `anyOf`, or a Zod union beside `:id`
+*   or a second source) throws at tool build: there is no lossless flat form, so
+*   bridge it with `mcpHandler` or opt out with `mcp: false`.
+*/
+/** A Zod v4 schema (carries the `_zod` marker and the Standard Schema slot). */
+function isZodTypeSchema(value) {
+	return value !== null && typeof value === "object" && "_zod" in value && "~standard" in value;
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object";
+}
+/** The JSON Schema HTTP validates this request slot with (`input` io, as the router converts it). */
+function requestJsonSchema(schema) {
+	return toJsonSchema(schema, "draft-7", "throw", "input");
+}
+/** Does this JSON Schema have a single top-level object a flat shape can carry? */
+function flattensLosslessly(json) {
+	if (!json) return true;
+	if ("anyOf" in json || "oneOf" in json || "allOf" in json) return false;
+	return json.type === "object" || "properties" in json;
+}
+function buildRouteInputSchema(route, hasId) {
+	const routeSchema = isRecord(route.schema) ? route.schema : void 0;
+	const sources = [routeSchema?.body, routeSchema?.querystring].filter(isRecord);
+	const whole = [];
+	let unflattenable = 0;
+	for (const source of sources) {
+		if (flattensLosslessly(requestJsonSchema(source))) continue;
+		unflattenable++;
+		if (isZodTypeSchema(source)) whole.push(source);
+	}
+	const [only] = whole;
+	if (unflattenable > 0) {
+		if (only && sources.length === 1 && !hasId) return only;
+		throw new Error(`[Arc/MCP] Route '${route.method} ${route.path}': a non-object input schema (union) is bridged only as a Zod schema that is the route's sole input with no ':id' — anything else loses validation. Declare \`mcpHandler\` for this route or set \`mcp: false\`.`);
+	}
+	const shape = {};
+	if (hasId) shape.id = z.string().describe("Resource ID");
+	let strict = sources.length === 0;
+	for (const source of sources) {
+		if (requestJsonSchema(source)?.additionalProperties === false) strict = true;
+		const ir = normalizeSchemaIR(source);
+		for (const [key, val] of Object.entries(schemaIRToZodShape(ir))) if (!(key in shape)) shape[key] = val;
+	}
+	return strict ? z.strictObject(shape) : shape;
+}
+/**
+* The field shape a tool advertises — the flat record itself, or a whole object
+* schema's `.shape`. `undefined` for a union, which has no single shape.
+*/
+function toolInputShape(schema) {
+	if (schema === void 0) return void 0;
+	if (!isZodTypeSchema(schema)) return schema;
+	return schema instanceof z.ZodObject ? schema.shape : void 0;
+}
+//#endregion
 //#region src/integrations/mcp/route-tools.ts
 /**
 * Custom-route → MCP tool generation.
@@ -1737,6 +1961,7 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 	const { resourceName, operationName, permissions, pipeline, fields, wiring } = options;
 	const pipelineSteps = resolvePipelineSteps(pipeline, operationName);
 	const contextExtras = wiring ? {
+		tenantMiddlewares: options.tenantMiddlewares,
 		arc: {
 			resourceName,
 			schemaOptions: options.schemaOptions,
@@ -1751,7 +1976,7 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 			audit: wiring.audit,
 			log: wiring.log
 		}
-	} : void 0;
+	} : { tenantMiddlewares: options.tenantMiddlewares };
 	return async (input, _ctx) => {
 		const session = _ctx.session;
 		const permResult = await evaluatePermission(permissions, session, resourceName, operationName, input);
@@ -1763,6 +1988,7 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 		});
 		try {
 			const reqCtx = buildRequestContext(input, session, operationKindForRoute(route.method, hasId), permResult?.policy, permResult?.scope, contextExtras);
+			if (options.allow && !await options.allow(session, reqCtx.metadata._scope)) return rateLimitedResult(operationName);
 			const emit = (envelope) => {
 				const data = applyMcpReadMasking(envelope.data, {
 					fields,
@@ -1881,10 +2107,18 @@ function resourceToTools(resource, config = {}) {
 	const tools = [];
 	const prefix = config.toolNamePrefix;
 	const wiring = config.wiring;
+	assertMcpIdempotencyFencing(wiring);
+	const hasIdempotencyStore = idempotencyStoreOf(wiring?.idempotencyStore) !== void 0;
+	const keyRequiredOps = new Set(resource.idempotency?.required ?? []);
+	const rateLimit = resource.rateLimit;
+	const rateLimiter = config.wiring?.rateLimiter ?? createMemoryResourceRateLimiter();
 	if (controller) {
 		let ops = ALL_CRUD_OPS.filter((op) => !resource.disabledRoutes?.includes(op));
 		if (config.operations) ops = ops.filter((op) => config.operations?.includes(op));
 		for (const op of ops) {
+			if (!resource.permissions?.[op]) continue;
+			const keyRequired = keyRequiredOps.has(op);
+			if (keyRequired && !hasIdempotencyStore) throw new Error(`[Arc/MCP] Resource '${resource.name}': '${op}' declares idempotency.required but no idempotency store is wired — register idempotencyPlugin before mcpPlugin, or the key would be demanded and never deduplicated.`);
 			const name = config.names?.[op] ?? (op === "list" ? `${prefix ? `${prefix}_` : ""}list_${pluralize(resource.name)}` : `${prefix ? `${prefix}_` : ""}${op}_${resource.name}`);
 			const defaultDescription = defaultCrudDescription(op, resource.displayName, hasSoftDelete, {
 				filterableFields,
@@ -1900,7 +2134,8 @@ function resourceToTools(resource, config = {}) {
 				maxLimit,
 				adapterBodies
 			});
-			if (wiring?.idempotencyStore && op !== "list" && op !== "get") inputSchema._idempotencyKey = z.string().optional().describe("Optional idempotency key — retrying with the same key and input replays the first successful result instead of re-executing.");
+			if (keyRequired) inputSchema._idempotencyKey = z.string().min(1).describe("Required idempotency key — reuse it on a retry; the first result replays.");
+			else if (hasIdempotencyStore && op !== "list" && op !== "get") inputSchema._idempotencyKey = z.string().optional().describe("Optional idempotency key — retrying with the same key and input replays the first successful result instead of re-executing.");
 			tools.push({
 				name,
 				description: resolveCrudDescription(config.descriptions?.[op], {
@@ -1913,11 +2148,15 @@ function resourceToTools(resource, config = {}) {
 					sortableFields
 				}),
 				annotations: CRUD_ANNOTATIONS[op],
-				inputSchema,
+				inputSchema: op === "list" || op === "get" ? z.strictObject(inputSchema) : inputSchema,
 				handler: createCrudHandler(op, controller, resource.name, resource.permissions, resource.fields, {
 					wiring,
+					tenantMiddlewares: resource.middlewares?.[op],
 					schemaOptions: resource.schemaOptions,
-					idField: resource.idField
+					idField: resource.idField,
+					keyRequired,
+					allow: createToolRateLimiter(rateLimit, resource.name, rateLimiter),
+					toolName: name
 				}),
 				source: `crud:${resource.name}:${op}`
 			});
@@ -1941,27 +2180,26 @@ function resourceToTools(resource, config = {}) {
 		const hasId = route.path.includes(":id");
 		const mcpConfig = typeof route.mcp === "object" && route.mcp !== null ? route.mcp : void 0;
 		const toolDescription = mcpConfig?.description ?? route.summary ?? route.description ?? `${opName} on ${resource.displayName}`;
-		const toolAnnotations = mcpConfig?.annotations ? { ...mcpConfig.annotations } : { openWorldHint: true };
-		const inputShape = {};
-		if (hasId) inputShape.id = z.string().describe("Resource ID");
-		const routeSchema = route.schema;
-		if (routeSchema?.body) {
-			const ir = normalizeSchemaIR(routeSchema.body);
-			for (const [key, val] of Object.entries(schemaIRToZodShape(ir))) inputShape[key] = val;
-		}
-		if (routeSchema?.querystring) {
-			const ir = normalizeSchemaIR(routeSchema.querystring);
-			for (const [key, val] of Object.entries(schemaIRToZodShape(ir))) if (!(key in inputShape)) inputShape[key] = val;
-		}
+		const toolAnnotations = mcpConfig?.annotations ? { ...mcpConfig.annotations } : route.method.toUpperCase() === "GET" ? { readOnlyHint: true } : { openWorldHint: true };
+		const inputShape = buildRouteInputSchema(route, hasId);
 		const toolName = prefix ? `${prefix}_${opName}_${resource.name}` : `${opName}_${resource.name}`;
 		const routeSource = route._presetSource ? `preset:${route._presetSource}:${resource.name}:${opName}` : `route:${resource.name}:${route.method} ${route.path}`;
+		const routePolicy = route.rateLimit !== void 0 ? route.rateLimit : rateLimit;
+		const allowRoute = createToolRateLimiter(routePolicy && typeof routePolicy === "object" ? {
+			...routePolicy,
+			...route.rateLimit ? { bucket: `route:${route.method}:${route.path}` } : {}
+		} : routePolicy, resource.name, rateLimiter);
+		const passthrough = mcpHandler ? createMcpHandlerPassthrough(mcpHandler) : void 0;
 		tools.push({
 			name: toolName,
 			description: toolDescription,
 			annotations: toolAnnotations,
 			inputSchema: inputShape,
 			source: routeSource,
-			handler: mcpHandler ? createMcpHandlerPassthrough(mcpHandler) : createCustomRouteHandler({
+			handler: passthrough ? async (input, ctx) => {
+				if (allowRoute && !await allowRoute(ctx.session)) return rateLimitedResult(toolName);
+				return passthrough(input, ctx);
+			} : createCustomRouteHandler({
 				handler: resolvedRouteHandler,
 				operation: route.operation,
 				method: route.method,
@@ -1969,48 +2207,70 @@ function resourceToTools(resource, config = {}) {
 			}, controller, hasId, {
 				resourceName: resource.name,
 				operationName: opName,
+				allow: allowRoute,
 				permissions: route.permissions,
 				pipeline: resource.pipe,
 				fields: resource.fields,
 				wiring,
+				tenantMiddlewares: route.tenantScope ? resource.middlewares?.tenantScope : void 0,
 				schemaOptions: resource.schemaOptions,
 				idField: resource.idField
 			})
 		});
 	}
-	if (resource.actions) for (const [actionName, entry] of Object.entries(resource.actions)) {
-		const def = typeof entry === "function" ? { handler: entry } : entry;
-		if (typeof def !== "function" && "mcp" in def && def.mcp === false) continue;
-		const mcpCfg = typeof def !== "function" && typeof def.mcp === "object" ? def.mcp : void 0;
-		const description = mcpCfg?.description ?? (typeof def !== "function" ? def.description : void 0) ?? `${actionName} action on ${resource.displayName}`;
-		const annotations = mcpCfg?.annotations ? { ...mcpCfg.annotations } : { destructiveHint: true };
-		const idLess = typeof def !== "function" && def.id === false;
-		const inputShape = idLess ? {} : { id: z.string().describe("Resource ID") };
-		const rawSchema = typeof def !== "function" ? def.schema : void 0;
-		if (rawSchema && typeof rawSchema === "object") {
-			const converted = convertActionSchemaToZod(rawSchema);
-			for (const [key, val] of Object.entries(converted)) inputShape[key] = val;
+	if (resource.actions) {
+		const actionConfig = normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, void 0);
+		const fence = resolveActionTargetFence(resource, actionConfig);
+		const handlerScoped = new Set(actionConfig.handlerScopedActionNames);
+		const keyRequiredActions = new Set(actionConfig.idempotentActionNames);
+		const allow = createToolRateLimiter(rateLimit, resource.name, rateLimiter);
+		for (const [actionName, entry] of Object.entries(resource.actions)) {
+			const def = typeof entry === "function" ? { handler: entry } : entry;
+			if (typeof def !== "function" && "mcp" in def && def.mcp === false) continue;
+			const mcpCfg = typeof def !== "function" && typeof def.mcp === "object" ? def.mcp : void 0;
+			const description = mcpCfg?.description ?? (typeof def !== "function" ? def.description : void 0) ?? `${actionName} action on ${resource.displayName}`;
+			const annotations = mcpCfg?.annotations ? { ...mcpCfg.annotations } : { destructiveHint: true };
+			const idLess = typeof def !== "function" && def.id === false;
+			const inputShape = idLess ? {} : { id: z.string().describe("Resource ID") };
+			const rawSchema = typeof def !== "function" ? def.schema : void 0;
+			if (rawSchema && typeof rawSchema === "object") {
+				const converted = convertActionSchemaToZod(rawSchema);
+				for (const [key, val] of Object.entries(converted)) inputShape[key] = val;
+			}
+			const toolName = prefix ? `${prefix}_${actionName}_${resource.name}` : `${actionName}_${resource.name}`;
+			const keyRequired = keyRequiredActions.has(actionName);
+			const handlerDedup = actionConfig.handlerDedupOwners[actionName] !== void 0;
+			if (keyRequired && !handlerDedup && !hasIdempotencyStore) throw new Error(`[Arc/MCP] Resource '${resource.name}': action '${actionName}' declares idempotency.required but no idempotency store is wired — register idempotencyPlugin before mcpPlugin, or the key would be demanded and never deduplicated.`);
+			if (keyRequired) inputShape._idempotencyKey = z.string().min(1).describe("Required idempotency key — reuse it on a retry; the first result replays.");
+			const handler = typeof entry === "function" ? entry : def.handler;
+			const actionPerms = resolveActionPermission({
+				action: entry,
+				resourcePermissions: resource.permissions,
+				resourceActionPermissions: resource.actionPermissions
+			});
+			if (!actionPerms) throw new Error(`[Arc/MCP] Resource '${resource.name}': action '${actionName}' has no permission gate and the resource defines no \`permissions.update\` fallback. Declare one of:\n  - \`actions.${actionName}.permissions: <PermissionCheck>\` (per-action)\n  - \`actionPermissions: <PermissionCheck>\` (resource-wide)\n  - \`permissions.update: <PermissionCheck>\` (inherited by actions)\nUse \`allowPublic()\` if you genuinely want the action unauthenticated.`);
+			tools.push({
+				name: toolName,
+				description: String(description),
+				annotations,
+				inputSchema: inputShape,
+				source: `action:${resource.name}:${actionName}`,
+				handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema, idLess, resource.fields, {
+					wiring,
+					tenantMiddlewares: withoutTenantInjection(resource.middlewares?.tenantScope),
+					schemaOptions: resource.schemaOptions,
+					idField: resource.idField,
+					parity: {
+						toolName,
+						keyRequired,
+						handlerDedup,
+						...fence && !idLess && !handlerScoped.has(actionName) ? { fence } : {},
+						audit: Boolean(resource.audit),
+						...allow ? { allow } : {}
+					}
+				})
+			});
 		}
-		const toolName = prefix ? `${prefix}_${actionName}_${resource.name}` : `${actionName}_${resource.name}`;
-		const handler = typeof entry === "function" ? entry : def.handler;
-		const actionPerms = resolveActionPermission({
-			action: entry,
-			resourcePermissions: resource.permissions,
-			resourceActionPermissions: resource.actionPermissions
-		});
-		if (!actionPerms) throw new Error(`[Arc/MCP] Resource '${resource.name}': action '${actionName}' has no permission gate and the resource defines no \`permissions.update\` fallback. Declare one of:\n  - \`actions.${actionName}.permissions: <PermissionCheck>\` (per-action)\n  - \`actionPermissions: <PermissionCheck>\` (resource-wide)\n  - \`permissions.update: <PermissionCheck>\` (inherited by actions)\nUse \`allowPublic()\` if you genuinely want the action unauthenticated.`);
-		tools.push({
-			name: toolName,
-			description: String(description),
-			annotations,
-			inputSchema: inputShape,
-			source: `action:${resource.name}:${actionName}`,
-			handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema, idLess, resource.fields, {
-				wiring,
-				schemaOptions: resource.schemaOptions,
-				idField: resource.idField
-			})
-		});
 	}
 	if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
 		const repoForAgg = resource.controller?.repository;
@@ -2036,6 +2296,7 @@ function resourceToTools(resource, config = {}) {
 			schemaOptions: resource.schemaOptions,
 			repo: repoForAgg,
 			buildOptionsFromSession,
+			tenantMiddlewares: resource.middlewares?.aggregations,
 			prefix,
 			fields: resource.fields
 		}));
@@ -2247,7 +2508,14 @@ const mcpPluginImpl = async (fastify, options) => {
 		exclude: options.exclude
 	});
 	const fastifyAny = fastify;
+	const rateLimiter = resolveResourceRateLimiter(fastify) ?? createMemoryResourceRateLimiter();
+	if (enabledResources.some((resource) => resource.rateLimit)) declareRuntimeCapability(fastify, {
+		subsystem: "mcp.resource-rate-limit",
+		durability: rateLimiter.durability,
+		detail: "REST and MCP resource budgets require a shared rate-limit backend across replicas."
+	});
 	const wiring = {
+		rateLimiter,
 		get hooks() {
 			return fastifyAny.arc?.hooks;
 		},
@@ -2260,6 +2528,15 @@ const mcpPluginImpl = async (fastify, options) => {
 		get log() {
 			return fastify.log;
 		},
+		get allowUnfencedCompletion() {
+			return fastifyAny.idempotency?.allowUnfencedCompletion;
+		},
+		get idempotencyTtlMs() {
+			return fastifyAny.idempotency?.ttlMs;
+		},
+		get idempotencyLockTimeoutMs() {
+			return fastifyAny.idempotency?.lockTimeoutMs;
+		},
 		get idempotencyStore() {
 			return fastifyAny.idempotency?.store;
 		}
@@ -2526,11 +2803,10 @@ function registerStatefulRoutes(fastify, prefix, options, cache, createServer, T
 	});
 }
 /**
-* Resolve `expose` / `include` / `exclude` into the filtered resource list
-* `mcpPlugin` should surface. Three mutually exclusive intents:
+* Resolve `expose` / `exclude` into the filtered resource list `mcpPlugin`
+* should surface. Two mutually exclusive intents:
 *
 *  - `expose`: default-deny allowlist (preferred — new resources auto-deny).
-*  - `include`: legacy alias for `expose`, kept for back-compat.
 *  - `exclude`: default-allow opt-out (drift-prone — new resources auto-leak).
 *
 * Conflicting combinations throw with an actionable message so a host that
@@ -2564,4 +2840,4 @@ const mcpPlugin = fp(mcpPluginImpl, {
 	fastify: "5.x"
 });
 //#endregion
-export { defaultCrudDescription as a, mcpHandlerAdapter as c, toCallToolResult as d, toCallToolSuccess as f, resolveToolCollisions as h, fieldRulesToZod as i, permissionDeniedResult as l, createMcpServer as m, mcpPlugin as n, resolveCrudDescription as o, buildRequestContext as p, resourceToTools as r, invokeController as s, filterResourcesForMcp as t, toCallToolError as u };
+export { resolveToolCollisions as _, toolInputShape as a, resolveCrudDescription as c, permissionDeniedResult as d, toCallToolError as f, createMcpServer as g, buildRequestContext as h, isZodTypeSchema as i, invokeController as l, toCallToolSuccess as m, mcpPlugin as n, fieldRulesToZod as o, toCallToolResult as p, resourceToTools as r, defaultCrudDescription as s, filterResourcesForMcp as t, mcpHandlerAdapter as u };