@classytic/arc 2.41.0 → 2.43.0

package/dist/{defineResource-DzGT-2LP.mjs → defineResource-DIC7JZGU.mjs}

@@ -1,339 +1,12 @@
-/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
-import { p as MUTATION_OPERATIONS, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-BxLgNFF7.mjs";
-import { arcLog } from "./logger/index.mjs";
-import { r as ForbiddenError } from "./errors-C_YhELhe.mjs";
-import { n as getUserRoles } from "./userHelpers-DDMOZ_Pm.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-CDy3-zw1.mjs";
-import { d as isWriteVerbCapable, p as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController, u as detectOverriddenWriteSlots } from "./BaseController-DYJRZ0EJ.mjs";
-import { y as getDefaultCrudSchemas } from "./utils-B-zj_b__.mjs";
-import { a as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-BTyPLHK0.mjs";
-import { n as convertRouteSchema, r as ensureSchemaConverter, t as convertOpenApiSchemas } from "./schemaConverter-BLCSmNbr.mjs";
-import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-dvppnxsr.mjs";
-import { a as createCrudHandlers, i as resolvePipelineSteps, o as createFastifyHandler, r as buildPipelineHandler, s as createRequestContext, t as resolveActionPermission } from "./actionPermissions-DPwPWPOV.mjs";
-import { a as selectPluginMw, c as buildRouteHooks, d as buildAuthMiddleware, i as resolveRouterPluginMw, l as resolveRoutePreHandlers, n as buildRateLimitConfig, p as buildArcDecorator, r as buildRouteConfig, s as buildCrudPermissionMw, t as tryRegisterRoute, u as routeHookOptions } from "./registerRoute-DRsSHPSM.mjs";
-import { t as hasEvents } from "./typeGuards-D7tHFdH6.mjs";
-import { B as requireAuth } from "./permissions-DiHXy8Ck.mjs";
-import { r as getAvailablePresets, t as applyPresets } from "./presets-BdlugYTc.mjs";
-import { t as pluralize } from "./pluralize-2_U6QZQg.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { m as MUTATION_OPERATIONS, t as CRUD_OPERATIONS } from "./constants-Cu7Mx7_U.mjs";
+import { t as arcLog } from "./logger-DXjfIqjV.mjs";
+import { a as autoInjectTenantFieldRules, c as BaseController, i as resolveOpenApiSchemas, t as buildResourcePlugin, v as detectOverriddenWriteSlots, y as isWriteVerbCapable } from "./plugin-BccET1tL.mjs";
+import { B as requireAuth } from "./permissions-Cm0uYHvd.mjs";
+import { n as getAvailablePresets, t as applyPresets } from "./presets-Cpvj6fGO.mjs";
+import { t as pluralize } from "./pluralize-CVIOcgMF.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.
-*
-* Auto-CRUD's create/update routes get this for free via `BodySanitizer.sanitize()`
-* inside `BaseController`. Custom routes (`config.routes`, presets, action endpoints)
-* never went through that path — so a host that declared
-* `fields: { role: fields.writableBy(['admin']) }` and a custom
-* `POST /users/promote` happily accepted `{ role: 'admin' }` from any caller.
-*
-* This preHandler closes that gap. It applies ONLY the `applyFieldWritePermissions`
-* step — no `SYSTEM_FIELDS` strip, no `fieldRules` strip — because custom-route
-* bodies don't necessarily mirror the resource's adapter shape, and we'd
-* generate surprising 403s by enforcing rules tied to that shape.
-*
-* Returns `null` when the resource has no field permissions configured — the
-* caller should then skip wiring it into the preHandler chain.
-*/
-function buildFieldWritePreHandler(fieldPermissions, policy = DEFAULT_FIELD_WRITE_DENIAL_POLICY) {
-	if (!fieldPermissions || Object.keys(fieldPermissions).length === 0) return null;
-	return async (request, _reply) => {
-		const body = request.body;
-		if (!body || typeof body !== "object" || Array.isArray(body)) return;
-		const scope = request.scope ?? PUBLIC_SCOPE;
-		if (isElevated(scope)) return;
-		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;
-	};
-}
-/**
-* True for HTTP methods that carry a request body and should run the
-* field-write preHandler. GET/DELETE/HEAD/OPTIONS skip enforcement.
-*/
-function methodCarriesBody(method) {
-	const m = method.toUpperCase();
-	return m === "POST" || m === "PUT" || m === "PATCH";
-}
-//#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.
-*/
-function createCustomRoutes(fastify, routes, controller, options) {
-	const { tag, resourceName, arcDecorator, rateLimitConfig, pluginMw, pipeline, routeGuards, tenantScopeMw, fieldPermissions, onFieldWriteDenied, extensions } = options;
-	for (const route of routes) {
-		if ("raw" in route) throw new Error(`Route ${route.method} ${route.path}: \`raw\` was removed in arc 2.31 — the FIELD now carries the intent. Move the function to \`rawHandler\` (Fastify-native \`(request, reply)\`) or leave it in \`handler\` (arc pipeline, \`(ctx)\`), and delete the flag. If this route comes from a dependency, that package needs a release built against arc >=2.31.`);
-		const routeWithRefs = route;
-		const hasHandler = route.handler !== void 0 || route.rawHandler !== void 0;
-		const hasControllerMethod = typeof routeWithRefs.controllerMethod === "function";
-		if (hasHandler && hasControllerMethod) throw new Error(`Route ${route.method} ${route.path}: pass either \`handler\` or \`controllerMethod\`, not both. Prefer \`controllerMethod: (c: MyController) => c.method\` for typed handler refs (TS catches typos).`);
-		if (!hasHandler && !hasControllerMethod) throw new Error(`Route ${route.method} ${route.path}: must declare one of \`handler\` (arc pipeline), \`rawHandler\` (Fastify-native), or \`controllerMethod: (c) => c.method\` (typed function-ref form).`);
-		let resolvedHandler;
-		if (hasControllerMethod) {
-			if (!controller) throw new Error(`Route ${route.method} ${route.path}: \`controllerMethod\` requires a controller. Provide one via \`defineResource({ controller, … })\`, or use \`defineResource\` with an \`adapter\` so arc auto-creates a BaseController.`);
-			const referenced = routeWithRefs.controllerMethod?.(controller);
-			if (typeof referenced !== "function") throw new Error(`Route ${route.method} ${route.path}: \`controllerMethod\` did not return a function. Return the method itself: \`controllerMethod: (c) => c.myMethod\`.`);
-			resolvedHandler = referenced.bind(controller);
-		} else {
-			if (route.rawHandler && route.handler) throw new Error(`Route ${route.method} ${route.path}: set either \`handler\` (arc pipeline) or \`rawHandler\` (Fastify-native), not both.`);
-			resolvedHandler = route.rawHandler ?? route.handler;
-		}
-		const opName = route.operation ?? (typeof resolvedHandler === "string" ? resolvedHandler : `${route.method.toLowerCase()}${route.path.replace(/[/:]/g, "_")}`);
-		const isRaw = route.rawHandler !== void 0;
-		const wrapHandler = !isRaw;
-		let handler;
-		if (typeof resolvedHandler === "string") {
-			if (!controller) throw new Error(`Route ${route.method} ${route.path}: string handler '${resolvedHandler}' requires a controller. Either provide a controller or use a function handler instead.`);
-			const method = controller[resolvedHandler];
-			if (typeof method !== "function") throw new Error(`Handler '${resolvedHandler}' not found on controller`);
-			const boundMethod = method.bind(controller);
-			if (wrapHandler) {
-				const steps = resolvePipelineSteps(pipeline, opName);
-				handler = steps.length > 0 ? buildPipelineHandler(boundMethod, steps, opName, resourceName) : createFastifyHandler(boundMethod);
-			} else handler = boundMethod;
-		} else if (wrapHandler) {
-			const steps = resolvePipelineSteps(pipeline, opName);
-			handler = steps.length > 0 ? buildPipelineHandler(resolvedHandler, steps, opName, resourceName) : createFastifyHandler(resolvedHandler);
-		} else handler = resolvedHandler;
-		const routeTags = route.tags ?? (tag ? [tag] : void 0);
-		const convertedSchema = route.schema ? convertRouteSchema(route.schema) : void 0;
-		const schema = {
-			...routeTags ? { tags: routeTags } : {},
-			...route.summary ? { summary: route.summary } : {},
-			...route.description ? { description: route.description } : {},
-			...convertedSchema ?? {}
-		};
-		const customPreHandlers = resolveRoutePreHandlers(route.preHandler, fastify, `${route.method} ${route.path}`);
-		if (route.tenantScope === true) {
-			if (!tenantScopeMw || tenantScopeMw.length === 0) throw new Error(`Route ${route.method} ${route.path}: \`tenantScope: true\` requires a multi-tenant preset. Add \`multiTenantPreset()\` (or \`flexibleMultiTenantPreset()\`) to the resource's \`presets\`, or remove the \`tenantScope\` flag from this route.`);
-			customPreHandlers.unshift(...tenantScopeMw);
-		}
-		if (!isRaw && route.fieldWrite !== false && methodCarriesBody(route.method)) {
-			const fieldWriteMw = buildFieldWritePreHandler(fieldPermissions, onFieldWriteDenied);
-			if (fieldWriteMw) customPreHandlers.push(fieldWriteMw);
-		}
-		const preAuthHandlers = route.preAuth ?? [];
-		const hooks = buildRouteHooks({
-			preAuth: preAuthHandlers,
-			arcDecorator,
-			authMw: buildAuthMiddleware(fastify, route.permissions),
-			permissionMw: buildCrudPermissionMw(route.permissions, resourceName, opName),
-			pluginMw: selectPluginMw(route.method, pluginMw),
-			routeGuards,
-			customMws: customPreHandlers
-		});
-		const isStream = route.streamResponse === true;
-		tryRegisterRoute(fastify, {
-			method: route.method,
-			url: route.path,
-			schema,
-			...routeHookOptions(hooks),
-			handler: isStream ? async function streamRoute(request, reply) {
-				reply.raw.setHeader("Content-Type", "text/event-stream");
-				reply.raw.setHeader("Cache-Control", "no-cache");
-				reply.raw.setHeader("Connection", "keep-alive");
-				const result = await handler.call(this, request, reply);
-				if (isReadableStream(result)) {
-					await pipeUIMessageStreamToReply(reply, result);
-					return reply;
-				}
-				return result;
-			} : handler,
-			/**
-			* 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
-		});
-	}
-}
-/**
-* Create CRUD routes for a controller.
-*
-* @param fastify    - Fastify instance with Arc decorators
-* @param controller - CRUD controller with handler methods (optional when
-*                     `disableDefaultRoutes: true` and only custom `routes`
-*                     are being registered)
-* @param options    - Router configuration
-*/
-function createCrudRouter(fastify, controller, options = {}) {
-	const { tag = "Resource", schemas = {}, permissions = {}, middlewares = {}, routeGuards = [], routes: customRoutes = [], disableDefaultRoutes = false, disabledRoutes = [], resourceName = "unknown", schemaOptions, rateLimit, pipe: pipeline, fields: fieldPermissions, onFieldWriteDenied, updateMethod = DEFAULT_UPDATE_METHOD, idField, extensions } = options;
-	const rateLimitConfig = buildRateLimitConfig(rateLimit);
-	const resourceHasQueryCache = fastify.hasDecorator("queryCache") && controller && typeof controller._cacheConfig !== "undefined" && controller._cacheConfig !== void 0;
-	const pluginMw = resolveRouterPluginMw(fastify, Boolean(resourceHasQueryCache));
-	const arcDecorator = buildArcDecorator({
-		resourceName,
-		schemaOptions,
-		permissions,
-		hooks: fastify.arc?.hooks,
-		events: fastify.events,
-		fields: fieldPermissions,
-		idField
-	});
-	const mw = {
-		list: middlewares.list ?? [],
-		get: middlewares.get ?? [],
-		create: middlewares.create ?? [],
-		update: middlewares.update ?? [],
-		delete: middlewares.delete ?? []
-	};
-	const tenantScopeMw = middlewares.tenantScope;
-	const idParamsSchema = {
-		type: "object",
-		properties: { id: { type: "string" } },
-		required: ["id"]
-	};
-	const defaultSchemas = getDefaultCrudSchemas();
-	/**
-	* Merge: base (tags/summary) → defaults (response/querystring) → user overrides.
-	* User-provided schemas always win; defaults enable fast-json-stringify when
-	* no user schema is set.
-	*/
-	const buildSchema = (base, defaults, userSchema) => ({
-		...defaults,
-		...base,
-		...userSchema ?? {}
-	});
-	if (!disableDefaultRoutes) {
-		if (!controller) throw new Error("Controller is required when disableDefaultRoutes is not true. Provide a controller or use defineResource which auto-creates BaseController.");
-		const handlers = buildCrudHandlers(controller, pipeline, resourceName);
-		const crudTable = [
-			{
-				op: "list",
-				method: "GET",
-				url: "/",
-				summary: `List ${tag}`,
-				hasIdParams: false
-			},
-			{
-				op: "get",
-				method: "GET",
-				url: "/:id",
-				summary: `Get ${tag} by ID`,
-				hasIdParams: true
-			},
-			{
-				op: "create",
-				method: "POST",
-				url: "/",
-				summary: `Create ${tag}`,
-				hasIdParams: false
-			},
-			{
-				op: "update",
-				method: "PATCH",
-				url: "/:id",
-				summary: `Update ${tag}`,
-				hasIdParams: true
-			},
-			{
-				op: "delete",
-				method: "DELETE",
-				url: "/:id",
-				summary: `Delete ${tag}`,
-				hasIdParams: true
-			}
-		];
-		for (const spec of crudTable) {
-			if (disabledRoutes.includes(spec.op)) continue;
-			const permission = permissions[spec.op];
-			const hooks = buildRouteHooks({
-				arcDecorator,
-				authMw: buildAuthMiddleware(fastify, permission),
-				permissionMw: buildCrudPermissionMw(permission, resourceName, spec.op),
-				pluginMw: selectPluginMw(spec.method, pluginMw),
-				routeGuards,
-				customMws: mw[spec.op]
-			});
-			const methodsToRegister = spec.op === "update" ? updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod] : [spec.method];
-			for (const method of methodsToRegister) {
-				const summary = spec.op === "update" ? `${method === "PUT" ? "Replace" : "Update"} ${tag}` : spec.summary;
-				tryRegisterRoute(fastify, {
-					method,
-					url: spec.url,
-					schema: buildSchema({
-						tags: [tag],
-						summary,
-						...spec.hasIdParams ? { params: idParamsSchema } : {}
-					}, defaultSchemas[spec.op], schemas[spec.op]),
-					...routeHookOptions(hooks),
-					handler: handlers[spec.op],
-					...buildRouteConfig(rateLimitConfig, extensions)
-				}, {
-					resourceName,
-					op: spec.op
-				});
-			}
-		}
-	}
-	if (customRoutes.length > 0) createCustomRoutes(fastify, customRoutes, controller, {
-		tag,
-		resourceName,
-		arcDecorator,
-		rateLimitConfig,
-		pluginMw,
-		pipeline,
-		routeGuards,
-		tenantScopeMw,
-		fieldPermissions,
-		onFieldWriteDenied,
-		extensions
-	});
-}
-function buildCrudHandlers(ctrl, pipeline, resourceName) {
-	const standardHandlers = createCrudHandlers(ctrl);
-	if (!pipeline) return standardHandlers;
-	const wrapped = { ...standardHandlers };
-	for (const op of CRUD_OPERATIONS) {
-		const steps = resolvePipelineSteps(pipeline, op);
-		if (steps.length === 0) continue;
-		const method = ctrl[op].bind(ctrl);
-		wrapped[op] = buildPipelineHandler(method, steps, op, resourceName);
-	}
-	return wrapped;
-}
-/**
-* Build a permission middleware from a PermissionCheck — useful when hosts
-* register their own routes outside the resource system but still want to
-* evaluate permissions through the shared applicator.
-*/
-function createPermissionMiddleware(permission, resourceName, action) {
-	return buildCrudPermissionMw(permission, resourceName, action);
-}
-//#endregion
+import { readEnv } from "@classytic/primitives/environment";
 //#region src/core/defineResource/writeVerbs.ts
 /**
 * Phase 4b — write-verb registration policy.
@@ -406,34 +79,13 @@ function warnOnWriteMethodOverride(controller, resolvedConfig) {
 }
 //#endregion
 //#region src/core/defineResource/controller.ts
-/**
-* Phase 4 — pick (or auto-create) the resource's controller.
-*
-* Three branches:
-*   1. User-supplied controller → forward `queryParser` (duck-typed)
-*      and warn on dropped resource-level options.
-*   2. No controller, has CRUD routes, has a repository → auto-build
-*      a `BaseController` with every resource-level knob threaded
-*      through (tenantField, schemaOptions, idField, defaultSort,
-*      cache, onFieldWriteDenied, presetFields).
-*   3. Otherwise → `undefined` (custom-routes-only resource).
-*
-* The warns are load-bearing DX: silently dropping `queryParser`,
-* `schemaOptions`, etc. on a custom controller produces 90-minute
-* "why don't my filters work" debugs. Each warn names the resource,
-* 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.
-*/
+/** Resolve the controller for the resource (branches in the module docstring). */
 function resolveOrAutoCreateController(resolvedConfig, adapter, repository, hasCrudRoutes) {
 	const userController = resolvedConfig.controller;
 	if (resolvedConfig.transactional === true) {
@@ -445,6 +97,7 @@ function resolveOrAutoCreateController(resolvedConfig, adapter, repository, hasC
 		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) {
+		bindControllerResourceName(userController, resolvedConfig.name);
 		threadQueryParser(userController, resolvedConfig);
 		enforceWriteVerbReachability(userController, resolvedConfig);
 		threadConfigureLifecycle(userController, resolvedConfig, adapter);
@@ -457,22 +110,12 @@ function resolveOrAutoCreateController(resolvedConfig, adapter, repository, hasC
 	return buildBaseController(resolvedConfig, adapter, repository);
 }
 /**
-* Forward resource-level options into a user-supplied controller via
-* the duck-typed `configure(opts)` lifecycle hook. Closes the pre-2.15
-* gap where `tenantField` / `schemaOptions` / `idField` / `defaultSort`
-* / `cache` / `onFieldWriteDenied` had no path into a host controller
-* unless the host remembered to forward them through `super(repo,
-* { ... })`. `BaseController` / `BaseCrudController` ship `configure()`;
-* custom controllers can opt in by adding the method.
+* Forward resource-level options into a user-supplied controller via the
+* duck-typed `configure(opts)` hook.
 *
-* **Gate by `_declaredKeys`**: only forward keys the user literally
-* passed at the resource level. Without this gate, arc-inferred values
-* (e.g. `inferTenantFieldFromAdapter` setting `tenantField: false`
-* because the model's organizationId path doesn't exist) would clobber
-* the matching value the host already set in the controller's
-* constructor (e.g. `new BaseController(repo, { tenantField:
-* "companyId" })`). Resource-level explicit values still win — the
-* snapshot captures what the user typed before any inference runs.
+* **Gated by `_declaredKeys`**: only keys the user literally passed are
+* forwarded, so arc-inferred values (e.g. `tenantField: false` from adapter
+* inference) never clobber what the host set in the controller's constructor.
 */
 function threadConfigureLifecycle(controller, resolvedConfig, adapter) {
 	const ctrl = controller;
@@ -482,20 +125,16 @@ function threadConfigureLifecycle(controller, resolvedConfig, adapter) {
 	const opts = {};
 	if (resolvedConfig.tenantField !== void 0 && wasDeclared("tenantField")) opts.tenantField = resolvedConfig.tenantField;
 	if (resolvedConfig.schemaOptions !== void 0 && wasDeclared("schemaOptions")) opts.schemaOptions = resolvedConfig.schemaOptions;
+	if (resolvedConfig.lookupFields !== void 0 && wasDeclared("lookupFields")) opts.lookupFields = resolvedConfig.lookupFields;
 	if (resolvedConfig.idField !== void 0 && wasDeclared("idField")) opts.idField = resolvedConfig.idField;
 	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 (resolvedConfig.concurrency !== void 0) opts.concurrency = resolvedConfig.concurrency;
 	if (adapter?.matchesFilter !== void 0) opts.matchesFilter = adapter.matchesFilter;
 	if (resolvedConfig._controllerOptions) opts.presetFields = {
 		slugField: resolvedConfig._controllerOptions.slugField,
@@ -505,18 +144,17 @@ function threadConfigureLifecycle(controller, resolvedConfig, adapter) {
 	ctrl.configure(opts);
 }
 /**
-* Forward a resource-level `queryParser` into a user-supplied
-* controller via duck-typed `setQueryParser`. Without this the
-* controller's internal default would silently override the
-* resource's parser, drifting `[contains]` / `[like]` semantics
-* away from what the OpenAPI schema advertises.
-*
-* **Fail-loud (2.15.0):** older versions warned and continued —
-* letting the resource register with a silently-shadowed parser. The
-* "ship and pray they read the log" path produced 90-minute "why
-* doesn't `[contains]` work" debugs in production. Now throws at
-* registration so the misconfig surfaces immediately, with the same
-* fix-it message in the error.
+* Bind the resource name into a supplied controller (duck-typed `bindResourceName`), so a
+* subclass that never passed `resourceName` to `super()` still runs its hooks, audit and events.
+*/
+function bindControllerResourceName(controller, name) {
+	const ctrl = controller;
+	if (typeof ctrl.bindResourceName === "function") ctrl.bindResourceName(name);
+}
+/**
+* Forward a resource-level `queryParser` into a user-supplied controller via
+* duck-typed `setQueryParser`. Throws when the controller can't accept it —
+* a shadowed parser silently drifts filter semantics from the OpenAPI schema.
 */
 function threadQueryParser(controller, resolvedConfig) {
 	if (!resolvedConfig.queryParser) return;
@@ -528,11 +166,8 @@ function threadQueryParser(controller, resolvedConfig) {
 	throw new Error(`Resource "${resolvedConfig.name}" declares a custom \`queryParser\` but its controller does not expose \`setQueryParser(qp)\`. The parser would be silently dropped, drifting \`[contains]\` / \`[like]\` semantics away from the OpenAPI schema. Extend \`BaseController\` / \`BaseCrudController\` (both implement \`setQueryParser\`) OR add a \`setQueryParser(qp)\` method to your custom controller that actually wires the parser into the controller's query resolution path. (arc 2.15.0 hardened this to a registration-time throw — pre-2.15 it was a warn.)`);
 }
 /**
-* Warn when the user supplies their own controller AND declares
-* resource-level options arc only auto-threads on the auto-build
-* path. The user *can* fix this by forwarding through `super(repo,
-* { ... })`, so the warn names the dropped options + the canonical
-* fix.
+* Warn when a custom controller without `configure()` can't receive
+* resource-level options the user declared.
 */
 function warnOnDroppedAuthorOptions(resolvedConfig) {
 	if (typeof resolvedConfig.controller?.configure === "function") return;
@@ -550,11 +185,9 @@ function warnOnDroppedAuthorOptions(resolvedConfig) {
 	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.`);
 }
 /**
-* Warn when a preset injected `_controllerOptions` (slugLookup,
-* softDelete, parent presets) but the user supplied their own
-* controller. The user did NOT declare these — "forward them" is
-* bad advice. The fix is either drop the preset or extend
-* `BaseController` so the auto-build path runs.
+* Warn when a preset injected `_controllerOptions` but the user supplied their
+* own controller. The user didn't declare these, so the fix is dropping the
+* preset or extending `BaseController` — not "forward them".
 */
 function warnOnDroppedPresetOptions(resolvedConfig) {
 	if (resolvedConfig._controllerOptions === void 0) return;
@@ -564,10 +197,8 @@ function warnOnDroppedPresetOptions(resolvedConfig) {
 	arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" applies a preset that injects controller field(s) [${presetFields.join(", ") || "preset metadata"}] (e.g. slugLookup / softDelete / parent), but the resource also declares a custom controller. Preset metadata only reaches arc's auto-built BaseController — your custom controller will not see \`slugField\`/\`parentField\`/etc. Either (a) drop the preset on this resource (\`presets: [...]\` without it), or (b) extend \`BaseController\` / \`BaseCrudController\` so arc auto-builds the controller and threads the preset fields automatically.`);
 }
 /**
-* Auto-build a `BaseController` with every resource-level knob
-* threaded in. `maxLimit` is extracted from the parser's schema so
-* `BaseController.QueryResolver` and Fastify validation stay in sync
-* with the parser's configured limit.
+* Auto-build a `BaseController` with every resource-level option. `maxLimit`
+* comes from the parser's schema so QueryResolver and Fastify validation agree.
 */
 function buildBaseController(resolvedConfig, adapter, repository) {
 	const qp = resolvedConfig.queryParser;
@@ -586,32 +217,32 @@ function buildBaseController(resolvedConfig, adapter, repository) {
 		...resourceConfigDefaultLimit !== void 0 ? { defaultLimit: resourceConfigDefaultLimit } : {},
 		tenantField: resolvedConfig.tenantField,
 		idField: resolvedConfig.idField,
+		...resolvedConfig.lookupFields ? { lookupFields: resolvedConfig.lookupFields } : {},
 		...resolvedConfig.defaultSort !== void 0 ? { defaultSort: resolvedConfig.defaultSort } : {},
 		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,
+		...resolvedConfig.concurrency ? { concurrency: resolvedConfig.concurrency } : {},
 		presetFields: resolvedConfig._controllerOptions ? {
 			slugField: resolvedConfig._controllerOptions.slugField,
 			parentField: resolvedConfig._controllerOptions.parentField
 		} : void 0
 	});
 }
+/** Deferred like the transaction check: `concurrency` needs the kit's CAS on `ifVersion`. */
+function assertConcurrencyCapability(repository, resourceName) {
+	const capabilities = repository?.capabilities;
+	if (!capabilities || capabilities.optimisticConcurrency === true) return;
+	throw new Error(`Resource "${resourceName}" declares \`concurrency\` but its repository reports \`capabilities.optimisticConcurrency: ${String(capabilities.optimisticConcurrency)}\` — an ETag it cannot enforce would promise a guard that is not there. Use a kit with CAS writes (mongokit), or remove the option.`);
+}
 /**
-* 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.
+* The DEFERRED half of the `transactional: true` gate — run at registration,
+* after `beforeBoot()` connects. Fail-closed: anything but a confirmed `true`
+* refuses the boot. A repository with NO capability descriptor passes (it never
+* promised one; the define-time presence check covered it).
 */
 function assertTransactionCapability(repository, resourceName) {
 	const capabilities = repository?.capabilities;
@@ -873,108 +504,6 @@ function resolveCrudAllowList(config) {
 	};
 }
 //#endregion
-//#region src/core/schemaOptions.ts
-/**
-* Inject the tenant-scoping field rule into `schemaOptions.fieldRules`:
-*
-*   { [tenantField]: { systemManaged: true, preserveForElevated: true } }
-*
-* Why both flags: `systemManaged` tells `BodySanitizer` to strip the
-* field from inbound bodies (so member clients can't forge a target
-* tenant). `preserveForElevated` exempts elevated-admin scopes from the
-* strip, so platform admins without a pinned org can still pick a target
-* org via the request body (the only channel they have —
-* `BaseController.create` can't re-stamp from scope when scope has no
-* orgId).
-*
-* **Returns a new `RouteSchemaOptions`** — the input is never mutated.
-* Callers should assign the return value to whatever config slot they
-* read from downstream (always the `resolvedConfig`, never raw `config`).
-*
-* **No-op when:**
-* - `tenantField` is `false` (platform-universal resource)
-* - `tenantField` is undefined
-* - The caller already declared `fieldRules[tenantField].systemManaged`
-*   (even as `false`) — explicit opt-outs are respected
-*
-* `preserveForElevated` defaults to `true` but is preserved verbatim
-* when the caller set it explicitly.
-*/
-function autoInjectTenantFieldRules(schemaOptions, tenantField) {
-	if (tenantField === false || tenantField === void 0) return schemaOptions;
-	const fieldName = tenantField || "organizationId";
-	const existing = schemaOptions?.fieldRules ?? {};
-	const existingRule = existing[fieldName];
-	if (existingRule && existingRule.systemManaged !== void 0) return schemaOptions;
-	return {
-		...schemaOptions ?? {},
-		fieldRules: {
-			...existing,
-			[fieldName]: {
-				...existingRule ?? {},
-				systemManaged: true,
-				preserveForElevated: existingRule?.preserveForElevated ?? true
-			}
-		}
-	};
-}
-/**
-* Remove a field from a JSON Schema's `required[]` array. Leaves `properties`
-* intact so advanced callers can still send the value — the field just isn't
-* mandatory at validation time.
-*
-* Returns a fresh schema (no mutation). No-op when the schema is undefined,
-* lacks a `required[]`, or the field is already absent from it.
-*/
-function stripFromRequired(schema, fieldName) {
-	if (!schema || typeof schema !== "object") return schema;
-	const required = schema.required;
-	if (!Array.isArray(required) || !required.includes(fieldName)) return schema;
-	const filtered = required.filter((f) => f !== fieldName);
-	const next = { ...schema };
-	if (filtered.length > 0) next.required = filtered;
-	else delete next.required;
-	return next;
-}
-/**
-* Drop `systemManaged` fields from `required[]` in generated body schemas.
-*
-* Arc populates those from scope / preset middleware / controller, so a client
-* never supplies them — but the DB schema may still mark them required, and the
-* adapter reflects that into the wire contract.
-*
-* THE GOTCHA THIS CLOSES: engines on `@classytic/primitives` default to
-* `tenant: { required: true }`, stamping `organizationId` as required. Fastify
-* preValidation runs BEFORE arc's preHandler chain, so the tenant-injection
-* hook never gets to run and the request dies on
-* `must have required property 'organizationId'` — even though the client sent
-* `x-organization-id` and arc had promised to inject it. The alternative was
-* `tenant: { required: false }` at every consumer site.
-*
-* Also covers `auditedPreset`'s `createdBy`/`updatedBy` and any host rule
-* marked `systemManaged`. Applies to create AND update, since update middleware
-* injects the same fields.
-*
-* `properties` is left INTACT — an elevated caller may still send these, and
-* `BodySanitizer` owns that runtime policy (`preserveForElevated`,
-* strip-vs-reject). No-op without `systemManaged` rules or generated schemas.
-*/
-function stripSystemManagedFromBodyRequired(schemas, schemaOptions) {
-	if (!schemas) return schemas;
-	const rules = schemaOptions?.fieldRules;
-	if (!rules) return schemas;
-	const systemManagedFields = Object.entries(rules).filter(([, rule]) => rule?.systemManaged === true).map(([field]) => field);
-	if (systemManagedFields.length === 0) return schemas;
-	const next = { ...schemas };
-	let createBody = schemas.createBody;
-	for (const field of systemManagedFields) createBody = stripFromRequired(createBody, field);
-	if (createBody !== schemas.createBody) next.createBody = createBody;
-	let updateBody = schemas.updateBody;
-	for (const field of systemManagedFields) updateBody = stripFromRequired(updateBody, field);
-	if (updateBody !== schemas.updateBody) next.updateBody = updateBody;
-	return next;
-}
-//#endregion
 //#region src/core/defineResource/presets.ts
 /**
 * Phase 3 — apply presets + auto-inject tenant-field schema rules.
@@ -1132,352 +661,6 @@ function assertTenantFieldUsable(resourceName, tenantField, strategyType) {
 	if (tenantField === false) throw new Error(`[Arc/Cascade] Resource '${resourceName}' declares onTenantDelete (strategy: ${strategyType}) but \`tenantField: false\`. Company-wide resources can't be cascaded by org — set a real \`tenantField\` or remove the \`onTenantDelete\` declaration.`);
 }
 //#endregion
-//#region src/core/defineResource/plugin.ts
-/**
-* Build the CRUD schema map from the adapter's `OpenApiSchemas` plus
-* any `customSchemas` overrides on the resource.
-*
-* Returns `null` when neither input has anything to contribute, so
-* the caller can pass `undefined` straight to `createCrudRouter`.
-*
-* **Per-slot layering (post-2.12 DX fix).** Adapter auto-gen runs
-* unconditionally — declaring one custom slot (e.g. a richer
-* `create.body`) no longer wholesale-disables generated `get`,
-* `update`, `delete`, and `params` schemas. The pre-fix branch
-* skipped auto-gen entirely whenever `customSchemas` had any entry,
-* which silently flipped four slots from "auto-derived from the
-* adapter's schema generator" to "Fastify default" the moment a
-* host customised one. Now: auto-gen first, then deep-merge
-* customSchemas on top per slot.
-*
-* **`params` cloning is load-bearing.** Three CRUD slots (`get`,
-* `delete`, `update`) need a `params` schema. The previous inline
-* code shared the same reference across all three, so a downstream
-* mutation (e.g. attaching a vendor `description` for OpenAPI
-* tooling) leaked across operations. Each slot now owns its own
-* shallow clone.
-*/
-function buildGeneratedCrudSchemas(openApi, customSchemas) {
-	const generated = {};
-	if (openApi) {
-		const { createBody, updateBody, params } = openApi;
-		if (createBody) generated.create = { body: safeBody(createBody) };
-		if (updateBody) {
-			const patchBody = structuredClone(updateBody);
-			stripRequiredDeep(patchBody);
-			generated.update = { body: safeBody(patchBody) };
-			if (params) generated.update.params = cloneShallow(params);
-		}
-		if (params) {
-			generated.get = { params: cloneShallow(params) };
-			generated.delete = { params: cloneShallow(params) };
-			if (!generated.update) generated.update = { params: cloneShallow(params) };
-			else if (!generated.update.params) generated.update.params = cloneShallow(params);
-		}
-	}
-	let schemas = Object.keys(generated).length > 0 ? generated : null;
-	if (customSchemas && Object.keys(customSchemas).length > 0) {
-		schemas = schemas ?? {};
-		for (const [op, customSchema] of Object.entries(customSchemas)) {
-			const key = op;
-			const converted = convertRouteSchema(customSchema);
-			schemas[key] = schemas[key] ? {
-				...schemas[key],
-				...converted
-			} : converted;
-		}
-	}
-	return schemas;
-}
-/**
-* Normalize the listQuery JSON Schema for Fastify/AJV strict-mode use.
-*
-* The `qs` parser turns bracket notation into nested objects/arrays:
-*   `?name[contains]=foo` → `{ name: { contains: "foo" } }`
-*   `?tags[]=a&tags[]=b`  → `{ tags: ["a", "b"] }`
-*   `?populate[author][select]=name` → deeply nested object
-*
-* AJV rejects these against the OpenAPI-friendly `type: "string"`
-* declarations adapters generate. The QueryParser is the source of truth
-* for filter validation/coercion, so we replace each property with a
-* minimal AJV-strict-mode-clean shape: numeric pagination keys keep
-* `type: "integer"` (so `minimum`/`maximum` don't trigger AJV warnings),
-* everything else collapses to `{}`.
-*
-* The original `limit.maximum` is preserved so the parser's configured
-* max stays effective at the AJV layer.
-*/
-function normalizeListQuerySchema(listQuerySchema) {
-	const NORMALIZED_PROPS = {
-		page: {
-			type: "integer",
-			minimum: 1
-		},
-		limit: {
-			type: "integer",
-			minimum: 1
-		},
-		sort: {},
-		search: {},
-		select: {},
-		after: {},
-		populate: {},
-		lookup: {},
-		aggregate: {}
-	};
-	const props = listQuerySchema.properties;
-	const normalizedProps = props ? { ...props } : void 0;
-	if (normalizedProps) {
-		const originalLimit = normalizedProps.limit;
-		if (originalLimit?.maximum) NORMALIZED_PROPS.limit = {
-			...NORMALIZED_PROPS.limit,
-			maximum: originalLimit.maximum
-		};
-		for (const key of Object.keys(normalizedProps)) normalizedProps[key] = NORMALIZED_PROPS[key] ?? {};
-	}
-	return {
-		type: "object",
-		...listQuerySchema,
-		...normalizedProps ? { properties: normalizedProps } : {},
-		additionalProperties: listQuerySchema.additionalProperties ?? true
-	};
-}
-/**
-* Merge two JSON schema branches deeply. Arrays are unioned with
-* deduplication (so combined `required` lists don't duplicate field
-* names); plain-object keys recurse; primitives are overwritten.
-*
-* Exported for the action/CRUD router-config code paths that need to
-* compose user overrides on top of generated schemas.
-*/
-function deepMergeSchemas(base, override) {
-	if (!override) return base;
-	if (!base) return override;
-	const result = { ...base };
-	for (const [key, value] of Object.entries(override)) if (Array.isArray(value) && Array.isArray(result[key])) result[key] = [.../* @__PURE__ */ new Set([...result[key], ...value])];
-	else if (value && typeof value === "object" && !Array.isArray(value)) result[key] = deepMergeSchemas(result[key], value);
-	else result[key] = value;
-	return result;
-}
-function cloneShallow(value) {
-	return { ...value };
-}
-/**
-* Delete every `required` from a JSON-schema subtree — PATCH means optional at
-* every depth, not just the root.
-*
-* A generator may legitimately return an `updateBody` whose nested
-* subdocument-array `items` carries its own `required`. Stripping only the
-* root left that intact, so a PATCH adding one item to a subdocument array was
-* rejected by AJV for a field the caller had no way to know it must resend.
-* Recursing here enforces PATCH semantics on whatever a generator produces,
-* rather than trusting each to recurse correctly.
-*/
-function stripRequiredDeep(node) {
-	if (Array.isArray(node)) {
-		for (const item of node) stripRequiredDeep(item);
-		return;
-	}
-	if (!node || typeof node !== "object") return;
-	const obj = node;
-	delete obj.required;
-	for (const value of Object.values(obj)) stripRequiredDeep(value);
-}
-function safeBody(schema) {
-	if (schema && typeof schema === "object" && schema.type === "object") return {
-		additionalProperties: true,
-		...schema
-	};
-	return schema;
-}
-/**
-* Normalize `ActionsMap` into the `ActionRouterConfig` shape that
-* `createActionRouter` expects.
-*
-* **Permission fallback chain (fail-closed, v2.10.5):** delegated to the
-* shared resolver in `actionPermissions.ts`. The resource-level gate
-* goes into the resolver's slot 2 (`resourceActionPermissions`) — its
-* semantic home — leaving slot 3 (`globalAuth`) reserved for direct
-* `createActionRouter` callers that genuinely have a router-wide gate.
-*
-* The returned `actionPermissions` map is FULLY RESOLVED per action.
-* Earlier versions returned a sparse map plus a `globalAuth` field that
-* `createActionRouter` flattened at request time via `?? globalAuth`.
-* That conflated two different layers in the resolver chain (slot 2 vs.
-* slot 3). Boot-time resolution closes the drift: every action that
-* survives this pass has its effective gate baked into the map, and
-* `createActionRouter`'s request-time `?? globalAuth` becomes a no-op
-* for the defineResource path.
-*/
-function normalizeActionsToRouterConfig(actions, resourceActionPermissions, tag, resourcePermissions, resourceName, log) {
-	const handlers = {};
-	const permissions = {};
-	const schemas = {};
-	const idLessActionNames = [];
-	for (const [name, entry] of Object.entries(actions)) {
-		const explicit = typeof entry !== "function" && entry.permissions ? entry.permissions : void 0;
-		if (typeof entry === "function") handlers[name] = entry;
-		else {
-			const def = entry;
-			handlers[name] = def.handler;
-			if (def.schema) schemas[name] = def.schema;
-			if (def.id === false) idLessActionNames.push(name);
-		}
-		const effective = resolveActionPermission({
-			action: entry,
-			resourcePermissions,
-			resourceActionPermissions,
-			globalAuth: void 0
-		});
-		if (!explicit && !resourceActionPermissions && effective && effective === resourcePermissions?.update) log?.warn?.({
-			resource: resourceName,
-			action: name,
-			fallback: "permissions.update"
-		}, `[Arc] Action '${resourceName}.${name}' has no explicit permission — falling back to the resource's \`permissions.update\` gate. Declare \`actions.${name}.permissions\` (or resource \`actionPermissions\`) to silence this.`);
-		if (!effective) throw new Error(`[Arc] Resource '${resourceName}': action '${name}' has no permission gate and the resource defines no \`permissions.update\` fallback. Declare one of:\n  - \`actions.${name}.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.`);
-		permissions[name] = effective;
-	}
-	return {
-		tag,
-		actions: handlers,
-		actionPermissions: permissions,
-		actionSchemas: schemas,
-		idLessActionNames
-	};
-}
-/**
-* Build the FastifyPluginAsync that materialises a `ResourceDefinition`
-* into routes, hooks, registry entries, and cache invalidation rules.
-*
-* Called once per `ResourceDefinition.toPlugin()`. The returned plugin
-* function captures `resource` in its closure and can be `app.register`-ed
-* any number of times — shared-state writes are idempotent per host
-* Fastify instance via `resource._sharedStateRegisteredOn`.
-*/
-function buildResourcePlugin(resource) {
-	return async function resourcePlugin(fastify, opts) {
-		await ensureSchemaConverter();
-		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);
-		}
-		const arc = fastify.arc;
-		if (isFirstMount && arc?.registry && resource._registryMeta) try {
-			arc.registry.register(resource, resource._registryMeta);
-		} catch (err) {
-			fastify.log?.warn?.(`Failed to register resource '${resource.name}' in registry: ${err instanceof Error ? err.message : err}`);
-		}
-		if (isFirstMount && resource._pendingHooks.length > 0 && arc?.hooks) for (const hook of resource._pendingHooks) arc.hooks.register({
-			resource: resource.name,
-			operation: hook.operation,
-			phase: hook.phase,
-			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.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.`);
-		}
-		if (isFirstMount && resource.events && Object.keys(resource.events).length > 0) {
-			const eventsDecor = fastify.events;
-			if (!(eventsDecor != null && typeof eventsDecor.publish === "function")) {
-				const eventNames = Object.keys(resource.events).join(", ");
-				fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares events (${eventNames}) but \`eventPlugin\` is not registered. The events will silently NOT be emitted on CRUD mutations. Either register the plugin (\`await fastify.register(eventPlugin, { transport: ... })\`) or remove the \`events\` declaration from the resource.`);
-			}
-		}
-		if (opts?.arcMountRoutes === false) return;
-		await fastify.register(async (instance) => {
-			const typedInstance = instance;
-			let schemas = buildGeneratedCrudSchemas(resource._registryMeta?.openApiSchemas, resource.customSchemas);
-			const listQuerySchema = resource._registryMeta?.openApiSchemas?.listQuery;
-			if (listQuerySchema) {
-				const normalizedSchema = normalizeListQuerySchema(listQuerySchema);
-				schemas = schemas ?? {};
-				schemas.list = schemas.list ? deepMergeSchemas({ querystring: normalizedSchema }, schemas.list) : { querystring: normalizedSchema };
-			}
-			createCrudRouter(typedInstance, resource.controller, {
-				tag: resource.tag,
-				schemas: schemas ?? void 0,
-				permissions: resource.permissions,
-				middlewares: resource.middlewares,
-				routeGuards: resource.routeGuards,
-				routes: resource.routes,
-				disableDefaultRoutes: resource.disableDefaultRoutes,
-				disabledRoutes: [...resource.disabledRoutes],
-				resourceName: resource.name,
-				schemaOptions: resource.schemaOptions,
-				rateLimit: resource.rateLimit,
-				updateMethod: resource.updateMethod,
-				pipe: resource.pipe,
-				fields: resource.fields,
-				onFieldWriteDenied: resource.onFieldWriteDenied,
-				idField: resource.idField,
-				extensions: resource.extensions
-			});
-			if (resource.actions && Object.keys(resource.actions).length > 0) {
-				const { createActionRouter } = await import("./createActionRouter-BBlbPs3k.mjs").then((n) => n.n);
-				createActionRouter(typedInstance, {
-					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
-					resourceName: resource.name,
-					fields: resource.fields,
-					schemaOptions: resource.schemaOptions,
-					idField: resource.idField,
-					permissions: resource.permissions,
-					routeGuards: resource.routeGuards,
-					pipeline: resource.pipe,
-					rateLimit: resource.rateLimit,
-					extensions: resource.extensions
-				});
-			}
-			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-Dv5SuK2x.mjs"), import("./validate-R0G_JrnK.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);
-					if (undispatchable.length > 0) throw new ArcAggregationConfigError(`Resource '${resource.name}' declares aggregations [${undispatchable.join(", ")}] but no repository implementing 'aggregate(req, options?)' is wired. Either (a) attach an adapter whose repo ships StandardRepo.aggregate (mongokit >= 3.13 / sqlitekit >= 0.3), (b) pass a custom controller exposing such a repository, or (c) declare 'materialized' on each aggregation so it dispatches through your own hook.`);
-				}
-				const buildOptions = (req) => {
-					const ctrl = resource.controller;
-					if (!ctrl?.tenantRepoOptions) return {};
-					const ctx = createRequestContext(req);
-					return ctrl.tenantRepoOptions(ctx);
-				};
-				createAggregationRouter(typedInstance, {
-					tag: resource.tag,
-					resourceName: resource.name,
-					aggregations: resource.aggregations,
-					fields: resource.fields,
-					schemaOptions: resource.schemaOptions,
-					permissions: resource.permissions,
-					routeGuards: resource.routeGuards,
-					repository: repoForAgg,
-					buildOptions,
-					middlewares: resource.middlewares?.aggregations
-				});
-			}
-			if (resource.events && Object.keys(resource.events).length > 0) typedInstance.log?.debug?.(`Resource '${resource.name}' defined ${Object.keys(resource.events).length} events`);
-		}, { prefix: resource.prefix });
-		if (hasEvents(fastify)) try {
-			await fastify.events.publish("arc.resource.registered", {
-				resource: resource.name,
-				prefix: resource.prefix,
-				presets: resource._appliedPresets,
-				timestamp: (/* @__PURE__ */ new Date()).toISOString()
-			});
-		} catch {}
-	};
-}
-//#endregion
 //#region src/core/defineResource/ResourceDefinition.ts
 var ResourceDefinition = class {
 	name;
@@ -1500,6 +683,8 @@ var ResourceDefinition = class {
 	aggregations;
 	events;
 	rateLimit;
+	idempotency;
+	lookupFields;
 	audit;
 	updateMethod;
 	pipe;
@@ -1533,6 +718,12 @@ var ResourceDefinition = class {
 	*/
 	resolvedTenantPurge;
 	idField;
+	/**
+	* The optimistic-concurrency version field, resolved (`concurrency: {}` → `'__v'`);
+	* `undefined` when the resource did not opt in. Published in the resource manifest
+	* so a client sends `If-Match` without repeating the field name.
+	*/
+	versionField;
 	queryParser;
 	_appliedPresets;
 	_pendingHooks;
@@ -1621,6 +812,8 @@ var ResourceDefinition = class {
 		this.actionPermissions = config.actionPermissions;
 		this.aggregations = config.aggregations;
 		this.rateLimit = config.rateLimit;
+		this.idempotency = config.idempotency;
+		this.lookupFields = config.lookupFields;
 		this.audit = config.audit;
 		this.updateMethod = config.updateMethod;
 		this.pipe = config.pipe;
@@ -1638,6 +831,7 @@ var ResourceDefinition = class {
 			onTenantDelete: this.onTenantDelete
 		});
 		this.idField = config.idField;
+		if (config.concurrency) this.versionField = config.concurrency.versionField ?? "__v";
 		this.queryParser = config.queryParser;
 		this._appliedPresets = config._appliedPresets ?? [];
 		this._pendingHooks = config._pendingHooks ?? [];
@@ -1754,161 +948,6 @@ function freezeActions(actions) {
 	return Object.freeze(frozen);
 }
 //#endregion
-//#region src/core/defineResource/schemas.ts
-/**
-* OpenAPI schema resolution — Phase 7 of `defineResource()`.
-*
-* Pipeline (each step is a pure function over `OpenApiSchemas | undefined`):
-*
-*   adapter.generateSchemas()
-*     → stripSystemManagedFromBodyRequired   (from `../schemaOptions.js`)
-*     → cleanLegacyObjectIdParams            (idField safety net)
-*     → layerQueryParserListQuery            (kit's listQuery JSON Schema)
-*     → mergeUserOpenApiOverrides            (per-resource overrides)
-*     → convertOpenApiSchemas                (Zod → JSON Schema if needed)
-*
-* Non-fatal: if any step throws, the orchestrator returns `undefined` so
-* the resource still boots — docs / introspection / MCP tool schemas
-* degrade visibly instead of silently drifting.
-*
-* Pulled out of `defineResource.ts` so the central function reads as
-* orchestration only; the schema mechanics live next to each other and
-* are easier to evolve in isolation.
-*/
-/**
-* Phase 7 orchestrator — runs the schema pipeline and returns the
-* registry metadata for the resource. Returns `undefined` (with a
-* structured warn log) if any step throws.
-*/
-function resolveOpenApiSchemas(resolvedConfig) {
-	try {
-		let openApiSchemas = generateAdapterSchemas(resolvedConfig);
-		openApiSchemas = stripSystemManagedFromBodyRequired(openApiSchemas, resolvedConfig.schemaOptions);
-		openApiSchemas = cleanLegacyObjectIdParams(openApiSchemas, resolvedConfig.idField);
-		openApiSchemas = layerQueryParserListQuery(openApiSchemas, resolvedConfig.queryParser);
-		openApiSchemas = applyResourcePaginationCaps(openApiSchemas, resolvedConfig);
-		openApiSchemas = mergeUserOpenApiOverrides(openApiSchemas, resolvedConfig.openApiSchemas);
-		if (openApiSchemas) openApiSchemas = convertOpenApiSchemas(openApiSchemas);
-		return {
-			module: resolvedConfig.module,
-			openApiSchemas
-		};
-	} catch (err) {
-		arcLog("defineResource").warn(`OpenAPI/MCP schema generation failed for resource "${resolvedConfig.name}": ${err instanceof Error ? err.message : String(err)}. Resource will boot without registry metadata — OpenAPI docs and MCP tool schemas will be missing.`);
-		return;
-	}
-}
-/**
-* Step 1 — delegate to the adapter's `generateSchemas`. Returns
-* `undefined` when the adapter doesn't implement the optional method.
-*/
-function generateAdapterSchemas(resolvedConfig) {
-	if (!resolvedConfig.adapter?.generateSchemas) return void 0;
-	const adapterContext = {
-		idField: resolvedConfig.idField,
-		resourceName: resolvedConfig.name
-	};
-	return resolvedConfig.adapter.generateSchemas(resolvedConfig.schemaOptions, adapterContext);
-}
-/**
-* Safety net: when `idField` is overridden to a non-default value (UUIDs,
-* slugs, ORD-2026-0001), strip any ObjectId pattern left on `params.id` by
-* legacy adapters or plugins that didn't honor `AdapterSchemaContext.idField`.
-* Custom IDs must not be rejected by AJV before BaseController runs the
-* actual lookup.
-*/
-function cleanLegacyObjectIdParams(openApiSchemas, idField) {
-	if (!openApiSchemas || !idField || idField === "_id") return openApiSchemas;
-	const params = openApiSchemas.params;
-	if (!params || typeof params !== "object") return openApiSchemas;
-	const properties = params.properties;
-	const idProp = properties?.id;
-	if (!idProp || typeof idProp !== "object") return openApiSchemas;
-	const pattern = idProp.pattern;
-	if (!(typeof pattern === "string" && (pattern === "^[0-9a-fA-F]{24}$" || pattern === "^[a-f\\d]{24}$" || pattern === "^[a-fA-F0-9]{24}$" || /^\^\[[a-fA-F0-9\\d]+\]\{24\}\$$/.test(pattern)))) return openApiSchemas;
-	const cleanedId = { ...idProp };
-	delete cleanedId.pattern;
-	delete cleanedId.minLength;
-	delete cleanedId.maxLength;
-	if (!cleanedId.description) cleanedId.description = `${idField} (custom ID field)`;
-	return {
-		...openApiSchemas,
-		params: {
-			...params,
-			properties: {
-				...properties,
-				id: cleanedId
-			}
-		}
-	};
-}
-/**
-* Layer the query parser's `getQuerySchema()` output as `listQuery` so
-* the kit's filterable-fields surface flows into OpenAPI / MCP without
-* the user re-declaring it.
-*/
-function layerQueryParserListQuery(openApiSchemas, queryParser) {
-	const qp = queryParser;
-	if (!qp?.getQuerySchema) return openApiSchemas;
-	const querySchema = qp.getQuerySchema();
-	if (!querySchema) return openApiSchemas;
-	return {
-		...openApiSchemas,
-		listQuery: querySchema
-	};
-}
-/**
-* Apply resource-level `defaultLimit` / `maxLimit` (2.17.0) onto the
-* listQuery schema. Resource-level caps win over both the framework
-* default and the parser-derived value because they're the most-explicit
-* declaration — a host that wrote `defaultLimit: 1000` on the resource
-* means "this resource specifically returns up to 1000", regardless of
-* what the parser's default would have been. The `referenceData: true`
-* shorthand lifts both to 1000 so reference-data resources don't need
-* a custom queryParser just to get the caps right.
-*
-* Bootstraps a minimal listQuery slot when none exists (no queryParser
-* registered, no adapter-generated schema) so the AJV layer still gets
-* a `maximum:` and surfaces the cap in the 400 envelope via
-* `errorHandler.describePaginationCap()` instead of producing the
-* generic "Bad Request" we ate pre-2.17.0.
-*/
-function applyResourcePaginationCaps(openApiSchemas, resolvedConfig) {
-	const cfg = resolvedConfig;
-	if (cfg.defaultLimit === void 0 && cfg.maxLimit === void 0) return openApiSchemas;
-	const existing = openApiSchemas?.listQuery;
-	const existingProps = existing?.properties ?? {};
-	const patchedLimit = { ...existingProps.limit ?? {
-		type: "integer",
-		minimum: 1
-	} };
-	if (cfg.maxLimit !== void 0) patchedLimit.maximum = cfg.maxLimit;
-	if (cfg.defaultLimit !== void 0) patchedLimit.default = cfg.defaultLimit;
-	return {
-		...openApiSchemas,
-		listQuery: {
-			type: "object",
-			...existing ?? {},
-			properties: {
-				...existingProps,
-				limit: patchedLimit
-			}
-		}
-	};
-}
-/**
-* Apply per-resource `openApiSchemas` overrides on top of the kit's
-* generated schemas. Shallow merge by slot — users who want field-level
-* surgery should compose at the schema-options layer before this point.
-*/
-function mergeUserOpenApiOverrides(openApiSchemas, userOverrides) {
-	if (!userOverrides) return openApiSchemas;
-	return {
-		...openApiSchemas,
-		...userOverrides
-	};
-}
-//#endregion
 //#region src/core/validateResourceConfig.ts
 /**
 * Resource Configuration Validator
@@ -2268,11 +1307,26 @@ const CRUD_OP_NAMES = /* @__PURE__ */ new Set([
 * resulting `ResourceDefinition` for the plugin layer to flush through
 * `fastify.log.warn` on first mount.
 */
-function validateDefineResourceConfig(config) {
-	assertValidConfig(config, { skipControllerCheck: true });
+/**
+* The checks NO flag may skip — `skipValidation` / `customRoutesOnly` skip structural and advisory
+* checks only. A route without a permission would otherwise mount PUBLIC.
+*/
+function validateSecurityInvariants(config) {
 	validatePermissionsShape(config);
 	validateCustomRoutePermissions(config);
 	validateActionsShape(config);
+	validateLookupPolicies(config);
+}
+/** Every allowed join names the server scope of its joined side — a collection name alone authorizes nothing. */
+function validateLookupPolicies(config) {
+	const allowed = config.schemaOptions?.query?.allowedLookups;
+	if (allowed === void 0) return;
+	if (Array.isArray(allowed) || typeof allowed !== "object" || allowed === null) throw new Error(`[Arc] Resource '${config.name}': schemaOptions.query.allowedLookups must map each collection to { scope: ({ scope }) => filter } — the joined side is not tenant-scoped by arc, so a name list authorizes nothing.`);
+	for (const [collection, policy] of Object.entries(allowed)) if (typeof policy?.scope !== "function") throw new Error(`[Arc] Resource '${config.name}': allowedLookups.${collection} needs a scope function — the filter on its joined rows.`);
+}
+function validateDefineResourceConfig(config) {
+	assertValidConfig(config, { skipControllerCheck: true });
+	validateSecurityInvariants(config);
 	validateRouteCapabilities(config);
 	return [
 		...collectRedundantFieldRuleDiagnostics(config),
@@ -2449,15 +1503,49 @@ function validateActionsShape(config) {
 }
 //#endregion
 //#region src/core/defineResource.ts
+/**
+* Resource Definition — database-agnostic single source of truth.
+*
+* `defineResource()` is the main entry point for arc resources. It
+* runs a fixed seven-phase pipeline that produces a fully-validated
+* `ResourceDefinition`:
+*
+*   1. validate                  — fail-fast structural checks
+*   2. resolveIdField            — auto-derive `idField` from repository
+*   3. applyPresetsAndAutoInject — clone + apply presets + tenant rules
+*   4. resolveController         — reuse user controller or auto-build
+*   5. buildResource             — construct ResourceDefinition + verify
+*   6. wireHooks                 — preset + inline `config.hooks`
+*   7. resolveOpenApiSchemas     — adapter → parser listQuery → user
+*
+* Each phase has its own module under `./defineResource/`. This file
+* is the orchestrator only — it threads `resolvedConfig` between
+* phases and delegates every responsibility. The `ResourceDefinition`
+* class itself lives in `./defineResource/ResourceDefinition.ts`.
+*
+* The adapter is the only kit-specific part — every kit's factory plugs in
+* identically.
+*
+* @example
+* ```typescript
+* export default defineResource({
+*   name: 'product',
+*   adapter: createMongooseAdapter({ model: ProductModel, repository: repo }),
+*   presets: ['softDelete', 'slugLookup'],
+*   permissions: { list: allowPublic(), create: requireRoles(['admin']) },
+* });
+* ```
+*/
 function defineResource(config) {
 	const normalisedConfig = normalizeResourceConfig(config);
 	let diagnostics = [];
 	if (!normalisedConfig.skipValidation) diagnostics = validateDefineResourceConfig(normalisedConfig);
+	else validateSecurityInvariants(normalisedConfig);
 	const repository = normalisedConfig.adapter?.repository;
 	const configWithId = resolveIdField(normalisedConfig, repository);
 	const resolvedConfig = applyPresetsAndAutoInject(configWithId);
 	const hasCrudRoutes = computeHasCrudRoutes(resolvedConfig);
-	const strict = resolvedConfig.strictPermissions ?? process.env.ARC_STRICT_PERMISSIONS === "true";
+	const strict = resolvedConfig.strictPermissions ?? readEnv(process.env).bool("ARC_STRICT_PERMISSIONS", true);
 	diagnostics = diagnostics.concat(collectUngatedCrudDiagnostics(resolvedConfig, strict));
 	const fatal = diagnostics.filter((d) => d.severity === "error");
 	if (fatal.length > 0) throw new Error(fatal.map((d) => d.message).join("\n\n"));
@@ -2475,12 +1563,18 @@ function defineResource(config) {
 		const registryMeta = resolveOpenApiSchemas(narrowedConfig);
 		if (registryMeta) resource._registryMeta = registryMeta;
 	}
+	const deferred = [];
 	if (resolvedConfig.transactional === true) {
 		const name = resolvedConfig.name;
-		resource._deferredChecks = [() => assertTransactionCapability(repository, name)];
+		deferred.push(() => assertTransactionCapability(repository, name));
+	}
+	if (resolvedConfig.concurrency) {
+		const name = resolvedConfig.name;
+		deferred.push(() => assertConcurrencyCapability(repository, name));
 	}
+	if (deferred.length > 0) resource._deferredChecks = deferred;
 	if (diagnostics.length > 0) resource._diagnostics = diagnostics;
 	return resource;
 }
 //#endregion
-export { ResourceDefinition as a, validateResourceConfig as i, assertValidConfig as n, createCrudRouter as o, formatValidationErrors as r, createPermissionMiddleware as s, defineResource as t };
+export { ResourceDefinition as a, validateResourceConfig as i, assertValidConfig as n, formatValidationErrors as r, defineResource as t };