@classytic/arc 2.21.0 → 2.23.0

package/dist/{mcpPlugin-B9XjjNVG.mjs → mcpPlugin-BtzIL_kM.mjs}

@@ -1,13 +1,14 @@
 import { p as isArcError, t as ArcError } from "./errors-DkO8Nk6-.mjs";
-import { c as getOrgId, g as getUserId } from "./types-bHblZ9YN.mjs";
-import { t as BaseController } from "./BaseController-BnLYgE9A.mjs";
-import { P as normalizePermissionResult } from "./permissions-BJMuKMl7.mjs";
+import { b as isElevated, c as getOrgId, g as getUserId, x as isMember } from "./types-bHblZ9YN.mjs";
+import { t as BaseController } from "./BaseController-BQ8KNvWC.mjs";
+import { i as applyFieldReadPermissions, r as normalizePermissionResult, s as resolveEffectiveRoles } from "./applyPermissionResult-Tw4iXtlf.mjs";
 import { t as executePipeline } from "./pipe-BOLmGIxa.mjs";
-import { i as resolvePipelineSteps, t as resolveActionPermission } from "./actionPermissions-ze70xXJi.mjs";
+import { d as buildRequestScopeProjection, i as resolvePipelineSteps, t as resolveActionPermission } from "./actionPermissions-lszoJle1.mjs";
 import { n as validateAggregations } from "./validate-C2mGgSXg.mjs";
 import { n as executeAggregation } from "./buildHandler-D_2ULWxZ.mjs";
 import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
-import { r as shouldRejectAdditionalProperties, t as normalizeSchemaIR } from "./schemaIR-ajetw3Fv.mjs";
+import { t as createIdempotencyResult } from "./interface-n5hpKg1d.mjs";
+import { r as shouldRejectAdditionalProperties, t as normalizeSchemaIR } from "./schemaIR-Ca7ySNPx.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
 import fp from "fastify-plugin";
