@classytic/arc 1.1.0 → 2.1.3

package/dist/defineResource-PXzSJ15_.mjs

@@ -0,0 +1,2197 @@
+import { a as DEFAULT_SORT, d as MAX_REGEX_LENGTH, h as SYSTEM_FIELDS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-DdXFXQtN.mjs";
+import { c as isElevated, l as isMember, n as PUBLIC_SCOPE, r as getOrgId } from "./types-Beqn1Un7.mjs";
+import { getUserId } from "./types/index.mjs";
+import { i as resolveEffectiveRoles, n as applyFieldWritePermissions, t as applyFieldReadPermissions } from "./fields-CTd_CrKr.mjs";
+import { t as getUserRoles } from "./types-DelU6kln.mjs";
+import { C as ArcQueryParser, u as getDefaultCrudSchemas } from "./circuitBreaker-DYhWBW_D.mjs";
+import { t as buildQueryKey } from "./keys-DhqDRxv3.mjs";
+import { r as ForbiddenError } from "./errors-DBANPbGr.mjs";
+import { t as hasEvents } from "./typeGuards-DwxA1t_L.mjs";
+import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-Dtg0Kt9T.mjs";
+import { t as requestContext } from "./requestContext-xi6OKBL-.mjs";
+import { applyPresets, getAvailablePresets } from "./presets/index.mjs";
+
+//#region src/core/AccessControl.ts
+var AccessControl = class AccessControl {
+	tenantField;
+	idField;
+	_adapterMatchesFilter;
+	/** Patterns that indicate dangerous regex (nested quantifiers, excessive backtracking).
+	*  Uses [^...] character classes instead of .+ to avoid backtracking in the detector itself. */
+	static DANGEROUS_REGEX = /(\{[0-9]+,\}[^{]*\{[0-9]+,\})|(\+[^+]*\+)|(\*[^*]*\*)|(\.\*){3,}|\\1/;
+	/** Forbidden paths that could lead to prototype pollution */
+	static FORBIDDEN_PATHS = [
+		"__proto__",
+		"constructor",
+		"prototype"
+	];
+	constructor(config) {
+		this.tenantField = config.tenantField;
+		this.idField = config.idField;
+		this._adapterMatchesFilter = config.matchesFilter;
+	}
+	/**
+	* Build filter for single-item operations (get/update/delete)
+	* Combines ID filter with policy/org filters for proper security enforcement
+	*/
+	buildIdFilter(id, req) {
+		const filter = { [this.idField]: id };
+		const arcContext = this._meta(req);
+		const policyFilters = arcContext?._policyFilters;
+		if (policyFilters) Object.assign(filter, policyFilters);
+		const scope = arcContext?._scope;
+		const orgId = scope ? getOrgId(scope) : void 0;
+		if (orgId && !policyFilters?.[this.tenantField]) filter[this.tenantField] = orgId;
+		return filter;
+	}
+	/**
+	* Check if item matches policy filters (for get/update/delete operations)
+	* Validates that fetched item satisfies all policy constraints
+	*
+	* Delegates to adapter-provided matchesFilter if available (for SQL, etc.),
+	* otherwise falls back to built-in MongoDB-style matching.
+	*/
+	checkPolicyFilters(item, req) {
+		const policyFilters = this._meta(req)?._policyFilters;
+		if (!policyFilters) return true;
+		if (this._adapterMatchesFilter) return this._adapterMatchesFilter(item, policyFilters);
+		return this.defaultMatchesPolicyFilters(item, policyFilters);
+	}
+	/**
+	* Check org/tenant scope for a document — uses configurable tenantField.
+	*
+	* SECURITY: When org scope is active (orgId present), documents that are
+	* missing the tenant field are DENIED by default. This prevents legacy or
+	* unscoped records from leaking across tenants.
+	*/
+	checkOrgScope(item, arcContext) {
+		const scope = arcContext?._scope;
+		const orgId = scope ? getOrgId(scope) : void 0;
+		if (!item || !orgId) return true;
+		if (scope && isElevated(scope) && !orgId) return true;
+		const itemOrgId = item[this.tenantField];
+		if (!itemOrgId) return false;
+		return String(itemOrgId) === String(orgId);
+	}
+	/** Check ownership for update/delete (ownedByUser preset) */
+	checkOwnership(item, req) {
+		const ownershipCheck = this._meta(req)?._ownershipCheck;
+		if (!item || !ownershipCheck) return true;
+		const { field, userId } = ownershipCheck;
+		const itemOwnerId = item[field];
+		if (!itemOwnerId) return true;
+		return String(itemOwnerId) === String(userId);
+	}
+	/**
+	* Fetch a single document with full access control enforcement.
+	* Combines compound DB filter (ID + org + policy) with post-hoc fallback.
+	*
+	* Takes repository as a parameter to avoid coupling.
+	*
+	* Replaces the duplicated pattern in get/update/delete:
+	*   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
+	*/
+	async fetchWithAccessControl(id, req, repository, queryOptions) {
+		const compoundFilter = this.buildIdFilter(id, req);
+		const hasCompoundFilters = Object.keys(compoundFilter).length > 1;
+		try {
+			if (hasCompoundFilters && typeof repository.getOne === "function") return await repository.getOne(compoundFilter, queryOptions);
+			const item = await repository.getById(id, queryOptions);
+			if (!item) return null;
+			const arcContext = this._meta(req);
+			if (!this.checkOrgScope(item, arcContext) || !this.checkPolicyFilters(item, req)) return null;
+			return item;
+		} catch (error) {
+			if (error instanceof Error && error.message?.includes("not found")) return null;
+			throw error;
+		}
+	}
+	/** Extract typed Arc internal metadata from request */
+	_meta(req) {
+		return req.metadata;
+	}
+	/**
+	* Check if a value matches a MongoDB query operator
+	*/
+	matchesOperator(itemValue, operator, filterValue) {
+		const equalsByValue = (a, b) => String(a) === String(b);
+		switch (operator) {
+			case "$eq": return equalsByValue(itemValue, filterValue);
+			case "$ne": return !equalsByValue(itemValue, filterValue);
+			case "$gt": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue > filterValue;
+			case "$gte": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue >= filterValue;
+			case "$lt": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue < filterValue;
+			case "$lte": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue <= filterValue;
+			case "$in":
+				if (!Array.isArray(filterValue)) return false;
+				if (Array.isArray(itemValue)) return itemValue.some((v) => filterValue.some((fv) => equalsByValue(v, fv)));
+				return filterValue.some((fv) => equalsByValue(itemValue, fv));
+			case "$nin":
+				if (!Array.isArray(filterValue)) return false;
+				if (Array.isArray(itemValue)) return itemValue.every((v) => filterValue.every((fv) => !equalsByValue(v, fv)));
+				return filterValue.every((fv) => !equalsByValue(itemValue, fv));
+			case "$exists": return filterValue ? itemValue !== void 0 : itemValue === void 0;
+			case "$regex":
+				if (typeof itemValue === "string" && (typeof filterValue === "string" || filterValue instanceof RegExp)) {
+					const regex = typeof filterValue === "string" ? AccessControl.safeRegex(filterValue) : filterValue;
+					return regex !== null && regex.test(itemValue);
+				}
+				return false;
+			default: return false;
+		}
+	}
+	/**
+	* Check if item matches a single filter condition
+	* Supports nested paths (e.g., "owner.id", "metadata.status")
+	*/
+	matchesFilter(item, key, filterValue) {
+		const itemValue = key.includes(".") ? this.getNestedValue(item, key) : item[key];
+		if (filterValue && typeof filterValue === "object" && !Array.isArray(filterValue)) {
+			if (Object.keys(filterValue).some((op) => op.startsWith("$"))) {
+				for (const [operator, opValue] of Object.entries(filterValue)) if (!this.matchesOperator(itemValue, operator, opValue)) return false;
+				return true;
+			}
+		}
+		if (Array.isArray(itemValue)) return itemValue.some((v) => String(v) === String(filterValue));
+		return String(itemValue) === String(filterValue);
+	}
+	/**
+	* Built-in MongoDB-style policy filter matching.
+	* Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
+	*/
+	defaultMatchesPolicyFilters(item, policyFilters) {
+		if (policyFilters.$and && Array.isArray(policyFilters.$and)) return policyFilters.$and.every((condition) => {
+			return Object.entries(condition).every(([key, value]) => {
+				return this.matchesFilter(item, key, value);
+			});
+		});
+		if (policyFilters.$or && Array.isArray(policyFilters.$or)) return policyFilters.$or.some((condition) => {
+			return Object.entries(condition).every(([key, value]) => {
+				return this.matchesFilter(item, key, value);
+			});
+		});
+		for (const [key, value] of Object.entries(policyFilters)) {
+			if (key.startsWith("$")) continue;
+			if (!this.matchesFilter(item, key, value)) return false;
+		}
+		return true;
+	}
+	/**
+	* Get nested value from object using dot notation (e.g., "owner.id")
+	* Security: Validates path against forbidden patterns to prevent prototype pollution
+	*/
+	getNestedValue(obj, path) {
+		if (AccessControl.FORBIDDEN_PATHS.some((p) => path.toLowerCase().includes(p))) return;
+		const keys = path.split(".");
+		let value = obj;
+		for (const key of keys) {
+			if (value == null) return void 0;
+			if (AccessControl.FORBIDDEN_PATHS.includes(key.toLowerCase())) return;
+			value = value[key];
+		}
+		return value;
+	}
+	/**
+	* Create a safe RegExp from a string, guarding against ReDoS.
+	* Returns null if the pattern is invalid or dangerous.
+	*/
+	static safeRegex(pattern) {
+		if (pattern.length > MAX_REGEX_LENGTH) return null;
+		if (AccessControl.DANGEROUS_REGEX.test(pattern)) return null;
+		try {
+			return new RegExp(pattern);
+		} catch {
+			return null;
+		}
+	}
+};
+
+//#endregion
+//#region src/core/BodySanitizer.ts
+var BodySanitizer = class {
+	schemaOptions;
+	constructor(config) {
+		this.schemaOptions = config.schemaOptions;
+	}
+	/**
+	* Strip readonly and system-managed fields from request body.
+	* Prevents clients from overwriting _id, timestamps, __v, etc.
+	*
+	* Also applies field-level write permissions when the request has
+	* field permission metadata.
+	*/
+	sanitize(body, _operation, req, meta) {
+		let sanitized = { ...body };
+		for (const field of SYSTEM_FIELDS) delete sanitized[field];
+		const fieldRules = this.schemaOptions.fieldRules ?? {};
+		for (const [field, rules] of Object.entries(fieldRules)) if (rules.systemManaged || rules.readonly) delete sanitized[field];
+		if (req) {
+			const arcContext = meta ?? req.metadata;
+			const scope = arcContext?._scope ?? PUBLIC_SCOPE;
+			if (!isElevated(scope)) {
+				const fieldPerms = arcContext?.arc?.fields;
+				if (fieldPerms) {
+					const effectiveRoles = resolveEffectiveRoles(getUserRoles(req.user), isMember(scope) ? scope.orgRoles : []);
+					sanitized = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
+				}
+			}
+		}
+		return sanitized;
+	}
+};
+
+//#endregion
+//#region src/core/QueryResolver.ts
+const defaultParser = new ArcQueryParser();
+function getDefaultQueryParser() {
+	return defaultParser;
+}
+var QueryResolver = class {
+	queryParser;
+	maxLimit;
+	defaultLimit;
+	defaultSort;
+	schemaOptions;
+	tenantField;
+	constructor(config = {}) {
+		this.queryParser = config.queryParser ?? getDefaultQueryParser();
+		this.maxLimit = config.maxLimit ?? 100;
+		this.defaultLimit = config.defaultLimit ?? DEFAULT_LIMIT;
+		this.defaultSort = config.defaultSort ?? DEFAULT_SORT;
+		this.schemaOptions = config.schemaOptions ?? {};
+		this.tenantField = config.tenantField ?? DEFAULT_TENANT_FIELD;
+	}
+	/**
+	* Resolve a request into parsed query options -- ONE parse per request.
+	* Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
+	*/
+	resolve(req, meta) {
+		const parsed = this.queryParser.parse(req.query);
+		const arcContext = meta ?? req.metadata;
+		delete parsed.filters?._policyFilters;
+		const limit = Math.min(Math.max(1, parsed.limit || this.defaultLimit), this.maxLimit);
+		const page = parsed.after ? void 0 : parsed.page ? Math.max(1, parsed.page) : 1;
+		const sortString = parsed.sort ? Object.entries(parsed.sort).map(([k, v]) => v === -1 ? `-${k}` : k).join(",") : this.defaultSort;
+		const selectString = this.selectToString(parsed.select) ?? req.query?.select;
+		const filters = { ...parsed.filters };
+		const policyFilters = arcContext?._policyFilters;
+		if (policyFilters) Object.assign(filters, policyFilters);
+		const scope = arcContext?._scope;
+		const orgId = scope ? getOrgId(scope) : void 0;
+		if (orgId && !policyFilters?.[this.tenantField]) filters[this.tenantField] = orgId;
+		return {
+			page,
+			limit,
+			sort: sortString,
+			select: this.sanitizeSelect(selectString, this.schemaOptions),
+			populate: this.sanitizePopulate(parsed.populate, this.schemaOptions),
+			populateOptions: parsed.populateOptions,
+			filters,
+			search: parsed.search,
+			after: parsed.after,
+			user: req.user,
+			context: arcContext
+		};
+	}
+	/**
+	* Convert parsed select object to string format
+	* Converts { name: 1, email: 1, password: 0 } -> 'name email -password'
+	*/
+	selectToString(select) {
+		if (!select) return void 0;
+		if (typeof select === "string") return select;
+		if (Array.isArray(select)) return select.join(" ");
+		if (Object.keys(select).length === 0) return void 0;
+		return Object.entries(select).map(([field, include]) => include === 0 ? `-${field}` : field).join(" ");
+	}
+	/** Sanitize select fields */
+	sanitizeSelect(select, schemaOptions) {
+		if (!select) return void 0;
+		const blockedFields = this.getBlockedFields(schemaOptions);
+		if (blockedFields.length === 0) return select;
+		const sanitized = select.split(/[\s,]+/).filter(Boolean).filter((f) => {
+			const fieldName = f.replace(/^-/, "");
+			return !blockedFields.includes(fieldName);
+		});
+		return sanitized.length > 0 ? sanitized.join(" ") : void 0;
+	}
+	/** Sanitize populate fields */
+	sanitizePopulate(populate, schemaOptions) {
+		if (!populate) return void 0;
+		const allowedPopulate = schemaOptions.query?.allowedPopulate;
+		const requested = typeof populate === "string" ? populate.split(",").map((p) => p.trim()) : Array.isArray(populate) ? populate.map(String) : [];
+		if (requested.length === 0) return void 0;
+		if (!allowedPopulate) return requested;
+		const sanitized = requested.filter((p) => allowedPopulate.includes(p));
+		return sanitized.length > 0 ? sanitized : void 0;
+	}
+	/** Get blocked fields from schema options */
+	getBlockedFields(schemaOptions) {
+		const fieldRules = schemaOptions.fieldRules ?? {};
+		return Object.entries(fieldRules).filter(([, rules]) => rules.systemManaged || rules.hidden).map(([field]) => field);
+	}
+};
+
+//#endregion
+//#region src/core/BaseController.ts
+/**
+* Framework-agnostic base controller implementing IController.
+*
+* Composes AccessControl, BodySanitizer, and QueryResolver for clean
+* separation of concerns. CRUD methods delegate directly to these
+* composed classes — no intermediate wrapper methods.
+*
+* @template TDoc - The document type
+* @template TRepository - The repository type (defaults to RepositoryLike)
+*/
+var BaseController = class {
+	repository;
+	schemaOptions;
+	queryParser;
+	maxLimit;
+	defaultLimit;
+	defaultSort;
+	resourceName;
+	tenantField;
+	idField = DEFAULT_ID_FIELD;
+	/** Composable access control (ID filtering, policy checks, org scope, ownership) */
+	accessControl;
+	/** Composable body sanitization (field permissions, system fields) */
+	bodySanitizer;
+	/** Composable query resolution (parsing, pagination, sort, select/populate) */
+	queryResolver;
+	_matchesFilter;
+	_presetFields = {};
+	_cacheConfig;
+	constructor(repository, options = {}) {
+		this.repository = repository;
+		this.schemaOptions = options.schemaOptions ?? {};
+		this.queryParser = options.queryParser ?? getDefaultQueryParser();
+		this.maxLimit = options.maxLimit ?? 100;
+		this.defaultLimit = options.defaultLimit ?? DEFAULT_LIMIT;
+		this.defaultSort = options.defaultSort ?? DEFAULT_SORT;
+		this.resourceName = options.resourceName;
+		this.tenantField = options.tenantField ?? DEFAULT_TENANT_FIELD;
+		this.idField = options.idField ?? DEFAULT_ID_FIELD;
+		this._matchesFilter = options.matchesFilter;
+		if (options.cache) this._cacheConfig = options.cache;
+		if (options.presetFields) this._presetFields = options.presetFields;
+		this.accessControl = new AccessControl({
+			tenantField: this.tenantField,
+			idField: this.idField,
+			matchesFilter: this._matchesFilter
+		});
+		this.bodySanitizer = new BodySanitizer({ schemaOptions: this.schemaOptions });
+		this.queryResolver = new QueryResolver({
+			queryParser: this.queryParser,
+			maxLimit: this.maxLimit,
+			defaultLimit: this.defaultLimit,
+			defaultSort: this.defaultSort,
+			schemaOptions: this.schemaOptions,
+			tenantField: this.tenantField
+		});
+		this.list = this.list.bind(this);
+		this.get = this.get.bind(this);
+		this.create = this.create.bind(this);
+		this.update = this.update.bind(this);
+		this.delete = this.delete.bind(this);
+	}
+	/** Extract typed Arc internal metadata from request */
+	meta(req) {
+		return req.metadata;
+	}
+	/** Get hook system from request context (instance-scoped) */
+	getHooks(req) {
+		return this.meta(req)?.arc?.hooks ?? null;
+	}
+	/** Resolve cache config for a specific operation, merging per-op overrides */
+	resolveCacheConfig(operation) {
+		const cfg = this._cacheConfig;
+		if (!cfg || cfg.disabled) return null;
+		const opOverride = cfg[operation];
+		return {
+			staleTime: opOverride?.staleTime ?? cfg.staleTime ?? 0,
+			gcTime: opOverride?.gcTime ?? cfg.gcTime ?? 60,
+			tags: cfg.tags
+		};
+	}
+	/** Extract user/org IDs from request for cache key scoping */
+	cacheScope(req) {
+		const userId = getUserId(req.user);
+		const scope = this.meta(req)?._scope;
+		return {
+			userId,
+			orgId: scope ? getOrgId(scope) : void 0
+		};
+	}
+	async list(req) {
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const cacheConfig = this.resolveCacheConfig("list");
+		const qc = req.server?.queryCache;
+		if (cacheConfig && qc) {
+			const version = await qc.getResourceVersion(this.resourceName);
+			const { userId, orgId } = this.cacheScope(req);
+			const key = buildQueryKey(this.resourceName, "list", version, options, userId, orgId);
+			const { data, status } = await qc.get(key);
+			if (status === "fresh") return {
+				success: true,
+				data,
+				status: 200,
+				headers: { "x-cache": "HIT" }
+			};
+			if (status === "stale") {
+				setImmediate(() => {
+					this.executeListQuery(options, req).then((fresh) => qc.set(key, fresh, cacheConfig)).catch(() => {});
+				});
+				return {
+					success: true,
+					data,
+					status: 200,
+					headers: { "x-cache": "STALE" }
+				};
+			}
+			const result = await this.executeListQuery(options, req);
+			await qc.set(key, result, cacheConfig);
+			return {
+				success: true,
+				data: result,
+				status: 200,
+				headers: { "x-cache": "MISS" }
+			};
+		}
+		return {
+			success: true,
+			data: await this.executeListQuery(options, req),
+			status: 200
+		};
+	}
+	/** Execute list query through hooks (extracted for cache revalidation) */
+	async executeListQuery(options, req) {
+		const hooks = this.getHooks(req);
+		const repoGetAll = async () => this.repository.getAll(options);
+		const result = hooks && this.resourceName ? await hooks.executeAround(this.resourceName, "list", options, repoGetAll, {
+			user: req.user,
+			context: this.meta(req)
+		}) : await repoGetAll();
+		if (Array.isArray(result)) return {
+			docs: result,
+			page: 1,
+			limit: result.length,
+			total: result.length,
+			pages: 1,
+			hasNext: false,
+			hasPrev: false
+		};
+		return result;
+	}
+	async get(req) {
+		const id = req.params.id;
+		if (!id) return {
+			success: false,
+			error: "ID parameter is required",
+			status: 400
+		};
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const cacheConfig = this.resolveCacheConfig("byId");
+		const qc = req.server?.queryCache;
+		if (cacheConfig && qc) {
+			const version = await qc.getResourceVersion(this.resourceName);
+			const { userId, orgId } = this.cacheScope(req);
+			const key = buildQueryKey(this.resourceName, "get", version, {
+				id,
+				...options
+			}, userId, orgId);
+			const { data, status } = await qc.get(key);
+			if (status === "fresh") return {
+				success: true,
+				data,
+				status: 200,
+				headers: { "x-cache": "HIT" }
+			};
+			if (status === "stale") {
+				setImmediate(() => {
+					this.executeGetQuery(id, options, req).then((fresh) => {
+						if (fresh) qc.set(key, fresh, cacheConfig);
+					}).catch(() => {});
+				});
+				return {
+					success: true,
+					data,
+					status: 200,
+					headers: { "x-cache": "STALE" }
+				};
+			}
+			const item = await this.executeGetQuery(id, options, req);
+			if (!item) return {
+				success: false,
+				error: "Resource not found",
+				status: 404
+			};
+			await qc.set(key, item, cacheConfig);
+			return {
+				success: true,
+				data: item,
+				status: 200,
+				headers: { "x-cache": "MISS" }
+			};
+		}
+		try {
+			const item = await this.executeGetQuery(id, options, req);
+			if (!item) return {
+				success: false,
+				error: "Resource not found",
+				status: 404
+			};
+			return {
+				success: true,
+				data: item,
+				status: 200
+			};
+		} catch (error) {
+			if (error instanceof Error && error.message?.includes("not found")) return {
+				success: false,
+				error: "Resource not found",
+				status: 404
+			};
+			throw error;
+		}
+	}
+	/** Execute get query through hooks (extracted for cache revalidation) */
+	async executeGetQuery(id, options, req) {
+		const hooks = this.getHooks(req);
+		const fetchItem = async () => this.accessControl.fetchWithAccessControl(id, req, this.repository, options);
+		return (hooks && this.resourceName ? await hooks.executeAround(this.resourceName, "read", null, fetchItem, {
+			user: req.user,
+			context: this.meta(req)
+		}) : await fetchItem()) ?? null;
+	}
+	async create(req) {
+		const arcContext = this.meta(req);
+		const data = this.bodySanitizer.sanitize(req.body ?? {}, "create", req, arcContext);
+		const scope = arcContext?._scope;
+		const createOrgId = scope ? getOrgId(scope) : void 0;
+		if (createOrgId) data[this.tenantField] = createOrgId;
+		const userId = getUserId(req.user);
+		if (userId) data.createdBy = userId;
+		const hooks = this.getHooks(req);
+		const user = req.user;
+		let processedData = data;
+		if (hooks && this.resourceName) try {
+			processedData = await hooks.executeBefore(this.resourceName, "create", data, {
+				user,
+				context: arcContext
+			});
+		} catch (err) {
+			return {
+				success: false,
+				error: "Hook execution failed",
+				details: {
+					code: "BEFORE_CREATE_HOOK_ERROR",
+					message: err.message
+				},
+				status: 400
+			};
+		}
+		const repoCreate = async () => this.repository.create(processedData, {
+			user,
+			context: arcContext
+		});
+		let item;
+		if (hooks && this.resourceName) {
+			item = await hooks.executeAround(this.resourceName, "create", processedData, repoCreate, {
+				user,
+				context: arcContext
+			});
+			await hooks.executeAfter(this.resourceName, "create", item, {
+				user,
+				context: arcContext
+			});
+		} else item = await repoCreate();
+		return {
+			success: true,
+			data: item,
+			status: 201,
+			meta: { message: "Created successfully" }
+		};
+	}
+	async update(req) {
+		const id = req.params.id;
+		if (!id) return {
+			success: false,
+			error: "ID parameter is required",
+			status: 400
+		};
+		const arcContext = this.meta(req);
+		const data = this.bodySanitizer.sanitize(req.body ?? {}, "update", req, arcContext);
+		const user = req.user;
+		const userId = getUserId(user);
+		if (userId) data.updatedBy = userId;
+		const existing = await this.accessControl.fetchWithAccessControl(id, req, this.repository);
+		if (!existing) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		if (!this.accessControl.checkOwnership(existing, req)) return {
+			success: false,
+			error: "You do not have permission to modify this resource",
+			details: { code: "OWNERSHIP_DENIED" },
+			status: 403
+		};
+		const hooks = this.getHooks(req);
+		let processedData = data;
+		if (hooks && this.resourceName) try {
+			processedData = await hooks.executeBefore(this.resourceName, "update", data, {
+				user,
+				context: arcContext,
+				meta: {
+					id,
+					existing
+				}
+			});
+		} catch (err) {
+			return {
+				success: false,
+				error: "Hook execution failed",
+				details: {
+					code: "BEFORE_UPDATE_HOOK_ERROR",
+					message: err.message
+				},
+				status: 400
+			};
+		}
+		const repoUpdate = async () => this.repository.update(id, processedData, {
+			user,
+			context: arcContext
+		});
+		let item;
+		if (hooks && this.resourceName) {
+			item = await hooks.executeAround(this.resourceName, "update", processedData, repoUpdate, {
+				user,
+				context: arcContext,
+				meta: {
+					id,
+					existing
+				}
+			});
+			if (item) await hooks.executeAfter(this.resourceName, "update", item, {
+				user,
+				context: arcContext,
+				meta: {
+					id,
+					existing
+				}
+			});
+		} else item = await repoUpdate();
+		if (!item) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		return {
+			success: true,
+			data: item,
+			status: 200,
+			meta: { message: "Updated successfully" }
+		};
+	}
+	async delete(req) {
+		const id = req.params.id;
+		if (!id) return {
+			success: false,
+			error: "ID parameter is required",
+			status: 400
+		};
+		const arcContext = this.meta(req);
+		const user = req.user;
+		const existing = await this.accessControl.fetchWithAccessControl(id, req, this.repository);
+		if (!existing) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		if (!this.accessControl.checkOwnership(existing, req)) return {
+			success: false,
+			error: "You do not have permission to delete this resource",
+			details: { code: "OWNERSHIP_DENIED" },
+			status: 403
+		};
+		const hooks = this.getHooks(req);
+		if (hooks && this.resourceName) try {
+			await hooks.executeBefore(this.resourceName, "delete", existing, {
+				user,
+				context: arcContext,
+				meta: { id }
+			});
+		} catch (err) {
+			return {
+				success: false,
+				error: "Hook execution failed",
+				details: {
+					code: "BEFORE_DELETE_HOOK_ERROR",
+					message: err.message
+				},
+				status: 400
+			};
+		}
+		const repoDelete = async () => this.repository.delete(id, {
+			user,
+			context: arcContext
+		});
+		let result;
+		if (hooks && this.resourceName) result = await hooks.executeAround(this.resourceName, "delete", existing, repoDelete, {
+			user,
+			context: arcContext,
+			meta: { id }
+		});
+		else result = await repoDelete();
+		if (!(typeof result === "object" && result !== null ? result.success : result)) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		if (hooks && this.resourceName) await hooks.executeAfter(this.resourceName, "delete", existing, {
+			user,
+			context: arcContext,
+			meta: { id }
+		});
+		return {
+			success: true,
+			data: { message: "Deleted successfully" },
+			status: 200
+		};
+	}
+	async getBySlug(req) {
+		const repo = this.repository;
+		if (!repo.getBySlug) return {
+			success: false,
+			error: "Slug lookup not implemented",
+			status: 501
+		};
+		const slugField = this._presetFields.slugField ?? "slug";
+		const slug = req.params[slugField] ?? req.params.slug;
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const arcContext = this.meta(req);
+		const item = await repo.getBySlug(slug, options);
+		if (!item || !this.accessControl.checkOrgScope(item, arcContext)) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		return {
+			success: true,
+			data: item,
+			status: 200
+		};
+	}
+	async getDeleted(req) {
+		const repo = this.repository;
+		if (!repo.getDeleted) return {
+			success: false,
+			error: "Soft delete not implemented",
+			status: 501
+		};
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const result = await repo.getDeleted(options);
+		if (Array.isArray(result)) return {
+			success: true,
+			data: {
+				docs: result,
+				page: 1,
+				limit: result.length,
+				total: result.length,
+				pages: 1,
+				hasNext: false,
+				hasPrev: false
+			},
+			status: 200
+		};
+		return {
+			success: true,
+			data: result,
+			status: 200
+		};
+	}
+	async restore(req) {
+		const repo = this.repository;
+		if (!repo.restore) return {
+			success: false,
+			error: "Restore not implemented",
+			status: 501
+		};
+		const id = req.params.id;
+		if (!id) return {
+			success: false,
+			error: "ID parameter is required",
+			status: 400
+		};
+		const item = await repo.restore(id);
+		if (!item) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		return {
+			success: true,
+			data: item,
+			status: 200,
+			meta: { message: "Restored successfully" }
+		};
+	}
+	async getTree(req) {
+		const repo = this.repository;
+		if (!repo.getTree) return {
+			success: false,
+			error: "Tree structure not implemented",
+			status: 501
+		};
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		return {
+			success: true,
+			data: await repo.getTree(options),
+			status: 200
+		};
+	}
+	async getChildren(req) {
+		const repo = this.repository;
+		if (!repo.getChildren) return {
+			success: false,
+			error: "Tree structure not implemented",
+			status: 501
+		};
+		const parentField = this._presetFields.parentField ?? "parent";
+		const parentId = req.params[parentField] ?? req.params.parent ?? req.params.id;
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		return {
+			success: true,
+			data: await repo.getChildren(parentId, options),
+			status: 200
+		};
+	}
+};
+
+//#endregion
+//#region src/core/fastifyAdapter.ts
+/** Type guard for Mongoose-like documents with toObject() */
+function isMongooseDoc(obj) {
+	return !!obj && typeof obj === "object" && "toObject" in obj && typeof obj.toObject === "function";
+}
+/**
+* Apply field mask to a single object
+* Filters fields based on include/exclude rules
+*/
+function applyFieldMaskToObject(obj, fieldMask) {
+	if (!obj || typeof obj !== "object") return obj;
+	const plain = isMongooseDoc(obj) ? obj.toObject() : obj;
+	const { include, exclude } = fieldMask;
+	if (include && include.length > 0) {
+		const filtered = {};
+		for (const field of include) if (field in plain) filtered[field] = plain[field];
+		return filtered;
+	}
+	if (exclude && exclude.length > 0) {
+		const filtered = { ...plain };
+		for (const field of exclude) delete filtered[field];
+		return filtered;
+	}
+	return plain;
+}
+/**
+* Apply field mask to response data (handles both objects and arrays)
+*/
+function applyFieldMask(data, fieldMask) {
+	if (!fieldMask) return data;
+	if (Array.isArray(data)) return data.map((item) => applyFieldMaskToObject(item, fieldMask));
+	if (data && typeof data === "object") return applyFieldMaskToObject(data, fieldMask);
+	return data;
+}
+/**
+* Create IRequestContext from Fastify request
+*
+* Extracts framework-agnostic context from Fastify-specific request object
+*/
+function createRequestContext(req) {
+	const reqWithExtras = req;
+	const requestContext = reqWithExtras.context ?? {};
+	const srv = req.server;
+	const serverAccessor = {
+		events: srv && "events" in srv ? srv.events : void 0,
+		audit: srv && "audit" in srv ? srv.audit : void 0,
+		queryCache: srv && "queryCache" in srv ? srv.queryCache : void 0,
+		log: req.log
+	};
+	return {
+		query: reqWithExtras.query ?? {},
+		body: reqWithExtras.body ?? {},
+		params: reqWithExtras.params ?? {},
+		headers: reqWithExtras.headers,
+		user: reqWithExtras.user ? (() => {
+			const user = reqWithExtras.user;
+			const rawId = user._id ?? user.id;
+			const normalizedId = rawId ? String(rawId) : void 0;
+			return {
+				...user,
+				id: normalizedId,
+				_id: normalizedId
+			};
+		})() : null,
+		context: requestContext,
+		metadata: {
+			...reqWithExtras.context,
+			arc: reqWithExtras.arc,
+			_scope: reqWithExtras.scope,
+			_ownershipCheck: reqWithExtras._ownershipCheck,
+			_policyFilters: reqWithExtras._policyFilters ?? {},
+			log: reqWithExtras.log
+		},
+		server: serverAccessor
+	};
+}
+/**
+* Get typed auth context from an IRequestContext.
+* Use this in controller overrides to access request context.
+*
+* For org scope, use `getControllerScope(req)` instead.
+*/
+function getControllerContext(req) {
+	return req.context ?? req.metadata ?? {};
+}
+/**
+* Get request scope from an IRequestContext.
+* Returns the RequestScope set by auth adapters.
+*/
+function getControllerScope(req) {
+	return req.metadata?._scope ?? PUBLIC_SCOPE;
+}
+/**
+* Compute per-field capability metadata for the current user.
+* Only includes fields that have restrictions — unrestricted fields
+* are omitted (frontend defaults to { readable: true, writable: true }).
+*/
+function computeFieldCapabilities(fieldPerms, effectiveRoles) {
+	const caps = {};
+	for (const [field, perm] of Object.entries(fieldPerms)) {
+		let readable = true;
+		let writable = true;
+		switch (perm._type) {
+			case "hidden":
+				readable = false;
+				writable = false;
+				break;
+			case "visibleTo":
+				readable = perm.roles?.some((r) => effectiveRoles.includes(r)) ?? false;
+				break;
+			case "writableBy":
+				writable = perm.roles?.some((r) => effectiveRoles.includes(r)) ?? false;
+				break;
+		}
+		caps[field] = {
+			readable,
+			writable
+		};
+	}
+	return caps;
+}
+/**
+* Send IControllerResponse via Fastify reply
+*
+* Converts framework-agnostic response to Fastify response
+* Applies field masking if specified in request
+*/
+function sendControllerResponse(reply, response, request) {
+	const reqWithExtras = request;
+	const fieldMaskConfig = reqWithExtras?.fieldMask;
+	const arcMeta = reqWithExtras?.arc;
+	const scope = reqWithExtras?.scope ?? PUBLIC_SCOPE;
+	const fieldPerms = isElevated(scope) ? void 0 : arcMeta?.fields;
+	const effectiveRoles = fieldPerms ? resolveEffectiveRoles(getUserRoles(reqWithExtras?.user), isMember(scope) ? scope.orgRoles : []) : [];
+	const fieldCaps = fieldPerms ? computeFieldCapabilities(fieldPerms, effectiveRoles) : void 0;
+	const hasFieldRestrictions = !!(fieldMaskConfig || fieldPerms);
+	/** Apply both field mask and field-level permissions to a data item */
+	const applyPermissions = (data) => {
+		let result = fieldMaskConfig ? applyFieldMask(data, fieldMaskConfig) : data;
+		if (fieldPerms && result && typeof result === "object") if (Array.isArray(result)) result = result.map((item) => applyFieldReadPermissions(item, fieldPerms, effectiveRoles));
+		else result = applyFieldReadPermissions(result, fieldPerms, effectiveRoles);
+		return result;
+	};
+	if (response.headers) for (const [key, value] of Object.entries(response.headers)) reply.header(key, value);
+	if (response.success && response.data && typeof response.data === "object" && "docs" in response.data) {
+		const paginatedData = response.data;
+		const filteredDocs = hasFieldRestrictions ? applyPermissions(paginatedData.docs) : paginatedData.docs;
+		reply.code(response.status ?? 200).send({
+			success: true,
+			docs: filteredDocs,
+			page: paginatedData.page,
+			limit: paginatedData.limit,
+			total: paginatedData.total,
+			pages: paginatedData.pages,
+			hasNext: paginatedData.hasNext,
+			hasPrev: paginatedData.hasPrev,
+			...response.meta ?? {},
+			...fieldCaps ? { fieldPermissions: fieldCaps } : {}
+		});
+		return;
+	}
+	const filteredData = hasFieldRestrictions ? applyPermissions(response.data) : response.data;
+	reply.code(response.status ?? (response.success ? 200 : 400)).send({
+		success: response.success,
+		data: filteredData,
+		error: response.error,
+		details: response.details,
+		...response.meta ?? {},
+		...fieldCaps ? { fieldPermissions: fieldCaps } : {}
+	});
+}
+/**
+* Create Fastify route handler from IController method
+*
+* Wraps framework-agnostic controller method in Fastify-specific handler
+*
+* @example
+* ```typescript
+* const controller = new BaseController(repository);
+*
+* // Create Fastify handler
+* const listHandler = createFastifyHandler(controller.list.bind(controller));
+*
+* // Register route
+* fastify.get('/products', listHandler);
+* ```
+*/
+function createFastifyHandler(controllerMethod) {
+	return async (req, reply) => {
+		sendControllerResponse(reply, await controllerMethod(createRequestContext(req)), req);
+	};
+}
+/**
+* Create Fastify adapters for all CRUD methods of an IController
+*
+* Returns Fastify-compatible handlers for each CRUD operation
+*
+* @example
+* ```typescript
+* const controller = new BaseController(repository);
+* const handlers = createCrudHandlers(controller);
+*
+* fastify.get('/', handlers.list);
+* fastify.get('/:id', handlers.get);
+* fastify.post('/', handlers.create);
+* fastify.patch('/:id', handlers.update);
+* fastify.delete('/:id', handlers.delete);
+* ```
+*/
+function createCrudHandlers(controller) {
+	return {
+		list: createFastifyHandler(controller.list.bind(controller)),
+		get: createFastifyHandler(controller.get.bind(controller)),
+		create: createFastifyHandler(controller.create.bind(controller)),
+		update: createFastifyHandler(controller.update.bind(controller)),
+		delete: createFastifyHandler(controller.delete.bind(controller))
+	};
+}
+
+//#endregion
+//#region src/pipeline/pipe.ts
+/**
+* Compose pipeline steps into an ordered array.
+* Accepts guards, transforms, and interceptors in any order.
+*/
+function pipe(...steps) {
+	return steps;
+}
+/**
+* Check if a step applies to the given operation.
+*/
+function appliesTo(step, operation) {
+	if (!step.operations || step.operations.length === 0) return true;
+	return step.operations.includes(operation);
+}
+/**
+* Execute a pipeline against a request context.
+*
+* This is the core runtime that createCrudRouter uses to execute pipelines.
+* External usage is not needed — this is wired automatically when `pipe` is set.
+*
+* @param steps - Pipeline steps to execute
+* @param ctx - The pipeline context (extends IRequestContext)
+* @param handler - The actual controller method to call
+* @param operation - The CRUD operation name
+* @returns The controller response (possibly modified by interceptors)
+*/
+async function executePipeline(steps, ctx, handler, operation) {
+	const guards = [];
+	const transforms = [];
+	const interceptors = [];
+	for (const step of steps) {
+		if (!appliesTo(step, operation)) continue;
+		switch (step._type) {
+			case "guard":
+				guards.push(step);
+				break;
+			case "transform":
+				transforms.push(step);
+				break;
+			case "interceptor":
+				interceptors.push(step);
+				break;
+		}
+	}
+	for (const g of guards) if (!await g.handler(ctx)) throw new ForbiddenError(`Guard '${g.name}' denied access`);
+	let currentCtx = ctx;
+	for (const t of transforms) {
+		const result = await t.handler(currentCtx);
+		if (result) currentCtx = result;
+	}
+	let chain = () => handler(currentCtx);
+	for (let i = interceptors.length - 1; i >= 0; i--) {
+		const interceptor = interceptors[i];
+		const next = chain;
+		chain = () => interceptor.handler(currentCtx, next);
+	}
+	return chain();
+}
+
+//#endregion
+//#region src/core/createCrudRouter.ts
+/**
+* Build per-route rate limit config object.
+*
+* Returns a `config` object suitable for Fastify's `route()` options,
+* or `undefined` if no rate limit is configured for this resource.
+*
+* - `RateLimitConfig` object  -> apply that limit to the route
+* - `false`                   -> explicitly disable rate limiting for the route
+* - `undefined`               -> no override (inherits instance-level config)
+*/
+function buildRateLimitConfig(rateLimit) {
+	if (rateLimit === void 0) return void 0;
+	if (rateLimit === false) return { rateLimit: false };
+	return { rateLimit: {
+		max: rateLimit.max,
+		timeWindow: rateLimit.timeWindow
+	} };
+}
+/**
+* Check if a permission requires authentication
+*
+* A permission requires auth if:
+* - It exists AND
+* - It doesn't have _isPublic flag set to true
+*
+* This is used to automatically add fastify.authenticate
+* to the preHandler chain for non-public routes.
+*/
+function requiresAuthentication(permission) {
+	if (!permission) return false;
+	return !permission._isPublic;
+}
+/**
+* Build authentication middleware
+*
+* - Protected routes (requireAuth, requireRoles, etc.): uses fastify.authenticate (fails without token)
+* - Public routes (allowPublic): uses fastify.optionalAuthenticate (parses token if present, doesn't fail)
+*
+* This ensures request.user is populated on public routes when a Bearer token is sent,
+* enabling downstream middleware (e.g. multiTenant flexible filter) to apply org-scoped queries.
+*/
+function buildAuthMiddleware(fastify, permission) {
+	if (requiresAuthentication(permission)) return fastify.authenticate ?? null;
+	return fastify.optionalAuthenticate ?? null;
+}
+/**
+* Build permission middleware from PermissionCheck function
+*
+* Creates a Fastify preHandler that:
+* 1. Executes the permission check
+* 2. Returns 401 if authentication required but user absent
+* 3. Returns 403 if permission denied
+* 4. Applies query filters from PermissionResult if present
+*/
+function buildPermissionMiddleware(permissionCheck, resourceName, action) {
+	if (!permissionCheck) return null;
+	return async (request, reply) => {
+		const reqWithExtras = request;
+		const params = request.params;
+		const context = {
+			user: reqWithExtras.user ?? null,
+			request,
+			resource: resourceName,
+			action,
+			resourceId: params?.id,
+			params,
+			data: request.body
+		};
+		let result;
+		try {
+			result = await permissionCheck(context);
+		} catch (err) {
+			request.log?.warn?.({
+				err,
+				resource: resourceName,
+				action
+			}, "Permission check threw");
+			reply.code(403).send({
+				success: false,
+				error: "Permission denied"
+			});
+			return;
+		}
+		if (typeof result === "boolean") {
+			if (!result) {
+				reply.code(context.user ? 403 : 401).send({
+					success: false,
+					error: context.user ? "Permission denied" : "Authentication required"
+				});
+				return;
+			}
+			return;
+		}
+		const permResult = result;
+		if (!permResult.granted) {
+			reply.code(context.user ? 403 : 401).send({
+				success: false,
+				error: permResult.reason ?? (context.user ? "Permission denied" : "Authentication required")
+			});
+			return;
+		}
+		if (permResult.filters) reqWithExtras._policyFilters = {
+			...reqWithExtras._policyFilters ?? {},
+			...permResult.filters
+		};
+	};
+}
+/**
+* Create additional routes from preset/custom definitions
+*/
+function createAdditionalRoutes(fastify, routes, controller, options) {
+	const { tag, resourceName, arcDecorator, rateLimitConfig, cacheMw, idempotencyMw, pipeline } = options;
+	for (const route of routes) {
+		const opName = route.operation ?? (typeof route.handler === "string" ? route.handler : `${route.method.toLowerCase()}${route.path.replace(/[/:]/g, "_")}`);
+		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 (route.wrapHandler) {
+				const steps = pipeline ? resolvePipelineSteps(pipeline, opName) : [];
+				if (steps.length > 0) handler = createPipelineHandler(boundMethod, steps, opName, resourceName);
+				else handler = createFastifyHandler(boundMethod);
+			} else handler = boundMethod;
+		} else if (route.wrapHandler) {
+			const steps = pipeline ? resolvePipelineSteps(pipeline, opName) : [];
+			if (steps.length > 0) handler = createPipelineHandler(route.handler, steps, opName, resourceName);
+			else handler = 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 authMw = buildAuthMiddleware(fastify, route.permissions);
+		const permissionMw = buildPermissionMiddleware(route.permissions, resourceName, opName);
+		const customPreHandlers = typeof route.preHandler === "function" ? route.preHandler(fastify) : route.preHandler ?? [];
+		const preHandler = [
+			arcDecorator,
+			authMw,
+			permissionMw,
+			route.method === "GET" ? cacheMw : [
+				"POST",
+				"PUT",
+				"PATCH"
+			].includes(route.method) ? idempotencyMw : null,
+			...customPreHandlers
+		].filter(Boolean);
+		fastify.route({
+			method: route.method,
+			url: route.path,
+			schema,
+			preHandler: preHandler.length > 0 ? preHandler : void 0,
+			handler,
+			...rateLimitConfig ? { config: rateLimitConfig } : {}
+		});
+	}
+}
+/**
+* Resolve pipeline steps for a specific operation.
+* If pipeline is a flat array, all steps are returned.
+* If it's a per-operation map, only matching steps are returned.
+*/
+function resolvePipelineSteps(pipeline, operation) {
+	if (!pipeline) return [];
+	if (Array.isArray(pipeline)) return pipeline;
+	return pipeline[operation] ?? [];
+}
+/**
+* Create a Fastify handler that wraps a controller method with pipeline execution.
+*/
+function createPipelineHandler(controllerMethod, steps, operation, resourceName) {
+	return async (req, reply) => {
+		sendControllerResponse(reply, await executePipeline(steps, {
+			...createRequestContext(req),
+			resource: resourceName,
+			operation
+		}, (ctx) => controllerMethod(ctx), operation), req);
+	};
+}
+/**
+* Create CRUD routes for a controller
+*
+* @param fastify - Fastify instance with Arc decorators
+* @param controller - CRUD controller with handler methods
+* @param options - Router configuration
+*/
+function createCrudRouter(fastify, controller, options = {}) {
+	const { tag = "Resource", schemas = {}, permissions = {}, middlewares = {}, additionalRoutes = [], disableDefaultRoutes = false, disabledRoutes = [], resourceName = "unknown", schemaOptions, rateLimit, pipe: pipeline, fields: fieldPermissions, updateMethod = DEFAULT_UPDATE_METHOD } = options;
+	const rateLimitConfig = buildRateLimitConfig(rateLimit);
+	const cacheMw = !(fastify.hasDecorator("queryCache") && controller && typeof controller._cacheConfig !== "undefined" && controller._cacheConfig !== void 0) && fastify.hasDecorator("responseCache") ? fastify.responseCache.middleware : null;
+	const idempotencyMw = fastify.hasDecorator("idempotency") ? fastify.idempotency.middleware : null;
+	const arcMeta = Object.freeze({
+		resourceName,
+		schemaOptions,
+		permissions,
+		hooks: fastify.arc?.hooks,
+		events: fastify.events,
+		fields: fieldPermissions
+	});
+	const arcDecorator = async (req, _reply) => {
+		req.arc = arcMeta;
+		const store = requestContext.get();
+		if (store) store.resourceName = resourceName;
+	};
+	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();
+	/**
+	* Build route schema by merging: base (tags/summary) → defaults (response/querystring) → user overrides.
+	* User-provided schemas always take precedence. Defaults enable fast-json-stringify when no user schema is set.
+	*/
+	const buildSchema = (base, defaults, userSchema) => ({
+		...defaults,
+		...base,
+		...userSchema ?? {}
+	});
+	let handlers;
+	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 ctrl = controller;
+		if (pipeline) {
+			const ops = CRUD_OPERATIONS;
+			const wrapped = {};
+			for (const op of ops) {
+				const steps = resolvePipelineSteps(pipeline, op);
+				if (steps.length > 0) wrapped[op] = createPipelineHandler(ctrl[op].bind(ctrl), steps, op, resourceName);
+			}
+			handlers = {
+				...createCrudHandlers(ctrl),
+				...wrapped
+			};
+		} else handlers = createCrudHandlers(ctrl);
+	}
+	if (!disableDefaultRoutes && handlers) {
+		if (!disabledRoutes.includes("list")) {
+			const listPreHandler = [
+				arcDecorator,
+				buildAuthMiddleware(fastify, permissions.list),
+				buildPermissionMiddleware(permissions.list, resourceName, "list"),
+				cacheMw,
+				...mw.list
+			].filter(Boolean);
+			fastify.route({
+				method: "GET",
+				url: "/",
+				schema: buildSchema({
+					tags: [tag],
+					summary: `List ${tag}`
+				}, defaultSchemas.list, schemas.list),
+				preHandler: listPreHandler.length > 0 ? listPreHandler : void 0,
+				handler: handlers.list,
+				...rateLimitConfig ? { config: rateLimitConfig } : {}
+			});
+		}
+		if (!disabledRoutes.includes("get")) {
+			const getPreHandler = [
+				arcDecorator,
+				buildAuthMiddleware(fastify, permissions.get),
+				buildPermissionMiddleware(permissions.get, resourceName, "get"),
+				cacheMw,
+				...mw.get
+			].filter(Boolean);
+			fastify.route({
+				method: "GET",
+				url: "/:id",
+				schema: buildSchema({
+					tags: [tag],
+					summary: `Get ${tag} by ID`,
+					params: idParamsSchema
+				}, defaultSchemas.get, schemas.get),
+				preHandler: getPreHandler.length > 0 ? getPreHandler : void 0,
+				handler: handlers.get,
+				...rateLimitConfig ? { config: rateLimitConfig } : {}
+			});
+		}
+		if (!disabledRoutes.includes("create")) {
+			const createPreHandler = [
+				arcDecorator,
+				buildAuthMiddleware(fastify, permissions.create),
+				buildPermissionMiddleware(permissions.create, resourceName, "create"),
+				idempotencyMw,
+				...mw.create
+			].filter(Boolean);
+			fastify.route({
+				method: "POST",
+				url: "/",
+				schema: buildSchema({
+					tags: [tag],
+					summary: `Create ${tag}`
+				}, defaultSchemas.create, schemas.create),
+				preHandler: createPreHandler.length > 0 ? createPreHandler : void 0,
+				handler: handlers.create,
+				...rateLimitConfig ? { config: rateLimitConfig } : {}
+			});
+		}
+		if (!disabledRoutes.includes("update")) {
+			const updateMethods = updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod];
+			const updatePreHandler = [
+				arcDecorator,
+				buildAuthMiddleware(fastify, permissions.update),
+				buildPermissionMiddleware(permissions.update, resourceName, "update"),
+				idempotencyMw,
+				...mw.update
+			].filter(Boolean);
+			for (const method of updateMethods) fastify.route({
+				method,
+				url: "/:id",
+				schema: buildSchema({
+					tags: [tag],
+					summary: `${method === "PUT" ? "Replace" : "Update"} ${tag}`,
+					params: idParamsSchema
+				}, defaultSchemas.update, schemas.update),
+				preHandler: updatePreHandler.length > 0 ? updatePreHandler : void 0,
+				handler: handlers.update,
+				...rateLimitConfig ? { config: rateLimitConfig } : {}
+			});
+		}
+		if (!disabledRoutes.includes("delete")) {
+			const deletePreHandler = [
+				arcDecorator,
+				buildAuthMiddleware(fastify, permissions.delete),
+				buildPermissionMiddleware(permissions.delete, resourceName, "delete"),
+				...mw.delete
+			].filter(Boolean);
+			fastify.route({
+				method: "DELETE",
+				url: "/:id",
+				schema: buildSchema({
+					tags: [tag],
+					summary: `Delete ${tag}`,
+					params: idParamsSchema
+				}, defaultSchemas.delete, schemas.delete),
+				preHandler: deletePreHandler.length > 0 ? deletePreHandler : void 0,
+				handler: handlers.delete,
+				...rateLimitConfig ? { config: rateLimitConfig } : {}
+			});
+		}
+	}
+	if (additionalRoutes.length > 0) createAdditionalRoutes(fastify, additionalRoutes, controller, {
+		tag,
+		resourceName,
+		arcDecorator,
+		rateLimitConfig,
+		cacheMw,
+		idempotencyMw,
+		pipeline
+	});
+}
+/**
+* Create permission middleware from PermissionCheck
+* Useful for custom route registration
+*/
+function createPermissionMiddleware(permission, resourceName, action) {
+	return buildPermissionMiddleware(permission, resourceName, action);
+}
+
+//#endregion
+//#region src/core/createActionRouter.ts
+/**
+* Create action-based state transition endpoint
+*
+* Registers: POST /:id/action
+* Body: { action: string, ...actionData }
+*
+* @param fastify - Fastify instance
+* @param config - Action router configuration
+*/
+function createActionRouter(fastify, config) {
+	const { tag, actions, actionPermissions = {}, actionSchemas = {}, globalAuth, idempotencyService, onError } = config;
+	const actionEnum = Object.keys(actions);
+	if (actionEnum.length === 0) {
+		fastify.log.warn("[createActionRouter] No actions defined, skipping route creation");
+		return;
+	}
+	const bodyProperties = { action: {
+		type: "string",
+		enum: actionEnum,
+		description: `Action to perform: ${actionEnum.join(" | ")}`
+	} };
+	Object.entries(actionSchemas).forEach(([actionName, schema]) => {
+		if (schema && typeof schema === "object") Object.entries(schema).forEach(([propName, propSchema]) => {
+			bodyProperties[propName] = {
+				...propSchema,
+				description: `${propSchema.description || ""} (for ${actionName} action)`.trim()
+			};
+		});
+	});
+	const routeSchema = {
+		tags: tag ? [tag] : void 0,
+		summary: `Perform action (${actionEnum.join("/")})`,
+		description: buildActionDescription(actions, actionPermissions),
+		params: {
+			type: "object",
+			properties: { id: {
+				type: "string",
+				description: "Resource ID"
+			} },
+			required: ["id"]
+		},
+		body: {
+			type: "object",
+			properties: bodyProperties,
+			required: ["action"]
+		},
+		response: {
+			200: {
+				type: "object",
+				properties: {
+					success: { type: "boolean" },
+					data: { type: "object" }
+				}
+			},
+			400: {
+				type: "object",
+				properties: {
+					success: { type: "boolean" },
+					error: { type: "string" }
+				}
+			},
+			403: {
+				type: "object",
+				properties: {
+					success: { type: "boolean" },
+					error: { type: "string" }
+				}
+			}
+		}
+	};
+	const preHandler = [];
+	const hasPublicActions = Object.entries(actionPermissions).some(([, p]) => p?._isPublic) || globalAuth && globalAuth?._isPublic;
+	const hasProtectedActions = Object.entries(actionPermissions).some(([, p]) => !p?._isPublic) || globalAuth && !globalAuth?._isPublic;
+	if (hasProtectedActions && !hasPublicActions && fastify.authenticate) preHandler.push(fastify.authenticate);
+	fastify.post("/:id/action", {
+		schema: routeSchema,
+		preHandler: preHandler.length ? preHandler : void 0
+	}, async (req, reply) => {
+		const { action, ...data } = req.body;
+		const { id } = req.params;
+		const rawIdempotencyKey = req.headers["idempotency-key"];
+		const idempotencyKey = Array.isArray(rawIdempotencyKey) ? rawIdempotencyKey[0] : rawIdempotencyKey;
+		const handler = actions[action];
+		if (!handler) return reply.code(400).send({
+			success: false,
+			error: `Invalid action '${action}'. Valid actions: ${actionEnum.join(", ")}`,
+			validActions: actionEnum
+		});
+		const permissionCheck = actionPermissions[action] ?? globalAuth;
+		if (hasPublicActions && hasProtectedActions && permissionCheck) {
+			if (!permissionCheck?._isPublic && fastify.authenticate) {
+				try {
+					await fastify.authenticate(req, reply);
+				} catch {
+					if (!reply.sent) return reply.code(401).send({
+						success: false,
+						error: "Authentication required"
+					});
+					return;
+				}
+				if (reply.sent) return;
+			}
+		}
+		if (permissionCheck) {
+			const context = {
+				user: req.user ?? null,
+				request: req,
+				resource: tag ?? "action",
+				action,
+				resourceId: id,
+				params: req.params,
+				data
+			};
+			let result;
+			try {
+				result = await permissionCheck(context);
+			} catch (err) {
+				req.log?.warn?.({
+					err,
+					resource: tag ?? "action",
+					action
+				}, "Permission check threw");
+				return reply.code(403).send({
+					success: false,
+					error: "Permission denied"
+				});
+			}
+			if (typeof result === "boolean") {
+				if (!result) return reply.code(context.user ? 403 : 401).send({
+					success: false,
+					error: context.user ? `Permission denied for '${action}'` : "Authentication required"
+				});
+			} else {
+				const permResult = result;
+				if (!permResult.granted) return reply.code(context.user ? 403 : 401).send({
+					success: false,
+					error: permResult.reason ?? (context.user ? `Permission denied for '${action}'` : "Authentication required")
+				});
+			}
+		}
+		try {
+			if (idempotencyKey && idempotencyService) {
+				const user = req.user;
+				const payloadForHash = {
+					action,
+					id,
+					data,
+					userId: (user?._id)?.toString?.() || user?.id || null
+				};
+				const idempotencyResult = await idempotencyService.check(idempotencyKey, payloadForHash);
+				if (!idempotencyResult.isNew && "existingResult" in idempotencyResult) return reply.send({
+					success: true,
+					data: idempotencyResult.existingResult,
+					cached: true
+				});
+			}
+			const result = await handler(id, data, req);
+			if (idempotencyService) await idempotencyService.complete(idempotencyKey, result);
+			return reply.send({
+				success: true,
+				data: result
+			});
+		} catch (error) {
+			if (idempotencyService) await idempotencyService.fail(idempotencyKey, error);
+			if (onError) {
+				const { statusCode, error: errorMsg, code } = onError(error, action, id);
+				return reply.code(statusCode).send({
+					success: false,
+					error: errorMsg,
+					code
+				});
+			}
+			const err = error;
+			const statusCode = err.statusCode || err.status || 500;
+			const errorCode = err.code || "ACTION_FAILED";
+			if (statusCode >= 500) req.log.error({
+				err: error,
+				action,
+				id
+			}, "Action handler error");
+			return reply.code(statusCode).send({
+				success: false,
+				error: err.message || `Failed to execute '${action}' action`,
+				code: errorCode
+			});
+		}
+	});
+	fastify.log.debug({
+		actions: actionEnum,
+		tag
+	}, "[createActionRouter] Registered action endpoint: POST /:id/action");
+}
+/**
+* Build description with action details
+* Uses _roles metadata from PermissionCheck functions for OpenAPI docs
+*/
+function buildActionDescription(actions, actionPermissions) {
+	const lines = ["Unified action endpoint for state transitions.\n\n**Available actions:**"];
+	Object.keys(actions).forEach((action) => {
+		const roles = actionPermissions[action]?._roles;
+		const roleStr = roles?.length ? ` (requires: ${roles.join(" or ")})` : "";
+		lines.push(`- \`${action}\`${roleStr}`);
+	});
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/core/validateResourceConfig.ts
+/**
+* Validate a resource configuration
+*/
+function validateResourceConfig(config, options = {}) {
+	const errors = [];
+	const warnings = [];
+	if (!config.name) errors.push({
+		field: "name",
+		message: "Resource name is required",
+		suggestion: "Add a unique resource name (e.g., \"product\", \"user\")"
+	});
+	else if (!/^[a-z][a-z0-9-]*$/i.test(config.name)) errors.push({
+		field: "name",
+		message: `Invalid resource name "${config.name}"`,
+		suggestion: "Use alphanumeric characters and hyphens, starting with a letter"
+	});
+	const crudRoutes = CRUD_OPERATIONS;
+	const disabledRoutes = new Set(config.disabledRoutes ?? []);
+	const enabledCrudRoutes = crudRoutes.filter((route) => !disabledRoutes.has(route));
+	if (!config.disableDefaultRoutes && enabledCrudRoutes.length > 0) {
+		if (!config.adapter) errors.push({
+			field: "adapter",
+			message: "Data adapter is required when CRUD routes are enabled",
+			suggestion: "Provide an adapter: createMongooseAdapter({ model, repository })"
+		});
+		else if (!config.adapter.repository) errors.push({
+			field: "adapter.repository",
+			message: "Adapter must provide a repository",
+			suggestion: "Ensure your adapter returns a valid CrudRepository"
+		});
+	} else if (!config.adapter && !config.additionalRoutes?.length) warnings.push({
+		field: "config",
+		message: "Resource has no adapter and no additionalRoutes",
+		suggestion: "Provide either adapter for CRUD or additionalRoutes for custom logic"
+	});
+	if (config.controller && !options.skipControllerCheck && !config.disableDefaultRoutes) {
+		const ctrl = config.controller;
+		const requiredMethods = CRUD_OPERATIONS;
+		for (const method of requiredMethods) if (typeof ctrl[method] !== "function") errors.push({
+			field: `controller.${method}`,
+			message: `Missing required CRUD method "${method}"`,
+			suggestion: "Extend BaseController which implements IController interface"
+		});
+	}
+	if (config.controller && config.additionalRoutes) validateAdditionalRouteHandlers(config.controller, config.additionalRoutes, errors);
+	if (config.permissions) validatePermissionKeys(config, options, errors, warnings);
+	if (config.presets && !options.allowUnknownPresets) validatePresets(config.presets, errors, warnings);
+	if (config.prefix) {
+		if (!config.prefix.startsWith("/")) errors.push({
+			field: "prefix",
+			message: `Prefix must start with "/" (got "${config.prefix}")`,
+			suggestion: `Change to "/${config.prefix}"`
+		});
+		if (config.prefix.endsWith("/") && config.prefix !== "/") warnings.push({
+			field: "prefix",
+			message: `Prefix should not end with "/" (got "${config.prefix}")`,
+			suggestion: `Change to "${config.prefix.slice(0, -1)}"`
+		});
+	}
+	if (config.additionalRoutes) validateAdditionalRoutes(config.additionalRoutes, errors);
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+function validateAdditionalRouteHandlers(controller, routes, errors) {
+	const ctrl = controller;
+	for (const route of routes) if (typeof route.handler === "string") {
+		if (typeof ctrl[route.handler] !== "function") errors.push({
+			field: `additionalRoutes[${route.method} ${route.path}]`,
+			message: `Handler "${route.handler}" not found on controller`,
+			suggestion: `Add method "${route.handler}" to controller or use a function handler`
+		});
+	}
+}
+function validatePermissionKeys(config, options, errors, warnings) {
+	const validKeys = new Set([...CRUD_OPERATIONS, ...options.additionalPermissionKeys ?? []]);
+	for (const route of config.additionalRoutes ?? []) if (typeof route.handler === "string") validKeys.add(route.handler);
+	for (const preset of config.presets ?? []) {
+		const presetName = typeof preset === "string" ? preset : preset.name;
+		if (presetName === "softDelete") {
+			validKeys.add("deleted");
+			validKeys.add("restore");
+		}
+		if (presetName === "slugLookup") validKeys.add("getBySlug");
+		if (presetName === "tree") {
+			validKeys.add("tree");
+			validKeys.add("children");
+			validKeys.add("getTree");
+			validKeys.add("getChildren");
+		}
+	}
+	for (const key of Object.keys(config.permissions ?? {})) if (!validKeys.has(key)) warnings.push({
+		field: `permissions.${key}`,
+		message: `Unknown permission key "${key}"`,
+		suggestion: `Valid keys: ${Array.from(validKeys).join(", ")}`
+	});
+}
+function validatePresets(presets, errors, warnings) {
+	const availablePresets = getAvailablePresets();
+	for (const preset of presets) {
+		if (typeof preset === "object" && ("middlewares" in preset || "additionalRoutes" in preset)) continue;
+		const presetName = typeof preset === "string" ? preset : preset.name;
+		if (!availablePresets.includes(presetName)) errors.push({
+			field: "presets",
+			message: `Unknown preset "${presetName}"`,
+			suggestion: `Available presets: ${availablePresets.join(", ")}`
+		});
+		if (typeof preset === "object") validatePresetOptions(preset, warnings);
+	}
+}
+function validatePresetOptions(preset, warnings) {
+	const validOptions = {
+		slugLookup: ["slugField"],
+		tree: ["parentField"],
+		softDelete: ["deletedField"],
+		ownedByUser: ["ownerField"],
+		multiTenant: ["tenantField", "allowPublic"]
+	}[preset.name] ?? [];
+	const providedOptions = Object.keys(preset).filter((k) => k !== "name");
+	for (const opt of providedOptions) if (!validOptions.includes(opt)) warnings.push({
+		field: `presets[${preset.name}].${opt}`,
+		message: `Unknown option "${opt}" for preset "${preset.name}"`,
+		suggestion: validOptions.length > 0 ? `Valid options: ${validOptions.join(", ")}` : `Preset "${preset.name}" has no configurable options`
+	});
+}
+function validateAdditionalRoutes(routes, errors) {
+	const validMethods = [
+		"GET",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE",
+		"OPTIONS",
+		"HEAD"
+	];
+	const seenRoutes = /* @__PURE__ */ new Set();
+	for (const [i, route] of routes.entries()) {
+		if (!validMethods.includes(route.method)) errors.push({
+			field: `additionalRoutes[${i}].method`,
+			message: `Invalid HTTP method "${route.method}"`,
+			suggestion: `Valid methods: ${validMethods.join(", ")}`
+		});
+		if (!route.path) errors.push({
+			field: `additionalRoutes[${i}].path`,
+			message: "Route path is required"
+		});
+		else if (!route.path.startsWith("/")) errors.push({
+			field: `additionalRoutes[${i}].path`,
+			message: `Route path must start with "/" (got "${route.path}")`,
+			suggestion: `Change to "/${route.path}"`
+		});
+		if (!route.handler) errors.push({
+			field: `additionalRoutes[${i}].handler`,
+			message: "Route handler is required"
+		});
+		const routeKey = `${route.method} ${route.path}`;
+		if (seenRoutes.has(routeKey)) errors.push({
+			field: `additionalRoutes[${i}]`,
+			message: `Duplicate route "${routeKey}"`
+		});
+		seenRoutes.add(routeKey);
+	}
+}
+/**
+* Format validation errors for display
+*/
+function formatValidationErrors(resourceName, result) {
+	const lines = [];
+	if (result.errors.length > 0) {
+		lines.push(`Resource "${resourceName}" validation failed:`);
+		lines.push("");
+		lines.push("ERRORS:");
+		for (const err of result.errors) {
+			lines.push(`  ✗ ${err.field}: ${err.message}`);
+			if (err.suggestion) lines.push(`    → ${err.suggestion}`);
+		}
+	}
+	if (result.warnings.length > 0) {
+		if (lines.length > 0) lines.push("");
+		lines.push("WARNINGS:");
+		for (const warn of result.warnings) {
+			lines.push(`  ⚠ ${warn.field}: ${warn.message}`);
+			if (warn.suggestion) lines.push(`    → ${warn.suggestion}`);
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Validate and throw if invalid
+*/
+function assertValidConfig(config, options) {
+	const result = validateResourceConfig(config, options);
+	if (!result.valid) {
+		const errorMsg = formatValidationErrors(config.name ?? "unknown", result);
+		throw new Error(errorMsg);
+	}
+	if (result.warnings.length > 0 && process.env.NODE_ENV !== "production") console.warn(formatValidationErrors(config.name ?? "unknown", {
+		valid: true,
+		errors: [],
+		warnings: result.warnings
+	}));
+}
+
+//#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.
+*/
+function defineResource(config) {
+	if (!config.skipValidation) {
+		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.additionalRoutes ?? []) {
+			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.\nUse allowPublic() or requireAuth() from @classytic/arc/permissions.`);
+			if (typeof route.wrapHandler !== "boolean") throw new Error(`[Arc] Resource '${config.name}' route ${route.method} ${route.path}: wrapHandler is required.\nSet true for ControllerHandler (context object) or false for FastifyHandler (req, reply).`);
+		}
+	}
+	const repository = config.adapter?.repository;
+	const crudRoutes = CRUD_OPERATIONS;
+	const disabledRoutes = new Set(config.disabledRoutes ?? []);
+	const hasCrudRoutes = !config.disableDefaultRoutes && crudRoutes.some((route) => !disabledRoutes.has(route));
+	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;
+	let controller = resolvedConfig.controller;
+	if (!controller && hasCrudRoutes && repository) controller = new BaseController(repository, {
+		resourceName: resolvedConfig.name,
+		schemaOptions: resolvedConfig.schemaOptions,
+		queryParser: resolvedConfig.queryParser,
+		tenantField: resolvedConfig.tenantField,
+		idField: resolvedConfig.idField,
+		matchesFilter: config.adapter?.matchesFilter,
+		cache: resolvedConfig.cache,
+		presetFields: resolvedConfig._controllerOptions ? {
+			slugField: resolvedConfig._controllerOptions.slugField,
+			parentField: resolvedConfig._controllerOptions.parentField
+		} : void 0
+	});
+	const resource = new ResourceDefinition({
+		...resolvedConfig,
+		adapter: config.adapter,
+		controller
+	});
+	if (!config.skipValidation && controller) resource._validateControllerMethods();
+	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 (!config.skipRegistry) try {
+		let openApiSchemas = config.openApiSchemas;
+		if (!openApiSchemas && config.adapter?.generateSchemas) {
+			const generated = config.adapter.generateSchemas(config.schemaOptions);
+			if (generated) openApiSchemas = generated;
+		}
+		const queryParser = config.queryParser;
+		if (!openApiSchemas?.listQuery && queryParser?.getQuerySchema) {
+			const querySchema = queryParser.getQuerySchema();
+			if (querySchema) openApiSchemas = {
+				...openApiSchemas,
+				listQuery: querySchema
+			};
+		}
+		if (openApiSchemas) openApiSchemas = convertOpenApiSchemas(openApiSchemas);
+		resource._registryMeta = {
+			module: config.module,
+			openApiSchemas
+		};
+	} catch {}
+	return resource;
+}
+var ResourceDefinition = class {
+	name;
+	displayName;
+	tag;
+	prefix;
+	adapter;
+	controller;
+	schemaOptions;
+	customSchemas;
+	permissions;
+	additionalRoutes;
+	middlewares;
+	disableDefaultRoutes;
+	disabledRoutes;
+	events;
+	rateLimit;
+	updateMethod;
+	pipe;
+	fields;
+	cache;
+	_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.adapter = config.adapter;
+		this.controller = config.controller;
+		this.schemaOptions = config.schemaOptions ?? {};
+		this.customSchemas = config.customSchemas ?? {};
+		this.permissions = config.permissions ?? {};
+		this.additionalRoutes = config.additionalRoutes ?? [];
+		this.middlewares = config.middlewares ?? {};
+		this.disableDefaultRoutes = config.disableDefaultRoutes ?? false;
+		this.disabledRoutes = config.disabledRoutes ?? [];
+		this.events = config.events ?? {};
+		this.rateLimit = config.rateLimit;
+		this.updateMethod = config.updateMethod;
+		this.pipe = config.pipe;
+		this.fields = config.fields;
+		this.cache = config.cache;
+		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.additionalRoutes) 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;
+				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 resolvedRoutes = self.additionalRoutes;
+				createCrudRouter(typedInstance, self.controller, {
+					tag: self.tag,
+					schemas: schemas ?? void 0,
+					permissions: self.permissions,
+					middlewares: self.middlewares,
+					additionalRoutes: resolvedRoutes,
+					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.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,
+			additionalRoutes: this.additionalRoutes,
+			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);
+}
+
+//#endregion
+export { QueryResolver as _, validateResourceConfig as a, createPermissionMiddleware as c, createFastifyHandler as d, createRequestContext as f, BaseController as g, sendControllerResponse as h, formatValidationErrors as i, pipe as l, getControllerScope as m, defineResource as n, createActionRouter as o, getControllerContext as p, assertValidConfig as r, createCrudRouter as s, ResourceDefinition as t, createCrudHandlers as u, BodySanitizer as v, AccessControl as y };