@classytic/arc 2.11.4 → 2.13.1

package/dist/core-CbcQRIch.mjs

@@ -1,1054 +0,0 @@
-import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-BhY1OHoH.mjs";
-import { arcLog } from "./logger/index.mjs";
-import { m as assertValidConfig, y as getDefaultCrudSchemas } from "./utils-CcYTj09l.mjs";
-import { t as BaseController } from "./BaseController-swXruJ2_.mjs";
-import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-B0oKLuqI.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-BqLRb5l7.mjs";
-import { t as applyPresets } from "./presets-Z7P5w4gF.mjs";
-import { t as hasEvents } from "./typeGuards-CcFZXgU7.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-sUUKDhtP.mjs";
-//#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/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.ts
-/**
-* Define a resource with database adapter.
-*
-* This is the MAIN entry point for creating Arc resources — the adapter
-* provides both repository and schema metadata.
-*
-* Staged into seven named phases so future refactors touch one phase at a
-* time instead of threading changes through a 450-line function:
-*
-*   1. validate                  — fail-fast structural checks
-*   2. resolveIdField            — auto-derive `idField` from repository
-*   3. applyPresetsAndAutoInject — clone + apply presets + tenant-field rules
-*   4. resolveController         — reuse user controller or auto-create BaseController
-*   5. buildResource             — construct ResourceDefinition + validate methods
-*   6. wireHooks                 — push preset + inline `config.hooks` onto _pendingHooks
-*   7. resolveOpenApiSchemas     — adapter schemas → parser listQuery → user override
-*
-* Each phase has a single responsibility; `resolvedConfig` is the canonical
-* post-preset, post-auto-inject config that every later phase reads. Raw
-* `config` is only consulted for things presets don't touch (adapter,
-* skipRegistry, skipValidation, hooks — which are wired separately from
-* preset hooks).
-*/
-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;
-}
-function validateDefineResourceConfig(config) {
-	assertValidConfig(config, { skipControllerCheck: true });
-	if (config.permissions) {
-		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.`);
-	}
-	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.`);
-	if (config.actions) {
-		const CRUD_OPS = new Set([
-			"create",
-			"update",
-			"delete",
-			"list",
-			"get"
-		]);
-		for (const [name, entry] of Object.entries(config.actions)) {
-			if (CRUD_OPS.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.`);
-			}
-		}
-	}
-}
-/**
-* Auto-derive `idField` from the repository when the user didn't set one
-* explicitly. MongoKit-style repositories declare their primary key field
-* via `repository.idField`. By picking it up here (BEFORE preset resolution),
-* the user configures idField in ONE place (the repo) and arc threads it
-* through `BaseController`, AJV params schema, `ResourceDefinition.idField`,
-* and preset field wiring consistently.
-*
-* Returns a fresh config — never mutates the caller's reference.
-*/
-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;
-}
-/**
-* Produce the canonical `resolvedConfig` — a fresh clone of the caller's
-* config with presets applied and tenant-field schema rules auto-injected.
-*
-* v2.11.0: always returns a fresh object so downstream mutations
-* (`_appliedPresets`, `schemaOptions` auto-inject, `_controllerOptions`,
-* `_pendingHooks`) never leak onto the caller's config. Before 2.11 the
-* no-preset branch returned the raw caller reference, which mutated
-* resource-config fragments hosts were reusing.
-*
-* Full rationale for tenant-field auto-inject lives in
-* `autoInjectTenantFieldRules` (src/core/schemaOptions.ts). Centralised here
-* so every downstream reader (`BodySanitizer`, adapter `generateSchemas()`,
-* MCP tool generator, OpenAPI builder) sees the same post-inject shape.
-*/
-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;
-	resolvedConfig.schemaOptions = autoInjectTenantFieldRules(resolvedConfig.schemaOptions, resolvedConfig.tenantField);
-	return resolvedConfig;
-}
-function computeHasCrudRoutes(config) {
-	const disabled = new Set(config.disabledRoutes ?? []);
-	return !config.disableDefaultRoutes && CRUD_OPERATIONS.some((op) => !disabled.has(op));
-}
-/**
-* Pick the controller for the resource:
-*   - user-supplied controller → forward `queryParser` to it (duck-typed)
-*   - no controller + CRUD routes + repository → auto-create BaseController
-*   - otherwise → undefined (custom-routes-only resource)
-*
-* Duck-typed `setQueryParser()` forwarding (v2.10.9) ensures operator filters
-* like `[contains]` / `[like]` work in custom controllers too. Controllers
-* that don't implement the method get a boot-time warn (v2.11) so authors
-* of hand-rolled controllers see the dropped parser instead of silently
-* debugging stale filter semantics. `BaseController` subclasses pick it up
-* automatically.
-*/
-function resolveOrAutoCreateController(resolvedConfig, adapter, repository, hasCrudRoutes) {
-	let controller = resolvedConfig.controller;
-	if (controller && resolvedConfig.queryParser) {
-		const ctrl = controller;
-		if (typeof ctrl.setQueryParser === "function") ctrl.setQueryParser(resolvedConfig.queryParser);
-		else 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.`);
-	}
-	if (controller) {
-		const authorOptions = [];
-		if (resolvedConfig.tenantField !== void 0) authorOptions.push("tenantField");
-		if (resolvedConfig.schemaOptions !== void 0 && Object.keys(resolvedConfig.schemaOptions).length > 0) authorOptions.push("schemaOptions");
-		if (resolvedConfig.idField !== void 0) authorOptions.push("idField");
-		if (resolvedConfig.defaultSort !== void 0) authorOptions.push("defaultSort");
-		if (resolvedConfig.cache !== void 0) authorOptions.push("cache");
-		if (resolvedConfig.onFieldWriteDenied !== void 0) authorOptions.push("onFieldWriteDenied");
-		if (authorOptions.length > 0) arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" declares a custom controller AND resource-level option(s) [${authorOptions.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.`);
-		if (resolvedConfig._controllerOptions !== void 0) {
-			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.`);
-		}
-		return controller;
-	}
-	if (!hasCrudRoutes || !repository) return controller;
-	const qp = resolvedConfig.queryParser;
-	let maxLimitFromParser;
-	if (qp?.getQuerySchema) {
-		const limitProp = qp.getQuerySchema()?.properties?.limit;
-		if (limitProp?.maximum) maxLimitFromParser = limitProp.maximum;
-	}
-	controller = new BaseController(repository, {
-		resourceName: resolvedConfig.name,
-		schemaOptions: resolvedConfig.schemaOptions,
-		queryParser: resolvedConfig.queryParser,
-		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
-	});
-	return controller;
-}
-/**
-* Push preset-collected hooks and inline `config.hooks` onto the resource's
-* `_pendingHooks`. The inline `config.hooks` handlers get a
-* `ResourceHookContext` projection (v2.10.8) so they can reach `scope` /
-* `context` without reaching into internal fields.
-*/
-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 toCtx = (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
-		};
-	};
-	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"
-		}
-	];
-	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(toCtx(ctx))
-		});
-	}
-}
-/**
-* Resolve OpenAPI schemas for a resource with a unified priority order:
-*
-*   listQuery:
-*     1. config.openApiSchemas.listQuery    (user override — wins)
-*     2. queryParser.getQuerySchema()       (parser is source of truth)
-*     3. adapter.generateSchemas().listQuery (fallback placeholder)
-*
-*   createBody / updateBody / response / params:
-*     1. config.openApiSchemas.{slot}       (user override — wins)
-*     2. adapter.generateSchemas().{slot}   (auto-generated from DB schema)
-*
-* Why parser beats adapter for listQuery: the QueryParser knows the real
-* query semantics (filter operators, max limit, sort whitelist, pagination).
-* The adapter only knows persistence — it can't infer `name_contains` or
-* `limit.maximum`.
-*
-* **Every downstream read comes from `resolvedConfig`, never raw `config`.**
-* This is an audited convention — 2.10.6 shipped with a single
-* `config.schemaOptions` slip that broke auto-inject forwarding, so every
-* access is normalised through `resolvedConfig` to close the bug class.
-*
-* Non-fatal: if any phase throws, returns registry metadata anyway (with
-* `openApiSchemas: undefined`) and warns. The resource still boots — docs
-* and MCP tool schemas degrade visibly instead of silently drifting.
-*/
-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;
-	}
-}
-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
-			}
-		}
-	};
-}
-function layerQueryParserListQuery(openApiSchemas, queryParser) {
-	const qp = queryParser;
-	if (!qp?.getQuerySchema) return openApiSchemas;
-	const querySchema = qp.getQuerySchema();
-	if (!querySchema) return openApiSchemas;
-	return {
-		...openApiSchemas,
-		listQuery: querySchema
-	};
-}
-function mergeUserOpenApiOverrides(openApiSchemas, userOverrides) {
-	if (!userOverrides) return openApiSchemas;
-	return {
-		...openApiSchemas,
-		...userOverrides
-	};
-}
-var ResourceDefinition = class {
-	name;
-	displayName;
-	tag;
-	prefix;
-	adapter;
-	controller;
-	schemaOptions;
-	customSchemas;
-	permissions;
-	routes;
-	middlewares;
-	routeGuards;
-	disableDefaultRoutes;
-	disabledRoutes;
-	actions;
-	actionPermissions;
-	events;
-	rateLimit;
-	audit;
-	updateMethod;
-	pipe;
-	fields;
-	cache;
-	skipGlobalPrefix;
-	tenantField;
-	idField;
-	queryParser;
-	_appliedPresets;
-	_pendingHooks;
-	_registryMeta;
-	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 = config.schemaOptions ?? {};
-		this.customSchemas = config.customSchemas ?? {};
-		this.permissions = config.permissions ?? {};
-		this.routes = config.routes ?? [];
-		this.middlewares = config.middlewares ?? {};
-		this.routeGuards = config.routeGuards;
-		this.disableDefaultRoutes = config.disableDefaultRoutes ?? false;
-		this.disabledRoutes = config.disabledRoutes ?? [];
-		this.actions = config.actions;
-		this.actionPermissions = config.actionPermissions;
-		this.events = config.events ?? {};
-		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 ?? [];
-	}
-	/** Get repository from adapter (if available) */
-	get repository() {
-		return this.adapter?.repository;
-	}
-	_validateControllerMethods() {
-		const errors = [];
-		const crudRoutes = CRUD_OPERATIONS;
-		const disabledRoutes = new Set(this.disabledRoutes ?? []);
-		const enabledCrudRoutes = crudRoutes.filter((route) => !disabledRoutes.has(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") {
-			if (!this.controller) errors.push(`Route ${route.method} ${route.path}: string handler '${route.handler}' requires a controller`);
-			else if (typeof this.controller[route.handler] !== "function") errors.push(`Route ${route.method} ${route.path}: handler '${route.handler}' not found`);
-		}
-		if (errors.length > 0) {
-			const errorMsg = [
-				`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");
-			throw new Error(errorMsg);
-		}
-	}
-	toPlugin() {
-		const self = this;
-		return async function resourcePlugin(fastify, _opts) {
-			const arc = fastify.arc;
-			if (arc?.registry && self._registryMeta) try {
-				arc.registry.register(self, self._registryMeta);
-			} catch (err) {
-				fastify.log?.warn?.(`Failed to register resource '${self.name}' in registry: ${err instanceof Error ? err.message : err}`);
-			}
-			if (self._pendingHooks.length > 0) {
-				const arc = fastify.arc;
-				if (arc?.hooks) for (const hook of self._pendingHooks) arc.hooks.register({
-					resource: self.name,
-					operation: hook.operation,
-					phase: hook.phase,
-					handler: hook.handler,
-					priority: hook.priority
-				});
-			}
-			const registerRule = fastify.registerCacheInvalidationRule;
-			if (self.cache?.invalidateOn && typeof registerRule === "function") for (const [pattern, tags] of Object.entries(self.cache.invalidateOn)) registerRule({
-				pattern,
-				tags
-			});
-			await fastify.register(async (instance) => {
-				const typedInstance = instance;
-				let schemas = null;
-				const openApi = self._registryMeta?.openApiSchemas;
-				if (openApi && (!self.customSchemas || Object.keys(self.customSchemas).length === 0)) {
-					const generated = {};
-					const { createBody, updateBody, params } = openApi;
-					const safeBody = (schema) => {
-						if (schema && typeof schema === "object" && schema.type === "object") return {
-							additionalProperties: true,
-							...schema
-						};
-						return schema;
-					};
-					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 = params;
-					}
-					if (params) {
-						generated.get = { params };
-						generated.delete = { params };
-						if (!generated.update) generated.update = { params };
-						else if (!generated.update.params) generated.update.params = params;
-					}
-					if (Object.keys(generated).length > 0) schemas = generated;
-				}
-				if (self.customSchemas && Object.keys(self.customSchemas).length > 0) {
-					schemas = schemas ?? {};
-					for (const [op, customSchema] of Object.entries(self.customSchemas)) {
-						const key = op;
-						const converted = convertRouteSchema(customSchema);
-						schemas[key] = schemas[key] ? deepMergeSchemas(schemas[key], converted) : converted;
-					}
-				}
-				const listQuerySchema = self._registryMeta?.openApiSchemas?.listQuery;
-				if (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 normalizedSchema = {
-						...listQuerySchema,
-						...normalizedProps ? { properties: normalizedProps } : {},
-						additionalProperties: listQuerySchema.additionalProperties ?? true
-					};
-					schemas = schemas ?? {};
-					schemas.list = schemas.list ? deepMergeSchemas({ querystring: normalizedSchema }, schemas.list) : { querystring: normalizedSchema };
-				}
-				createCrudRouter(typedInstance, self.controller, {
-					tag: self.tag,
-					schemas: schemas ?? void 0,
-					permissions: self.permissions,
-					middlewares: self.middlewares,
-					routeGuards: self.routeGuards,
-					routes: self.routes,
-					disableDefaultRoutes: self.disableDefaultRoutes,
-					disabledRoutes: self.disabledRoutes,
-					resourceName: self.name,
-					schemaOptions: self.schemaOptions,
-					rateLimit: self.rateLimit,
-					updateMethod: self.updateMethod,
-					pipe: self.pipe,
-					fields: self.fields
-				});
-				if (self.actions && Object.keys(self.actions).length > 0) {
-					const { createActionRouter } = await import("./createActionRouter-CIKOcNA7.mjs").then((n) => n.n);
-					createActionRouter(typedInstance, {
-						...normalizeActionsToRouterConfig(self.actions, self.actionPermissions, self.tag, self.permissions, self.name, typedInstance.log),
-						resourceName: self.name,
-						fields: self.fields,
-						schemaOptions: self.schemaOptions,
-						permissions: self.permissions,
-						routeGuards: self.routeGuards,
-						pipeline: self.pipe,
-						rateLimit: self.rateLimit
-					});
-				}
-				if (self.events && Object.keys(self.events).length > 0) typedInstance.log?.debug?.(`Resource '${self.name}' defined ${Object.keys(self.events).length} events`);
-			}, { prefix: self.prefix });
-			if (hasEvents(fastify)) try {
-				await fastify.events.publish("arc.resource.registered", {
-					resource: self.name,
-					prefix: self.prefix,
-					presets: self._appliedPresets,
-					timestamp: (/* @__PURE__ */ new Date()).toISOString()
-				});
-			} catch {}
-		};
-	}
-	/**
-	* Get event definitions for registry
-	*/
-	getEvents() {
-		return Object.entries(this.events).map(([action, meta]) => ({
-			name: `${this.name}:${action}`,
-			module: this.name,
-			schema: meta.schema,
-			description: meta.description
-		}));
-	}
-	/**
-	* Get resource metadata
-	*/
-	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 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 capitalize(str) {
-	if (!str) return "";
-	return str.charAt(0).toUpperCase() + str.slice(1);
-}
-/**
-* Normalize `ActionsMap` into the `ActionRouterConfig` shape that
-* `createActionRouter` expects.
-*
-* **Permission fallback chain (fail-closed, v2.10.5):**
-* Actions mutate state, so "no permission declared" historically meant
-* "authenticated users can call it" — a silent authz hole for apps using
-* the function shorthand `actions: { send: async (id, data, req) => ... }`.
-*
-* The chain is now:
-*   1. `ActionDefinition.permissions` — explicit per-action check.
-*   2. Resource-level `actionPermissions` — explicit global-for-actions.
-*   3. Resource-level `permissions.update` — sensible default (actions mutate).
-*   4. Boot-time error — forces the author to pick an explicit gate.
-*
-* When step 3 fires, we log a warning (not a throw) so upgrading apps
-* aren't bricked by the behavior change, but the gap is visible. Apps
-* that genuinely want public actions must declare `allowPublic()`
-* explicitly — auth-by-accident is no longer a supported state.
-*/
-function normalizeActionsToRouterConfig(actions, globalAuth, 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.permissions) permissions[name] = def.permissions;
-			if (def.schema) schemas[name] = def.schema;
-		}
-		const effective = resolveActionPermission({
-			action: entry,
-			resourcePermissions,
-			resourceActionPermissions: void 0,
-			globalAuth
-		});
-		if (!explicit && !globalAuth && effective && effective === resourcePermissions?.update) {
-			permissions[name] = effective;
-			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.`);
-	}
-	return {
-		tag,
-		actions: handlers,
-		actionPermissions: permissions,
-		actionSchemas: schemas,
-		globalAuth
-	};
-}
-//#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, ResourceDefinition as n, defineResource as r, defineResourceVariants as t };