@classytic/arc 2.41.1 → 2.43.0

package/dist/{BaseController-CYEwjyjN.mjs → plugin-BccET1tL.mjs}

@@ -1,18 +1,28 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-D5Ubn1fe.mjs";
-import { arcLog } from "./logger/index.mjs";
-import { a as conjoinPolicyFilters } from "./authorizationDecision-DawKGoXb.mjs";
-import { d as createDomainError, f as createError, i as NotFoundError, p as isArcError, r as ForbiddenError, u as ValidationError } from "./errors-BH7YU_9O.mjs";
-import { n as getUserRoles, t as getUserId } from "./userHelpers-ChRvkuSZ.mjs";
-import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-CgenB1gv.mjs";
-import { t as simpleEqualityMatcher } from "./simpleEqualityMatcher-C9bzq2gO.mjs";
-import { t as buildQueryKey } from "./keys-cpZCtcIE.mjs";
-import { t as transactionContext } from "./transactionContext-CPbdlnVw.mjs";
-import { D as ArcQueryParser, j as scheduleBackground } from "./utils-CxcctrAh.mjs";
-import { a as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-BHrkoF5y.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { g as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-Cu7Mx7_U.mjs";
+import { t as arcLog } from "./logger-DXjfIqjV.mjs";
+import { t as conjoinPolicyFilters } from "./filter-merge-IpGywvym.mjs";
+import { d as createDomainError, f as createError, i as NotFoundError, p as isArcError, r as ForbiddenError, u as ValidationError } from "./errors-CtrywMHP.mjs";
+import { t as simpleEqualityMatcher } from "./simpleEqualityMatcher-auW8QjXN.mjs";
+import { n as requireSingleHeaderValue } from "./headers-BbkIF6vA.mjs";
+import { n as getUserRoles, t as getUserId } from "./userHelpers-aklawRaK.mjs";
+import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-Bk9NOgOC.mjs";
+import { r as resolveTenancy } from "./tenancy--ed9eH_z.mjs";
+import { t as buildQueryKey } from "./keys-B2KtgMLJ.mjs";
+import { t as transactionContext } from "./transactionContext-DjFkrNG6.mjs";
+import { a as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-ToPYpMqS.mjs";
+import { E as ArcQueryParser, v as getDefaultCrudSchemas } from "./utils-ec1oTo1n.mjs";
+import { n as convertRouteSchema, r as ensureSchemaConverter, t as convertOpenApiSchemas } from "./schemaConverter-BORek3O-.mjs";
+import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-DjTQhZrN.mjs";
+import { _ as buildArcDecorator, a as resolveRouterPluginMw, b as createRequestContext, c as buildPipelineHandler, d as buildCrudPermissionMw, f as buildRouteHooks, h as buildAuthMiddleware, i as buildRouteConfig, l as resolvePipelineSteps, m as routeHookOptions, n as tryRegisterRoute, o as selectPluginMw, p as resolveRoutePreHandlers, r as buildRateLimitConfig, t as resolveActionPermission, v as createCrudHandlers, y as createFastifyHandler } from "./actionPermissions-BotX1YOa.mjs";
+import { a as withoutTenantInjection } from "./tenantPreparation-BKon6Yox.mjs";
+import { t as hasEvents } from "./typeGuards-CySF12G-.mjs";
+import { n as idempotencyConfigProblem } from "./requirement-KDdoRcOP.mjs";
+import { ARC_ERROR_CODES } from "@classytic/repo-core/errors";
 import { policyRecordToFilter } from "@classytic/repo-core/filter";
 import { retryingTransaction } from "@classytic/repo-core/repository";
-import { isProductionEnv } from "@classytic/primitives/environment";
+import { scheduleBackground } from "@classytic/repo-core/cache";
+import { isProductionEnv, readEnv } from "@classytic/primitives/environment";
 //#region src/core/repositoryFilter.ts
 const NATIVE_FILTER_DIALECT = Symbol.for("@classytic/arc/native-filter-dialect");
 /**
@@ -115,10 +125,8 @@ var AccessControl = class {
 		const arcContext = this._meta(req);
 		const policyFilters = arcContext?._policyFilters;
 		if (policyFilters) filter = conjoinPolicyFilters(filter, policyFilters);
-		const crossTenantRead = arcContext?._crossTenantRead === true;
-		const scope = arcContext?._scope;
-		const orgId = scope ? getOrgId(scope) : void 0;
-		if (this.tenantField && orgId && !crossTenantRead) filter = conjoinPolicyFilters(filter, { [this.tenantField]: orgId });
+		const tenancy = resolveTenancy(arcContext, this.tenantField);
+		if (tenancy.mode === "scoped") filter = conjoinPolicyFilters(filter, { [tenancy.field]: tenancy.orgId });
 		return toRepositoryFilter(filter);
 	}
 	/**
@@ -179,14 +187,11 @@ var AccessControl = class {
 	* unscoped records from leaking across tenants.
 	*/
 	checkOrgScope(item, arcContext) {
-		if (!this.tenantField) return true;
-		if (arcContext?._crossTenantRead === true) return true;
-		const scope = arcContext?._scope;
-		const orgId = scope ? getOrgId(scope) : void 0;
-		if (!item || !orgId) return true;
-		const itemOrgId = item[this.tenantField];
+		const tenancy = resolveTenancy(arcContext, this.tenantField);
+		if (tenancy.mode !== "scoped" || !item) return true;
+		const itemOrgId = item[tenancy.field];
 		if (!itemOrgId) return false;
-		return String(itemOrgId) === String(orgId);
+		return String(itemOrgId) === String(tenancy.orgId);
 	}
 	/** Check ownership for update/delete (ownedByUser preset) */
 	checkOwnership(item, req) {
@@ -342,7 +347,7 @@ var BodySanitizer = class {
 	constructor(config) {
 		this.schemaOptions = config.schemaOptions;
 		this.onFieldWriteDenied = config.onFieldWriteDenied ?? "reject";
-		this.onImmutableWrite = config.onImmutableWrite ?? (process.env.ARC_STRICT_IMMUTABLE_WRITES === "true" ? "reject" : "strip");
+		this.onImmutableWrite = config.onImmutableWrite ?? (readEnv(process.env).bool("ARC_STRICT_IMMUTABLE_WRITES", true) ? "reject" : "strip");
 	}
 	/**
 	* Strip readonly and system-managed fields from request body.
@@ -424,21 +429,16 @@ function buildTenantRepoOptions(req, tenantField, arcContext) {
 	const cached = req._tenantRepoOptions;
 	if (cached) return cached;
 	const out = {};
-	const scope = arcContext?._scope;
-	if (arcContext?._crossTenantRead === true) {
-		out.bypassTenant = true;
-		req._tenantRepoOptions = out;
-		return out;
-	}
-	if (tenantField) {
-		const orgId = scope ? getOrgId(scope) : void 0;
-		if (orgId) out[tenantField] = orgId;
-	}
-	const presetFields = req._tenantFields;
-	if (presetFields && typeof presetFields === "object") {
-		for (const [key, value] of Object.entries(presetFields)) if (value != null && out[key] == null) out[key] = value;
+	const tenancy = resolveTenancy(arcContext, tenantField);
+	if (tenancy.mode === "unscoped" && tenancy.reason === "cross-tenant") out.bypassTenant = true;
+	else {
+		if (tenancy.mode === "scoped") out[tenancy.field] = tenancy.orgId;
+		const presetFields = arcContext?._tenantFields ?? req._tenantFields;
+		if (presetFields && typeof presetFields === "object") {
+			for (const [key, value] of Object.entries(presetFields)) if (value != null && out[key] == null) out[key] = value;
+		}
+		if (tenancy.mode === "unscoped" && tenancy.reason === "platform" && tenantField && out[tenantField] == null) out.bypassTenant = true;
 	}
-	if (tenantField && out[tenantField] == null && scope && isElevated(scope)) out.bypassTenant = true;
 	const userId = getUserId(req.user);
 	if (userId) out.userId = userId;
 	if (req.user) out.user = req.user;
@@ -567,6 +567,14 @@ function resolveOpCacheConfig(cfg, operation) {
 * Extract user/org IDs from request for cache key scoping.
 * Only includes orgId when the resource uses tenant-scoped data (tenantField is set).
 * Universal resources (tenantField: false) get shared cache keys.
+*
+* Deliberately NOT `resolveTenancy`. That answers "is this read FILTERED by
+* tenant?"; this answers "whose cache PARTITION is it?", and the two diverge on
+* a cross-tenant read: unfiltered, yet still partitioned by the caller's org.
+* A cross-tenant listing's row policy may differ per org ("plus anything your
+* organization bought"), so dropping the org from the key would let one org's
+* cached page answer another's. Over-partitioning costs hit rate; the other
+* direction costs a leak.
 */
 function deriveCacheScope(req, tenantField, arcContext) {
 	return {
@@ -751,6 +759,21 @@ function isFieldReadable(rule) {
 	return rule.hidden !== true;
 }
 /**
+* Does `path` touch a blocked field? The ONE path rule every read surface uses: blocked by its own
+* name or by ANY ancestor (a rule on a parent covers its children). With `descendants`, a blocked
+* field UNDER `path` counts too — for surfaces that return the value raw (`_distinct`, aggregation
+* groups), where the parent object carries the hidden child.
+*/
+function pathTouchesBlocked(path, blocked, options = {}) {
+	if (blocked.has(path)) return true;
+	for (let dot = path.indexOf("."); dot > 0; dot = path.indexOf(".", dot + 1)) if (blocked.has(path.slice(0, dot))) return true;
+	if (options.descendants) {
+		const prefix = `${path}.`;
+		for (const field of blocked) if (field.startsWith(prefix)) return true;
+	}
+	return false;
+}
+/**
 * The set of field names blocked from read-side surfaces (used by
 * `QueryResolver.sanitizeSelectAny` and `BaseCrudController._distinct`).
 *
@@ -796,27 +819,6 @@ function noteDeniedJoins(kind) {
 	notedDeniedJoins = true;
 	log.warn(`client requested ${kind} but no allowlist is configured — DENIED (2.24 default flip; it was allow-all). Set schemaOptions.query.allowedPopulate / allowedLookups to enable client-driven joins. (dev-only note, shown once)`);
 }
-/**
-* A `$lookup` reaches ANOTHER collection, and the tenant filter arc conjoins applies to the
-* BASE one only. The joined side carries whatever predicate the lookup itself names and
-* nothing more — no tenant scope, no soft-delete filter — so a resource that opens
-* `allowedLookups` can return rows from a collection the caller could not query directly.
-*
-* Unreachable by default (2.24 denies `lookup=` with no allowlist) and no resource in this
-* fleet configures one, so this is a WARNING at the moment a deployment first opts in
-* rather than machinery for a door nobody has opened. Warned once per collection set: the
-* decision is made when the allowlist is written, not per request.
-*
-* Scope the join with the lookup's own `where`, which mongokit compiles into a `$match`
-* inside the lookup pipeline.
-*/
-const notedUnscopedJoins = /* @__PURE__ */ new Set();
-function noteUnscopedJoin(lookups) {
-	const key = lookups.map((l) => l.from).filter((f) => typeof f === "string").sort().join(",");
-	if (key.length === 0 || notedUnscopedJoins.has(key)) return;
-	notedUnscopedJoins.add(key);
-	log.warn(`client-driven $lookup on [${key}] — the JOINED side carries no tenant or soft-delete filter (arc scopes the base collection only). Narrow each lookup with its own \`where\`, or the join can surface rows the caller cannot query directly. (shown once)`);
-}
 var QueryResolver = class {
 	queryParser;
 	maxLimit;
@@ -939,6 +941,8 @@ var QueryResolver = class {
 			const { _policyFilters: _ignored, ...rest } = rawQuery;
 			query = rest;
 		}
+		const keyset = readKeysetControls(query);
+		if (keyset.stripped) query = keyset.query;
 		const parsed = this.queryParser.parse(query);
 		/**
 		* Client-supplied keys only, and BEFORE the policy conjunction below: trusted policy
@@ -948,14 +952,16 @@ var QueryResolver = class {
 		this.assertNoBlockedReadKeys(parsed.filters, parsed.sort);
 		const arcContext = meta ?? req.metadata;
 		const limit = Math.min(Math.max(1, parsed.limit || this.defaultLimit), this.maxLimit);
-		const page = parsed.after ? void 0 : parsed.page ? Math.max(1, parsed.page) : 1;
+		const after = parsed.after;
+		const before = keyset.before;
+		const keysetMode = keyset.mode === "keyset" || after !== void 0 || before !== void 0;
+		const page = keysetMode ? void 0 : parsed.page ? Math.max(1, parsed.page) : 1;
 		const sortString = parsed.sort ? Object.entries(parsed.sort).map(([k, v]) => v === -1 ? `-${k}` : k).join(",") : this.permittedDefaultSort();
 		const rawSelect = parsed.select ?? req.query?.select;
 		const policyFilters = arcContext?._policyFilters;
 		let filters = conjoinPolicyFilters(parsed.filters, policyFilters);
-		const scope = arcContext?._scope;
-		const orgId = scope ? getOrgId(scope) : void 0;
-		if (this.tenantField && orgId && !arcContext?._crossTenantRead && !policyFilters?.[this.tenantField]) filters = conjoinPolicyFilters(filters, { [this.tenantField]: orgId });
+		const tenancy = resolveTenancy(arcContext, this.tenantField);
+		if (tenancy.mode === "scoped" && !policyFilters?.[tenancy.field]) filters = conjoinPolicyFilters(filters, { [tenancy.field]: tenancy.orgId });
 		const portableFilters = toRepositoryFilter(filters);
 		return {
 			page,
@@ -964,10 +970,12 @@ var QueryResolver = class {
 			select: this.sanitizeSelectAny(rawSelect, this.schemaOptions),
 			populate: this.sanitizePopulate(parsed.populate, this.schemaOptions),
 			populateOptions: this.sanitizePopulateOptions(parsed.populateOptions, this.schemaOptions),
-			lookups: this.sanitizeLookups(parsed.lookups, this.schemaOptions),
+			lookups: this.sanitizeLookups(parsed.lookups, this.schemaOptions, arcContext?._scope),
 			filters: portableFilters,
 			search: parsed.search,
-			after: parsed.after,
+			...after !== void 0 ? { after } : {},
+			...before !== void 0 ? { before } : {},
+			...keysetMode ? { mode: "keyset" } : {},
 			user: req.user,
 			context: arcContext
 		};
@@ -1019,11 +1027,11 @@ var QueryResolver = class {
 		return sanitized.length > 0 ? sanitized : void 0;
 	}
 	/**
-	* Sanitize lookup/join options. Deny-by-default: `allowedLookups` must be
-	* configured for any client-driven lookup to pass; listed collections are
-	* then structurally validated to prevent injection.
+	* Client lookups, deny-by-default. An allowed one is structurally validated, and its joined side
+	* is filtered by the resource's server-owned `LookupPolicy.scope` — the base collection's tenant
+	* filter never reaches a join, and a client-supplied `where` is replaced, never merged.
 	*/
-	sanitizeLookups(lookups, schemaOptions) {
+	sanitizeLookups(lookups, schemaOptions, scope) {
 		if (!lookups || lookups.length === 0) return void 0;
 		const allowedLookups = schemaOptions.query?.allowedLookups;
 		if (!allowedLookups) {
@@ -1031,15 +1039,17 @@ var QueryResolver = class {
 			return;
 		}
 		const validFieldName = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
-		const sanitized = lookups.filter((lookup) => {
-			if (!lookup.from || !lookup.localField || !lookup.foreignField) return false;
-			if (!validFieldName.test(lookup.from)) return false;
-			if (!validFieldName.test(lookup.localField)) return false;
-			if (!validFieldName.test(lookup.foreignField)) return false;
-			if (!allowedLookups.includes(lookup.from)) return false;
-			return true;
+		const sanitized = lookups.flatMap((lookup) => {
+			if (!lookup.from || !lookup.localField || !lookup.foreignField) return [];
+			if (!validFieldName.test(lookup.from)) return [];
+			if (!validFieldName.test(lookup.localField)) return [];
+			if (!validFieldName.test(lookup.foreignField)) return [];
+			const policy = Object.hasOwn(allowedLookups, lookup.from) ? allowedLookups[lookup.from] : void 0;
+			return policy ? [{
+				...lookup,
+				where: policy.scope({ scope })
+			}] : [];
 		});
-		if (sanitized.length > 0) noteUnscopedJoin(sanitized);
 		return sanitized.length > 0 ? sanitized : void 0;
 	}
 	/**
@@ -1061,8 +1071,7 @@ var QueryResolver = class {
 	* whoever wrote it.
 	*/
 	isBlockedProjection(path, blockedFields) {
-		const field = path.replace(/^-/, "");
-		return blockedFields.some((blocked) => field === blocked || field.startsWith(`${blocked}.`));
+		return pathTouchesBlocked(path.replace(/^-/, ""), new Set(blockedFields));
 	}
 	/**
 	* Refuse a read that FILTERS or SORTS on a `hidden` field.
@@ -1085,11 +1094,7 @@ var QueryResolver = class {
 		const blocked = collectReadBlockedFields(this.schemaOptions);
 		if (!blocked) return;
 		const offenders = /* @__PURE__ */ new Set();
-		const isBlocked = (key) => {
-			if (blocked.has(key)) return true;
-			const dot = key.indexOf(".");
-			return dot > 0 && blocked.has(key.slice(0, dot));
-		};
+		const isBlocked = (key) => pathTouchesBlocked(key, blocked);
 		const walk = (node, depth) => {
 			if (depth > 8 || !node || typeof node !== "object") return;
 			if (Array.isArray(node)) {
@@ -1115,14 +1120,33 @@ var QueryResolver = class {
 		})));
 	}
 };
+/**
+* `mode` and `before` — lifted out of the query so no
+* parser reads them as filters. An unknown `mode` is refused with a closed code.
+*/
+function readKeysetControls(query) {
+	if (!query || !("mode" in query || "before" in query)) return {
+		query,
+		stripped: false
+	};
+	const { mode, before, ...rest } = query;
+	if (mode !== void 0 && mode !== "offset" && mode !== "keyset") throw createDomainError("arc.pagination.invalid_mode", `mode must be 'offset' or 'keyset', got '${String(mode)}'`, 400);
+	if (before !== void 0 && (typeof before !== "string" || before === "")) throw new ValidationError("before must be a non-empty cursor string", [{
+		field: "before",
+		message: "a cursor from a page's prev"
+	}]);
+	return {
+		query: rest,
+		stripped: true,
+		...mode !== void 0 ? { mode } : {},
+		...typeof before === "string" ? { before } : {}
+	};
+}
 //#endregion
 //#region src/core/BaseCrudController.ts
 /**
 * Framework-agnostic CRUD controller implementing IController.
-*
-* Composes AccessControl, BodySanitizer, and QueryResolver. All shared
-* state and helpers are `protected` so the preset mixins (SoftDelete,
-* Tree, Slug, Bulk) can extend cleanly.
+* Composes AccessControl, BodySanitizer, and QueryResolver.
 *
 * @template TDoc - The document type.
 * @template TRepository - The repository type (defaults to RepositoryLike).
@@ -1136,73 +1160,38 @@ var BaseCrudController = class {
 	resourceName;
 	tenantField;
 	idField = "_id";
-	/**
-	* Composable access control (ID filtering, policy checks, org scope, ownership).
-	*
-	* Not `readonly` — `configure()` rebuilds it when the host
-	* supplies tenant/idField/matchesFilter post-construction. Same model as
-	* `queryResolver` after `setQueryParser` shipped in 2.10.9.
-	*/
+	/** Alternate unique keys, each with its own access control over the SAME scope. */
+	lookupAccess = [];
+	_lookupFields;
+	/** Access control (ID filtering, policy checks, org scope, ownership). */
 	accessControl;
-	/**
-	* Composable body sanitization (field permissions, system fields).
-	*
-	* Not `readonly` — `configure()` rebuilds it when the host
-	* supplies schemaOptions/onFieldWriteDenied post-construction.
-	*/
+	/** Body sanitization (field permissions, system fields). */
 	bodySanitizer;
-	/**
-	* Composable query resolution (parsing, pagination, sort, select/populate).
-	*
-	* Not `readonly` — `setQueryParser()` rebuilds this resolver to swap in a
-	* different parser (e.g. mongokit's `QueryParser`). `defineResource` calls
-	* it automatically when a resource supplies both `controller` and
-	* `queryParser`.
-	*/
+	/** Query resolution (parsing, pagination, sort, select/populate). */
 	queryResolver;
 	_matchesFilter;
 	_presetFields = {};
 	_cacheConfig;
 	/**
-	* Retained construction-time values so partial `configure()` rebuilds
-	* (e.g. `configure({ schemaOptions })`) reuse them instead of silently
-	* falling back to the sub-component defaults (`-createdAt` sort,
-	* `reject` write-denial) — `defaultSort: false` matters for kits
-	* without a `createdAt` column, `strip` for legacy write semantics.
+	* Retained so partial `configure()` rebuilds reuse them instead of falling back
+	* to sub-component defaults (`-createdAt` sort breaks kits without that column).
 	*/
 	_defaultSort;
 	_onFieldWriteDenied;
 	_onImmutableWrite;
 	/**
-	* Domain commands bound to the write slots (`ResourceWrites`). Consulted at
-	* the PERSISTENCE step only — everything upstream of it (sanitizer, tenant
-	* injection, actor stamp, hook sandwich) runs exactly as it does without
-	* one, which is the entire point of the seam.
+	* Domain commands bound to the write slots. Consulted at the PERSISTENCE step
+	* only — sanitizer, tenant injection, actor stamp, and hooks run unchanged.
 	*/
 	_writes;
 	/** Transactional write envelope — see `ResourceConfig.transactional`. */
 	_transactional = false;
+	/** Version field under optimistic concurrency — `null` when the resource did not opt in. */
+	_versionField = null;
 	constructor(repository, options = {}) {
 		this.repository = repository;
 		this.schemaOptions = options.schemaOptions ?? {};
 		this.queryParser = options.queryParser ?? getDefaultQueryParser();
-		/**
-		* The parser's cap is consulted BEFORE the framework default.
-		*
-		* A resource that hands us a parser has already stated how large a page it
-		* can serve — a bounded catalog like a chart of accounts declares 1000 so
-		* pickers can read it whole. Defaulting straight to 100 here silently
-		* overrode that: the resource asked for 1000, `QueryResolver` received a
-		* `maxLimit` of 100 that was indistinguishable from a host deliberately
-		* choosing 100, and the list came back truncated with a `200`. be-prod
-		* served 100 of 696 accounts that way, and every account picker in the
-		* product was short by 85% with nothing anywhere to report it.
-		*
-		* Order matters and is the whole point: an explicit `options.maxLimit` from
-		* the host still wins over the parser, and the parser wins over this
-		* framework floor. A general default must only ever fill a gap — never
-		* outrank something specific that was actually stated.
-		*/
 		this.maxLimit = options.maxLimit ?? this.queryParser?.maxLimit ?? 100;
 		this.defaultLimit = options.defaultLimit ?? 20;
 		this.resourceName = options.resourceName;
@@ -1216,11 +1205,14 @@ var BaseCrudController = class {
 		this._onImmutableWrite = options.onImmutableWrite;
 		this._writes = options.writes;
 		this._transactional = options.transactional === true;
+		this._versionField = options.concurrency ? options.concurrency.versionField ?? "__v" : null;
 		this.accessControl = new AccessControl({
 			tenantField: this.tenantField,
 			idField: this.idField,
 			matchesFilter: this._matchesFilter
 		});
+		this._lookupFields = options.lookupFields;
+		this.lookupAccess = this.buildLookupAccess(options.lookupFields);
 		this.bodySanitizer = new BodySanitizer({
 			schemaOptions: this.schemaOptions,
 			onFieldWriteDenied: this._onFieldWriteDenied,
@@ -1236,63 +1228,39 @@ var BaseCrudController = class {
 		});
 		this.list = this.list.bind(this);
 		this.get = this.get.bind(this);
-		/**
-		* The write methods are bound here, which means EVERY instance carries an
-		* own `create`/`update`/`delete` property — so "does it have an own
-		* property" cannot distinguish arc's binding from a host's override.
-		*
-		* Marking what arc installed makes the difference observable. A class-field
-		* override (`update = async (req) => …`) initialises AFTER `super()`
-		* returns and therefore REPLACES this bound method outright — the mark goes
-		* with it, which is exactly the signal `warnOnWriteMethodOverride` needs.
-		* A prototype-method override binds through here and stays marked; that
-		* shape is caught by the prototype comparison instead.
-		*/
 		this.create = markArcBoundWrite(this.create.bind(this));
 		this.update = markArcBoundWrite(this.update.bind(this));
 		this.delete = markArcBoundWrite(this.delete.bind(this));
 	}
 	/**
-	* Swap the controller's query parser. Mutates the existing `QueryResolver`
-	* in place via `QueryResolver.setParser()` — the resolver instance stays
-	* referentially stable, and there is no second copy of `defaultSort` /
-	* `tenantField` / `schemaOptions` for the swap to drift away from.
-	*
-	* Closes the v2.10.9 gap where `defineResource({ controller, queryParser })`
-	* forwarded the parser only to auto-constructed controllers. `defineResource`
-	* calls this via duck-typing when both `controller` and `queryParser` are
-	* supplied; controllers that don't implement it are left untouched.
+	* Bind the resource this controller serves — hooks, audit, events and cache key on it.
+	* `defineResource` calls it for a supplied controller; an unset name is assigned, a
+	* different one throws (the controller would run another resource's hooks).
+	*/
+	bindResourceName(name) {
+		if (this.resourceName === void 0) {
+			this.resourceName = name;
+			return;
+		}
+		if (this.resourceName !== name) throw new Error(`Resource "${name}": its controller is bound to resourceName "${this.resourceName}", so hooks, audit and events would key on the wrong resource.`);
+	}
+	/**
+	* Swap the controller's query parser. Mutates the existing `QueryResolver` in
+	* place, so the resolver stays referentially stable. `defineResource` calls this
+	* (duck-typed) when a resource supplies both `controller` and `queryParser`.
 	*/
 	setQueryParser(queryParser) {
 		this.queryParser = queryParser;
 		this.queryResolver.setParser(queryParser);
 	}
 	/**
-	* Apply resource-level options to a custom controller AFTER construction.
-	*
-	* Closes the pre-2.15 footgun where `defineResource({ controller, tenantField,
-	* schemaOptions, ... })` warned that the options were "dropped" because the
-	* user-supplied controller never received them. Hosts had to remember to
-	* forward each one through `super(repo, { ... })` — easy to miss, silently
-	* mis-scopes queries when missed.
-	*
-	* `defineResource()` now calls `controller.configure(resolvedOpts)` after
-	* `resolveOrAutoCreateController()` runs. Configure-aware controllers receive
-	* the resolved values; arc skips the dropped-options warn for them.
-	*
-	* Only the keys that affect cross-cutting state (tenant scope, schema/field
-	* rules, sort/limit policy, cache, write-denial policy) are honoured —
-	* `repository` / `resourceName` are constructor-only because they participate
-	* in mixin composition. Each known key rebuilds the affected sub-component
-	* (AccessControl / BodySanitizer / QueryResolver) so referentially-stable
-	* consumers don't see stale state.
-	*
-	* Idempotent: safe to call zero, one, or many times before first request;
-	* arc calls it exactly once.
+	* Apply resource-level options to a controller AFTER construction.
+	* `defineResource()` calls this once after resolving the controller, so custom
+	* controllers receive tenant scope, field rules, sort/limit, cache, and
+	* write-denial policy without forwarding them through `super(repo, { … })`.
 	*
-	* Type narrowed to `ControllerConfigurableOptions` — `resourceName` is
-	* construction-only and intentionally excluded so accidental "rename
-	* the resource at runtime" calls fail to typecheck.
+	* Each key rebuilds only the affected sub-component. Idempotent.
+	* `repository` / `resourceName` are construction-only and excluded by type.
 	*/
 	configure(options) {
 		let rebuildAccessControl = false;
@@ -1341,11 +1309,19 @@ var BaseCrudController = class {
 		if (options.presetFields !== void 0) this._presetFields = options.presetFields;
 		if (options.writes !== void 0) this._writes = options.writes;
 		if (options.transactional !== void 0) this._transactional = options.transactional === true;
-		if (rebuildAccessControl) this.accessControl = new AccessControl({
-			tenantField: this.tenantField,
-			idField: this.idField,
-			matchesFilter: this._matchesFilter
-		});
+		if (options.concurrency !== void 0) this._versionField = options.concurrency ? options.concurrency.versionField ?? "__v" : null;
+		if (options.lookupFields !== void 0) {
+			this._lookupFields = options.lookupFields;
+			rebuildAccessControl = true;
+		}
+		if (rebuildAccessControl) {
+			this.accessControl = new AccessControl({
+				tenantField: this.tenantField,
+				idField: this.idField,
+				matchesFilter: this._matchesFilter
+			});
+			this.lookupAccess = this.buildLookupAccess(this._lookupFields);
+		}
 		if (rebuildBodySanitizer) this.bodySanitizer = new BodySanitizer({
 			schemaOptions: this.schemaOptions,
 			onFieldWriteDenied: this._onFieldWriteDenied,
@@ -1360,25 +1336,15 @@ var BaseCrudController = class {
 			tenantField: this.tenantField
 		});
 	}
-	/**
-	* Get the tenant field name if multi-tenant scoping is enabled.
-	* Returns `undefined` when `tenantField` is `false`.
-	*/
+	/** Tenant field name, or `undefined` when `tenantField` is `false`. */
 	getTenantField() {
 		return this.tenantField || void 0;
 	}
 	/**
-	* Build the canonical repo-options bag (tenant scope, audit
-	* attribution, trace correlation) from the Fastify request. Full
-	* contract + rationale on `buildTenantRepoOptions` in
-	* `crud/requestPipeline.ts` — this delegate exists so host overrides
-	* and duck-typed consumers (aggregation router, MCP bridge) keep the
-	* same `protected` entry point.
-	*
-	* Method kept named `tenantRepoOptions` for back-compat with hosts
-	* that spread `...this.tenantRepoOptions(req)` (10+ call sites in
-	* arc, plus host overrides). The bag has always grown over time —
-	* hosts that don't want audit forwarding never read those keys.
+	* Canonical repo-options bag (tenant scope, audit attribution, trace
+	* correlation) — see `buildTenantRepoOptions` in `crud/requestPipeline.ts`.
+	* Kept as a `protected` entry point for host overrides and duck-typed
+	* consumers (aggregation router, MCP bridge).
 	*/
 	tenantRepoOptions(req) {
 		return buildTenantRepoOptions(req, this.tenantField, this.meta(req));
@@ -1401,18 +1367,11 @@ var BaseCrudController = class {
 		return resolveMutationRepoId(id, existing, this.idField, this.repository);
 	}
 	/**
-	* Read-side preflight for mutable-target operations (`update`, `delete`).
+	* Shared preflight for mutations: extract `:id`, fetch under access control +
+	* tenant scope, verify ownership, translate the route id to the repo primary
+	* key. One path so `update` and `delete` cannot drift.
 	*
-	* Bundles the four steps that every mutation must do before touching the
-	* repo: (1) extract `:id`, (2) fetch under access control + tenant scope,
-	* (3) verify ownership, (4) translate the route id to the repo's primary
-	* key. Returning `{id, existing, repoId}` keeps the call sites a single
-	* line and makes drift between `update` and `delete` structurally
-	* impossible — there is one preflight, one denial-reason mapping, one
-	* ownership check.
-	*
-	* Pass `extraFetchOptions` for callers (e.g. soft-delete restore) that
-	* need to widen the fetch (`{ includeDeleted: true }`).
+	* `extraFetchOptions` widens the fetch (e.g. restore's `{ includeDeleted: true }`).
 	*/
 	async loadMutableTarget(req, extraFetchOptions) {
 		const id = this.requireIdParam(req);
@@ -1431,10 +1390,83 @@ var BaseCrudController = class {
 		};
 	}
 	/**
-	* Centralized 404 thrower. Maps the denial reason from `fetchDetailed()`
-	* into a `NotFoundError` so consumers can distinguish "doc doesn't
-	* exist" from "doc filtered by policy/org scope" via the error
-	* `details.code` set by the global error handler.
+	* Whether the target of an id-bound ACTION is a row this request may read — the same
+	* compound filter (id + tenant + `_policyFilters`) `GET /:id` uses. The action router
+	* refuses the action with a 404 when it is not, so a caller can act on a row iff it can
+	* read it. Skips the read when neither tenancy nor a row policy narrows the request.
+	*/
+	buildLookupAccess(fields) {
+		return (fields ?? []).filter((field) => field !== this.idField).map((idField) => new AccessControl({
+			tenantField: this.tenantField,
+			idField,
+			matchesFilter: this._matchesFilter
+		}));
+	}
+	/**
+	* THE single-row lookup — `GET /:id` and the action-target fence both read through it.
+	* The primary key first; when it finds nothing (or the id cannot be that key's type), each
+	* `lookupFields` key in turn, under the same tenant and row policy.
+	*/
+	async fetchByAnyKey(id, req, options) {
+		let primary;
+		let primaryError;
+		try {
+			primary = await this.accessControl.fetchDetailed(id, req, this.repository, options);
+			if (primary.doc || this.lookupAccess.length === 0) return primary;
+		} catch (err) {
+			if (this.lookupAccess.length === 0) throw err;
+			primaryError = err;
+		}
+		let answered = primary;
+		for (const access of this.lookupAccess) try {
+			const found = await access.fetchDetailed(id, req, this.repository, options);
+			if (found.doc) return found;
+			answered ??= found;
+		} catch {}
+		if (answered) return answered;
+		throw primaryError;
+	}
+	/** Whether {@link isActionTargetVisible} can answer — it reads through the repository. */
+	canFenceActionTargets() {
+		return this.repository !== void 0 && this.repository !== null;
+	}
+	async isActionTargetVisible(req, id) {
+		const meta = this.meta(req);
+		const scoped = resolveTenancy(meta, this.tenantField).mode === "scoped";
+		const policy = meta?._policyFilters;
+		if (!scoped && (!policy || Object.keys(policy).length === 0)) return true;
+		const { doc } = await this.fetchByAnyKey(id, req, this.tenantRepoOptions(req));
+		return doc !== null && doc !== void 0;
+	}
+	/** `ETag: "<version>"` for a versioned document under optimistic concurrency. */
+	etagHeaders(doc) {
+		if (!this._versionField) return void 0;
+		const version = doc?.[this._versionField];
+		return typeof version === "number" ? { etag: `"${version}"` } : void 0;
+	}
+	/**
+	* The version an update must apply at. `If-Match` must name the CURRENT version or the
+	* request fails 412 before anything is written; without it (or with `*`) the write is a CAS
+	* on the version just loaded, so a concurrent write in between is a 409, never overwritten.
+	*/
+	expectedVersion(req, existing) {
+		if (!this._versionField) return { fromClient: false };
+		const current = existing[this._versionField];
+		const header = requireSingleHeaderValue(req.headers, "if-match")?.trim();
+		if (header === void 0 || header === "*") return typeof current === "number" ? {
+			version: current,
+			fromClient: false
+		} : { fromClient: false };
+		const offered = header.split(",").map((tag) => /^"(\d+)"$/.exec(tag.trim())?.[1]);
+		if (typeof current !== "number" || !offered.includes(String(current))) throw createDomainError(ARC_ERROR_CODES.PRECONDITION_FAILED, `If-Match ${header} does not match the current version${typeof current === "number" ? ` "${current}"` : ""} — re-read and retry.`, 412);
+		return {
+			version: current,
+			fromClient: true
+		};
+	}
+	/**
+	* 404 thrower. Maps the `fetchDetailed()` denial reason into `details.code` so
+	* "doesn't exist" is distinguishable from "filtered by policy/org scope".
 	*/
 	throwNotFound(reason = "NOT_FOUND") {
 		throw buildNotFoundError(reason, this.resourceName);
@@ -1444,9 +1476,8 @@ var BaseCrudController = class {
 		return resolveOpCacheConfig(this._cacheConfig, operation);
 	}
 	/**
-	* Extract user/org IDs from request for cache key scoping.
-	* Only includes orgId when the resource uses tenant-scoped data (tenantField is set).
-	* Universal resources (tenantField: false) get shared cache keys.
+	* User/org IDs for cache key scoping. orgId is included only when `tenantField`
+	* is set; universal resources share cache keys.
 	*/
 	cacheScope(req) {
 		return deriveCacheScope(req, this.tenantField, this.meta(req));
@@ -1461,11 +1492,7 @@ var BaseCrudController = class {
 		if (!id) throw createError(400, "ID parameter is required");
 		return id;
 	}
-	/**
-	* Normalizes `repo.exists()` return shapes across adapters. Per
-	* StandardRepo's contract, `exists` may return `boolean`, `{ _id }`,
-	* or `null` — every truthy non-null shape collapses to `true`.
-	*/
+	/** Normalizes `repo.exists()` (`boolean | { _id } | null`) to a boolean. */
 	isExistsTruthy(result) {
 		return isExistsResultTruthy(result);
 	}
@@ -1479,25 +1506,18 @@ var BaseCrudController = class {
 		};
 	}
 	/**
-	* Run `executeBefore` then `executeAround` (or just the executor if no
-	* hooks are wired). Returns the around-phase result directly. Throws an
-	* `ArcError` (status 400, code `BEFORE_<OP>_HOOK_ERROR`) when the
-	* before-hook fails. Full contract on `executeHookedOp` in
-	* `crud/requestPipeline.ts`.
+	* Run before + around hooks (or just the executor if none are wired) and
+	* return the result. A failing before-hook throws 400 `BEFORE_<OP>_HOOK_ERROR`.
 	*/
 	async runHookedOpUntilResult(req, args, executor) {
 		return executeHookedOp(this.hookOpContext(req), args, executor);
 	}
 	/**
 	* Run a write's PERSISTENCE step, transactionally when the resource asked.
-	*
-	* Plain mode hands `fn` the live repository. Transactional mode runs it
-	* through repo-core's `retryingTransaction`: the callback receives the
-	* TX-BOUND repository (so declared verbs and repository calls join the same
-	* transaction), transient conflicts re-run `fn` with jittered bounded
-	* backoff, everything else — including `VersionConflictError` — surfaces
-	* once. Hooks stay OUTSIDE: before/around ran already and must not re-run;
-	* after-hooks run post-commit, which they already do by running after this.
+	* Transactional mode uses `retryingTransaction`: `fn` gets the TX-BOUND repo and
+	* re-runs on transient conflicts; anything else (incl. `VersionConflictError`)
+	* surfaces once. Hooks stay OUTSIDE so before/around never re-run and after
+	* runs post-commit.
 	*/
 	runWritePersistence(fn) {
 		if (!this._transactional) return fn(this.repository);
@@ -1517,16 +1537,9 @@ var BaseCrudController = class {
 	/**
 	* Assemble the `MutationWriteContext` an `update` / `delete` verb receives.
 	*
-	* `existing` is the document arc ALREADY loaded to run its permission and
-	* tenant checks — `loadMutableTarget` throws before any verb runs when it
-	* cannot produce one, which is why the context types it required. Handing
-	* it over rather than letting the verb re-fetch is deliberate: a second
-	* read can observe a different document than the one the request was
-	* authorised against.
-	*
-	* `id` is the REPOSITORY PRIMARY KEY (`repoId`), never the raw route param —
-	* see the note on `MutationWriteContext.id`. Callers pass `resolveRepoId`'s
-	* output.
+	* `existing` is the document the request was AUTHORISED against — handed over
+	* so the verb does not re-fetch and possibly observe a different document.
+	* `id` is the REPOSITORY PRIMARY KEY (`resolveRepoId` output), never the route param.
 	*/
 	mutationWriteContext(req, id, existing, repo = this.repository, uow) {
 		return {
@@ -1538,24 +1551,16 @@ var BaseCrudController = class {
 		};
 	}
 	/**
-	* Run `executeAfter` for the given op + data. No-op when hooks aren't
-	* wired or `resourceName` isn't set. Caller passes the data shape it
-	* wants downstream after-handlers to receive — typically the result for
-	* create/update, the original input (`existing`) for delete.
+	* Run after-hooks for `op`. No-op without hooks or `resourceName`. `data` is the
+	* result for create/update, `existing` for delete.
 	*/
 	async runAfterHook(req, op, data, meta) {
 		return executeAfterHook(this.hookOpContext(req), op, data, meta);
 	}
 	/**
-	* Per-instance single-flight for cache fills — concurrent requests for
-	* the SAME cache key coalesce onto one repository query instead of each
-	* issuing its own (a popular entry expiring under 1,000 concurrent
-	* readers must produce 1 DB query, not 1,000). Keys already encode the
-	* resolved query + user/org scope + resource version, so coalescing can
-	* never cross tenants, scopes, or invalidation generations. Per-process
-	* by design; distributed refresh leases are a store-level concern
-	* (planned with the repo-core CacheEngine façade, which ships
-	* single-flight natively).
+	* Per-process single-flight for cache fills: concurrent requests for the SAME
+	* key coalesce onto one repository query. Keys encode query + user/org scope +
+	* resource version, so coalescing never crosses tenants or invalidation generations.
 	*/
 	inFlightCacheFills = /* @__PURE__ */ new Map();
 	cacheSingleFlight(key, fill) {
@@ -1568,10 +1573,8 @@ var BaseCrudController = class {
 		return flight;
 	}
 	/**
-	* Register a background SWR refresh for `key` unless one is already in
-	* flight. Registration is SYNCHRONOUS (before the deferred tick) so a
-	* burst of stale readers arriving in the same tick schedules exactly one
-	* revalidation.
+	* Register a background SWR refresh for `key` unless one is in flight.
+	* Registration is SYNCHRONOUS so a same-tick burst of stale readers schedules one.
 	*/
 	scheduleCacheRefresh(key, refresh) {
 		if (this.inFlightCacheFills.has(key)) return;
@@ -1653,19 +1656,14 @@ var BaseCrudController = class {
 		};
 	}
 	/**
-	* Resource-dispatch verbs router. Returns `null` when the request is
-	* a regular list query, otherwise returns the dispatch promise.
-	*
-	* Verbs (mutually exclusive — first match wins):
+	* Resource-dispatch verbs router; `null` for a regular list query.
+	* First match wins:
 	*   - `?_count=true` → `{ count: number }` via `repo.count()`
 	*   - `?_distinct=field` → `unknown[]` via `repo.distinct(field)`
 	*   - `?_exists=true` → `{ exists: boolean }` via `repo.exists()`
 	*
-	* All verbs share the resolved filter (parsed query + policy filters
-	* + tenant scope). Adapters that don't ship the underlying repo
-	* method get a `501` so failures surface loudly instead of falling
-	* back to a full table scan. Matching + repo invocation live in
-	* `crud/resourceVerbs.ts`.
+	* All share the resolved filter (query + policy + tenant scope). A missing repo
+	* method is a `501`, never a fallback to a full scan.
 	*/
 	dispatchResourceVerb(req) {
 		const verb = matchResourceVerb(req.query);
@@ -1705,16 +1703,12 @@ var BaseCrudController = class {
 		};
 	}
 	/**
-	* True when `field` is safe to expose via `_distinct`.
-	*
-	* Read-side gate only — only `hidden: true` blocks. `systemManaged`
-	* is a *write* rule (clients can't PATCH the value); the field is
-	* still in every list response, so blocking `_distinct` adds nothing
-	* but inconvenience. See `core/fieldRulePredicates.ts` for the
-	* canonical predicate shared with `QueryResolver`.
+	* True when `field` is safe to expose via `_distinct`. Only `hidden: true`
+	* blocks — `systemManaged` is a write rule and the field is already readable.
 	*/
 	isFieldExposedForRead(field) {
-		return isFieldReadable(this.schemaOptions.fieldRules?.[field]);
+		const blocked = collectReadBlockedFields(this.schemaOptions);
+		return !blocked || !pathTouchesBlocked(field, blocked, { descendants: true });
 	}
 	/** Execute list query through hooks (extracted for cache revalidation) */
 	async executeListQuery(options, req) {
@@ -1736,21 +1730,30 @@ var BaseCrudController = class {
 			...this.tenantRepoOptions(req)
 		};
 		const cached = await this.withGetCache(req, id, options);
-		if (cached) return cached;
+		if (cached) {
+			const etag = this.etagHeaders(cached.data);
+			return etag ? {
+				...cached,
+				headers: {
+					...cached.headers,
+					...etag
+				}
+			} : cached;
+		}
 		const { doc, reason } = await this.executeGetQuery(id, options, req);
 		if (!doc) this.throwNotFound(reason);
 		await this.runAfterHook(req, "read", doc);
+		const etag = this.etagHeaders(doc);
 		return {
 			data: doc,
-			status: 200
+			status: 200,
+			...etag ? { headers: etag } : {}
 		};
 	}
 	/** Execute get query through hooks (extracted for cache revalidation) */
 	async executeGetQuery(id, options, req) {
 		const hooks = this.getHooks(req);
-		const fetchItem = async () => {
-			return await this.accessControl.fetchDetailed(id, req, this.repository, options);
-		};
+		const fetchItem = async () => this.fetchByAnyKey(id, req, options);
 		if (hooks && this.resourceName) {
 			const result = await fetchItem();
 			if (!result.doc) return result;
@@ -1767,6 +1770,7 @@ var BaseCrudController = class {
 	async create(req) {
 		const arcContext = this.meta(req);
 		const data = this.bodySanitizer.sanitize(req.body ?? {}, "create", req, arcContext);
+		Object.assign(data, arcContext?._tenantFields);
 		const scope = arcContext?._scope;
 		const createOrgId = scope ? getOrgId(scope) : void 0;
 		if (this.tenantField && createOrgId) data[this.tenantField] = createOrgId;
@@ -1781,16 +1785,7 @@ var BaseCrudController = class {
 			context: arcContext,
 			...this.tenantRepoOptions(req)
 		})));
-		/**
-		* A create COMMAND must return the created document — enforced, because
-		* the alternative is quietly worse than any failure: a `201` carrying
-		* `undefined` data, after-hooks (audit, events, cache invalidation) fed a
-		* non-document, and a client that believes the write happened with no way
-		* to address what it created. TypeScript types the contract, but arc is a
-		* JavaScript runtime framework and a JS command returning nothing is one
-		* missing `return` away.
-		*/
-		if (this._writes?.create && item == null) throw createError(500, `writes.create for resource "${this.resourceName ?? "unknown"}" returned ${item === null ? "null" : "undefined"} — a create command must return the created document. Signal failure by throwing a typed error; a nullish return would otherwise answer 201 with no document.`, { code: "WRITE_VERB_CONTRACT_VIOLATION" });
+		if (this._writes?.create && item == null) throw createError(500, `writes.create for resource "${this.resourceName ?? "unknown"}" returned ${item === null ? "null" : "undefined"} — a create command must return the created document. Signal failure by throwing a typed error; a nullish return would otherwise answer 201 with no document.`, { code: ARC_ERROR_CODES.WRITE_VERB_CONTRACT_VIOLATION });
 		await this.runAfterHook(req, "create", item);
 		return {
 			data: item,
@@ -1801,6 +1796,7 @@ var BaseCrudController = class {
 	async update(req) {
 		const arcContext = this.meta(req);
 		const data = this.bodySanitizer.sanitize(req.body ?? {}, "update", req, arcContext);
+		Object.assign(data, arcContext?._tenantFields);
 		const user = req.user;
 		const userId = getUserId(user);
 		if (userId) data.updatedBy = userId;
@@ -1809,6 +1805,7 @@ var BaseCrudController = class {
 			id,
 			existing
 		};
+		const cas = this._writes?.update ? { fromClient: false } : this.expectedVersion(req, existing);
 		const item = await this.runHookedOpUntilResult(req, {
 			op: "update",
 			input: data,
@@ -1816,15 +1813,12 @@ var BaseCrudController = class {
 		}, async (processed) => this.runWritePersistence((repo, uow) => this._writes?.update ? this._writes.update(repoId, processed, this.mutationWriteContext(req, repoId, existing, repo, uow)) : repo.update(repoId, processed, {
 			user,
 			context: arcContext,
-			...this.tenantRepoOptions(req)
-		})));
-		/**
-		* A declared verb signals "not found" by THROWING, so reaching this line
-		* means the command succeeded. Translating its `void` return into a 404
-		* would report failure for a write that happened — the repository's
-		* `null`-means-miss contract is the repository's, not a domain command's.
-		* Re-read so the response still carries the document.
-		*/
+			...this.tenantRepoOptions(req),
+			...cas.version !== void 0 ? { ifVersion: cas.version } : {}
+		}))).catch((err) => {
+			if (cas.fromClient && err?.code === "version_conflict") throw createDomainError(ARC_ERROR_CODES.PRECONDITION_FAILED, "The resource changed since it was read — re-read and retry.", 412);
+			throw err;
+		});
 		const resolved = this._writes?.update ? item ?? await this.repository.getById(repoId, {
 			user,
 			context: arcContext,
@@ -1832,10 +1826,12 @@ var BaseCrudController = class {
 		}) : item;
 		if (!resolved) this.throwNotFound("NOT_FOUND");
 		await this.runAfterHook(req, "update", resolved, hookMeta);
+		const etag = this.etagHeaders(resolved);
 		return {
 			data: resolved,
 			status: 200,
-			meta: { message: "Updated successfully" }
+			meta: { message: "Updated successfully" },
+			...etag ? { headers: etag } : {}
 		};
 	}
 	async delete(req) {
@@ -1869,12 +1865,9 @@ var BaseCrudController = class {
 	}
 };
 /**
-* This class's write methods dispatch declared write verbs (`_writes`), so
-* `defineResource` may accept a `writes` declaration for controllers built on
-* it. One mark on the prototype — inherited by every subclass and mixin
-* composition, zero per-instance cost. A duck-typed `configure()` is NOT this
-* proof: it shows an options channel exists, not that anything dispatches
-* `writes` out of it.
+* Marks that this class dispatches declared write verbs, so `defineResource` may
+* accept `writes` for controllers built on it (inherited by subclasses and mixins).
+* A duck-typed `configure()` is not proof that `writes` is dispatched.
 */
 markWriteVerbCapable(BaseCrudController.prototype);
 //#endregion
@@ -1906,22 +1899,18 @@ function BulkMixin(Base) {
 			const items = rawItems;
 			const arcContext = this.meta(req);
 			const user = req.user;
-			const sanitizedItems = items.map((item) => this.bodySanitizer.sanitize(item ?? {}, "create", req, arcContext));
+			const sanitizedItems = items.map((item) => ({
+				...this.bodySanitizer.sanitize(item ?? {}, "create", req, arcContext),
+				...arcContext?._tenantFields
+			}));
 			let scopedItems = sanitizedItems;
-			if (this.tenantField) {
-				const scope = arcContext?._scope;
-				if (scope) {
-					if (scope.kind === "public") throw createError(403, "Organization context required to bulk-create resources", { code: "ORG_CONTEXT_REQUIRED" });
-					if (!isElevated(scope)) {
-						const orgId = getOrgId(scope);
-						if (!orgId) throw createError(403, "Organization context required to bulk-create resources", { code: "ORG_CONTEXT_REQUIRED" });
-						const tenantField = this.tenantField;
-						scopedItems = sanitizedItems.map((item) => ({
-							...item,
-							[tenantField]: orgId
-						}));
-					}
-				}
+			if (this.tenantField && arcContext?._scope) {
+				const tenancy = resolveTenancy(arcContext, this.tenantField);
+				if (tenancy.mode === "scoped") scopedItems = sanitizedItems.map((item) => ({
+					...item,
+					[tenancy.field]: tenancy.orgId
+				}));
+				else if (tenancy.reason !== "platform" && tenancy.reason !== "untenanted-resource") throw createError(403, "Organization context required to bulk-create resources", { code: "ORG_CONTEXT_REQUIRED" });
 			}
 			const created = await repo.createMany(scopedItems, {
 				user,
@@ -1948,28 +1937,26 @@ function BulkMixin(Base) {
 		/**
 		* Build a tenant-scoped filter for bulk update/delete.
 		*
-		* Mirrors `AccessControl.buildIdFilter` semantics:
+		* Same tenancy as `AccessControl.buildIdFilter` — both go through
+		* `resolveTenancy`:
 		*   - Always merge `_policyFilters` (from permission middleware)
-		*   - `member` scope on a tenant resource → add org filter
-		*   - `elevated` scope → no org filter (admin cross-org operation)
-		*   - `public` scope on a tenant resource → deny
+		*   - A caller with an org (member, service, or an elevated admin who
+		*     selected one) → add org filter
+		*   - Elevated with NO org (platform view) → no org filter
+		*   - No org, or anonymous, on a tenant resource → deny
 		*   - No scope at all (unit tests) → leave filter unchanged
 		*
 		* Returns the merged filter, or `null` when access must be denied.
 		*/
 		buildBulkFilter(userFilter, req) {
 			const arcContext = this.meta(req);
-			let filter = conjoinPolicyFilters(userFilter, arcContext?._policyFilters);
-			if (this.tenantField) {
-				const scope = arcContext?._scope;
-				if (!scope) return filter;
-				if (scope.kind === "public") return null;
-				if (isElevated(scope)) return filter;
-				const orgId = getOrgId(scope);
-				if (!orgId) return null;
-				filter = conjoinPolicyFilters(filter, { [this.tenantField]: orgId });
+			const filter = conjoinPolicyFilters(userFilter, arcContext?._policyFilters);
+			if (!this.tenantField || !arcContext?._scope) return filter;
+			const tenancy = resolveTenancy(arcContext, this.tenantField);
+			switch (tenancy.mode) {
+				case "scoped": return conjoinPolicyFilters(filter, { [tenancy.field]: tenancy.orgId });
+				case "unscoped": return tenancy.reason === "platform" || tenancy.reason === "untenanted-resource" ? filter : null;
 			}
-			return filter;
 		}
 		/**
 		* Sanitize a bulk update data payload through the same write-permission
@@ -2213,10 +2200,934 @@ function TreeMixin(Base) {
 //#region src/core/BaseController.ts
 /**
 * Fully-composed controller: `BaseCrudController` + SoftDelete + Tree +
-* Slug + Bulk. Drop-in replacement for the pre-2.11 god class. The
-* companion interface above gives every method full generic precision
-* on `TDoc` via declaration merging.
+* Slug + Bulk. The companion interface above types every method over `TDoc`.
 */
 var BaseController = class extends SoftDeleteMixin(TreeMixin(SlugMixin(BulkMixin(BaseCrudController)))) {};
 //#endregion
-export { BulkMixin as a, collectReadBlockedFields as c, isWriteVerbCapable as d, BodySanitizer as f, toRepositoryFilter as g, nativePolicyFilter as h, SlugMixin as i, isFieldReadable as l, AccessControl as m, TreeMixin as n, BaseCrudController as o, DEFAULT_FIELD_WRITE_DENIAL_POLICY as p, SoftDeleteMixin as r, QueryResolver as s, BaseController as t, detectOverriddenWriteSlots as u };
+//#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 ?? {}
+	} };
+}
+/**
+* Wrap a raw handler so one that called `reply.send()` and resolved `undefined` returns the
+* reply: otherwise, while an async send hook (idempotency `onSend`, encryption `preSerialization`) is pending,
+* Fastify re-sends the `undefined` and the client gets an empty body.
+* Pinned by `tests/idempotency/raw-route-keyed-body.test.ts`.
+*/
+function keepRawReply(raw) {
+	return async function rawRoute(request, reply) {
+		let sendCalled = false;
+		const send = reply.send;
+		reply.send = function trackedSend(payload) {
+			sendCalled = true;
+			return send.call(this, payload);
+		};
+		try {
+			const result = await raw.call(this, request, reply);
+			return result === void 0 && (sendCalled || reply.sent) ? reply : result;
+		} finally {
+			reply.send = send;
+		}
+	};
+}
+/** Mount custom routes (from presets or user-defined `routes`) on Fastify. */
+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 = keepRawReply(boundMethod);
+		} else if (wrapHandler) {
+			const steps = resolvePipelineSteps(pipeline, opName);
+			handler = steps.length > 0 ? buildPipelineHandler(resolvedHandler, steps, opName, resourceName) : createFastifyHandler(resolvedHandler);
+		} else handler = keepRawReply(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()\` 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,
+			...mergeRouteConfig(route.config, buildRouteConfig(route.rateLimit !== void 0 ? buildRateLimitConfig(route.rateLimit) : rateLimitConfig, extensions, route.cors))
+		}, {
+			resourceName,
+			op: opName,
+			...route.rateLimit && typeof route.rateLimit === "object" ? { rateLimitBucket: `route:${route.method}:${route.path}` } : {}
+		});
+	}
+}
+/**
+* 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, idempotency } = options;
+	const idempotentOps = new Set(idempotency?.required ?? []);
+	for (const op of idempotentOps) if (disableDefaultRoutes || disabledRoutes.includes(op)) throw new Error(`[arc] Resource "${resourceName}" declares idempotency.required '${op}', but that built-in route is not mounted — drop it from idempotency.required.`);
+	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();
+	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, void 0, idempotentOps.has(spec.op) ? { required: true } : void 0)
+				}, {
+					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, for host routes
+* registered outside the resource system.
+*/
+function createPermissionMiddleware(permission, resourceName, action) {
+	return buildCrudPermissionMw(permission, resourceName, action);
+}
+//#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/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 = withoutObjectIdPattern(openApiSchemas.params, `${idField} (custom ID field)`);
+	return params === openApiSchemas.params ? openApiSchemas : {
+		...openApiSchemas,
+		params
+	};
+}
+/**
+* `params` with the ObjectId pattern removed from `id` — the same object when there is none.
+* `GET /:id` on a resource with `lookupFields` uses it: the id may be a business number.
+*/
+function withoutObjectIdPattern(params, description) {
+	if (!params || typeof params !== "object") return params;
+	const properties = params.properties;
+	const idProp = properties?.id;
+	if (!idProp || typeof idProp !== "object") return params;
+	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 params;
+	const cleanedId = { ...idProp };
+	delete cleanedId.pattern;
+	delete cleanedId.minLength;
+	delete cleanedId.maxLength;
+	if (!cleanedId.description) cleanedId.description = description;
+	return {
+		...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/defineResource/plugin.ts
+/**
+* Build the CRUD schema map from the adapter's `OpenApiSchemas`, then layer
+* `customSchemas` on top per slot (auto-gen always runs, so customising one
+* slot never disables the others). Returns `null` when neither contributes.
+*
+* **`params` cloning is load-bearing:** `get` / `delete` / `update` each own a
+* clone, so a downstream mutation on one slot cannot leak into the others.
+*/
+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.
+*
+* `qs` turns bracket notation (`?name[contains]=foo`, `?tags[]=a`) into nested
+* objects/arrays that AJV rejects against adapters' `type: "string"` props. The
+* QueryParser owns filter validation, so every property collapses to `{}` except
+* integer `page` / `limit`; `limit.maximum` is preserved so the parser's cap holds.
+*/
+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] ?? {};
+	}
+	const keysetProps = {
+		mode: {
+			type: "string",
+			description: "Pagination mode: `offset` (default) or `keyset` (walk by `after` / `before`)."
+		},
+		before: {
+			type: "string",
+			description: "Cursor from a page's `prev` — the page before it."
+		}
+	};
+	return {
+		type: "object",
+		...listQuerySchema,
+		properties: {
+			...keysetProps,
+			...normalizedProps ?? listQuerySchema.properties ?? {}
+		},
+		additionalProperties: listQuerySchema.additionalProperties ?? true
+	};
+}
+/**
+* Deep-merge two JSON schema branches: arrays union (deduplicated), objects
+* recurse, primitives are overwritten.
+*/
+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 (e.g. subdocument-array `items`), whatever the generator produced.
+*/
+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 config `createActionRouter` expects.
+*
+* Permissions are resolved FAIL-CLOSED at boot via `actionPermissions.ts`: the
+* returned map carries every action's effective gate, and an action with none
+* throws. The resource-level gate uses slot `resourceActionPermissions`;
+* `globalAuth` stays reserved for direct `createActionRouter` callers.
+*/
+function normalizeActionsToRouterConfig(actions, resourceActionPermissions, tag, resourcePermissions, resourceName, log) {
+	const handlers = {};
+	const permissions = {};
+	const schemas = {};
+	const idLessActionNames = [];
+	const handlerScopedActionNames = [];
+	const idempotentActionNames = [];
+	const handlerDedupOwners = {};
+	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);
+			if (def.idempotency?.required === true) idempotentActionNames.push(name);
+			const problem = idempotencyConfigProblem({ idempotency: def.idempotency ? { ...def.idempotency } : void 0 });
+			if (problem) throw new Error(`[Arc] Resource '${resourceName}': action '${name}' idempotency: ${problem}.`);
+			if (def.idempotency?.dedup === "handler") handlerDedupOwners[name] = String(def.idempotency.owner);
+			if (def.target !== void 0) {
+				if (def.target.scope !== "handler" || def.target.reason.trim() === "") throw new Error(`[Arc] Resource '${resourceName}': action '${name}' declares \`target\` without \`scope: 'handler'\` and a non-empty \`reason\` — say why its target is not this resource's row.`);
+				handlerScopedActionNames.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,
+		handlerScopedActionNames,
+		idempotentActionNames,
+		handlerDedupOwners
+	};
+}
+/**
+* The action-target fence: an id-bound action may act only on a row the caller could
+* `GET`. Built from the controller's access control; a tenant-scoped resource whose
+* controller cannot answer is refused at boot rather than mounted unfenced. HTTP and MCP
+* both call it, so the two surfaces fence the same rows.
+*/
+function resolveActionTargetFence(resource, actionConfig) {
+	const exempt = /* @__PURE__ */ new Set([...actionConfig.idLessActionNames, ...actionConfig.handlerScopedActionNames]);
+	const fenced = Object.keys(actionConfig.actions).filter((name) => !exempt.has(name));
+	if (fenced.length === 0) return void 0;
+	const ctrl = resource.controller;
+	const check = ctrl?.isActionTargetVisible;
+	if (!(typeof check === "function" && ctrl?.canFenceActionTargets?.() === true)) {
+		if (typeof resource.tenantField === "string" || ctrl !== void 0 && resource.tenantField !== false) throw new Error(`[Arc] Resource '${resource.name}' is tenant-scoped (tenantField '${resource.tenantField === void 0 ? "organizationId (default)" : resource.tenantField}') and declares id-bound actions [${fenced.join(", ")}], but its controller cannot authorize an action target. Use a BaseController with a repository, declare \`tenantField: false\`, or declare \`target: { scope: 'handler', reason }\` on each action.`);
+		return;
+	}
+	return (id, ctx) => check.call(ctrl, ctx, id);
+}
+/**
+* Build the FastifyPluginAsync that materialises a `ResourceDefinition` into
+* routes, hooks, registry entries, and cache invalidation rules. Can be
+* registered any number of times; shared-state writes happen once per host.
+*/
+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) arc.registry.register(resource, resource._registryMeta);
+		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 getParams = schemas?.get?.params;
+			if (resource.lookupFields?.length && schemas?.get && getParams) schemas.get = {
+				...schemas.get,
+				params: withoutObjectIdPattern(getParams, `${resource.idField ?? "_id"} or ${resource.lookupFields.join(" / ")}`)
+			};
+			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,
+				idempotency: resource.idempotency,
+				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-xjqonMRO.mjs").then((n) => n.n);
+				const actionConfig = normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log);
+				const actionTarget = resolveActionTargetFence(resource, actionConfig);
+				createActionRouter(typedInstance, {
+					...actionConfig,
+					...actionTarget ? { isTargetVisible: (id, req) => actionTarget(id, createRequestContext(req)) } : {},
+					auditActions: Boolean(resource.audit),
+					resourceName: resource.name,
+					fields: resource.fields,
+					schemaOptions: resource.schemaOptions,
+					idField: resource.idField,
+					permissions: resource.permissions,
+					routeGuards: resource.routeGuards,
+					tenantMiddlewares: withoutTenantInjection(resource.middlewares?.tenantScope),
+					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-zRYWw_5D.mjs"), import("./validate-9yzHC1e2.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
+export { toRepositoryFilter as C, nativePolicyFilter as S, pathTouchesBlocked as _, autoInjectTenantFieldRules as a, BodySanitizer as b, BaseController as c, SlugMixin as d, BulkMixin as f, isFieldReadable as g, collectReadBlockedFields as h, resolveOpenApiSchemas as i, TreeMixin as l, QueryResolver as m, normalizeActionsToRouterConfig as n, createCrudRouter as o, BaseCrudController as p, resolveActionTargetFence as r, createPermissionMiddleware as s, buildResourcePlugin as t, SoftDeleteMixin as u, detectOverriddenWriteSlots as v, AccessControl as x, isWriteVerbCapable as y };