@@ -160,6 +161,13 @@ function registerPrompt(server, prompt) {
 //#endregion
 //#region src/integrations/mcp/buildRequestContext.ts
 /**
+* @classytic/arc — MCP → IRequestContext Bridge
+*
+* Builds an IRequestContext from MCP tool input + session identity.
+* Ensures MCP tool handlers go through the same BaseController pipeline
+* as REST requests (AccessControl, BodySanitizer, QueryResolver, HookSystem).
+*/
+/**
 * Build an IRequestContext from MCP tool input and session auth.
 *
 * | Operation | params     | query                | body                |
@@ -177,7 +185,7 @@ function registerPrompt(server, prompt) {
 * the session-derived scope is `public` (i.e. MCP called with `auth: false`).
 * An authenticated session scope is never overwritten.
 */
-function buildRequestContext(input, auth, operation, policyFilters, scopeOverride) {
+function buildRequestContext(input, auth, operation, policyFilters, scopeOverride, extras) {
 	const sessionScope = buildScope(auth);
 	const scope = scopeOverride && sessionScope.kind === "public" ? scopeOverride : sessionScope;
 	const base = {
@@ -188,10 +196,13 @@ function buildRequestContext(input, auth, operation, policyFilters, scopeOverrid
 		} : null,
 		headers: {},
 		context: {},
+		scope: buildRequestScopeProjection(scope),
 		metadata: {
 			_scope: scope,
-			_policyFilters: policyFilters ?? {}
-		}
+			_policyFilters: policyFilters ?? {},
+			...extras?.arc ? { arc: extras.arc } : {}
+		},
+		...extras?.server ? { server: extras.server } : {}
 	};
 	switch (operation) {
 		case "list": return {
@@ -375,6 +386,42 @@ async function evaluatePermission(check, session, resource, action, input) {
 	}));
 }
 /**
+* Apply field-level READ permissions to an MCP tool payload — the same
+* masking `sendControllerResponse` applies on the HTTP wire and the
+* realtime plugin applies per frame. Without this, a resource declaring
+* `fields: { salary: fields.visibleTo(['admin']) }` masked salary over
+* REST and SSE but leaked it verbatim through every MCP tool.
+*
+* Mirrors the HTTP adapter's semantics exactly:
+*  - Elevated scope (platform admin) bypasses masking — consistent with
+*    `requireOrgRole()` and `BodySanitizer` bypass logic.
+*  - Effective roles = session roles ∪ org roles (member scope only),
+*    via the shared `resolveEffectiveRoles`.
+*  - `scopeOverride` (a `PermissionResult.scope`) follows the same
+*    non-downgrade rule as `buildRequestContext`: honored only when the
+*    session-derived scope is `public`.
+*
+* Handles the three payload shapes MCP tools emit: a single record, an
+* array of records, and a paginated result object carrying an inner
+* `data: T[]`. Scalars and `null` pass through untouched.
+*/
+function applyMcpReadMasking(data, options) {
+	const { fields, session, scopeOverride } = options;
+	if (!fields || data === null || typeof data !== "object") return data;
+	const sessionScope = buildScope(session);
+	const scope = scopeOverride && sessionScope.kind === "public" ? scopeOverride : sessionScope;
+	if (isElevated(scope)) return data;
+	const roles = resolveEffectiveRoles(session?.roles ?? [], isMember(scope) ? scope.orgRoles : []);
+	const maskItem = (item) => item !== null && typeof item === "object" && !Array.isArray(item) ? applyFieldReadPermissions(item, fields, roles) : item;
+	if (Array.isArray(data)) return data.map(maskItem);
+	const inner = data.data;
+	if (Array.isArray(inner)) return {
+		...data,
+		data: inner.map(maskItem)
+	};
+	return maskItem(data);
+}
+/**
 * Convert a controller response envelope into an MCP `CallToolResult`.
 * Carries `meta` into the serialized payload so consumers see pagination
 * totals, stripped-field arrays, etc.
@@ -476,6 +523,78 @@ function createMcpController(resource) {
 //#endregion
 //#region src/integrations/mcp/invokeController.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.
+*/
+/**
+* Assemble the {@link McpContextExtras} for a controller invocation from
+* resource-scoped metadata + app-level wiring. Mirrors what
+* `buildArcDecorator` (metadata.arc) and `createRequestContext` (server
+* accessor) assemble on the HTTP path.
+*/
+function buildContextExtras(options) {
+	const { wiring, resourceName, permissions, fields, schemaOptions, idField } = options;
+	if (!wiring) return void 0;
+	return {
+		arc: {
+			resourceName,
+			schemaOptions,
+			permissions,
+			hooks: wiring.hooks,
+			events: wiring.events,
+			fields,
+			idField
+		},
+		server: {
+			events: wiring.events,
+			audit: wiring.audit,
+			log: wiring.log
+		}
+	};
+}
+/**
+* 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 = 1440 * 60 * 1e3;
+const MCP_IDEMPOTENCY_LOCK_MS = 1e4;
+/**
 * Invoke a controller method through the MCP synthetic-context path.
 *
 * Runs the same chain CRUD MCP tools run:
@@ -508,7 +627,7 @@ function createMcpController(resource) {
 * checks compose.
 */
 async function invokeController(controller, op, input, options) {
-	const { session, resourceName, actionName = op, permissions, methodName = op } = options;
+	const { session, resourceName, actionName = op, permissions, methodName = op, fields, wiring, idempotencyKey } = options;
 	const ctrl = controller;
 	try {
 		const method = ctrl[methodName];
@@ -524,7 +643,39 @@ async function invokeController(controller, op, input, options) {
 			reason: permResult.reason,
 			session
 		});
-		return toCallToolResult(await method(buildRequestContext(input, session, op, permResult?.filters, permResult?.scope)));
+		const dispatch = async () => {
+			const reqCtx = buildRequestContext(input, session, op, permResult?.filters, permResult?.scope, buildContextExtras(options));
+			const response = await method(reqCtx);
+			const data = applyMcpReadMasking(response.data, {
+				fields,
+				session,
+				scopeOverride: permResult?.scope
+			});
+			return toCallToolResult(data === response.data ? response : {
+				...response,
+				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);
+			}
+		}
+		return await dispatch();
 	} catch (err) {
 		return toCallToolError(err instanceof Error ? err : new Error(String(err)));
 	}
@@ -605,13 +756,33 @@ const CRUD_ANNOTATIONS = {
 * build + envelope/error conversion all live in one place — this factory
 * only resolves the op-specific permission and threads it through.
 */
-function createCrudHandler(op, controller, resourceName, permissions) {
+/** Ops where an idempotency key is meaningful (mutations). */
+const MUTATING_CRUD_OPS = /* @__PURE__ */ new Set([
+	"create",
+	"update",
+	"delete"
+]);
+function createCrudHandler(op, controller, resourceName, permissions, fields, extras) {
 	const permission = permissions?.[op];
-	return (input, ctx) => invokeController(controller, op, input, {
-		session: ctx.session,
-		resourceName,
-		permissions: permission
-	});
+	return (input, ctx) => {
+		let idempotencyKey;
+		let payload = input;
+		if ("_idempotencyKey" in input) {
+			const { _idempotencyKey, ...rest } = input;
+			payload = rest;
+			if (MUTATING_CRUD_OPS.has(op) && typeof _idempotencyKey === "string" && _idempotencyKey) idempotencyKey = _idempotencyKey;
+		}
+		return invokeController(controller, op, payload, {
+			session: ctx.session,
+			resourceName,
+			permissions: permission,
+			fields,
+			wiring: extras?.wiring,
+			schemaOptions: extras?.schemaOptions,
+			idField: extras?.idField,
+			idempotencyKey
+		});
+	};
 }
 /**
 * Default description for a CRUD tool. Enriches list descriptions with the
@@ -630,6 +801,7 @@ function defaultCrudDescription(op, displayName, softDelete, queryMeta) {
 			if (queryMeta?.filterableFields?.length) parts.push(`Filterable fields: ${queryMeta.filterableFields.join(", ")}.`);
 			if (queryMeta?.allowedOperators?.length) parts.push(`Filter operators: ${queryMeta.allowedOperators.join(", ")} (use field[op]=value syntax).`);
 			if (queryMeta?.sortableFields?.length) parts.push(`Sortable fields: ${queryMeta.sortableFields.join(", ")}.`);
+			parts.push("Set _count: true for a count-only result, _exists: true for a boolean existence check, or _distinct: '<field>' for distinct values — all honor the same filters.");
 			return parts.join(" ");
 		}
 		case "get": return `Get a single ${singular} by ID`;
@@ -772,6 +944,9 @@ function buildListShape(fieldRules, options) {
 	const { filterableFields = [], hiddenFields = [], extraHideFields = [], allowedOperators } = options;
 	const allHidden = /* @__PURE__ */ new Set([...hiddenFields, ...extraHideFields]);
 	const shape = { ...PAGINATION_SHAPE };
+	shape._count = z.boolean().optional().describe("Return only { count } of records matching the filters — no documents fetched. Cheapest way to answer 'how many'.");
+	shape._exists = z.boolean().optional().describe("Return only whether ANY record matches the filters (boolean existence check).");
+	shape._distinct = z.string().optional().describe("Return the distinct values of this field across records matching the filters.");
 	if (!fieldRules) return shape;
 	for (const name of filterableFields) {
 		if (allHidden.has(name)) continue;
@@ -1004,7 +1179,24 @@ function convertActionSchemaToZod(raw) {
 * in the 2.10.8 review: REST and MCP action tools share identical
 * context-building machinery.
 */
-function createActionToolHandler(actionName, handler, permissions, resourceName, _resourcePermissions, rawSchema, idLess = false) {
+function createActionToolHandler(actionName, handler, permissions, resourceName, _resourcePermissions, rawSchema, idLess = false, fields, extras) {
+	const wiring = extras?.wiring;
+	const contextExtras = wiring ? {
+		arc: {
+			resourceName,
+			schemaOptions: extras?.schemaOptions,
+			permissions,
+			hooks: wiring.hooks,
+			events: wiring.events,
+			fields,
+			idField: extras?.idField
+		},
+		server: {
+			events: wiring.events,
+			audit: wiring.audit,
+			log: wiring.log
+		}
+	} : void 0;
 	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) => {
@@ -1032,11 +1224,15 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 		const reqCtx = buildRequestContext({
 			...input,
 			action: actionName
-		}, session, "action", permResult?.filters, permResult?.scope);
+		}, session, "action", permResult?.filters, permResult?.scope, contextExtras);
 		const id = idLess ? "" : typeof input.id === "string" ? input.id : "";
 		const { id: _discardId, ...data } = input;
 		try {
-			return toCallToolSuccess(await handler(id, data, reqCtx));
+			return toCallToolSuccess(applyMcpReadMasking(await handler(id, data, reqCtx), {
+				fields,
+				session,
+				scopeOverride: permResult?.scope
+			}));
 		} catch (err) {
 			return toCallToolError(err instanceof Error ? err : new Error(String(err)));
 		}
@@ -1051,7 +1247,7 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 * every aggregation opts out via `mcp: false`.
 */
 function buildAggregationTools(args) {
-	const { resourceName, displayName, aggregations, schemaOptions, repo, buildOptionsFromSession, prefix } = args;
+	const { resourceName, displayName, aggregations, schemaOptions, repo, buildOptionsFromSession, prefix, fields } = args;
 	if (!aggregations || Object.keys(aggregations).length === 0) return [];
 	const normalized = validateAggregations(resourceName, aggregations, schemaOptions);
 	const tools = [];
@@ -1075,7 +1271,8 @@ function buildAggregationTools(args) {
 				permissions: config.permissions,
 				resourceName,
 				repo,
-				buildOptionsFromSession
+				buildOptionsFromSession,
+				fields
 			})
 		});
 	}
@@ -1117,7 +1314,7 @@ function buildAggregationInputSchema(norm) {
 	return shape;
 }
 function createAggregationToolHandler(args) {
-	const { normalized, permissions, resourceName, repo, buildOptionsFromSession } = args;
+	const { normalized, permissions, resourceName, repo, buildOptionsFromSession, fields } = args;
 	return async (input, ctx) => {
 		const permResult = await evaluatePermission(permissions, ctx.session, resourceName, `aggregation:${normalized.name}`, input);
 		if (permResult && !permResult.granted) return permissionDeniedResult({
@@ -1136,7 +1333,21 @@ function createAggregationToolHandler(args) {
 			query: filterInput,
 			tenantOptions
 		});
-		if (result.status === 200) return toCallToolSuccess(result.body);
+		if (result.status === 200) {
+			const body = result.body;
+			if (fields && Array.isArray(body?.rows)) {
+				const rows = applyMcpReadMasking(body.rows, {
+					fields,
+					session: ctx.session,
+					scopeOverride: permResult?.scope
+				});
+				return toCallToolSuccess({
+					...body,
+					rows
+				});
+			}
+			return toCallToolSuccess(result.body);
+		}
 		return toCallToolError(result.body);
 	};
 }
@@ -1476,8 +1687,24 @@ function operationKindForRoute(method, hasId) {
 function createCustomRouteHandler(route, controller, hasId, options) {
 	const ctrl = controller;
 	const handlerName = typeof route.handler === "string" ? route.handler : route.operation ?? slugifyRoute(route.method, route.path);
-	const { resourceName, operationName, permissions, pipeline } = options;
+	const { resourceName, operationName, permissions, pipeline, fields, wiring } = options;
 	const pipelineSteps = resolvePipelineSteps(pipeline, operationName);
+	const contextExtras = wiring ? {
+		arc: {
+			resourceName,
+			schemaOptions: options.schemaOptions,
+			permissions,
+			hooks: wiring.hooks,
+			events: wiring.events,
+			fields,
+			idField: options.idField
+		},
+		server: {
+			events: wiring.events,
+			audit: wiring.audit,
+			log: wiring.log
+		}
+	} : void 0;
 	return async (input, _ctx) => {
 		const session = _ctx.session;
 		const permResult = await evaluatePermission(permissions, session, resourceName, operationName, input);
@@ -1488,7 +1715,18 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 			session
 		});
 		try {
-			const reqCtx = buildRequestContext(input, session, operationKindForRoute(route.method, hasId), permResult?.filters, permResult?.scope);
+			const reqCtx = buildRequestContext(input, session, operationKindForRoute(route.method, hasId), permResult?.filters, permResult?.scope, contextExtras);
+			const emit = (envelope) => {
+				const data = applyMcpReadMasking(envelope.data, {
+					fields,
+					session,
+					scopeOverride: permResult?.scope
+				});
+				return toCallToolResult(data === envelope.data ? envelope : {
+					...envelope,
+					data
+				});
+			};
 			if (typeof route.handler === "function") {
 				const fn = route.handler;
 				if (pipelineSteps.length > 0) {
@@ -1497,13 +1735,13 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 						resource: resourceName,
 						operation: operationName
 					};
-					return toCallToolResult(await executePipeline(pipelineSteps, pipeCtx, async (ctx) => {
+					return emit(await executePipeline(pipelineSteps, pipeCtx, async (ctx) => {
 						const raw = await fn(ctx);
 						return raw !== null && typeof raw === "object" && "data" in raw ? raw : { data: raw };
 					}, operationName));
 				}
 				const out = await fn(reqCtx);
-				return toCallToolResult(out !== null && typeof out === "object" && "data" in out ? out : { data: out });
+				return emit(out !== null && typeof out === "object" && "data" in out ? out : { data: out });
 			}
 			if (!ctrl) return {
 				content: [{
@@ -1520,7 +1758,7 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 				}],
 				isError: true
 			};
-			return toCallToolResult(await method(reqCtx));
+			return emit(await method(reqCtx));
 		} catch (err) {
 			return toCallToolError(err instanceof Error ? err : new Error(String(err)));
 		}
@@ -1594,6 +1832,7 @@ function resourceToTools(resource, config = {}) {
 	const hasSoftDelete = resource._appliedPresets?.includes("softDelete") ?? false;
 	const tools = [];
 	const prefix = config.toolNamePrefix;
+	const wiring = config.wiring;
 	if (controller) {
 		let ops = ALL_CRUD_OPS.filter((op) => !resource.disabledRoutes?.includes(op));
 		if (config.operations) ops = ops.filter((op) => config.operations?.includes(op));
@@ -1604,6 +1843,15 @@ function resourceToTools(resource, config = {}) {
 				allowedOperators,
 				sortableFields
 			});
+			const inputSchema = buildInputSchema(op, fieldRules, {
+				hiddenFields,
+				readonlyFields,
+				extraHideFields: config.hideFields,
+				filterableFields,
+				allowedOperators,
+				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.");
 			tools.push({
 				name,
 				description: resolveCrudDescription(config.descriptions?.[op], {
@@ -1616,15 +1864,12 @@ function resourceToTools(resource, config = {}) {
 					sortableFields
 				}),
 				annotations: CRUD_ANNOTATIONS[op],
-				inputSchema: buildInputSchema(op, fieldRules, {
-					hiddenFields,
-					readonlyFields,
-					extraHideFields: config.hideFields,
-					filterableFields,
-					allowedOperators,
-					adapterBodies
+				inputSchema,
+				handler: createCrudHandler(op, controller, resource.name, resource.permissions, resource.fields, {
+					wiring,
+					schemaOptions: resource.schemaOptions,
+					idField: resource.idField
 				}),
-				handler: createCrudHandler(op, controller, resource.name, resource.permissions),
 				source: `crud:${resource.name}:${op}`
 			});
 		}
@@ -1676,7 +1921,11 @@ function resourceToTools(resource, config = {}) {
 				resourceName: resource.name,
 				operationName: opName,
 				permissions: route.permissions,
-				pipeline: resource.pipe
+				pipeline: resource.pipe,
+				fields: resource.fields,
+				wiring,
+				schemaOptions: resource.schemaOptions,
+				idField: resource.idField
 			})
 		});
 	}
@@ -1707,7 +1956,11 @@ function resourceToTools(resource, config = {}) {
 			annotations,
 			inputSchema: inputShape,
 			source: `action:${resource.name}:${actionName}`,
-			handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema, idLess)
+			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) {
@@ -1734,7 +1987,8 @@ function resourceToTools(resource, config = {}) {
 			schemaOptions: resource.schemaOptions,
 			repo: repoForAgg,
 			buildOptionsFromSession,
-			prefix
+			prefix,
+			fields: resource.fields
 		}));
 	}
 	return tools;
@@ -1944,10 +2198,29 @@ const mcpPluginImpl = async (fastify, options) => {
 		include: options.include,
 		exclude: options.exclude
 	});
+	const fastifyAny = fastify;
+	const wiring = {
+		get hooks() {
+			return fastifyAny.arc?.hooks;
+		},
+		get events() {
+			return fastifyAny.events;
+		},
+		get audit() {
+			return fastifyAny.audit;
+		},
+		get log() {
+			return fastify.log;
+		},
+		get idempotencyStore() {
+			return fastifyAny.idempotency?.store;
+		}
+	};
 	const overrides = options.overrides ?? {};
 	const allTools = enabledResources.flatMap((r) => {
 		const resOverrides = overrides[r.name] ?? {};
 		return resourceToTools(r, {
+			wiring,
 			...resOverrides,
 			toolNamePrefix: resOverrides.toolNamePrefix ?? options.toolNamePrefix
 		});

package/dist/middleware/index.d.mts

@@ -1,4 +1,4 @@
-import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-Dtrj6XZk.mjs";
+import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-BBsvQt7U.mjs";
 import { RouteHandlerMethod } from "fastify";
 //#region src/middleware/middleware.d.ts
 interface NamedMiddleware {

package/dist/{module-WeuU5jfd.d.mts → module-B4u10iOJ.d.mts}

@@ -1,4 +1,4 @@
-import { n as ErrorMapper } from "./errorHandler-B0e-bq-O.mjs";
+import { n as ErrorMapper } from "./errorHandler-C6yv4ZTW.mjs";
 import { FastifyInstance } from "fastify";
 //#region src/factory/loadResources.d.ts
 /**
@@ -306,6 +306,31 @@ interface ArcModule<TExports = unknown> {
    * ```
    */
   bootstrap?: (fastify: FastifyInstance) => TExports | Promise<TExports>;
+  /**
+   * App-level resource NAMES this module authoritatively SUPERSEDES. When the
+   * host also lists (or `resourceDir`-discovers) a resource of the same name,
+   * arc DROPS the app copy and registers THIS module's version instead — so the
+   * host keeps NO hand-maintained "which resources did modules take over" filter
+   * set. Ownership lives on the atom that provides it (colocated, drift-proof):
+   *
+   * ```ts
+   * defineModule({ name: "order", owns: ["order", "quotation", "rfq"], resources: () => [...] })
+   * ```
+   *
+   * Semantics:
+   *   - Purely a supersede-the-app-fork switch — it filters the *app* resource
+   *     list, never the module's own `resources` (those always register).
+   *   - Static + declarative: read at compose time, so it works regardless of
+   *     whether `resources` is an array or a post-bootstrap factory (no early
+   *     factory resolution, no boot-order coupling).
+   *   - Idempotent + tolerant: an `owns` entry with no matching app resource is
+   *     a silent no-op — a module may pre-declare a name before any fork exists.
+   *   - Collected across ALL modules; the app-side supersession is their union.
+   *
+   * Contract: if you `owns` a name, PROVIDE it (in this module's `resources`).
+   * Dropping the app fork without supplying a replacement removes the route.
+   */
+  readonly owns?: readonly string[];
   /**
    * The module's resources. Array or factory — the factory form runs AFTER all
    * bootstraps, so `defineResource(...)` receives fully-booted engines. Flows

package/dist/{openapi-Kyod_di6.mjs → openapi-jSDx-VDv.mjs}

@@ -1,8 +1,8 @@
 import { t as getUserRoles } from "./types-XTApa8b6.mjs";
-import { n as convertRouteSchema } from "./schemaConverter-U0MnO9vd.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-ze70xXJi.mjs";
+import { n as convertRouteSchema } from "./schemaConverter-DJvodiHj.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-lszoJle1.mjs";
 import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-BWMDW-dL.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-BuOv-m4Y.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi/canonical-schemas.ts
 /**

package/dist/permissions/index.d.mts

@@ -1,3 +1,4 @@
-import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, f as getUserRoles, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, p as normalizeRoles, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission, u as PermissionResult } from "../fields-BGqrAa_u.mjs";
-import { A as requireOwnership, B as requireMandate, C as createOrgPermissions, D as denyAll, E as anyOf, F as normalizePermissionResult, I as RequireAgentScopeOptions, L as RequireMandateOptions, M as roles, N as when, O as not, P as applyPermissionResult, R as requireAgentScope, S as createDynamicPermissionMatrix, T as allowPublic, _ as createRoleHierarchy, a as permissionMatrix, b as DynamicPermissionMatrixConfig, c as publicReadAdminWrite, d as requireOrgMembership, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, j as requireRoles, k as requireAuth, l as readOnly, m as requireServiceScope, n as authenticated, o as presets_d_exports, p as requireScopeContext, r as fullPublic, s as publicRead, t as adminOnly, u as requireOrgInScope, v as ConnectEventsOptions, w as allOf, x as PermissionEventBus, y as DynamicPermissionMatrix, z as requireDPoP } from "../index-B5PoNbfu.mjs";
-export { type ConnectEventsOptions, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, type PermissionCheck, type PermissionContext, type PermissionEventBus, type PermissionResult, type RequireAgentScopeOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };
+import { a as getUserRoles, i as UserBase, n as PermissionContext, o as normalizeRoles, r as PermissionResult, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-D3lhgzhD.mjs";
+import { A as allOf, B as applyPermissionResult, C as requireGrant, D as PermissionEventBus, E as DynamicPermissionMatrixConfig, F as requireAuth, G as requireDPoP, H as RequireAgentScopeOptions, I as requireOwnership, K as requireMandate, L as requireRoles, M as anyOf, N as denyAll, O as createDynamicPermissionMatrix, P as not, R as roles, S as modeSatisfies, T as DynamicPermissionMatrix, U as RequireMandateOptions, V as normalizePermissionResult, W as requireAgentScope, _ as createRoleHierarchy, a as permissionMatrix, b as GrantResolution, c as publicReadAdminWrite, d as requireOrgMembership, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, j as allowPublic, k as createOrgPermissions, l as readOnly, m as requireServiceScope, n as authenticated, o as presets_d_exports, p as requireScopeContext, r as fullPublic, s as publicRead, t as adminOnly, u as requireOrgInScope, v as GRANT_MODES, w as ConnectEventsOptions, x as RequireGrantOptions, y as GrantMode, z as when } from "../index-wMoWBLkn.mjs";
+export { type ConnectEventsOptions, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, GRANT_MODES, type GrantMode, type GrantResolution, type PermissionCheck, type PermissionContext, type PermissionEventBus, type PermissionResult, type RequireAgentScopeOptions, type RequireGrantOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, modeSatisfies, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/permissions/index.mjs

@@ -1,3 +1,4 @@
-import { A as requireDPoP, C as not, D as roles, E as requireRoles, F as applyFieldReadPermissions, I as applyFieldWritePermissions, L as fields, M as applyPermissionResult, O as when, P as normalizePermissionResult, R as resolveEffectiveRoles, S as denyAll, T as requireOwnership, _ as requireServiceScope, a as permissionMatrix, b as allowPublic, c as publicReadAdminWrite, d as createDynamicPermissionMatrix, f as createOrgPermissions, g as requireScopeContext, h as requireOrgRole, i as ownerWithAdminBypass, j as requireMandate, k as requireAgentScope, l as readOnly, m as requireOrgMembership, n as authenticated, o as presets_exports, p as requireOrgInScope, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as requireTeamMembership, w as requireAuth, x as anyOf, y as allOf } from "../permissions-BJMuKMl7.mjs";
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, o as fields, r as normalizePermissionResult, s as resolveEffectiveRoles, t as applyPermissionResult } from "../applyPermissionResult-Tw4iXtlf.mjs";
 import { n as normalizeRoles, t as getUserRoles } from "../types-XTApa8b6.mjs";
-export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };
+import { A as roles, C as allowPublic, D as requireAuth, E as not, M as requireAgentScope, N as requireDPoP, O as requireOwnership, P as requireMandate, S as allOf, T as denyAll, _ as requireOrgMembership, a as permissionMatrix, b as requireServiceScope, c as publicReadAdminWrite, d as GRANT_MODES, f as modeSatisfies, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as when, k as requireRoles, l as readOnly, m as createDynamicPermissionMatrix, n as authenticated, o as presets_exports, p as requireGrant, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as requireOrgRole, w as anyOf, x as requireTeamMembership, y as requireScopeContext } from "../permissions-tbxFHxjZ.mjs";
+export { GRANT_MODES, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, modeSatisfies, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };