@classytic/arc 2.11.3 → 2.13.1

package/dist/core-D72ia0EH.mjs

@@ -0,0 +1,1399 @@
+import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-Cxde4rpC.mjs";
+import { arcLog } from "./logger/index.mjs";
+import { A as assertValidConfig, l as getDefaultCrudSchemas } from "./utils-_h9B3c57.mjs";
+import { t as BaseController } from "./BaseController-DX_T-bDB.mjs";
+import { t as applyPresets } from "./presets-BbkjdPeH.mjs";
+import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-De34B1ZG.mjs";
+import { t as hasEvents } from "./typeGuards-BzkXkvVv.mjs";
+import { b as buildRequestScopeProjection, c as buildPreHandlerChain, d as resolveRoutePreHandlers, f as resolveRouterPluginMw, h as createFastifyHandler, i as buildAuthMiddleware, l as buildRateLimitConfig, m as createCrudHandlers, o as buildCrudPermissionMw, p as selectPluginMw, r as buildArcDecorator, s as buildPipelineHandler, u as resolvePipelineSteps } from "./routerShared-D6_fEGHh.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-CyUkQu6O.mjs";
+//#region src/core/aggregation/defineAggregation.ts
+/**
+* Declare a single resource aggregation. Exported configs flow into
+* `defineResource({ aggregations: { ... } })` either as named keys or
+* via auto-discovery patterns (loadAggregations — future).
+*
+* @example Inline
+* ```ts
+* defineResource({
+*   name: 'order',
+*   aggregations: {
+*     revenueByStatus: defineAggregation({
+*       groupBy: 'status',
+*       measures: { count: 'count', revenue: 'sum:totalPrice' },
+*       permissions: requireRoles(['admin']),
+*     }),
+*   },
+* });
+* ```
+*
+* @example Multi-file
+* ```ts
+* // orders/aggregations/revenue-by-status.ts
+* import { defineAggregation } from '@classytic/arc';
+*
+* export const revenueByStatus = defineAggregation({
+*   groupBy: 'status',
+*   measures: { count: 'count', revenue: 'sum:totalPrice' },
+*   permissions: requireRoles(['admin']),
+*   timeout: 5000,
+*   cache: { staleTime: 60 },
+* });
+*
+* // orders/order.resource.ts
+* import * as aggregations from './aggregations/index.js';
+*
+* defineResource({
+*   name: 'order',
+*   aggregations,                                  // 30+ entries flow in
+* });
+* ```
+*/
+function defineAggregation(config) {
+	return config;
+}
+//#endregion
+//#region src/core/createCrudRouter.ts
+/**
+* Mount custom routes (from presets or user-defined `routes`) on Fastify.
+* `wrapHandler` is derived inline from `!route.raw`.
+*/
+function createCustomRoutes(fastify, routes, controller, options) {
+	const { tag, resourceName, arcDecorator, rateLimitConfig, pluginMw, pipeline, routeGuards } = options;
+	for (const route of routes) {
+		const opName = route.operation ?? (typeof route.handler === "string" ? route.handler : `${route.method.toLowerCase()}${route.path.replace(/[/:]/g, "_")}`);
+		const wrapHandler = !route.raw;
+		let handler;
+		if (typeof route.handler === "string") {
+			if (!controller) throw new Error(`Route ${route.method} ${route.path}: string handler '${route.handler}' requires a controller. Either provide a controller or use a function handler instead.`);
+			const method = controller[route.handler];
+			if (typeof method !== "function") throw new Error(`Handler '${route.handler}' not found on controller`);
+			const boundMethod = method.bind(controller);
+			if (wrapHandler) {
+				const steps = resolvePipelineSteps(pipeline, opName);
+				handler = steps.length > 0 ? buildPipelineHandler(boundMethod, steps, opName, resourceName) : createFastifyHandler(boundMethod);
+			} else handler = boundMethod;
+		} else if (wrapHandler) {
+			const steps = resolvePipelineSteps(pipeline, opName);
+			handler = steps.length > 0 ? buildPipelineHandler(route.handler, steps, opName, resourceName) : createFastifyHandler(route.handler);
+		} else handler = route.handler;
+		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}`);
+		const preHandler = buildPreHandlerChain({
+			preAuth: route.preAuth ?? [],
+			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;
+		fastify.route({
+			method: route.method,
+			url: route.path,
+			schema,
+			preHandler: preHandler.length > 0 ? preHandler : void 0,
+			handler: isStream ? async (request, reply) => {
+				reply.raw.setHeader("Content-Type", "text/event-stream");
+				reply.raw.setHeader("Cache-Control", "no-cache");
+				reply.raw.setHeader("Connection", "keep-alive");
+				return handler(request, reply);
+			} : handler,
+			...rateLimitConfig ? { config: rateLimitConfig } : {}
+		});
+	}
+}
+/**
+* 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, updateMethod = DEFAULT_UPDATE_METHOD } = options;
+	const rateLimitConfig = buildRateLimitConfig(rateLimit);
+	const resourceHasQueryCache = fastify.hasDecorator("queryCache") && controller && typeof controller._cacheConfig !== "undefined" && controller._cacheConfig !== void 0;
+	const pluginMw = resolveRouterPluginMw(fastify, Boolean(resourceHasQueryCache));
+	const arcDecorator = buildArcDecorator({
+		resourceName,
+		schemaOptions,
+		permissions,
+		hooks: fastify.arc?.hooks,
+		events: fastify.events,
+		fields: fieldPermissions
+	});
+	const mw = {
+		list: middlewares.list ?? [],
+		get: middlewares.get ?? [],
+		create: middlewares.create ?? [],
+		update: middlewares.update ?? [],
+		delete: middlewares.delete ?? []
+	};
+	const idParamsSchema = {
+		type: "object",
+		properties: { id: { type: "string" } },
+		required: ["id"]
+	};
+	const defaultSchemas = getDefaultCrudSchemas();
+	/**
+	* Merge: base (tags/summary) → defaults (response/querystring) → user overrides.
+	* User-provided schemas always win; defaults enable fast-json-stringify when
+	* no user schema is set.
+	*/
+	const buildSchema = (base, defaults, userSchema) => ({
+		...defaults,
+		...base,
+		...userSchema ?? {}
+	});
+	if (!disableDefaultRoutes) {
+		if (!controller) throw new Error("Controller is required when disableDefaultRoutes is not true. Provide a controller or use defineResource which auto-creates BaseController.");
+		const handlers = buildCrudHandlers(controller, pipeline, resourceName);
+		const crudTable = [
+			{
+				op: "list",
+				method: "GET",
+				url: "/",
+				summary: `List ${tag}`,
+				hasIdParams: false
+			},
+			{
+				op: "get",
+				method: "GET",
+				url: "/:id",
+				summary: `Get ${tag} by ID`,
+				hasIdParams: true
+			},
+			{
+				op: "create",
+				method: "POST",
+				url: "/",
+				summary: `Create ${tag}`,
+				hasIdParams: false
+			},
+			{
+				op: "update",
+				method: "PATCH",
+				url: "/:id",
+				summary: `Update ${tag}`,
+				hasIdParams: true
+			},
+			{
+				op: "delete",
+				method: "DELETE",
+				url: "/:id",
+				summary: `Delete ${tag}`,
+				hasIdParams: true
+			}
+		];
+		for (const spec of crudTable) {
+			if (disabledRoutes.includes(spec.op)) continue;
+			const permission = permissions[spec.op];
+			const preHandler = buildPreHandlerChain({
+				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;
+				fastify.route({
+					method,
+					url: spec.url,
+					schema: buildSchema({
+						tags: [tag],
+						summary,
+						...spec.hasIdParams ? { params: idParamsSchema } : {}
+					}, defaultSchemas[spec.op], schemas[spec.op]),
+					preHandler: preHandler.length > 0 ? preHandler : void 0,
+					handler: handlers[spec.op],
+					...rateLimitConfig ? { config: rateLimitConfig } : {}
+				});
+			}
+		}
+	}
+	if (customRoutes.length > 0) createCustomRoutes(fastify, customRoutes, controller, {
+		tag,
+		resourceName,
+		arcDecorator,
+		rateLimitConfig,
+		pluginMw,
+		pipeline,
+		routeGuards
+	});
+}
+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;
+		wrapped[op] = buildPipelineHandler(ctrl[op].bind(ctrl), steps, op, resourceName);
+	}
+	return wrapped;
+}
+/**
+* Build a permission middleware from a PermissionCheck — useful when hosts
+* register their own routes outside the resource system but still want to
+* evaluate permissions through the shared applicator.
+*/
+function createPermissionMiddleware(permission, resourceName, action) {
+	return buildCrudPermissionMw(permission, resourceName, action);
+}
+//#endregion
+//#region src/core/defineResource/controller.ts
+/**
+* Phase 4 — pick (or auto-create) the resource's controller.
+*
+* Three branches:
+*   1. User-supplied controller → forward `queryParser` (duck-typed)
+*      and warn on dropped resource-level options.
+*   2. No controller, has CRUD routes, has a repository → auto-build
+*      a `BaseController` with every resource-level knob threaded
+*      through (tenantField, schemaOptions, idField, defaultSort,
+*      cache, onFieldWriteDenied, presetFields).
+*   3. Otherwise → `undefined` (custom-routes-only resource).
+*
+* The warns are load-bearing DX: silently dropping `queryParser`,
+* `schemaOptions`, etc. on a custom controller produces 90-minute
+* "why don't my filters work" debugs. Each warn names the resource,
+* lists the dropped options, and points at the canonical fix. All
+* warns honour `ARC_SUPPRESS_WARNINGS=1` via `arcLog()`.
+*/
+/**
+* Resolve the controller for the resource. See module docstring for
+* branch semantics.
+*/
+function resolveOrAutoCreateController(resolvedConfig, adapter, repository, hasCrudRoutes) {
+	const userController = resolvedConfig.controller;
+	if (userController) {
+		threadQueryParser(userController, resolvedConfig);
+		warnOnDroppedAuthorOptions(resolvedConfig);
+		warnOnDroppedPresetOptions(resolvedConfig);
+		return userController;
+	}
+	if (!hasCrudRoutes || !repository) return void 0;
+	return buildBaseController(resolvedConfig, adapter, repository);
+}
+/**
+* Forward a resource-level `queryParser` into a user-supplied
+* controller via duck-typed `setQueryParser`. Without this the
+* controller's internal default would silently override the
+* resource's parser, drifting `[contains]` / `[like]` semantics
+* away from what the OpenAPI schema advertises.
+*/
+function threadQueryParser(controller, resolvedConfig) {
+	if (!resolvedConfig.queryParser) return;
+	const ctrl = controller;
+	if (typeof ctrl.setQueryParser === "function") {
+		ctrl.setQueryParser(resolvedConfig.queryParser);
+		return;
+	}
+	arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" declares a custom \`queryParser\` but its controller does not expose \`setQueryParser(qp)\`. The parser will NOT be threaded into the controller's query resolution — operator filters (\`[contains]\`, \`[like]\`, etc.) may fall back to the controller's internal default. Extend \`BaseController\` / \`BaseCrudController\` (both implement \`setQueryParser\`) OR add the method to your custom controller to honor the resource-level parser.`);
+}
+/**
+* Warn when the user supplies their own controller AND declares
+* resource-level options arc only auto-threads on the auto-build
+* path. The user *can* fix this by forwarding through `super(repo,
+* { ... })`, so the warn names the dropped options + the canonical
+* fix.
+*/
+function warnOnDroppedAuthorOptions(resolvedConfig) {
+	const dropped = [];
+	if (resolvedConfig.tenantField !== void 0) dropped.push("tenantField");
+	if (resolvedConfig.schemaOptions !== void 0 && Object.keys(resolvedConfig.schemaOptions).length > 0) dropped.push("schemaOptions");
+	if (resolvedConfig.idField !== void 0) dropped.push("idField");
+	if (resolvedConfig.defaultSort !== void 0) dropped.push("defaultSort");
+	if (resolvedConfig.cache !== void 0) dropped.push("cache");
+	if (resolvedConfig.onFieldWriteDenied !== void 0) dropped.push("onFieldWriteDenied");
+	if (dropped.length === 0) return;
+	arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" declares a custom controller AND resource-level option(s) [${dropped.join(", ")}]. Arc only threads these when it auto-builds the controller — when you pass your own, they are dropped silently and the controller falls back to its own defaults (e.g. tenantField → 'organizationId'). Forward them to your controller's \`super(repo, { ... })\` call. Same root cause as the \`queryParser\` warn above.`);
+}
+/**
+* Warn when a preset injected `_controllerOptions` (slugLookup,
+* softDelete, parent presets) but the user supplied their own
+* controller. The user did NOT declare these — "forward them" is
+* bad advice. The fix is either drop the preset or extend
+* `BaseController` so the auto-build path runs.
+*/
+function warnOnDroppedPresetOptions(resolvedConfig) {
+	if (resolvedConfig._controllerOptions === void 0) return;
+	const presetFields = [];
+	if (resolvedConfig._controllerOptions.slugField) presetFields.push("slugField");
+	if (resolvedConfig._controllerOptions.parentField) presetFields.push("parentField");
+	arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" applies a preset that injects controller field(s) [${presetFields.join(", ") || "preset metadata"}] (e.g. slugLookup / softDelete / parent), but the resource also declares a custom controller. Preset metadata only reaches arc's auto-built BaseController — your custom controller will not see \`slugField\`/\`parentField\`/etc. Either (a) drop the preset on this resource (\`presets: [...]\` without it), or (b) extend \`BaseController\` / \`BaseCrudController\` so arc auto-builds the controller and threads the preset fields automatically.`);
+}
+/**
+* Auto-build a `BaseController` with every resource-level knob
+* threaded in. `maxLimit` is extracted from the parser's schema so
+* `BaseController.QueryResolver` and Fastify validation stay in sync
+* with the parser's configured limit.
+*/
+function buildBaseController(resolvedConfig, adapter, repository) {
+	const qp = resolvedConfig.queryParser;
+	let maxLimitFromParser;
+	if (qp?.getQuerySchema) {
+		const limitProp = qp.getQuerySchema()?.properties?.limit;
+		if (limitProp?.maximum) maxLimitFromParser = limitProp.maximum;
+	}
+	return new BaseController(repository, {
+		resourceName: resolvedConfig.name,
+		schemaOptions: resolvedConfig.schemaOptions,
+		queryParser: qp,
+		maxLimit: maxLimitFromParser,
+		tenantField: resolvedConfig.tenantField,
+		idField: resolvedConfig.idField,
+		...resolvedConfig.defaultSort !== void 0 ? { defaultSort: resolvedConfig.defaultSort } : {},
+		matchesFilter: adapter?.matchesFilter,
+		cache: resolvedConfig.cache,
+		onFieldWriteDenied: resolvedConfig.onFieldWriteDenied,
+		presetFields: resolvedConfig._controllerOptions ? {
+			slugField: resolvedConfig._controllerOptions.slugField,
+			parentField: resolvedConfig._controllerOptions.parentField
+		} : void 0
+	});
+}
+//#endregion
+//#region src/core/defineResource/hooks.ts
+/**
+* Phase 6 — wire preset hooks + inline `config.hooks` onto the
+* resource's `_pendingHooks`.
+*
+* Two sources feed the same array:
+*   1. Preset hooks collected during `applyPresets()` (raw `_hooks`
+*      on the internal config). Already in the canonical
+*      `{ operation, phase, handler, priority }` shape — copied
+*      verbatim (priority defaults to 10).
+*   2. Inline `config.hooks.beforeCreate` / `afterCreate` / etc.
+*      Authored by the user on the original `ResourceConfig`.
+*      Wrapped in a `ResourceHookContext` projection (v2.10.8) so
+*      authors can read `scope` / `context` without reaching into
+*      internal request fields.
+*
+* The 6 inline hook keys (before/after × create/update/delete) used
+* to be 6 nearly-identical blocks; collapsed into a table + loop so
+* a future hook (e.g. `beforeRead`) is one row, not seven scattered
+* edits.
+*/
+/**
+* Combined entry-point for Phase 6. Pushes preset-collected hooks
+* first, then inline `config.hooks` (so hosts can rely on
+* registration order if priorities tie).
+*/
+function wireHooks(resource, resolvedConfig, inlineHooksConfig) {
+	if (resolvedConfig._hooks?.length) resource._pendingHooks.push(...resolvedConfig._hooks.map((hook) => ({
+		operation: hook.operation,
+		phase: hook.phase,
+		handler: hook.handler,
+		priority: hook.priority ?? 10
+	})));
+	if (!inlineHooksConfig) return;
+	const h = inlineHooksConfig;
+	for (const spec of INLINE_HOOK_SPECS) {
+		const fn = h[spec.key];
+		if (typeof fn !== "function") continue;
+		resource._pendingHooks.push({
+			operation: spec.operation,
+			phase: spec.phase,
+			priority: 10,
+			handler: (ctx) => fn(buildHookContext(ctx))
+		});
+	}
+}
+/**
+* Inline hook spec table — one row per `config.hooks.{key}`. Adding
+* a new lifecycle hook (e.g. `beforeRead`) means appending one row
+* here; the loop handles the rest.
+*/
+const INLINE_HOOK_SPECS = [
+	{
+		key: "beforeCreate",
+		operation: "create",
+		phase: "before"
+	},
+	{
+		key: "afterCreate",
+		operation: "create",
+		phase: "after"
+	},
+	{
+		key: "beforeUpdate",
+		operation: "update",
+		phase: "before"
+	},
+	{
+		key: "afterUpdate",
+		operation: "update",
+		phase: "after"
+	},
+	{
+		key: "beforeDelete",
+		operation: "delete",
+		phase: "before"
+	},
+	{
+		key: "afterDelete",
+		operation: "delete",
+		phase: "after"
+	}
+];
+/**
+* Project a raw HookSystem context into a `ResourceHookContext` for
+* inline `config.hooks.*` handlers. The projection lifts `scope`
+* out of `context._scope` so authors don't reach into internal
+* fields.
+*/
+function buildHookContext(ctx) {
+	const context = ctx.context;
+	const rawScope = context?._scope;
+	return {
+		data: ctx.data ?? ctx.result ?? {},
+		user: ctx.user,
+		context,
+		scope: buildRequestScopeProjection(rawScope),
+		meta: ctx.meta
+	};
+}
+//#endregion
+//#region src/core/defineResource/idField.ts
+/**
+* Returns a fresh config with `idField` filled in (when applicable),
+* or the original reference when nothing changes. Never mutates the
+* caller's input.
+*/
+function resolveIdField(config, repository) {
+	if (config.idField !== void 0 || !repository) return config;
+	const repoIdField = repository.idField;
+	if (typeof repoIdField === "string" && repoIdField !== "_id") return {
+		...config,
+		idField: repoIdField
+	};
+	return config;
+}
+//#endregion
+//#region src/core/schemaOptions.ts
+/**
+* Inject the tenant-scoping field rule into `schemaOptions.fieldRules`:
+*
+*   { [tenantField]: { systemManaged: true, preserveForElevated: true } }
+*
+* Why both flags: `systemManaged` tells `BodySanitizer` to strip the
+* field from inbound bodies (so member clients can't forge a target
+* tenant). `preserveForElevated` exempts elevated-admin scopes from the
+* strip, so platform admins without a pinned org can still pick a target
+* org via the request body (the only channel they have —
+* `BaseController.create` can't re-stamp from scope when scope has no
+* orgId).
+*
+* **Returns a new `RouteSchemaOptions`** — the input is never mutated.
+* Callers should assign the return value to whatever config slot they
+* read from downstream (always the `resolvedConfig`, never raw `config`).
+*
+* **No-op when:**
+* - `tenantField` is `false` (platform-universal resource)
+* - `tenantField` is undefined
+* - The caller already declared `fieldRules[tenantField].systemManaged`
+*   (even as `false`) — explicit opt-outs are respected
+*
+* `preserveForElevated` defaults to `true` but is preserved verbatim
+* when the caller set it explicitly.
+*/
+function autoInjectTenantFieldRules(schemaOptions, tenantField) {
+	if (tenantField === false || tenantField === void 0) return schemaOptions;
+	const fieldName = tenantField || "organizationId";
+	const existing = schemaOptions?.fieldRules ?? {};
+	const existingRule = existing[fieldName];
+	if (existingRule && existingRule.systemManaged !== void 0) return schemaOptions;
+	return {
+		...schemaOptions ?? {},
+		fieldRules: {
+			...existing,
+			[fieldName]: {
+				...existingRule ?? {},
+				systemManaged: true,
+				preserveForElevated: existingRule?.preserveForElevated ?? true
+			}
+		}
+	};
+}
+/**
+* Remove a field from a JSON Schema's `required[]` array. Leaves `properties`
+* intact so advanced callers can still send the value — the field just isn't
+* mandatory at validation time.
+*
+* Returns a fresh schema (no mutation). No-op when the schema is undefined,
+* lacks a `required[]`, or the field is already absent from it.
+*/
+function stripFromRequired(schema, fieldName) {
+	if (!schema || typeof schema !== "object") return schema;
+	const required = schema.required;
+	if (!Array.isArray(required) || !required.includes(fieldName)) return schema;
+	const filtered = required.filter((f) => f !== fieldName);
+	const next = { ...schema };
+	if (filtered.length > 0) next.required = filtered;
+	else delete next.required;
+	return next;
+}
+/**
+* Strip framework-injected fields from the `required[]` list of every
+* body-shaped slot in an adapter's generated schemas (v2.11.0).
+*
+* A "framework-injected field" is any field marked `systemManaged: true`
+* in `schemaOptions.fieldRules`. Arc populates those fields from the
+* request scope / preset middleware / controller — the client is never
+* expected to supply them, so they must not be in the wire contract's
+* `required[]` even if the underlying engine's Mongoose/Zod schema
+* declares them as required at the DB layer.
+*
+* **The primary gotcha this closes:** engines built on
+* `@classytic/primitives` (mongokit, pricelist, and every downstream
+* `@classytic/*` engine) default to `tenant: { required: true }` in
+* `resolveTenantConfig()`. That stamps `organizationId: { required: true }`
+* on the Mongoose schema, which the adapter faithfully reflects into the
+* generated `createBody` / `updateBody` schema's `required[]`. Fastify's
+* preValidation runs BEFORE arc's preHandler chain, so
+* `multiTenantPreset`'s tenant-injection hook never gets a chance to run —
+* the request is rejected with `must have required property 'organizationId'`
+* even though the client correctly supplied `x-organization-id` and the
+* framework had already promised to inject the value.
+*
+* The only workaround before 2.11 was
+* `createEngine({ tenant: { required: false } })` at every consumer site —
+* a leaky abstraction every new engine-backed resource had to remember.
+*
+* **Secondary coverage (defense-in-depth):** the same transform also fires
+* for `auditedPreset`'s `createdBy` / `updatedBy`, any future preset that
+* marks fields `systemManaged`, and any host-declared `fieldRules` with
+* `systemManaged: true`. Every framework-injected field gets the wire
+* contract / runtime pairing for free.
+*
+* **Leaves `properties` intact** — elevated admins or advanced callers can
+* still send systemManaged fields in the body. `BodySanitizer` enforces
+* the runtime policy (`preserveForElevated`, `strip` vs `reject`, etc.).
+*
+* **No-op when:**
+* - `schemaOptions.fieldRules` is undefined / empty
+* - No rule has `systemManaged: true`
+* - The generated schemas object is undefined (adapter didn't generate any)
+*
+* Applies to both `createBody` and `updateBody` — update middleware also
+* injects tenant/audit fields, so the update wire contract has the same
+* problem as create.
+*/
+function stripSystemManagedFromBodyRequired(schemas, schemaOptions) {
+	if (!schemas) return schemas;
+	const rules = schemaOptions?.fieldRules;
+	if (!rules) return schemas;
+	const systemManagedFields = Object.entries(rules).filter(([, rule]) => rule?.systemManaged === true).map(([field]) => field);
+	if (systemManagedFields.length === 0) return schemas;
+	const next = { ...schemas };
+	let createBody = schemas.createBody;
+	for (const field of systemManagedFields) createBody = stripFromRequired(createBody, field);
+	if (createBody !== schemas.createBody) next.createBody = createBody;
+	let updateBody = schemas.updateBody;
+	for (const field of systemManagedFields) updateBody = stripFromRequired(updateBody, field);
+	if (updateBody !== schemas.updateBody) next.updateBody = updateBody;
+	return next;
+}
+//#endregion
+//#region src/core/defineResource/presets.ts
+/**
+* Phase 3 — apply presets + auto-inject tenant-field schema rules.
+*
+* Produces the canonical `resolvedConfig` — a fresh clone of the
+* caller's config with presets applied and tenant-field schema rules
+* inferred. Always returns a fresh object so downstream mutations
+* (`_appliedPresets`, `schemaOptions` auto-inject, `_controllerOptions`,
+* `_hooks`) never leak onto the caller's config. Pre-2.11 the
+* no-preset branch returned the raw caller reference, which mutated
+* resource-config fragments hosts were reusing.
+*
+* Centralising the auto-inject + tenant inference here means every
+* downstream reader (`BodySanitizer`, adapter `generateSchemas()`,
+* MCP tool generator, OpenAPI builder) sees the same post-inject
+* shape — `defineResource()` only ever consults `resolvedConfig`,
+* never the raw user input, after this phase runs.
+*/
+/**
+* Run the Phase 3 pipeline: clone → apply presets → infer tenant
+* field → auto-inject system-managed rules. Returns the resolved
+* `InternalResourceConfig` that every later phase consumes.
+*/
+function applyPresetsAndAutoInject(config) {
+	const originalPresets = (config.presets ?? []).map((p) => typeof p === "string" ? p : p.name);
+	const resolvedConfig = config.presets?.length ? applyPresets(config, config.presets) : { ...config };
+	resolvedConfig._appliedPresets = originalPresets;
+	inferTenantFieldFromAdapter(resolvedConfig);
+	resolvedConfig.schemaOptions = autoInjectTenantFieldRules(resolvedConfig.schemaOptions, resolvedConfig.tenantField);
+	return resolvedConfig;
+}
+/**
+* Infer `tenantField: false` for resources whose model schema doesn't
+* declare the configured tenant path. Closes the silent-zero-results
+* footgun where hosts forget `tenantField: false` on company-wide
+* tables (lookup tables, platform settings, single-tenant apps) — the
+* default `'organizationId'` filter would scope every read to the
+* caller's org and return nothing for documents that don't carry the
+* field. Adapters opt into inference by implementing `hasFieldPath`;
+* when the hook is absent, behaviour is unchanged (legacy default).
+*
+* Mutates the resolved config in place because (a) the next call
+* (`autoInjectTenantFieldRules`) reads the inferred value, and (b)
+* `_appliedPresets` is already stamped — keeping the mutation here
+* avoids a second clone per resource.
+*
+* Three branches:
+*   - `tenantField === false` → host explicitly opted out, no inference.
+*   - `tenantField === undefined` AND adapter says the default doesn't
+*     exist → set to `false`, log info (the inferred decision).
+*   - `tenantField === '<custom>'` AND adapter says it doesn't exist →
+*     warn (likely typo or stale field); leave the value as-is so
+*     failures surface at runtime with the configured name in error
+*     messages.
+*/
+function inferTenantFieldFromAdapter(config) {
+	if (config.tenantField === false) return;
+	const adapter = config.adapter;
+	if (!adapter?.hasFieldPath) return;
+	const configured = config.tenantField ?? "organizationId";
+	const exists = adapter.hasFieldPath(configured);
+	if (exists === void 0) return;
+	if (exists) return;
+	if (config.tenantField === void 0) {
+		config.tenantField = false;
+		arcLog("defineResource").info(`Resource "${config.name}": auto-inferred \`tenantField: false\` — model has no \`${configured}\` path. Set \`tenantField\` explicitly to silence this log, or to a real field name on this resource's model.`);
+		return;
+	}
+	arcLog("defineResource").warn(`Resource "${config.name}": configured \`tenantField: '${configured}'\` but the model has no such path. Queries scoped by this field will silently return nothing. Either set \`tenantField: false\` (company-wide resource), or fix the field name.`);
+}
+/** Does this resource register any default CRUD routes? */
+function computeHasCrudRoutes(config) {
+	const disabled = new Set(config.disabledRoutes ?? []);
+	return !config.disableDefaultRoutes && CRUD_OPERATIONS.some((op) => !disabled.has(op));
+}
+//#endregion
+//#region src/core/defineResource/plugin.ts
+/**
+* Build the CRUD schema map from the adapter's `OpenApiSchemas` plus
+* any `customSchemas` overrides on the resource.
+*
+* Returns `null` when neither input has anything to contribute, so
+* the caller can pass `undefined` straight to `createCrudRouter`.
+*
+* **Per-slot layering (post-2.12 DX fix).** Adapter auto-gen runs
+* unconditionally — declaring one custom slot (e.g. a richer
+* `create.body`) no longer wholesale-disables generated `get`,
+* `update`, `delete`, and `params` schemas. The pre-fix branch
+* skipped auto-gen entirely whenever `customSchemas` had any entry,
+* which silently flipped four slots from "auto-derived from the
+* adapter's schema generator" to "Fastify default" the moment a
+* host customised one. Now: auto-gen first, then deep-merge
+* customSchemas on top per slot.
+*
+* **`params` cloning is load-bearing.** Three CRUD slots (`get`,
+* `delete`, `update`) need a `params` schema. The previous inline
+* code shared the same reference across all three, so a downstream
+* mutation (e.g. attaching a vendor `description` for OpenAPI
+* tooling) leaked across operations. Each slot now owns its own
+* shallow clone.
+*/
+function buildGeneratedCrudSchemas(openApi, customSchemas) {
+	const generated = {};
+	if (openApi) {
+		const { createBody, updateBody, params } = openApi;
+		if (createBody) generated.create = { body: safeBody(createBody) };
+		if (updateBody) {
+			const patchBody = { ...updateBody };
+			delete patchBody.required;
+			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] ? deepMergeSchemas(schemas[key], converted) : converted;
+		}
+	}
+	return schemas;
+}
+/**
+* Normalize the listQuery JSON Schema for Fastify/AJV strict-mode use.
+*
+* The `qs` parser turns bracket notation into nested objects/arrays:
+*   `?name[contains]=foo` → `{ name: { contains: "foo" } }`
+*   `?tags[]=a&tags[]=b`  → `{ tags: ["a", "b"] }`
+*   `?populate[author][select]=name` → deeply nested object
+*
+* AJV rejects these against the OpenAPI-friendly `type: "string"`
+* declarations adapters generate. The QueryParser is the source of truth
+* for filter validation/coercion, so we replace each property with a
+* minimal AJV-strict-mode-clean shape: numeric pagination keys keep
+* `type: "integer"` (so `minimum`/`maximum` don't trigger AJV warnings),
+* everything else collapses to `{}`.
+*
+* The original `limit.maximum` is preserved so the parser's configured
+* max stays effective at the AJV layer.
+*/
+function normalizeListQuerySchema(listQuerySchema) {
+	const NORMALIZED_PROPS = {
+		page: {
+			type: "integer",
+			minimum: 1
+		},
+		limit: {
+			type: "integer",
+			minimum: 1
+		},
+		sort: {},
+		search: {},
+		select: {},
+		after: {},
+		populate: {},
+		lookup: {},
+		aggregate: {}
+	};
+	const props = listQuerySchema.properties;
+	const normalizedProps = props ? { ...props } : void 0;
+	if (normalizedProps) {
+		const originalLimit = normalizedProps.limit;
+		if (originalLimit?.maximum) NORMALIZED_PROPS.limit = {
+			...NORMALIZED_PROPS.limit,
+			maximum: originalLimit.maximum
+		};
+		for (const key of Object.keys(normalizedProps)) normalizedProps[key] = NORMALIZED_PROPS[key] ?? {};
+	}
+	return {
+		...listQuerySchema,
+		...normalizedProps ? { properties: normalizedProps } : {},
+		additionalProperties: listQuerySchema.additionalProperties ?? true
+	};
+}
+/**
+* Merge two JSON schema branches deeply. Arrays are unioned with
+* deduplication (so combined `required` lists don't duplicate field
+* names); plain-object keys recurse; primitives are overwritten.
+*
+* Exported for the action/CRUD router-config code paths that need to
+* compose user overrides on top of generated schemas.
+*/
+function deepMergeSchemas(base, override) {
+	if (!override) return base;
+	if (!base) return override;
+	const result = { ...base };
+	for (const [key, value] of Object.entries(override)) if (Array.isArray(value) && Array.isArray(result[key])) result[key] = [...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 };
+}
+function safeBody(schema) {
+	if (schema && typeof schema === "object" && schema.type === "object") return {
+		additionalProperties: true,
+		...schema
+	};
+	return schema;
+}
+/**
+* Normalize `ActionsMap` into the `ActionRouterConfig` shape that
+* `createActionRouter` expects.
+*
+* **Permission fallback chain (fail-closed, v2.10.5):** delegated to the
+* shared resolver in `actionPermissions.ts`. The resource-level gate
+* goes into the resolver's slot 2 (`resourceActionPermissions`) — its
+* semantic home — leaving slot 3 (`globalAuth`) reserved for direct
+* `createActionRouter` callers that genuinely have a router-wide gate.
+*
+* The returned `actionPermissions` map is FULLY RESOLVED per action.
+* Earlier versions returned a sparse map plus a `globalAuth` field that
+* `createActionRouter` flattened at request time via `?? globalAuth`.
+* That conflated two different layers in the resolver chain (slot 2 vs.
+* slot 3). Boot-time resolution closes the drift: every action that
+* survives this pass has its effective gate baked into the map, and
+* `createActionRouter`'s request-time `?? globalAuth` becomes a no-op
+* for the defineResource path.
+*/
+function normalizeActionsToRouterConfig(actions, resourceActionPermissions, tag, resourcePermissions, resourceName, log) {
+	const handlers = {};
+	const permissions = {};
+	const schemas = {};
+	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;
+		}
+		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
+	};
+}
+/**
+* Build the FastifyPluginAsync that materialises a `ResourceDefinition`
+* into routes, hooks, registry entries, and cache invalidation rules.
+*
+* Called once per `ResourceDefinition.toPlugin()`. The returned plugin
+* function captures `resource` in its closure and can be `app.register`-ed
+* any number of times — shared-state writes are idempotent per host
+* Fastify instance via `resource._sharedStateRegisteredOn`.
+*/
+function buildResourcePlugin(resource) {
+	return async function resourcePlugin(fastify, _opts) {
+		const sharedRoot = fastify.server ?? fastify;
+		const isFirstMount = !resource._sharedStateRegisteredOn.has(sharedRoot);
+		if (isFirstMount) resource._sharedStateRegisteredOn.add(sharedRoot);
+		const arc = fastify.arc;
+		if (isFirstMount && arc?.registry && resource._registryMeta) try {
+			arc.registry.register(resource, resource._registryMeta);
+		} catch (err) {
+			fastify.log?.warn?.(`Failed to register resource '${resource.name}' in registry: ${err instanceof Error ? err.message : err}`);
+		}
+		if (isFirstMount && resource._pendingHooks.length > 0 && arc?.hooks) for (const hook of resource._pendingHooks) arc.hooks.register({
+			resource: resource.name,
+			operation: hook.operation,
+			phase: hook.phase,
+			handler: hook.handler,
+			priority: hook.priority
+		});
+		const registerRule = fastify.registerCacheInvalidationRule;
+		if (isFirstMount && resource.cache?.invalidateOn && typeof registerRule === "function") for (const [pattern, tags] of Object.entries(resource.cache.invalidateOn)) registerRule({
+			pattern,
+			tags
+		});
+		await fastify.register(async (instance) => {
+			const typedInstance = instance;
+			let schemas = buildGeneratedCrudSchemas(resource._registryMeta?.openApiSchemas, resource.customSchemas);
+			const listQuerySchema = resource._registryMeta?.openApiSchemas?.listQuery;
+			if (listQuerySchema) {
+				const normalizedSchema = normalizeListQuerySchema(listQuerySchema);
+				schemas = schemas ?? {};
+				schemas.list = schemas.list ? deepMergeSchemas({ querystring: normalizedSchema }, schemas.list) : { querystring: normalizedSchema };
+			}
+			createCrudRouter(typedInstance, resource.controller, {
+				tag: resource.tag,
+				schemas: schemas ?? void 0,
+				permissions: resource.permissions,
+				middlewares: resource.middlewares,
+				routeGuards: resource.routeGuards,
+				routes: resource.routes,
+				disableDefaultRoutes: resource.disableDefaultRoutes,
+				disabledRoutes: [...resource.disabledRoutes],
+				resourceName: resource.name,
+				schemaOptions: resource.schemaOptions,
+				rateLimit: resource.rateLimit,
+				updateMethod: resource.updateMethod,
+				pipe: resource.pipe,
+				fields: resource.fields
+			});
+			if (resource.actions && Object.keys(resource.actions).length > 0) {
+				const { createActionRouter } = await import("./createActionRouter-CEvzKcy8.mjs").then((n) => n.n);
+				createActionRouter(typedInstance, {
+					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
+					resourceName: resource.name,
+					fields: resource.fields,
+					schemaOptions: resource.schemaOptions,
+					permissions: resource.permissions,
+					routeGuards: resource.routeGuards,
+					pipeline: resource.pipe,
+					rateLimit: resource.rateLimit
+				});
+			}
+			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
+				const { createAggregationRouter } = await import("./createAggregationRouter-CyecOxnO.mjs");
+				const repoForAgg = resource.controller?.repository;
+				const buildOptions = (req) => {
+					return resource.controller?.tenantRepoOptions?.(req) ?? {};
+				};
+				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
+				});
+			}
+			if (resource.events && Object.keys(resource.events).length > 0) typedInstance.log?.debug?.(`Resource '${resource.name}' defined ${Object.keys(resource.events).length} events`);
+		}, { prefix: resource.prefix });
+		if (hasEvents(fastify)) try {
+			await fastify.events.publish("arc.resource.registered", {
+				resource: resource.name,
+				prefix: resource.prefix,
+				presets: resource._appliedPresets,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		} catch {}
+	};
+}
+//#endregion
+//#region src/core/defineResource/ResourceDefinition.ts
+var ResourceDefinition = class {
+	name;
+	displayName;
+	tag;
+	prefix;
+	skipGlobalPrefix;
+	adapter;
+	controller;
+	schemaOptions;
+	customSchemas;
+	permissions;
+	routes;
+	middlewares;
+	routeGuards;
+	disableDefaultRoutes;
+	disabledRoutes;
+	actions;
+	actionPermissions;
+	aggregations;
+	events;
+	rateLimit;
+	audit;
+	updateMethod;
+	pipe;
+	fields;
+	cache;
+	tenantField;
+	idField;
+	queryParser;
+	_appliedPresets;
+	_pendingHooks;
+	_registryMeta;
+	/**
+	* Per-host idempotency guard used by `buildResourcePlugin` to
+	* skip duplicate shared-state writes when the same resource is
+	* mounted at multiple prefixes (`/v1`, `/v2`). See the plugin
+	* file for the full rationale; surfaced here as `readonly` so
+	* the helper can consult it without a class-method indirection.
+	*/
+	_sharedStateRegisteredOn = /* @__PURE__ */ new WeakSet();
+	constructor(config) {
+		this.name = config.name;
+		this.displayName = config.displayName ?? `${capitalize(config.name)}s`;
+		this.tag = config.tag ?? this.displayName;
+		this.prefix = config.prefix ?? `/${config.name}s`;
+		this.skipGlobalPrefix = config.skipGlobalPrefix ?? false;
+		this.adapter = config.adapter;
+		this.controller = config.controller;
+		this.schemaOptions = Object.freeze({ ...config.schemaOptions ?? {} });
+		this.customSchemas = Object.freeze({ ...config.customSchemas ?? {} });
+		this.permissions = Object.freeze({ ...config.permissions ?? {} });
+		this.routes = freezeRoutes(config.routes);
+		this.disabledRoutes = Object.freeze([...config.disabledRoutes ?? []]);
+		this.events = Object.freeze({ ...config.events ?? {} });
+		this.middlewares = config.middlewares ?? {};
+		this.routeGuards = config.routeGuards;
+		this.disableDefaultRoutes = config.disableDefaultRoutes ?? false;
+		this.actions = freezeActions(config.actions);
+		this.actionPermissions = config.actionPermissions;
+		this.aggregations = config.aggregations;
+		this.rateLimit = config.rateLimit;
+		this.audit = config.audit;
+		this.updateMethod = config.updateMethod;
+		this.pipe = config.pipe;
+		this.fields = config.fields;
+		this.cache = config.cache;
+		this.tenantField = config.tenantField;
+		this.idField = config.idField;
+		this.queryParser = config.queryParser;
+		this._appliedPresets = config._appliedPresets ?? [];
+		this._pendingHooks = config._pendingHooks ?? [];
+	}
+	/** Repository accessor — pulled off the adapter when one is wired. */
+	get repository() {
+		return this.adapter?.repository;
+	}
+	/**
+	* Validate that the wired controller implements every method
+	* needed by enabled CRUD routes + every string-handler custom
+	* route. Runs at the end of `defineResource()` (skippable via
+	* `skipValidation: true`) so misconfigured resources fail at
+	* boot, not on first request.
+	*/
+	_validateControllerMethods() {
+		const errors = [];
+		const enabledCrudRoutes = CRUD_OPERATIONS.filter((route) => !this.disabledRoutes.includes(route));
+		if (!this.disableDefaultRoutes && enabledCrudRoutes.length > 0) if (!this.controller) errors.push("Controller is required when CRUD routes are enabled");
+		else {
+			const ctrl = this.controller;
+			for (const method of enabledCrudRoutes) if (typeof ctrl[method] !== "function") errors.push(`CRUD method '${method}' not found on controller`);
+		}
+		for (const route of this.routes) {
+			if (typeof route.handler !== "string") continue;
+			if (!this.controller) {
+				errors.push(`Route ${route.method} ${route.path}: string handler '${route.handler}' requires a controller`);
+				continue;
+			}
+			if (typeof this.controller[route.handler] !== "function") errors.push(`Route ${route.method} ${route.path}: handler '${route.handler}' not found`);
+		}
+		if (errors.length === 0) return;
+		throw new Error([
+			`Resource '${this.name}' validation failed:`,
+			...errors.map((e) => `  - ${e}`),
+			"",
+			"Ensure controller implements IController<TDoc> interface.",
+			"For preset routes (softDelete, tree), add corresponding methods to controller."
+		].join("\n"));
+	}
+	/**
+	* Build the Fastify plugin that materialises this resource into
+	* routes, hooks, registry entries, and cache invalidation rules.
+	* One-line delegate — the implementation lives in `./plugin.ts`.
+	*/
+	toPlugin() {
+		return buildResourcePlugin(this);
+	}
+	/** Event definitions for registry consumption. */
+	getEvents() {
+		return Object.entries(this.events).map(([action, meta]) => ({
+			name: `${this.name}:${action}`,
+			module: this.name,
+			schema: meta.schema,
+			description: meta.description
+		}));
+	}
+	/** Resource metadata — shape consumed by registry / introspection. */
+	getMetadata() {
+		return {
+			name: this.name,
+			displayName: this.displayName,
+			tag: this.tag,
+			prefix: this.prefix,
+			presets: this._appliedPresets,
+			permissions: this.permissions,
+			customRoutes: this.routes.map((r) => ({
+				method: r.method,
+				path: r.path,
+				handler: typeof r.handler === "string" ? r.handler : r.handler.name || "anonymous",
+				operation: r.operation,
+				summary: r.summary,
+				description: r.description,
+				permissions: r.permissions,
+				raw: r.raw,
+				schema: r.schema
+			})),
+			routes: [],
+			events: Object.keys(this.events)
+		};
+	}
+};
+function capitalize(str) {
+	if (!str) return "";
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+* Freeze the routes array AND each route object inside it. Catches
+* `resource.routes[0].permissions = bypass` and equivalent post-
+* define mutations that would silently rewire the registered surface.
+*
+* Each route is shallow-copied before freezing so the host's
+* original route object stays mutable (consistent with how the
+* top-level config slots are treated).
+*/
+function freezeRoutes(routes) {
+	const list = (routes ?? []).map((route) => Object.freeze({ ...route }));
+	return Object.freeze(list);
+}
+/**
+* Freeze the actions map AND each action entry. Function-shorthand
+* actions (`async (id, data, req) => ...`) need no per-entry freeze
+* — function references are immutable in practice; you can't mutate
+* a closure post-hoc. Object-form `ActionDefinition` entries DO need
+* a freeze so `actions.send.permissions = bypass` throws.
+*/
+function freezeActions(actions) {
+	if (!actions) return void 0;
+	const frozen = {};
+	for (const [name, entry] of Object.entries(actions)) frozen[name] = typeof entry === "function" ? entry : Object.freeze({ ...entry });
+	return Object.freeze(frozen);
+}
+//#endregion
+//#region src/core/defineResource/schemas.ts
+/**
+* OpenAPI schema resolution — Phase 7 of `defineResource()`.
+*
+* Pipeline (each step is a pure function over `OpenApiSchemas | undefined`):
+*
+*   adapter.generateSchemas()
+*     → stripSystemManagedFromBodyRequired   (from `../schemaOptions.js`)
+*     → cleanLegacyObjectIdParams            (idField safety net)
+*     → layerQueryParserListQuery            (kit's listQuery JSON Schema)
+*     → mergeUserOpenApiOverrides            (per-resource overrides)
+*     → convertOpenApiSchemas                (Zod → JSON Schema if needed)
+*
+* Non-fatal: if any step throws, the orchestrator returns `undefined` so
+* the resource still boots — docs / introspection / MCP tool schemas
+* degrade visibly instead of silently drifting.
+*
+* Pulled out of `defineResource.ts` so the central function reads as
+* orchestration only; the schema mechanics live next to each other and
+* are easier to evolve in isolation.
+*/
+/**
+* Phase 7 orchestrator — runs the schema pipeline and returns the
+* registry metadata for the resource. Returns `undefined` (with a
+* structured warn log) if any step throws.
+*/
+function resolveOpenApiSchemas(resolvedConfig) {
+	try {
+		let openApiSchemas = generateAdapterSchemas(resolvedConfig);
+		openApiSchemas = stripSystemManagedFromBodyRequired(openApiSchemas, resolvedConfig.schemaOptions);
+		openApiSchemas = cleanLegacyObjectIdParams(openApiSchemas, resolvedConfig.idField);
+		openApiSchemas = layerQueryParserListQuery(openApiSchemas, resolvedConfig.queryParser);
+		openApiSchemas = mergeUserOpenApiOverrides(openApiSchemas, resolvedConfig.openApiSchemas);
+		if (openApiSchemas) openApiSchemas = convertOpenApiSchemas(openApiSchemas);
+		return {
+			module: resolvedConfig.module,
+			openApiSchemas
+		};
+	} catch (err) {
+		arcLog("defineResource").warn(`OpenAPI/MCP schema generation failed for resource "${resolvedConfig.name}": ${err instanceof Error ? err.message : String(err)}. Resource will boot without registry metadata — OpenAPI docs and MCP tool schemas will be missing.`);
+		return;
+	}
+}
+/**
+* Step 1 — delegate to the adapter's `generateSchemas`. Returns
+* `undefined` when the adapter doesn't implement the optional method.
+*/
+function generateAdapterSchemas(resolvedConfig) {
+	if (!resolvedConfig.adapter?.generateSchemas) return void 0;
+	const adapterContext = {
+		idField: resolvedConfig.idField,
+		resourceName: resolvedConfig.name
+	};
+	return resolvedConfig.adapter.generateSchemas(resolvedConfig.schemaOptions, adapterContext);
+}
+/**
+* Safety net: when `idField` is overridden to a non-default value (UUIDs,
+* slugs, ORD-2026-0001), strip any ObjectId pattern left on `params.id` by
+* legacy adapters or plugins that didn't honor `AdapterSchemaContext.idField`.
+* Custom IDs must not be rejected by AJV before BaseController runs the
+* actual lookup.
+*/
+function cleanLegacyObjectIdParams(openApiSchemas, idField) {
+	if (!openApiSchemas || !idField || idField === "_id") return openApiSchemas;
+	const params = openApiSchemas.params;
+	if (!params || typeof params !== "object") return openApiSchemas;
+	const properties = params.properties;
+	const idProp = properties?.id;
+	if (!idProp || typeof idProp !== "object") return openApiSchemas;
+	const pattern = idProp.pattern;
+	if (!(typeof pattern === "string" && (pattern === "^[0-9a-fA-F]{24}$" || pattern === "^[a-f\\d]{24}$" || pattern === "^[a-fA-F0-9]{24}$" || /^\^\[[a-fA-F0-9\\d]+\]\{24\}\$$/.test(pattern)))) return openApiSchemas;
+	const cleanedId = { ...idProp };
+	delete cleanedId.pattern;
+	delete cleanedId.minLength;
+	delete cleanedId.maxLength;
+	if (!cleanedId.description) cleanedId.description = `${idField} (custom ID field)`;
+	return {
+		...openApiSchemas,
+		params: {
+			...params,
+			properties: {
+				...properties,
+				id: cleanedId
+			}
+		}
+	};
+}
+/**
+* Layer the query parser's `getQuerySchema()` output as `listQuery` so
+* the kit's filterable-fields surface flows into OpenAPI / MCP without
+* the user re-declaring it.
+*/
+function layerQueryParserListQuery(openApiSchemas, queryParser) {
+	const qp = queryParser;
+	if (!qp?.getQuerySchema) return openApiSchemas;
+	const querySchema = qp.getQuerySchema();
+	if (!querySchema) return openApiSchemas;
+	return {
+		...openApiSchemas,
+		listQuery: querySchema
+	};
+}
+/**
+* Apply 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/validate.ts
+/**
+* CRUD op names — kept module-scope (vs allocated per `defineResource()`
+* call) since the set is fixed and the cost of re-allocating is a
+* pointless boot tax for hosts with hundreds of resources.
+*/
+const CRUD_OP_NAMES = new Set([
+	"create",
+	"update",
+	"delete",
+	"list",
+	"get"
+]);
+/**
+* Run the structural validation pipeline. Throws an `Error` with a
+* resource-named message on the first failure — `defineResource()`
+* surfaces it verbatim so hosts get a clear "fix this resource"
+* pointer.
+*/
+function validateDefineResourceConfig(config) {
+	assertValidConfig(config, { skipControllerCheck: true });
+	validatePermissionsShape(config);
+	validateCustomRoutePermissions(config);
+	validateActionsShape(config);
+}
+/** Permissions must be `PermissionCheck` functions, not arbitrary values. */
+function validatePermissionsShape(config) {
+	if (!config.permissions) return;
+	for (const [key, value] of Object.entries(config.permissions)) if (value !== void 0 && typeof value !== "function") throw new Error(`[Arc] Resource '${config.name}': permissions.${key} must be a PermissionCheck function.\nUse allowPublic(), requireAuth(), or requireRoles(['role']) from @classytic/arc/permissions.`);
+}
+/**
+* Custom routes must declare `permissions` as a function — fail-closed
+* default. A missing `permissions` could otherwise quietly mount an
+* unauthenticated route.
+*/
+function validateCustomRoutePermissions(config) {
+	for (const route of config.routes ?? []) if (typeof route.permissions !== "function") throw new Error(`[Arc] Resource '${config.name}' route ${route.method} ${route.path}: permissions is required and must be a PermissionCheck function.`);
+}
+/**
+* Actions (v2.8) — name must not collide with CRUD ops; handler +
+* permissions must have the right shapes. Fail at boot so production
+* never ships a misconfigured action endpoint.
+*/
+function validateActionsShape(config) {
+	if (!config.actions) return;
+	for (const [name, entry] of Object.entries(config.actions)) {
+		if (CRUD_OP_NAMES.has(name)) throw new Error(`[Arc] Resource '${config.name}': action '${name}' conflicts with CRUD operation.\nUse a different name (e.g., '${name}_item', 'do_${name}').`);
+		if (typeof entry !== "function") {
+			const def = entry;
+			if (typeof def.handler !== "function") throw new Error(`[Arc] Resource '${config.name}': actions.${name}.handler must be a function.`);
+			if (def.permissions !== void 0 && typeof def.permissions !== "function") throw new Error(`[Arc] Resource '${config.name}': actions.${name}.permissions must be a PermissionCheck function.`);
+		}
+	}
+}
+//#endregion
+//#region src/core/defineResource.ts
+/**
+* `TDoc` is **unconstrained** at this layer. The previous `TDoc
+* extends AnyRecord` bound leaked out of `BaseController`'s
+* mixin-composition requirement into every host's adapter boundary:
+* Mongoose's `HydratedDocument<T>`, Prisma's generated row types,
+* and any domain interface without an explicit index signature all
+* failed to satisfy `Record<string, unknown>` even though at runtime
+* they ARE string-keyed objects. Hosts were forced to cast at every
+* adapter (`as RepositoryLike<Record<string, unknown>>`) — a type
+* escape with no runtime purpose, since arc's pipeline only reads
+* known envelope fields.
+*
+* The cast moved inside `resolveOrAutoCreateController` where
+* `BaseController<TDoc extends AnyRecord>` actually requires it.
+* One internal boundary cast replaces N host-side casts.
+*/
+function defineResource(config) {
+	if (!config.skipValidation) validateDefineResourceConfig(config);
+	const repository = config.adapter?.repository;
+	const configWithId = resolveIdField(config, repository);
+	const resolvedConfig = applyPresetsAndAutoInject(configWithId);
+	const hasCrudRoutes = computeHasCrudRoutes(resolvedConfig);
+	const narrowedConfig = resolvedConfig;
+	const narrowedAdapter = configWithId.adapter;
+	const controller = resolveOrAutoCreateController(narrowedConfig, narrowedAdapter, repository, hasCrudRoutes);
+	const resource = new ResourceDefinition({
+		...resolvedConfig,
+		adapter: configWithId.adapter,
+		controller
+	});
+	if (!config.skipValidation && controller) resource._validateControllerMethods();
+	wireHooks(resource, narrowedConfig, configWithId.hooks);
+	if (!config.skipRegistry) {
+		const registryMeta = resolveOpenApiSchemas(narrowedConfig);
+		if (registryMeta) resource._registryMeta = registryMeta;
+	}
+	return resource;
+}
+//#endregion
+//#region src/core/defineResourceVariants.ts
+/**
+* Define multiple resources from a shared base config and per-variant overrides.
+*
+* Each variant is independently passed through `defineResource()` — the
+* returned `ResourceDefinition`s are real, fully-registered resources.
+* Register each one's plugin in your app:
+*
+* ```typescript
+* await app.register(articlePublic.toPlugin());
+* await app.register(articleAdmin.toPlugin());
+* ```
+*
+* @param base    Shared config — adapter, queryParser, schemaOptions, hooks, etc.
+*                Must NOT include `name` or `prefix` (those are per-variant).
+* @param variants  Map of variant key → override. Each variant must declare
+*                  its own `name` and `prefix`. Other fields override the base.
+* @returns A record where each key from `variants` maps to a real
+*          `ResourceDefinition` ready for `.toPlugin()` registration.
+*/
+function defineResourceVariants(base, variants) {
+	const out = {};
+	for (const key of Object.keys(variants)) {
+		const override = variants[key];
+		out[key] = defineResource({
+			...base,
+			...override
+		});
+	}
+	return out;
+}
+//#endregion
+export { createPermissionMiddleware as a, createCrudRouter as i, defineResource as n, defineAggregation as o, ResourceDefinition as r, defineResourceVariants as t };