@classytic/arc 2.10.3 → 2.11.0

package/dist/core-DXdSSFW-.mjs

@@ -0,0 +1,1037 @@
+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-D3Yxnrwr.mjs";
+import { t as BaseController } from "./BaseController-JNV08qOT.mjs";
+import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-B0oKLuqI.mjs";
+import { c as buildPreHandlerChain, d as resolveRouterPluginMw, f as selectPluginMw, i as buildAuthMiddleware, l as buildRateLimitConfig, m as createFastifyHandler, o as buildCrudPermissionMw, p as createCrudHandlers, r as buildArcDecorator, s as buildPipelineHandler, u as resolvePipelineSteps, y as buildRequestScopeProjection } from "./routerShared-DeESFp4a.mjs";
+import { t as applyPresets } from "./presets-k604Lj99.mjs";
+import { t as hasEvents } from "./typeGuards-CcFZXgU7.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-C8YYU92K.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 = typeof route.preHandler === "function" ? route.preHandler(fastify) : route.preHandler ?? [];
+		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 || !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-BwaSM0No.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 };