@classytic/arc 2.31.0 → 2.33.0

package/dist/{defineResource-Bv6EtN1x.mjs → defineResource-DR9vsUYy.mjs}

@@ -1,22 +1,23 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-D3Dv4LAV.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { p as MUTATION_OPERATIONS, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-BxCoxmiN.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { r as ForbiddenError } from "./errors-Cj42AntO.mjs";
-import { n as getUserRoles } from "./userHelpers-ChYJ6CdK.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-Cys0ko9Z.mjs";
-import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-De7GqHck.mjs";
-import { a as buildRouteHooks, c as buildAuthMiddleware, i as selectPluginMw, n as buildRouteConfig, o as resolveRoutePreHandlers, r as resolveRouterPluginMw, s as routeHookOptions, t as buildRateLimitConfig, u as buildArcDecorator } from "./rateLimit-CMPY5Qms.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-CB5Cuzk9.mjs";
-import { r as buildCrudPermissionMw, t as tryRegisterRoute } from "./registerRoute-CBN84fc7.mjs";
-import { c as getDefaultCrudSchemas } from "./utils-vL8BrDE2.mjs";
-import { n as convertRouteSchema, r as ensureSchemaConverter, t as convertOpenApiSchemas } from "./schemaConverter-D--wdJM-.mjs";
-import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-PSZwi8JV.mjs";
-import { t as hasEvents } from "./typeGuards-B0ryPo3I.mjs";
-import { a as createFastifyHandler, i as createCrudHandlers, n as buildPipelineHandler, o as createRequestContext, r as resolvePipelineSteps } from "./pipeline-UPQFatit.mjs";
-import { I as requireAuth } from "./permissions-L--QDAir.mjs";
-import { r as getAvailablePresets, t as applyPresets } from "./presets-C4-g4_4P.mjs";
-import { t as pluralize } from "./pluralize-O0FZgESl.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-BE5NwaQk.mjs";
+import { r as ForbiddenError } from "./errors-Cd_yy7aW.mjs";
+import { n as getUserRoles } from "./userHelpers-CWF5pbZD.mjs";
+import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-CoqIRrkY.mjs";
+import { d as isWriteVerbCapable, p as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController, u as detectOverriddenWriteSlots } from "./BaseController-CaQC5EXX.mjs";
+import { a as buildRouteHooks, c as buildAuthMiddleware, i as selectPluginMw, n as buildRouteConfig, o as resolveRoutePreHandlers, r as resolveRouterPluginMw, s as routeHookOptions, t as buildRateLimitConfig, u as buildArcDecorator } from "./rateLimit-D4-ASwsI.mjs";
+import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-CojeUkS4.mjs";
+import { r as buildCrudPermissionMw, t as tryRegisterRoute } from "./registerRoute-DNnd3vkz.mjs";
+import { c as getDefaultCrudSchemas } from "./utils-h1V_sT-t.mjs";
+import { n as convertRouteSchema, r as ensureSchemaConverter, t as convertOpenApiSchemas } from "./schemaConverter-XH1RZRyu.mjs";
+import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-DsT1B5zJ.mjs";
+import { t as hasEvents } from "./typeGuards-jjKJDN13.mjs";
+import { a as createFastifyHandler, i as createCrudHandlers, n as buildPipelineHandler, o as createRequestContext, r as resolvePipelineSteps } from "./pipeline-q69DZzgG.mjs";
+import { B as requireAuth } from "./permissions-BAfwgBxc.mjs";
+import { r as getAvailablePresets, t as applyPresets } from "./presets-D-h0uWtP.mjs";
+import { t as pluralize } from "./pluralize-B7xf8qZF.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-CUeCmpUd.mjs";
+import { isReadOnlyRepo } from "@classytic/repo-core/repository";
 //#region src/core/middlewares/fieldWrite.ts
 /**
 * Build a preHandler that enforces field-write permissions on the request body.
@@ -42,7 +43,10 @@ function buildFieldWritePreHandler(fieldPermissions, policy = DEFAULT_FIELD_WRIT
 		if (!body || typeof body !== "object" || Array.isArray(body)) return;
 		const scope = request.scope ?? PUBLIC_SCOPE;
 		if (isElevated(scope)) return;
-		const { body: filtered, deniedFields } = applyFieldWritePermissions(body, fieldPermissions, resolveEffectiveRoles(getUserRoles(request.user), isMember(scope) ? scope.orgRoles : []));
+		const globalRoles = getUserRoles(request.user);
+		const orgRoles = isMember(scope) ? scope.orgRoles : [];
+		const effectiveRoles = resolveEffectiveRoles(globalRoles, orgRoles);
+		const { body: filtered, deniedFields } = applyFieldWritePermissions(body, fieldPermissions, effectiveRoles);
 		if (deniedFields.length > 0 && policy === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
 		request.body = filtered;
 	};
@@ -58,6 +62,18 @@ function methodCarriesBody(method) {
 //#endregion
 //#region src/core/createCrudRouter.ts
 /**
+* Fold a route's host-supplied `config` together with arc's derived one into the
+* SINGLE `config` key Fastify reads. Returns arc's object untouched when the host
+* supplied none, so the route options stay literally what was declared.
+*/
+function mergeRouteConfig(hostConfig, arcConfig) {
+	if (!hostConfig) return arcConfig;
+	return { config: {
+		...hostConfig,
+		...arcConfig.config ?? {}
+	} };
+}
+/**
 * Mount custom routes (from presets or user-defined `routes`) on Fastify.
 * `wrapHandler` is derived inline from whether `rawHandler` was set.
 */
@@ -114,8 +130,9 @@ function createCustomRoutes(fastify, routes, controller, options) {
 			const fieldWriteMw = buildFieldWritePreHandler(fieldPermissions, onFieldWriteDenied);
 			if (fieldWriteMw) customPreHandlers.push(fieldWriteMw);
 		}
+		const preAuthHandlers = route.preAuth ?? [];
 		const hooks = buildRouteHooks({
-			preAuth: route.preAuth ?? [],
+			preAuth: preAuthHandlers,
 			arcDecorator,
 			authMw: buildAuthMiddleware(fastify, route.permissions),
 			permissionMw: buildCrudPermissionMw(route.permissions, resourceName, opName),
@@ -140,7 +157,25 @@ function createCustomRoutes(fastify, routes, controller, options) {
 				}
 				return result;
 			} : handler,
-			...buildRouteConfig(route.rateLimit !== void 0 ? buildRateLimitConfig(route.rateLimit) : rateLimitConfig, extensions, route.cors)
+			/**
+			* ONE `config` object, merging the host's `route.config` with arc's own
+			* derived keys (per-route rate limit, cors, `arcExtensions`).
+			*
+			* It has to be merged HERE because Fastify does not merge for us: it
+			* builds the context from a single `opts.config`
+			* (`{ ...opts.config, url, method }` — lib/route.js), so two spreads
+			* writing `config` means the later one silently replaces the earlier.
+			* Emitting them separately dropped `route.config` on every resource
+			* that declared extensions, a rate limit or per-route cors — which is
+			* the same silent-absence bug `config` was added to fix, just narrowed
+			* to the resources most likely to have it.
+			*
+			* Arc's derived keys win on collision: they come from the declared
+			* `route.rateLimit` / `route.cors` / `extensions` fields, so letting a
+			* hand-written `config.rateLimit` override them would give one setting
+			* two sources that can disagree.
+			*/
+			...mergeRouteConfig(route.config, buildRouteConfig(route.rateLimit !== void 0 ? buildRateLimitConfig(route.rateLimit) : rateLimitConfig, extensions, route.cors))
 		}, {
 			resourceName,
 			op: opName
@@ -287,7 +322,8 @@ function buildCrudHandlers(ctrl, pipeline, resourceName) {
 	for (const op of CRUD_OPERATIONS) {
 		const steps = resolvePipelineSteps(pipeline, op);
 		if (steps.length === 0) continue;
-		wrapped[op] = buildPipelineHandler(ctrl[op].bind(ctrl), steps, op, resourceName);
+		const method = ctrl[op].bind(ctrl);
+		wrapped[op] = buildPipelineHandler(method, steps, op, resourceName);
 	}
 	return wrapped;
 }
@@ -300,6 +336,77 @@ function createPermissionMiddleware(permission, resourceName, action) {
 	return buildCrudPermissionMw(permission, resourceName, action);
 }
 //#endregion
+//#region src/core/defineResource/writeVerbs.ts
+/**
+* Phase 4b — write-verb registration policy.
+*
+* A declared command that never executes is the defect `writes` exists to
+* close, one layer up: the resource READS as though the kernel's guarded verb
+* owns the slot while generic CRUD serves the route. So reachability is
+* enforced at REGISTRATION, fail-loud (same posture as `threadQueryParser`):
+*
+*   1. the controller must DISPATCH `_writes` — proven by a prototype
+*      capability mark, not by a duck-typed `configure()`, which shows an
+*      options channel exists and not that anything reads `writes` from it;
+*   2. no declared verb's slot may be OVERRIDDEN — route dispatch calls the
+*      override, so the verb behind it is dead code. Holds even for overrides
+*      that delegate to `super`: unprovable statically, so the combination is
+*      forbidden. Wrap behaviour with `hooks` instead.
+*
+* Config-SHAPE validation (unknown keys, non-function entries, disabled slots)
+* needs no controller and lives in `validateResourceConfig`.
+*/
+/**
+* The write slots, as a runtime list. `MUTATION_OPERATIONS` is the canonical
+* constant; `satisfies` pins it to the `WriteVerbKey` type so the two cannot
+* drift without a compile error.
+*/
+const WRITE_VERBS = MUTATION_OPERATIONS;
+/** The verbs a resource actually declared (function-valued entries only). */
+function declaredWriteVerbs(writes) {
+	if (!writes) return [];
+	return WRITE_VERBS.filter((op) => typeof writes[op] === "function");
+}
+/**
+* Boot-fatal reachability check for declared write verbs on a HOST-SUPPLIED
+* controller. Auto-built controllers never call this — they are capable and
+* un-overridden by construction.
+*
+* Throws before any option threading, so a rejected resource has no partial
+* side effects to reason about.
+*/
+function enforceWriteVerbReachability(controller, resolvedConfig) {
+	const declared = declaredWriteVerbs(resolvedConfig.writes);
+	if (declared.length === 0) return;
+	if (typeof controller !== "object" || controller === null || !isWriteVerbCapable(controller)) throw new Error(`Resource "${resolvedConfig.name}" declares write verb(s) [${declared.join(", ")}] but its controller is not built on arc's write pipeline, so the verbs would be silently dropped and generic CRUD would serve those routes — the exact bypass \`writes\` exists to close. Extend \`BaseController\` / \`BaseCrudController\` (their write methods dispatch declared verbs), or omit \`controller\` and let arc auto-build one, or move the commands into the controller itself and remove \`writes\`.`);
+	const collisions = detectOverriddenWriteSlots(controller, declared);
+	if (collisions.length > 0) throw new Error(`Resource "${resolvedConfig.name}" declares write verb(s) [${collisions.join(", ")}] AND overrides the controller method(s) for the same slot(s). Route dispatch calls the override, so the declared verb can never execute — it is dead code that reads as if it guards the route. Keep exactly one owner per slot: remove the override and let the verb own persistence (wrap request-level behaviour with \`hooks\` — before/around/after run around the verb), or remove the \`writes\` entry and let the override own the whole pipeline.`);
+}
+/**
+* Warn when a controller OVERRIDES a write method while the resource declares
+* field rules only arc's pipeline enforces.
+*
+* Measured: a resource with eight `systemManaged` fields overrode `update` to
+* reach its kernel's guarded verb; `PATCH` then wrote `status: "posted"` and a
+* forged `number` straight through, answering 200. The override was added to
+* close one hole and opened a wider one.
+*
+* Scoped so it stays worth reading: write-verb-capable controllers only,
+* BODY-BEARING ops only (`delete` carries no body for the sanitizer), and only
+* when protection is actually declared. A slot WITH a verb never reaches here —
+* `enforceWriteVerbReachability` already threw.
+*/
+function warnOnWriteMethodOverride(controller, resolvedConfig) {
+	if (typeof controller !== "object" || controller === null || !isWriteVerbCapable(controller)) return;
+	const fieldRules = resolvedConfig.schemaOptions?.fieldRules;
+	const protectedFields = fieldRules ? Object.keys(fieldRules) : [];
+	const hasFieldPermissions = resolvedConfig.fields !== void 0 && Object.keys(resolvedConfig.fields).length > 0;
+	if (protectedFields.length === 0 && !hasFieldPermissions) return;
+	const overridden = detectOverriddenWriteSlots(controller, ["create", "update"]);
+	if (overridden.length === 0) return;
+	arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" overrides controller method(s) [${overridden.join(", ")}] AND declares field protection (${protectedFields.length > 0 ? `fieldRules: ${protectedFields.join(", ")}` : "fields"}). An override replaces arc's entire write pipeline — body sanitization against those field rules, tenant injection, createdBy/updatedBy stamping and the before/around/after hooks all stop running for that op, so the declared protection is NOT enforced. If the override exists to reach a domain command, declare it as a write verb instead (\`writes: { ${overridden[0]}: (…) => engine.<verb>(…) } \`) — arc keeps the pipeline and calls your command in place of the repository. If the override genuinely needs to replace the pipeline, call \`this.bodySanitizer.sanitize(body, op, req, ctx)\` inside it.`);
+}
+//#endregion
 //#region src/core/defineResource/controller.ts
 /**
 * Phase 4 — pick (or auto-create) the resource's controller.
@@ -319,17 +426,33 @@ function createPermissionMiddleware(permission, resourceName, action) {
 * lists the dropped options, and points at the canonical fix. All
 * warns honour `ARC_SUPPRESS_WARNINGS=1` via `arcLog()`.
 */
+/** CRUD routes refused over a read-only repository. */
+const READ_ONLY_REFUSED_ROUTES = [
+	"create",
+	"update",
+	"delete"
+];
 /**
 * Resolve the controller for the resource. See module docstring for
 * branch semantics.
 */
 function resolveOrAutoCreateController(resolvedConfig, adapter, repository, hasCrudRoutes) {
 	const userController = resolvedConfig.controller;
+	if (resolvedConfig.transactional === true) {
+		if (typeof repository?.withTransaction !== "function") throw new Error(`Resource "${resolvedConfig.name}" declares \`transactional: true\` but its repository has no \`withTransaction\` (capability \`transactions: false\` — D1, standalone Mongo). Wire a transactional kit, or remove the flag; arc will not silently drop a requested transaction envelope.`);
+	}
+	if (repository && isReadOnlyRepo(repository)) {
+		const disabled = new Set(resolvedConfig.disabledRoutes ?? []);
+		const enabledWrites = READ_ONLY_REFUSED_ROUTES.filter((op) => !resolvedConfig.disableDefaultRoutes && !disabled.has(op));
+		if (enabledWrites.length > 0) throw new Error(`Resource "${resolvedConfig.name}" mounts write routes (${enabledWrites.join(", ")}) over a READ-ONLY repository — its rows are owned by another component that enforces invariants generic CRUD would bypass (Better Auth hashes passwords, revokes sessions, and cascades org membership on every write it performs). Disable the write routes (\`disabledRoutes: ['create', 'update', 'delete']\`), or if raw writes are genuinely required, build the repository with the kit's explicit \`unsafeWritable: true\` opt-in.`);
+	}
 	if (userController) {
 		threadQueryParser(userController, resolvedConfig);
+		enforceWriteVerbReachability(userController, resolvedConfig);
 		threadConfigureLifecycle(userController, resolvedConfig, adapter);
 		warnOnDroppedAuthorOptions(resolvedConfig);
 		warnOnDroppedPresetOptions(resolvedConfig);
+		warnOnWriteMethodOverride(userController, resolvedConfig);
 		return userController;
 	}
 	if (!hasCrudRoutes || !repository) return void 0;
@@ -365,7 +488,16 @@ function threadConfigureLifecycle(controller, resolvedConfig, adapter) {
 	if (resolvedConfig.defaultSort !== void 0 && wasDeclared("defaultSort")) opts.defaultSort = resolvedConfig.defaultSort;
 	if (resolvedConfig.cache !== void 0 && wasDeclared("cache")) opts.cache = resolvedConfig.cache;
 	if (resolvedConfig.onFieldWriteDenied !== void 0 && wasDeclared("onFieldWriteDenied")) opts.onFieldWriteDenied = resolvedConfig.onFieldWriteDenied;
+	if (resolvedConfig.onImmutableWrite !== void 0 && wasDeclared("onImmutableWrite")) opts.onImmutableWrite = resolvedConfig.onImmutableWrite;
 	if (resolvedConfig.queryParser !== void 0 && wasDeclared("queryParser")) opts.queryParser = resolvedConfig.queryParser;
+	/**
+	* NOT gated on `_declaredKeys`: `writes` is never inferred or injected by a
+	* preset, so its presence IS the declaration. Gating it would mean a
+	* resource that declares write verbs alongside its own controller silently
+	* kept generic CRUD — the exact bypass the seam exists to close.
+	*/
+	if (resolvedConfig.writes !== void 0) opts.writes = resolvedConfig.writes;
+	if (resolvedConfig.transactional !== void 0) opts.transactional = resolvedConfig.transactional;
 	if (adapter?.matchesFilter !== void 0) opts.matchesFilter = adapter.matchesFilter;
 	if (resolvedConfig._controllerOptions) opts.presetFields = {
 		slugField: resolvedConfig._controllerOptions.slugField,
@@ -415,6 +547,7 @@ function warnOnDroppedAuthorOptions(resolvedConfig) {
 	if (resolvedConfig.defaultSort !== void 0 && isDeclared("defaultSort")) dropped.push("defaultSort");
 	if (resolvedConfig.cache !== void 0 && isDeclared("cache")) dropped.push("cache");
 	if (resolvedConfig.onFieldWriteDenied !== void 0 && isDeclared("onFieldWriteDenied")) dropped.push("onFieldWriteDenied");
+	if (resolvedConfig.onImmutableWrite !== void 0 && isDeclared("onImmutableWrite")) dropped.push("onImmutableWrite");
 	if (dropped.length === 0) return;
 	arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" declares a custom controller AND resource-level option(s) [${dropped.join(", ")}]. Arc only threads these when it auto-builds the controller — when you pass your own, they are dropped silently and the controller falls back to its own defaults (e.g. tenantField → 'organizationId'). Either implement \`configure(opts)\` on the controller (arc 2.15+ canonical) or forward them via \`super(repo, { ... })\`. Same root cause as the \`queryParser\` warn above.`);
 }
@@ -459,12 +592,34 @@ function buildBaseController(resolvedConfig, adapter, repository) {
 		matchesFilter: adapter?.matchesFilter,
 		cache: resolvedConfig.cache,
 		onFieldWriteDenied: resolvedConfig.onFieldWriteDenied,
+		onImmutableWrite: resolvedConfig.onImmutableWrite,
+		/**
+		* Domain commands for the write slots. Threaded here rather than
+		* subclassing: the pipeline stays arc's and the command stays the
+		* kernel's, so neither has to be re-implemented to reach the other.
+		*/
+		writes: resolvedConfig.writes,
+		transactional: resolvedConfig.transactional === true,
 		presetFields: resolvedConfig._controllerOptions ? {
 			slugField: resolvedConfig._controllerOptions.slugField,
 			parentField: resolvedConfig._controllerOptions.parentField
 		} : void 0
 	});
 }
+/**
+* The DEFERRED half of the `transactional: true` gate — run at resource
+* registration, after `beforeBoot()` has had its chance to connect.
+*
+* Fail-closed: anything other than a confirmed `true` refuses the boot. A
+* repository with NO capability descriptor (hand-written, custom kit) passes
+* — it never promised one, and the define-time presence check already covered
+* the only signal it offers.
+*/
+function assertTransactionCapability(repository, resourceName) {
+	const capabilities = repository?.capabilities;
+	if (!capabilities || capabilities.transactions === true) return;
+	throw new Error(`Resource "${resourceName}" declares \`transactional: true\` but its repository reports \`capabilities.transactions: ${String(capabilities.transactions)}\` — this deployment cannot run transactions (standalone MongoDB, D1, or a topology arc could not confirm). \`withTransaction\` exists but every call would fail at BEGIN. Point at a replica set / transactional backend, or remove the flag. Checked at REGISTRATION, so a connection opened in \`beforeBoot()\` is already live by now.`);
+}
 //#endregion
 //#region src/core/defineResource/hooks.ts
 /**
@@ -965,7 +1120,7 @@ function collectUngatedCrudDiagnostics(config, strict = false) {
 		code: "crud-public-by-omission",
 		message: `[Arc] Resource '${config.name}' mounts ${ungated.length} CRUD route(s) with no permission gate: ${ungated.join(", ")}.\n` + (severity === "error" ? "strictPermissions is on and an ungated WRITE is fatal. State intent explicitly:\n" : "An omitted permission mounts the route WITHOUT auth. State intent explicitly:\n") + `  permissions: permissions.fullPublic()     // intentionally public
   permissions: permissions.authenticated()  // require auth on every op
-  permissions: { ${ungated[0]}: requireAuth(), ... }  // per-operation`
+  permissions: { ${ungated[0]}: requireAuth(), ... }  // per-operation` + (severity === "warn" ? "\nRecommended in production: ARC_STRICT_PERMISSIONS=true (or `strictPermissions: true` on the resource) makes an ungated WRITE fail the boot instead of shipping. This is the arc v3 default." : "")
 	}];
 }
 //#endregion
@@ -1209,6 +1364,7 @@ function buildResourcePlugin(resource) {
 		const sharedRoot = fastify.server;
 		const isFirstMount = !resource._sharedStateRegisteredOn.has(sharedRoot);
 		if (isFirstMount) resource._sharedStateRegisteredOn.add(sharedRoot);
+		if (isFirstMount && resource._deferredChecks?.length) for (const check of resource._deferredChecks) check();
 		if (isFirstMount && resource._diagnostics?.length) for (const diagnostic of resource._diagnostics) {
 			const level = diagnostic.severity === "info" ? "info" : diagnostic.severity === "error" ? "error" : "warn";
 			fastify.log?.[level]?.(diagnostic.message);
@@ -1226,11 +1382,13 @@ function buildResourcePlugin(resource) {
 			handler: hook.handler,
 			priority: hook.priority
 		});
-		if (isFirstMount && resource.cache?.invalidateOn) if (fastify.registerCacheInvalidationRule) for (const [pattern, tags] of Object.entries(resource.cache.invalidateOn)) fastify.registerCacheInvalidationRule({
-			pattern,
-			tags
-		});
-		else fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares \`cache.invalidateOn\` but \`queryCachePlugin\` is not registered. Cache-invalidation rules are silently ignored. Either register the plugin (\`await fastify.register(queryCachePlugin, ...)\`) or remove the \`cache.invalidateOn\` config to clean up the resource definition.`);
+		if (isFirstMount && resource.cache?.invalidateOn) {
+			if (fastify.registerCacheInvalidationRule) for (const [pattern, tags] of Object.entries(resource.cache.invalidateOn)) fastify.registerCacheInvalidationRule({
+				pattern,
+				tags
+			});
+			else fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares \`cache.invalidateOn\` but \`queryCachePlugin\` is not registered. Cache-invalidation rules are silently ignored. Either register the plugin (\`await fastify.register(queryCachePlugin, ...)\`) or remove the \`cache.invalidateOn\` config to clean up the resource definition.`);
+		}
 		if (isFirstMount && resource.audit) {
 			if (!(fastify.hasDecorator("audit") && typeof fastify.audit?.create === "function" && fastify.audit?._noop !== true)) fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares \`audit: ${JSON.stringify(resource.audit)}\` but \`auditPlugin\` is not registered (or is registered with a noop logger). Audit events for this resource will NOT be recorded. Either register \`auditPlugin\` (\`await fastify.register(auditPlugin, { store: ... })\`) or remove the \`audit\` flag from the resource definition.`);
 		}
@@ -1271,7 +1429,7 @@ function buildResourcePlugin(resource) {
 				extensions: resource.extensions
 			});
 			if (resource.actions && Object.keys(resource.actions).length > 0) {
-				const { createActionRouter } = await import("./createActionRouter-CDXEdasl.mjs").then((n) => n.n);
+				const { createActionRouter } = await import("./createActionRouter-DVpoA0do.mjs").then((n) => n.n);
 				createActionRouter(typedInstance, {
 					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
 					resourceName: resource.name,
@@ -1286,7 +1444,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-KrQDzx-k.mjs"), import("./validate-_KbifpHF.mjs").then((n) => n.r)]);
+				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-B_B48JZ-.mjs"), import("./validate-CdQlz52F.mjs").then((n) => n.r)]);
 				const repoForAgg = resource.controller?.repository ?? resource.repository;
 				if (!adapterSupportsAggregate(repoForAgg)) {
 					const undispatchable = Object.entries(resource.aggregations).filter(([, cfg]) => !cfg.materialized).map(([name]) => name);
@@ -1399,6 +1557,22 @@ var ResourceDefinition = class {
 	*/
 	_diagnostics;
 	/**
+	* Boot-time assertions that CANNOT be settled at define time because
+	* they read state a connection establishes.
+	*
+	* `defineResource()` frequently runs at module-import time — before
+	* `beforeBoot()` opens the database. A repository's capability
+	* descriptor is therefore not yet authoritative then: mongokit
+	* deliberately reports `transactions: false` for an unresolved topology
+	* (fail-closed), so asserting at define time would reject a correctly
+	* configured app for the crime of importing its resources early.
+	*
+	* `buildResourcePlugin` runs these on first mount — lifecycle slot 5,
+	* after `beforeBoot` (0) and module resolution (0.5) — where the same
+	* fail-closed rule finally means what it says.
+	*/
+	_deferredChecks;
+	/**
 	* Public view of {@link _diagnostics} for programmatic consumption.
 	*
 	* Returns the collected define-time diagnostics for this resource.
@@ -1486,10 +1660,12 @@ var ResourceDefinition = class {
 	_validateControllerMethods() {
 		const errors = [];
 		const enabledCrudRoutes = CRUD_OPERATIONS.filter((route) => !this.disabledRoutes.includes(route));
-		if (!this.disableDefaultRoutes && enabledCrudRoutes.length > 0) if (!this.controller) errors.push("Controller is required when CRUD routes are enabled");
-		else {
-			const ctrl = this.controller;
-			for (const method of enabledCrudRoutes) if (typeof ctrl[method] !== "function") errors.push(`CRUD method '${method}' not found on controller`);
+		if (!this.disableDefaultRoutes && enabledCrudRoutes.length > 0) {
+			if (!this.controller) errors.push("Controller is required when CRUD routes are enabled");
+			else {
+				const ctrl = this.controller;
+				for (const method of enabledCrudRoutes) if (typeof ctrl[method] !== "function") errors.push(`CRUD method '${method}' not found on controller`);
+			}
 		}
 		for (const route of this.routes) {
 			if (typeof route.handler !== "string") continue;
@@ -1542,6 +1718,7 @@ var ResourceDefinition = class {
 				summary: r.summary,
 				description: r.description,
 				permissions: r.permissions,
+				capability: r.capability,
 				raw: r.rawHandler !== void 0,
 				schema: r.schema
 			})),
@@ -1784,6 +1961,41 @@ function validateResourceConfig(config, options = {}) {
 		message: "Resource has no adapter and no routes",
 		suggestion: "Provide either adapter for CRUD or routes for custom logic"
 	});
+	if (config.writes) {
+		const writeVerbSlots = MUTATION_OPERATIONS;
+		const entries = Object.entries(config.writes);
+		const unknownKeys = entries.map(([key]) => key).filter((key) => !writeVerbSlots.includes(key));
+		if (unknownKeys.length > 0) errors.push({
+			field: "writes",
+			message: `Unknown write verb slot(s) [${unknownKeys.join(", ")}] — only [${writeVerbSlots.join(", ")}] exist. An unknown slot is silently never called, so the command it names guards nothing`,
+			suggestion: "Rename to a real slot (create/update/delete), or move the behaviour into a custom route / action"
+		});
+		const nonFunction = entries.filter(([key, value]) => writeVerbSlots.includes(key) && typeof value !== "function");
+		for (const [key, value] of nonFunction) errors.push({
+			field: `writes.${key}`,
+			message: `Write verb "${key}" is declared but is ${value === void 0 ? "undefined" : `a ${typeof value}`}, not a function — generic repository CRUD would silently serve that slot instead of the command the config claims guards it`,
+			suggestion: "Pass the command function itself (e.g. `update: (id, data, ctx) => engine.updateDraft(id, data)`), or delete the entry"
+		});
+		const declared = writeVerbSlots.filter((op) => typeof config.writes?.[op] === "function");
+		if (entries.length === 0) warnings.push({
+			field: "writes",
+			message: "`writes` is declared but contains no verb functions",
+			suggestion: "Remove the empty `writes` block, or declare create/update/delete"
+		});
+		if (declared.length > 0 && config.disableDefaultRoutes) errors.push({
+			field: "writes",
+			message: `Resource declares write verb(s) [${declared.join(", ")}] but \`disableDefaultRoutes: true\` means no CRUD slot will call them`,
+			suggestion: "Drop `disableDefaultRoutes` so the slots mount, or move the command into a custom route / action and remove `writes`"
+		});
+		else if (declared.length > 0) {
+			const notMounted = declared.filter((op) => disabledRoutes.has(op));
+			if (notMounted.length > 0) errors.push({
+				field: "writes",
+				message: `Write verb(s) [${notMounted.join(", ")}] are declared but those CRUD slots are disabled, so the verbs can never run`,
+				suggestion: `Remove [${notMounted.join(", ")}] from \`disabledRoutes\`, or delete the matching \`writes\` entr(ies) — a command nothing calls is decoration`
+			});
+		}
+	}
 	if (config.controller && !options.skipControllerCheck && !config.disableDefaultRoutes) {
 		const ctrl = config.controller;
 		const requiredMethods = CRUD_OPERATIONS;
@@ -2065,7 +2277,12 @@ function validateDefineResourceConfig(config) {
 	validatePermissionsShape(config);
 	validateCustomRoutePermissions(config);
 	validateActionsShape(config);
-	return [...collectRedundantFieldRuleDiagnostics(config), ...collectReservedFilterNameDiagnostics(config)];
+	validateRouteCapabilities(config);
+	return [
+		...collectRedundantFieldRuleDiagnostics(config),
+		...collectReservedFilterNameDiagnostics(config),
+		...collectPaginationCapDiagnostics(config)
+	];
 }
 /**
 * Query-string param names arc's `QueryParser` reserves for
@@ -2102,6 +2319,37 @@ function collectReservedFilterNameDiagnostics(config) {
 		message: `[Arc] Resource '${config.name}': filterable field(s) [${collisions.join(", ")}] collide with reserved query params (page, limit, cursor, after, sort, search, select, populate). The query parser consumes these names for pagination/projection, so filtering by them via the query string — and via the MCP list tool — will NOT work. Rename the field(s), or drop them from \`filterableFields\` if the collision is intended.`
 	}];
 }
+/**
+* Warn when the parser's page cap exceeds the repository's.
+*
+* Page size is capped in THREE independent places — the query parser, the
+* repository's pagination engine, and arc — and none of them can see the others.
+* The lowest silently wins, so a resource that declares 1000 and a repository
+* left at its default 100 serves 100 rows with a `200` and no signal anywhere.
+* That is not hypothetical: an account picker read 100 of 696 rows, filtered
+* that arbitrary slice client-side, and rendered "No accounts found".
+*
+* arc is the only layer that holds BOTH, so it is the only one that can notice.
+* A diagnostic rather than a throw: the mismatch is usually an unconfigured
+* default rather than a mistake, and a published framework must not refuse to
+* boot an app that works today — it just works less than the author intended.
+*
+* Read structurally, never by importing a kit: `repository._pagination.config`
+* is mongokit's shape, and arc stays database-agnostic (`check:boundaries`).
+* Any kit exposing the same shape gets the check for free; one that does not is
+* simply skipped.
+*/
+function collectPaginationCapDiagnostics(config) {
+	const parserCap = config.queryParser?.maxLimit;
+	if (typeof parserCap !== "number") return [];
+	const repoCap = (config.adapter?.repository)?._pagination?.config?.maxLimit;
+	if (typeof repoCap !== "number" || parserCap <= repoCap) return [];
+	return [{
+		severity: "warn",
+		code: "pagination-cap-mismatch",
+		message: `[Arc] Resource '${config.name}': the query parser allows ${parserCap} rows per page but the repository caps at ${repoCap}, so ${repoCap} wins and larger pages are truncated with a 200 and no error. Configure the repository's pagination \`maxLimit\` to ${parserCap} as well, or lower the parser's to match.`
+	}];
+}
 /** Permissions must be `PermissionCheck` functions, not arbitrary values. */
 function validatePermissionsShape(config) {
 	if (!config.permissions) return;
@@ -2157,6 +2405,37 @@ function collectRedundantFieldRuleDiagnostics(config) {
 	return diagnostics;
 }
 /**
+* Route `capability` keys — must not collide with a CRUD slot, an action, an
+* aggregation, or another route on the same resource.
+*
+* At BOOT, not at introspection. `introspectRegistry` also refuses a collision,
+* but nothing inside arc calls it: it is a host API, and a host calls it from a
+* permission-matrix endpoint. So the only thing catching a duplicate key was a
+* 500 on that endpoint at REQUEST time — and because a UI reads its whole
+* permission map from there, one static config typo took every client's gates
+* out at once, in production, rather than failing the deploy.
+*
+* A duplicate `capability` is decidable from the config alone, so it belongs
+* with the other boot checks. The introspection-side throw stays as a backstop
+* for callers that build a registry entry by hand instead of via
+* `defineResource`.
+*/
+function validateRouteCapabilities(config) {
+	const routes = config.routes;
+	if (!routes?.length) return;
+	const taken = /* @__PURE__ */ new Map();
+	for (const op of Object.keys(config.permissions ?? {})) taken.set(op, "CRUD slot");
+	for (const name of Object.keys(config.actions ?? {})) taken.set(`action:${name}`, "action");
+	for (const name of Object.keys(config.aggregations ?? {})) taken.set(`agg:${name}`, "aggregation");
+	for (const route of routes) {
+		const key = route.capability;
+		if (key === void 0) continue;
+		const owner = taken.get(key);
+		if (owner !== void 0) throw new Error(`[Arc] Resource '${config.name}': route ${route.method} ${route.path} declares capability '${key}', which is already published by a ${owner}. Two gates under one key means one answers for the other verb — rename the route's \`capability\`.`);
+		taken.set(key, `route ${route.method} ${route.path}`);
+	}
+}
+/**
 * Actions (v2.8) — name must not collide with CRUD ops; handler +
 * permissions must have the right shapes. Fail at boot so production
 * never ships a misconfigured action endpoint.
@@ -2202,6 +2481,10 @@ function defineResource(config) {
 		const registryMeta = resolveOpenApiSchemas(narrowedConfig);
 		if (registryMeta) resource._registryMeta = registryMeta;
 	}
+	if (resolvedConfig.transactional === true) {
+		const name = resolvedConfig.name;
+		resource._deferredChecks = [() => assertTransactionCapability(repository, name)];
+	}
 	if (diagnostics.length > 0) resource._diagnostics = diagnostics;
 	return resource;
 }

package/dist/discovery/index.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 import { readdir } from "node:fs/promises";
 import { extname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/docs/index.d.mts

@@ -1,5 +1,5 @@
 
-import { p as RegistryEntry } from "../index-CpzxqePp.mjs";
+import { p as RegistryEntry } from "../index-BcR2bFZQ.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-CmGOxOtD.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/docs/openapi/types.d.ts

package/dist/docs/index.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { n as getUserRoles } from "../userHelpers-ChYJ6CdK.mjs";
-import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-B2L4js1v.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { n as getUserRoles } from "../userHelpers-CWF5pbZD.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-BN5cQaO2.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {

package/dist/{elevation-D2l1mh4g.mjs → elevation-B0tlY8y1.mjs}

@@ -1,8 +1,8 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DNg-KNCk.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { n as requireSingleHeaderValue } from "./headers-3zvE0rM3.mjs";
-import { n as getUserRoles } from "./userHelpers-ChYJ6CdK.mjs";
+import { n as requireSingleHeaderValue } from "./headers-CveNO9gR.mjs";
+import { n as getUserRoles } from "./userHelpers-CWF5pbZD.mjs";
 import fp from "fastify-plugin";
 //#region src/scope/elevation.ts
 var elevation_exports = /* @__PURE__ */ __exportAll({

package/dist/encryption/index.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as ArcError } from "../errors-Cj42AntO.mjs";
-import { t as parseJsonBody } from "../jsonBody-BYbLDi5D.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as ArcError } from "../errors-Cd_yy7aW.mjs";
+import { t as parseJsonBody } from "../jsonBody-CfGH-GxO.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/encryption/fieldCipher.ts
@@ -71,7 +71,8 @@ function parseFieldEnvelope(token) {
 }
 /** Decrypt a parsed `arc.v1` envelope with the resolved key. Throws on tamper. */
 function decryptField(envelope, key) {
-	const decipher = createDecipheriv("aes-256-gcm", toKeyBuffer(key), envelope.iv);
+	const secret = toKeyBuffer(key);
+	const decipher = createDecipheriv("aes-256-gcm", secret, envelope.iv);
 	decipher.setAuthTag(envelope.tag);
 	return Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]).toString("utf8");
 }