@classytic/arc 2.18.3 → 2.18.5

package/dist/{utils-xAQeDyU_.mjs → utils-C6QQ9-hd.mjs}

@@ -1,9 +1,8 @@
-import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-TrJVIJl0.mjs";
+import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-gaEeMlz-.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { t as ArcError } from "./errors-j4aJm1Wg.mjs";
-import { r as getAvailablePresets } from "./presets-CF79RHEo.mjs";
+import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
+import { r as getAvailablePresets } from "./presets-BtyFwTO4.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
-import { Readable } from "node:stream";
 //#region src/utils/simpleEqualityMatcher.ts
 /**
 * `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
@@ -71,1504 +70,1522 @@ function simpleEqualityMatcher(item, filters) {
 	return true;
 }
 //#endregion
-//#region src/core/validateResourceConfig.ts
+//#region src/utils/runtime.ts
 /**
-* Resource Configuration Validator
+* Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
+* available in Bun workers, Deno, Cloudflare Workers, or edge runtimes.
+*/
+const scheduleBackground = typeof setImmediate === "function" ? (cb) => void setImmediate(cb) : (cb) => queueMicrotask(cb);
+//#endregion
+//#region src/utils/userHelpers.ts
+/**
+* Extract a user ID from a user object. Accepts `id` or `_id` — returns
+* `undefined` when neither is present. Used by arc's controllers to
+* populate `createdBy` / `updatedBy` fields and for cache scoping.
 *
-* Fail-fast validation at definition time.
-* Invalid configs throw immediately with clear, actionable errors.
+* @example
+* ```ts
+* import { getUserId } from '@classytic/arc/utils';
+* const uid = getUserId(request.user);
+* ```
+*/
+function getUserId(user) {
+	if (!user) return void 0;
+	const id = user.id ?? user._id;
+	return id ? String(id) : void 0;
+}
+//#endregion
+//#region src/utils/queryParser.ts
+/**
+* Arc Query Parser - Default URL-to-Query Parser
+*
+* Framework-agnostic query parser that converts URL parameters to query options.
+* This is Arc's built-in parser; users can swap in MongoKit's QueryParser,
+* pgkit's parser, or any custom parser implementing QueryParserInterface.
 *
 * @example
-* const result = validateResourceConfig(config);
-* if (!result.valid) {
-*   console.error(formatValidationErrors(result.errors));
-* }
+* // Use Arc default parser (auto-applied if no queryParser option)
+* defineResource({ name: 'product', adapter: ... });
+*
+* // Use MongoKit's QueryParser (recommended for MongoDB - has $lookup, aggregations, etc.)
+* import { QueryParser } from '@classytic/mongokit';
+* defineResource({
+*   name: 'product',
+*   adapter: ...,
+*   queryParser: new QueryParser(),
+* });
+*
+* // Use custom parser for SQL databases
+* defineResource({
+*   name: 'user',
+*   adapter: ...,
+*   queryParser: new PgQueryParser(),
+* });
 */
+const log = arcLog("queryParser");
 /**
-* Validate a resource configuration
+* Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
+* Detects:
+* - Quantifiers: {n,m}
+* - Possessive quantifiers: *+, ++, ?+
+* - Nested quantifiers: (a+)+, (a*)*
+* - Backreferences: \1, \2, etc.
 */
-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 StandardRepo (see @classytic/repo-core)"
-		});
-	} else if (!config.adapter && !config.routes?.length) warnings.push({
-		field: "config",
-		message: "Resource has no adapter and no routes",
-		suggestion: "Provide either adapter for CRUD or routes 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.routes) validateRouteHandlers(config.controller, config.routes, 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.routes) {
-		validateRoutes(config.routes, errors);
-		validateRouteCrudCollisions(config, errors);
-	}
-	return {
-		valid: errors.length === 0,
-		errors,
-		warnings
-	};
-}
-function validateRouteHandlers(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: `routes[${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.routes ?? []) 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 || "routes" 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`
-	});
-}
+const DANGEROUS_REGEX_PATTERNS = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
 /**
-* Detect collisions between user-declared `routes:` entries and the
-* auto-CRUD route table that `createCrudRouter` will register.
+* Arc's default query parser
 *
-* Without this check, a custom `POST /` on the same prefix as auto-CRUD's
-* `create` boots fine through `defineResource()` and only blows up at
-* `app.register()` time with Fastify's opaque `FST_ERR_DUPLICATED_ROUTE`.
-* That error doesn't mention `disabledRoutes` and doesn't distinguish
-* "you collided with auto-CRUD" from "you collided with yourself" — so
-* the consumer has to grep arc's source to discover the fix.
+* Converts URL query parameters to a structured query format:
+* - Pagination: ?page=1&limit=20
+* - Sorting: ?sort=-createdAt,name (- prefix = descending)
+* - Filtering — TWO supported forms (both produce identical output):
+*     - Bare (default, terse):     `?status=active&price[gte]=100&price[lte]=500`
+*     - Bracket envelope:          `?filter[status]=active&filter[price][gte]=100`
+*   The envelope form matches the convention used by JSON:API / Stripe /
+*   most modern REST style guides, and is the safe choice on busy URLs
+*   that might otherwise collide with reserved meta keys (`page`, `sort`,
+*   `select`, `populate`, etc.). Operator notation (`[gte]`, `[lte]`,
+*   `[ne]`, `[in]`, ...) works inside either form.
+* - Search: ?search=keyword
+* - Populate: ?populate=author,category
+* - Field selection: ?select=name,price,status
+* - Keyset pagination: ?after=cursor_value
 *
-* We surface the fix in the error message, naming the conflicting op
-* and the literal line to add.
+* **NOTE on parser portability.** `ArcQueryParser` accepts both filter
+* forms. Other parser implementations (`@classytic/mongokit`'s
+* `QueryParser`, custom hosts-side parsers) may accept only one form —
+* MongoKit historically only accepts the bare form. If your host swaps
+* `queryParser` to a different implementation, double-check which forms
+* it understands before publishing URLs that mix the two.
 *
-* Honored config:
-*   - `disableDefaultRoutes: true` → no auto-CRUD, no collisions possible
-*   - `disabledRoutes: ['create']` → that op's path is free for custom use
-*   - `updateMethod: 'PUT' | 'both'` → update slot covers PUT/PATCH accordingly
+* For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
 */
-function validateRouteCrudCollisions(config, errors) {
-	if (config.disableDefaultRoutes) return;
-	if (!config.routes || config.routes.length === 0) return;
-	const updateMethod = config.updateMethod ?? "PATCH";
-	const updateMethods = updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod];
-	const disabled = new Set(config.disabledRoutes ?? []);
-	const crudTable = [
-		{
-			op: "list",
-			method: "GET",
-			path: "/"
-		},
-		{
-			op: "get",
-			method: "GET",
-			path: "/:id"
-		},
-		{
-			op: "create",
-			method: "POST",
-			path: "/"
-		},
-		...updateMethods.map((m) => ({
-			op: "update",
-			method: m,
-			path: "/:id"
-		})),
-		{
-			op: "delete",
-			method: "DELETE",
-			path: "/:id"
-		}
-	];
-	for (const [i, route] of config.routes.entries()) {
-		if (!route.method || !route.path) continue;
-		for (const crud of crudTable) {
-			if (disabled.has(crud.op)) continue;
-			if (route.method !== crud.method || route.path !== crud.path) continue;
-			errors.push({
-				field: `routes[${i}]`,
-				message: `Route ${route.method} ${route.path} collides with auto-CRUD "${crud.op}"`,
-				suggestion: `Add \`disabledRoutes: ['${crud.op}']\` to suppress the auto-CRUD route, or move your custom handler to a different path. Set \`disableDefaultRoutes: true\` to disable all auto-CRUD on this resource.`
-			});
+var ArcQueryParser = class {
+	maxLimit;
+	defaultLimit;
+	maxRegexLength;
+	maxSearchLength;
+	maxFilterDepth;
+	_allowedFilterFields;
+	_allowedSortFields;
+	_allowedOperators;
+	/** Allowed filter fields (used by MCP for auto-derive) */
+	allowedFilterFields;
+	/** Allowed sort fields (used by MCP for sort descriptions) */
+	allowedSortFields;
+	/** Allowed operators (used by MCP for operator descriptions) */
+	allowedOperators;
+	/** Supported filter operators */
+	operators = {
+		eq: "$eq",
+		ne: "$ne",
+		gt: "$gt",
+		gte: "$gte",
+		lt: "$lt",
+		lte: "$lte",
+		in: "$in",
+		nin: "$nin",
+		like: "$regex",
+		contains: "$regex",
+		regex: "$regex",
+		exists: "$exists"
+	};
+	constructor(options = {}) {
+		this.maxLimit = options.maxLimit ?? 1e3;
+		this.defaultLimit = options.defaultLimit ?? 20;
+		this.maxRegexLength = options.maxRegexLength ?? 200;
+		this.maxSearchLength = options.maxSearchLength ?? 200;
+		this.maxFilterDepth = options.maxFilterDepth ?? 10;
+		if (options.allowedFilterFields) {
+			this._allowedFilterFields = new Set(options.allowedFilterFields);
+			this.allowedFilterFields = options.allowedFilterFields;
 		}
-	}
-}
-function validateRoutes(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: `routes[${i}].method`,
-			message: `Invalid HTTP method "${route.method}"`,
-			suggestion: `Valid methods: ${validMethods.join(", ")}`
-		});
-		if (!route.path) errors.push({
-			field: `routes[${i}].path`,
-			message: "Route path is required"
-		});
-		else if (!route.path.startsWith("/")) errors.push({
-			field: `routes[${i}].path`,
-			message: `Route path must start with "/" (got "${route.path}")`,
-			suggestion: `Change to "/${route.path}"`
-		});
-		const routeWithRefs = route;
-		if (!route.handler && typeof routeWithRefs.controllerMethod !== "function") errors.push({
-			field: `routes[${i}].handler`,
-			message: "Route must declare either `handler` (string / function) or `controllerMethod`",
-			suggestion: "Prefer `controllerMethod: (c: MyController) => c.method` for typed handler refs."
-		});
-		const routeKey = `${route.method} ${route.path}`;
-		if (seenRoutes.has(routeKey)) errors.push({
-			field: `routes[${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 (options.allowedSortFields) {
+			this._allowedSortFields = new Set(options.allowedSortFields);
+			this.allowedSortFields = options.allowedSortFields;
 		}
-	}
-	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}`);
+		if (options.allowedOperators) {
+			this._allowedOperators = new Set(options.allowedOperators);
+			this.allowedOperators = options.allowedOperators;
 		}
 	}
-	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);
+	/**
+	* Parse URL query parameters into structured query options
+	*/
+	parse(query) {
+		const q = query ?? {};
+		const page = this.parseNumber(q.page, 1);
+		const limit = Math.min(this.parseNumber(q.limit, this.defaultLimit), this.maxLimit);
+		const after = this.parseString(q.after ?? q.cursor);
+		const sort = this.parseSort(q.sort);
+		const { populate, populateOptions } = this.parsePopulate(q.populate);
+		const search = this.parseSearch(q.search);
+		const select = this.parseSelect(q.select);
+		return {
+			filters: this.parseFilters(q),
+			limit,
+			sort,
+			populate,
+			populateOptions,
+			search,
+			page: after ? void 0 : page,
+			after,
+			select
+		};
 	}
-}
-//#endregion
-//#region src/utils/circuitBreaker.ts
-/**
-* Circuit Breaker Pattern
-*
-* Wraps external service calls with failure protection.
-* Prevents cascading failures by "opening" the circuit when
-* a service is failing, allowing it time to recover.
-*
-* States:
-* - CLOSED: Normal operation, requests pass through
-* - OPEN: Too many failures, all requests fail fast
-* - HALF_OPEN: Testing if service recovered, limited requests
-*
-* @example
-* import { CircuitBreaker } from '@classytic/arc/utils';
-*
-* const paymentBreaker = new CircuitBreaker(async (amount) => {
-*   return await stripe.charges.create({ amount });
-* }, {
-*   failureThreshold: 5,
-*   resetTimeout: 30000,
-*   timeout: 5000,
-* });
-*
-* try {
-*   const result = await paymentBreaker.call(100);
-* } catch (error) {
-*   // Handle failure or circuit open
-* }
-*/
-const CircuitState = {
-	CLOSED: "CLOSED",
-	OPEN: "OPEN",
-	HALF_OPEN: "HALF_OPEN"
-};
-var CircuitBreakerError = class extends Error {
-	state;
-	constructor(message, state) {
-		super(message);
-		this.name = "CircuitBreakerError";
-		this.state = state;
+	parseNumber(value, defaultValue) {
+		if (value === void 0 || value === null) return defaultValue;
+		const num = parseInt(String(value), 10);
+		return Number.isNaN(num) ? defaultValue : Math.max(1, num);
 	}
-};
-var CircuitBreaker = class {
-	state = CircuitState.CLOSED;
-	failures = 0;
-	successes = 0;
-	totalCalls = 0;
-	nextAttempt = 0;
-	lastCallAt = null;
-	openedAt = null;
-	failureThreshold;
-	resetTimeout;
-	timeout;
-	successThreshold;
-	fallback;
-	onStateChange;
-	onError;
-	name;
-	fn;
-	constructor(fn, options = {}) {
-		this.fn = fn;
-		this.failureThreshold = options.failureThreshold ?? 5;
-		this.resetTimeout = options.resetTimeout ?? 6e4;
-		this.timeout = options.timeout ?? 1e4;
-		this.successThreshold = options.successThreshold ?? 1;
-		this.fallback = options.fallback;
-		this.onStateChange = options.onStateChange;
-		this.onError = options.onError;
-		this.name = options.name ?? "CircuitBreaker";
+	parseString(value) {
+		if (value === void 0 || value === null) return void 0;
+		const str = String(value).trim();
+		return str.length > 0 ? str : void 0;
 	}
 	/**
-	* Call the wrapped function with circuit breaker protection
+	* Parse populate parameter — handles both simple string and bracket notation.
+	*
+	* Simple: ?populate=author,category → { populate: 'author,category' }
+	* Bracket: ?populate[author][select]=name,email → { populateOptions: [{ path: 'author', select: 'name email' }] }
 	*/
-	async call(...args) {
-		this.totalCalls++;
-		this.lastCallAt = Date.now();
-		if (this.state === CircuitState.OPEN) {
-			if (Date.now() < this.nextAttempt) {
-				const error = new CircuitBreakerError(`Circuit breaker is OPEN for ${this.name}`, CircuitState.OPEN);
-				if (this.fallback) return this.fallback(...args);
-				throw error;
-			}
-			this.setState(CircuitState.HALF_OPEN);
+	parsePopulate(value) {
+		if (value === void 0 || value === null) return {};
+		if (typeof value === "string") {
+			const trimmed = value.trim();
+			return trimmed.length > 0 ? { populate: trimmed } : {};
 		}
-		try {
-			const result = await this.executeWithTimeout(args);
-			this.onSuccess();
-			return result;
-		} catch (err) {
-			this.onFailure(err instanceof Error ? err : new Error(String(err)));
-			throw err;
-		}
-	}
-	/**
-	* Execute function with timeout
-	*/
-	async executeWithTimeout(args) {
-		return new Promise((resolve, reject) => {
-			const timeoutId = setTimeout(() => {
-				reject(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
-			}, this.timeout);
-			this.fn(...args).then((result) => {
-				clearTimeout(timeoutId);
-				resolve(result);
-			}).catch((error) => {
-				clearTimeout(timeoutId);
-				reject(error);
-			});
-		});
-	}
-	/**
-	* Handle successful call
-	*/
-	onSuccess() {
-		this.failures = 0;
-		this.successes++;
-		if (this.state === CircuitState.HALF_OPEN) {
-			if (this.successes >= this.successThreshold) {
-				this.setState(CircuitState.CLOSED);
-				this.successes = 0;
+		if (typeof value === "object" && !Array.isArray(value)) {
+			const obj = value;
+			const keys = Object.keys(obj);
+			if (keys.length === 0) return {};
+			const options = [];
+			for (const path of keys) {
+				if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(path)) continue;
+				const config = obj[path];
+				if (typeof config === "object" && config !== null && !Array.isArray(config)) {
+					const cfg = config;
+					const option = { path };
+					if (typeof cfg.select === "string") option.select = cfg.select.split(",").map((s) => s.trim()).filter(Boolean).join(" ");
+					if (typeof cfg.match === "object" && cfg.match !== null) option.match = cfg.match;
+					options.push(option);
+				} else options.push({ path });
 			}
+			return options.length > 0 ? { populateOptions: options } : {};
 		}
+		return {};
 	}
-	/**
-	* Handle failed call
-	*/
-	onFailure(error) {
-		this.failures++;
-		this.successes = 0;
-		if (this.onError) this.onError(error);
-		if (this.state === CircuitState.HALF_OPEN || this.failures >= this.failureThreshold) {
-			this.setState(CircuitState.OPEN);
-			this.nextAttempt = Date.now() + this.resetTimeout;
-			this.openedAt = Date.now();
+	parseSort(value) {
+		if (!value) return void 0;
+		const sortStr = String(value);
+		const result = {};
+		for (const field of sortStr.split(",")) {
+			const trimmed = field.trim();
+			if (!trimmed) continue;
+			if (!/^-?[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed)) continue;
+			const fieldName = trimmed.startsWith("-") ? trimmed.slice(1) : trimmed;
+			if (this._allowedSortFields && !this._allowedSortFields.has(fieldName)) continue;
+			if (trimmed.startsWith("-")) result[fieldName] = -1;
+			else result[fieldName] = 1;
 		}
+		return Object.keys(result).length > 0 ? result : void 0;
 	}
-	/**
-	* Change circuit state
-	*/
-	setState(newState) {
-		const oldState = this.state;
-		if (oldState !== newState) {
-			this.state = newState;
-			if (this.onStateChange) this.onStateChange(oldState, newState);
-		}
+	parseSearch(value) {
+		if (!value) return void 0;
+		const search = String(value).trim();
+		if (search.length === 0) return void 0;
+		if (search.length > this.maxSearchLength) return search.slice(0, this.maxSearchLength);
+		return search;
 	}
-	/**
-	* Manually open the circuit
-	*/
-	open() {
-		this.setState(CircuitState.OPEN);
-		this.nextAttempt = Date.now() + this.resetTimeout;
-		this.openedAt = Date.now();
+	parseSelect(value) {
+		if (!value) return void 0;
+		const selectStr = String(value);
+		const result = {};
+		for (const field of selectStr.split(",")) {
+			const trimmed = field.trim();
+			if (!trimmed) continue;
+			if (!/^-?[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed)) continue;
+			if (trimmed.startsWith("-")) result[trimmed.slice(1)] = 0;
+			else result[trimmed] = 1;
+		}
+		return Object.keys(result).length > 0 ? result : void 0;
 	}
 	/**
-	* Manually close the circuit
+	* Check if a value exceeds the maximum nesting depth.
+	* Prevents filter bombs where deeply nested objects consume excessive memory/CPU.
 	*/
-	close() {
-		this.failures = 0;
-		this.successes = 0;
-		this.setState(CircuitState.CLOSED);
-		this.openedAt = null;
+	exceedsDepth(obj, currentDepth = 0) {
+		if (currentDepth > this.maxFilterDepth) return true;
+		if (obj === null || obj === void 0) return false;
+		if (Array.isArray(obj)) return obj.some((v) => this.exceedsDepth(v, currentDepth));
+		if (typeof obj !== "object") return false;
+		return Object.values(obj).some((v) => this.exceedsDepth(v, currentDepth + 1));
 	}
 	/**
-	* Get current statistics
+	* Parse all filter entries from the query, supporting BOTH the bare
+	* top-level form and the bracket-wrapped `filter[...]` envelope.
+	*
+	* Two equivalent ways to express the same query:
+	*   - Bare (legacy, arc default): `?status=active&price[gte]=40`
+	*   - Bracket envelope (REST convention): `?filter[status]=active&filter[price][gte]=40`
+	*
+	* Both forms parse to the same `filters: { status: 'active', price: { $gte: 40 } }`.
+	* The envelope form mirrors the convention used by most REST API style
+	* guides (JSON:API, Stripe API, etc.) and disambiguates filter fields
+	* from reserved meta params on busy URLs — a query string with a field
+	* literally named `page` or `sort` can't collide with the framework's
+	* meta keys when wrapped under `filter[...]`. The bare form stays as
+	* the default since it's the shortest path for simple queries; expect
+	* it to remain supported indefinitely.
+	*
+	* Precedence when the same key appears in both forms:
+	*   `?status=closed&filter[status]=active` → bare wins (`status: closed`).
+	* Mixing should be rare; the deterministic rule avoids silent surprises.
 	*/
-	getStats() {
-		return {
-			name: this.name,
-			state: this.state,
-			failures: this.failures,
-			successes: this.successes,
-			totalCalls: this.totalCalls,
-			openedAt: this.openedAt,
-			lastCallAt: this.lastCallAt
-		};
+	parseFilters(query) {
+		const filters = {};
+		const envelope = query.filter;
+		if (typeof envelope === "object" && envelope !== null && !Array.isArray(envelope)) for (const [key, value] of Object.entries(envelope)) this.applyFilterEntry(filters, key, value);
+		for (const [key, value] of Object.entries(query)) {
+			if (RESERVED_QUERY_PARAMS.has(key)) continue;
+			this.applyFilterEntry(filters, key, value);
+		}
+		return filters;
 	}
 	/**
-	* Get current state
+	* Apply one filter entry — used by both the bracket-envelope branch and
+	* the bare top-level branch of `parseFilters`. Centralising the field-
+	* validation + operator-conversion logic keeps the two forms in
+	* lockstep; a future regex/security tweak only changes one place.
 	*/
-	getState() {
-		return this.state;
+	applyFilterEntry(filters, key, value) {
+		if (value === void 0 || value === null) return;
+		if (!/^[a-zA-Z_][a-zA-Z0-9_.]*(?:\[[a-z]+\])?$/.test(key)) return;
+		const bareKey = key.replace(/\[[a-z]+\]$/, "");
+		if (this._allowedFilterFields && !this._allowedFilterFields.has(bareKey)) return;
+		if (this.exceedsDepth(value)) return;
+		if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+			const operatorObj = value;
+			const operatorKeys = Object.keys(operatorObj);
+			const allOperators = operatorKeys.every((op) => this.operators[op] && (!this._allowedOperators || this._allowedOperators.has(op)));
+			const allKnownOperators = operatorKeys.every((op) => this.operators[op]);
+			if (allOperators && operatorKeys.length > 0) {
+				const mongoFilters = {};
+				let needsCaseInsensitive = false;
+				for (const [op, opValue] of Object.entries(operatorObj)) {
+					const mongoOp = this.operators[op];
+					if (mongoOp) {
+						mongoFilters[mongoOp] = this.parseFilterValue(opValue, op);
+						if (op === "contains" || op === "like") needsCaseInsensitive = true;
+					}
+				}
+				if (needsCaseInsensitive) mongoFilters.$options = "i";
+				filters[key] = mongoFilters;
+				return;
+			}
+			if (allKnownOperators && this._allowedOperators) return;
+		}
+		const match = key.match(/^([a-zA-Z_][a-zA-Z0-9_.]*)(?:\[([a-z]+)\])?$/);
+		if (!match) return;
+		const [, fieldName, operator] = match;
+		if (!fieldName) return;
+		if (operator && this.operators[operator] && (!this._allowedOperators || this._allowedOperators.has(operator))) {
+			const mongoOp = this.operators[operator];
+			const parsedValue = this.parseFilterValue(value, operator);
+			if (!filters[fieldName]) filters[fieldName] = {};
+			const fieldFilter = filters[fieldName];
+			fieldFilter[mongoOp] = parsedValue;
+			if (operator === "contains" || operator === "like") fieldFilter.$options = "i";
+		} else if (!operator) filters[fieldName] = this.parseFilterValue(value);
 	}
-	/**
-	* Check if circuit is open
-	*/
-	isOpen() {
-		return this.state === CircuitState.OPEN;
+	parseFilterValue(value, operator) {
+		if (operator === "in" || operator === "nin") {
+			if (Array.isArray(value)) return value.map((v) => this.coerceValue(v));
+			if (typeof value === "string" && value.includes(",")) return value.split(",").map((v) => this.coerceValue(v.trim()));
+			return [this.coerceValue(value)];
+		}
+		if (operator === "like" || operator === "contains" || operator === "regex") return this.sanitizeRegex(String(value));
+		if (operator === "exists") {
+			const str = String(value).toLowerCase();
+			return str === "true" || str === "1";
+		}
+		return this.coerceValue(value);
 	}
-	/**
-	* Check if circuit is closed
-	*/
-	isClosed() {
-		return this.state === CircuitState.CLOSED;
+	coerceValue(value) {
+		if (value === "true") return true;
+		if (value === "false") return false;
+		if (value === "null") return null;
+		if (typeof value === "string") {
+			const num = Number(value);
+			if (!Number.isNaN(num) && value.trim() !== "") return num;
+		}
+		return value;
 	}
 	/**
-	* Reset statistics
+	* Generate OpenAPI-compatible JSON Schema for query parameters.
+	* Arc's defineResource() auto-detects this method and uses it
+	* to document list endpoint query parameters in OpenAPI/Swagger.
 	*/
-	reset() {
-		this.failures = 0;
-		this.successes = 0;
-		this.totalCalls = 0;
-		this.lastCallAt = null;
-		this.openedAt = null;
-		this.setState(CircuitState.CLOSED);
-	}
-};
-/**
-* Create a circuit breaker with sensible defaults
-*
-* @example
-* const emailBreaker = createCircuitBreaker(
-*   async (to, subject, body) => sendEmail(to, subject, body),
-*   { name: 'email-service' }
-* );
-*/
-function createCircuitBreaker(fn, options) {
-	return new CircuitBreaker(fn, options);
-}
-/**
-* Circuit breaker registry for managing multiple breakers
-*/
-var CircuitBreakerRegistry = class {
-	breakers = /* @__PURE__ */ new Map();
-	/**
-	* Register a circuit breaker
-	*/
-	register(name, fn, options) {
-		const breaker = new CircuitBreaker(fn, {
-			...options,
-			name
+	getQuerySchema() {
+		const operatorLines = Object.entries(this.operators).map(([op, mongoOp]) => {
+			return `  ${op} → ${mongoOp}: ${{
+				eq: "Equal (default when no operator specified)",
+				ne: "Not equal",
+				gt: "Greater than",
+				gte: "Greater than or equal",
+				lt: "Less than",
+				lte: "Less than or equal",
+				in: "In list (comma-separated values)",
+				nin: "Not in list",
+				like: "Pattern match (case-insensitive)",
+				contains: "Contains substring (case-insensitive)",
+				regex: "Regex pattern",
+				exists: "Field exists (true/false)"
+			}[op] || op}`;
 		});
-		this.breakers.set(name, breaker);
-		return breaker;
-	}
-	/**
-	* Get a circuit breaker by name
-	*/
-	get(name) {
-		return this.breakers.get(name);
-	}
-	/**
-	* Get all breakers
-	*/
-	getAll() {
-		return this.breakers;
-	}
-	/**
-	* Get statistics for all breakers
-	*/
-	getAllStats() {
-		const stats = {};
-		for (const [name, breaker] of this.breakers.entries()) stats[name] = breaker.getStats();
-		return stats;
-	}
-	/**
-	* Reset all breakers
-	*/
-	resetAll() {
-		for (const breaker of this.breakers.values()) breaker.reset();
-	}
-	/**
-	* Open all breakers
-	*/
-	openAll() {
-		for (const breaker of this.breakers.values()) breaker.open();
+		return {
+			type: "object",
+			properties: {
+				page: {
+					type: "integer",
+					description: "Page number for offset pagination",
+					default: 1,
+					minimum: 1
+				},
+				limit: {
+					type: "integer",
+					description: "Number of items per page",
+					default: this.defaultLimit,
+					minimum: 1,
+					maximum: this.maxLimit
+				},
+				sort: {
+					type: "string",
+					description: "Sort fields (comma-separated). Prefix with - for descending. Example: -createdAt,name"
+				},
+				search: {
+					type: "string",
+					description: "Full-text search query",
+					maxLength: this.maxSearchLength
+				},
+				select: {
+					type: "string",
+					description: "Fields to include/exclude (comma-separated). Prefix with - to exclude. Example: name,email,-password"
+				},
+				populate: {
+					type: "string",
+					description: "Fields to populate/join (comma-separated). Example: author,category"
+				},
+				after: {
+					type: "string",
+					description: "Cursor value for keyset pagination"
+				},
+				_filterOperators: {
+					type: "string",
+					description: ["Available filter operators (use as field[operator]=value):", ...operatorLines].join("\n")
+				}
+			}
+		};
 	}
-	/**
-	* Close all breakers
-	*/
-	closeAll() {
-		for (const breaker of this.breakers.values()) breaker.close();
+	sanitizeRegex(pattern) {
+		const truncated = pattern.length > this.maxRegexLength;
+		let sanitized = pattern.slice(0, this.maxRegexLength);
+		if (DANGEROUS_REGEX_PATTERNS.test(sanitized)) {
+			sanitized = sanitized.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			log.warn(`regex pattern matched a ReDoS-dangerous shape and was escaped to a literal string. original="${pattern}" sanitized="${sanitized}"`);
+		} else if (truncated) log.warn(`regex pattern exceeded maxRegexLength (${this.maxRegexLength}) and was truncated. original-length=${pattern.length}`);
+		return sanitized;
 	}
 };
 /**
-* Create a new CircuitBreakerRegistry instance.
-* Use this instead of a global singleton — attach to fastify.arc or pass explicitly.
+* Create a new ArcQueryParser instance
 */
-function createCircuitBreakerRegistry() {
-	return new CircuitBreakerRegistry();
+function createQueryParser(options) {
+	return new ArcQueryParser(options);
 }
 //#endregion
-//#region src/utils/compensation.ts
+//#region src/utils/responseSchemas.ts
 /**
-* Run steps in order with automatic compensation on failure.
+* JSON Schema definitions for arc API responses.
 *
-* @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
+* Wire shape (post-2.12): no envelope. HTTP status discriminates success
+* vs error. Success-path schemas describe the data shape directly; the
+* error path uses the canonical `ErrorContract` JSON Schema imported
+* from `@classytic/repo-core/errors` — single source of truth shared
+* with every other consumer in the org.
 */
-async function withCompensation(_name, steps, initialContext, hooks) {
-	const ctx = { ...initialContext };
-	const completedSteps = [];
-	const results = {};
-	const completed = [];
-	for (const step of steps) {
-		if (step.fireAndForget) {
-			completedSteps.push(step.name);
-			step.execute(ctx).then((result) => hooks?.onStepComplete?.(step.name, result), () => {});
-			continue;
-		}
-		try {
-			const result = await step.execute(ctx);
-			completedSteps.push(step.name);
-			results[step.name] = result;
-			completed.push({
-				step,
-				result
-			});
-			hooks?.onStepComplete?.(step.name, result);
-		} catch (err) {
-			const error = err instanceof Error ? err : new Error(String(err));
-			hooks?.onStepFailed?.(step.name, error);
-			const compensationErrors = await rollback(ctx, completed, hooks);
-			return {
-				success: false,
-				completedSteps,
-				results,
-				failedStep: step.name,
-				error: error.message,
-				...compensationErrors.length > 0 ? { compensationErrors } : {}
-			};
-		}
-	}
-	return {
-		success: true,
-		completedSteps,
-		results
-	};
-}
-async function rollback(ctx, completed, hooks) {
-	const errors = [];
-	for (let i = completed.length - 1; i >= 0; i--) {
-		const entry = completed[i];
-		if (!entry?.step.compensate) continue;
-		const compensateFn = entry.step.compensate;
-		try {
-			await compensateFn(ctx, entry.result);
-			hooks?.onCompensate?.(entry.step.name);
-		} catch (err) {
-			errors.push({
-				step: entry.step.name,
-				error: err instanceof Error ? err.message : String(err)
-			});
-		}
-	}
-	return errors;
-}
-function defineCompensation(name, steps) {
-	return {
-		name,
-		execute: (initialContext, hooks) => withCompensation(name, steps, initialContext, hooks)
-	};
-}
-//#endregion
-//#region src/utils/defineErrorMapper.ts
 /**
-* Register an `ErrorMapper` with its domain-specific generic argument and
-* have it assign cleanly into `ErrorMapper[]` (no `as unknown as ErrorMapper`).
-*
-* The returned mapper is identical at runtime — `type` and `toResponse` are
-* passed through untouched. Only the declared type widens from
-* `ErrorMapper<T>` to `ErrorMapper` so the array inference works.
+* Pagination schema - matches MongoKit/Arc runtime format
 *
-* Safety: the `errorHandlerPlugin` dispatches via `error instanceof mapper.type`
-* before invoking `toResponse`, so the widened callback signature is never
-* called with a non-`T` error at runtime. This helper codifies that invariant
-* in one place.
-*/
-function defineErrorMapper(mapper) {
-	return mapper;
-}
-//#endregion
-//#region src/utils/defineGuard.ts
-/** Hidden property key for guard context storage on the request object. */
-const GUARD_STORE_KEY = "__arcGuardContext";
-/**
-* Create a typed guard. See module JSDoc for usage.
+* Runtime format (flat fields):
+* { page, limit, total, pages, hasNext, hasPrev }
 */
-function defineGuard(config) {
-	const { name, resolve } = config;
-	const preHandler = async (req, reply) => {
-		const ctx = await resolve(req, reply);
-		if (!reply.sent) {
-			const store = req[GUARD_STORE_KEY] ?? {};
-			store[name] = ctx;
-			req[GUARD_STORE_KEY] = store;
-		}
-	};
-	return {
-		preHandler,
-		name,
-		from(req) {
-			const store = req[GUARD_STORE_KEY];
-			if (!store || !(name in store)) throw new Error(`Guard '${name}' not resolved on this request. Add it to routeGuards or the route's preHandler array.`);
-			return store[name];
-		}
-	};
-}
-//#endregion
-//#region src/utils/handleRaw.ts
-/**
-* Wrap a raw Fastify handler with Arc's response shape and error handling.
-*
-* @param handler - Async function that receives `(request, reply)` and returns data.
-*   The return value is sent raw (no envelope). If it returns `undefined`,
-*   the response body is empty (HTTP status only).
-* @param statusCode - HTTP status code for successful responses (default: 200)
-*/
-function handleRaw(handler, statusCode = 200) {
-	return async (request, reply) => {
-		try {
-			const result = await handler(request, reply);
-			if (reply.sent) return;
-			if (result === void 0 || result === null) reply.code(statusCode).send();
-			else reply.code(statusCode).send(result);
-		} catch (err) {
-			if (reply.sent) return;
-			if (err instanceof ArcError) {
-				reply.code(err.statusCode).send({
-					error: err.message,
-					code: err.code,
-					...err.details ? { details: err.details } : {}
-				});
-				return;
-			}
-			const error = err;
-			const code = error.statusCode ?? error.status ?? 500;
-			reply.code(code).send({
-				error: error.message ?? "Internal server error",
-				...error.code && { code: error.code }
-			});
+const paginationSchema = {
+	type: "object",
+	properties: {
+		page: {
+			type: "integer",
+			example: 1
+		},
+		limit: {
+			type: "integer",
+			example: 20
+		},
+		total: {
+			type: "integer",
+			example: 100
+		},
+		pages: {
+			type: "integer",
+			example: 5
+		},
+		hasNext: {
+			type: "boolean",
+			example: true
+		},
+		hasPrev: {
+			type: "boolean",
+			example: false
 		}
-	};
-}
-//#endregion
-//#region src/utils/queryParser.ts
-/**
-* Arc Query Parser - Default URL-to-Query Parser
-*
-* Framework-agnostic query parser that converts URL parameters to query options.
-* This is Arc's built-in parser; users can swap in MongoKit's QueryParser,
-* pgkit's parser, or any custom parser implementing QueryParserInterface.
-*
-* @example
-* // Use Arc default parser (auto-applied if no queryParser option)
-* defineResource({ name: 'product', adapter: ... });
-*
-* // Use MongoKit's QueryParser (recommended for MongoDB - has $lookup, aggregations, etc.)
-* import { QueryParser } from '@classytic/mongokit';
-* defineResource({
-*   name: 'product',
-*   adapter: ...,
-*   queryParser: new QueryParser(),
-* });
-*
-* // Use custom parser for SQL databases
-* defineResource({
-*   name: 'user',
-*   adapter: ...,
-*   queryParser: new PgQueryParser(),
-* });
-*/
-const log = arcLog("queryParser");
-/**
-* Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
-* Detects:
-* - Quantifiers: {n,m}
-* - Possessive quantifiers: *+, ++, ?+
-* - Nested quantifiers: (a+)+, (a*)*
-* - Backreferences: \1, \2, etc.
-*/
-const DANGEROUS_REGEX_PATTERNS = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
+	},
+	required: [
+		"page",
+		"limit",
+		"total",
+		"pages",
+		"hasNext",
+		"hasPrev"
+	]
+};
 /**
-* Arc's default query parser
-*
-* Converts URL query parameters to a structured query format:
-* - Pagination: ?page=1&limit=20
-* - Sorting: ?sort=-createdAt,name (- prefix = descending)
-* - Filtering — TWO supported forms (both produce identical output):
-*     - Bare (default, terse):     `?status=active&price[gte]=100&price[lte]=500`
-*     - Bracket envelope:          `?filter[status]=active&filter[price][gte]=100`
-*   The envelope form matches the convention used by JSON:API / Stripe /
-*   most modern REST style guides, and is the safe choice on busy URLs
-*   that might otherwise collide with reserved meta keys (`page`, `sort`,
-*   `select`, `populate`, etc.). Operator notation (`[gte]`, `[lte]`,
-*   `[ne]`, `[in]`, ...) works inside either form.
-* - Search: ?search=keyword
-* - Populate: ?populate=author,category
-* - Field selection: ?select=name,price,status
-* - Keyset pagination: ?after=cursor_value
-*
-* **NOTE on parser portability.** `ArcQueryParser` accepts both filter
-* forms. Other parser implementations (`@classytic/mongokit`'s
-* `QueryParser`, custom hosts-side parsers) may accept only one form —
-* MongoKit historically only accepts the bare form. If your host swaps
-* `queryParser` to a different implementation, double-check which forms
-* it understands before publishing URLs that mix the two.
+* List response schema — full union of every wire shape `toCanonicalList`
+* can emit. Hosts who know their endpoint only ever produces one variant
+* can pin to a narrower helper:
+*   - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
+*   - `keysetListResponse(item)` — `{ method: 'keyset', data, limit, hasMore, next: string|null }`
+*   - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
+*   - `bareListResponse(item)` — `{ data }`
 *
-* For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
+* The default `listResponse(item)` is the union (`oneOf`) of all four so
+* Fastify validation accepts any canonical kit shape — pre-2.13 this only
+* modelled offset and rejected keyset/aggregate/bare lists at the
+* response-schema gate.
 */
-var ArcQueryParser = class {
-	maxLimit;
-	defaultLimit;
-	maxRegexLength;
-	maxSearchLength;
-	maxFilterDepth;
-	_allowedFilterFields;
-	_allowedSortFields;
-	_allowedOperators;
-	/** Allowed filter fields (used by MCP for auto-derive) */
-	allowedFilterFields;
-	/** Allowed sort fields (used by MCP for sort descriptions) */
-	allowedSortFields;
-	/** Allowed operators (used by MCP for operator descriptions) */
-	allowedOperators;
-	/** Supported filter operators */
-	operators = {
-		eq: "$eq",
-		ne: "$ne",
-		gt: "$gt",
-		gte: "$gte",
-		lt: "$lt",
-		lte: "$lte",
-		in: "$in",
-		nin: "$nin",
-		like: "$regex",
-		contains: "$regex",
-		regex: "$regex",
-		exists: "$exists"
+function listResponse(itemSchema) {
+	return { oneOf: [
+		offsetListResponse(itemSchema),
+		keysetListResponse(itemSchema),
+		aggregateListResponse(itemSchema),
+		bareListResponse(itemSchema)
+	] };
+}
+/** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
+function offsetListResponse(itemSchema) {
+	return {
+		type: "object",
+		properties: {
+			method: {
+				type: "string",
+				const: "offset",
+				example: "offset"
+			},
+			data: {
+				type: "array",
+				items: itemSchema
+			},
+			page: {
+				type: "integer",
+				example: 1
+			},
+			limit: {
+				type: "integer",
+				example: 20
+			},
+			total: {
+				type: "integer",
+				example: 100
+			},
+			pages: {
+				type: "integer",
+				example: 5
+			},
+			hasNext: {
+				type: "boolean",
+				example: false
+			},
+			hasPrev: {
+				type: "boolean",
+				example: false
+			}
+		},
+		required: [
+			"method",
+			"data",
+			"page",
+			"limit",
+			"total",
+			"pages",
+			"hasNext",
+			"hasPrev"
+		],
+		additionalProperties: true
 	};
-	constructor(options = {}) {
-		this.maxLimit = options.maxLimit ?? 1e3;
-		this.defaultLimit = options.defaultLimit ?? 20;
-		this.maxRegexLength = options.maxRegexLength ?? 200;
-		this.maxSearchLength = options.maxSearchLength ?? 200;
-		this.maxFilterDepth = options.maxFilterDepth ?? 10;
-		if (options.allowedFilterFields) {
-			this._allowedFilterFields = new Set(options.allowedFilterFields);
-			this.allowedFilterFields = options.allowedFilterFields;
-		}
-		if (options.allowedSortFields) {
-			this._allowedSortFields = new Set(options.allowedSortFields);
-			this.allowedSortFields = options.allowedSortFields;
-		}
-		if (options.allowedOperators) {
-			this._allowedOperators = new Set(options.allowedOperators);
-			this.allowedOperators = options.allowedOperators;
-		}
-	}
-	/**
-	* Parse URL query parameters into structured query options
-	*/
-	parse(query) {
-		const q = query ?? {};
-		const page = this.parseNumber(q.page, 1);
-		const limit = Math.min(this.parseNumber(q.limit, this.defaultLimit), this.maxLimit);
-		const after = this.parseString(q.after ?? q.cursor);
-		const sort = this.parseSort(q.sort);
-		const { populate, populateOptions } = this.parsePopulate(q.populate);
-		const search = this.parseSearch(q.search);
-		const select = this.parseSelect(q.select);
-		return {
-			filters: this.parseFilters(q),
-			limit,
-			sort,
-			populate,
-			populateOptions,
-			search,
-			page: after ? void 0 : page,
-			after,
-			select
-		};
-	}
-	parseNumber(value, defaultValue) {
-		if (value === void 0 || value === null) return defaultValue;
-		const num = parseInt(String(value), 10);
-		return Number.isNaN(num) ? defaultValue : Math.max(1, num);
-	}
-	parseString(value) {
-		if (value === void 0 || value === null) return void 0;
-		const str = String(value).trim();
-		return str.length > 0 ? str : void 0;
-	}
-	/**
-	* Parse populate parameter — handles both simple string and bracket notation.
-	*
-	* Simple: ?populate=author,category → { populate: 'author,category' }
-	* Bracket: ?populate[author][select]=name,email → { populateOptions: [{ path: 'author', select: 'name email' }] }
-	*/
-	parsePopulate(value) {
-		if (value === void 0 || value === null) return {};
-		if (typeof value === "string") {
-			const trimmed = value.trim();
-			return trimmed.length > 0 ? { populate: trimmed } : {};
-		}
-		if (typeof value === "object" && !Array.isArray(value)) {
-			const obj = value;
-			const keys = Object.keys(obj);
-			if (keys.length === 0) return {};
-			const options = [];
-			for (const path of keys) {
-				if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(path)) continue;
-				const config = obj[path];
-				if (typeof config === "object" && config !== null && !Array.isArray(config)) {
-					const cfg = config;
-					const option = { path };
-					if (typeof cfg.select === "string") option.select = cfg.select.split(",").map((s) => s.trim()).filter(Boolean).join(" ");
-					if (typeof cfg.match === "object" && cfg.match !== null) option.match = cfg.match;
-					options.push(option);
-				} else options.push({ path });
+}
+/** Keyset variant — `{ method: 'keyset', data, limit, hasMore, next: string | null }`. */
+function keysetListResponse(itemSchema) {
+	return {
+		type: "object",
+		properties: {
+			method: {
+				type: "string",
+				const: "keyset",
+				example: "keyset"
+			},
+			data: {
+				type: "array",
+				items: itemSchema
+			},
+			limit: {
+				type: "integer",
+				example: 20
+			},
+			hasMore: {
+				type: "boolean",
+				example: true
+			},
+			next: {
+				type: ["string", "null"],
+				description: "Cursor token for the next page, or null."
 			}
-			return options.length > 0 ? { populateOptions: options } : {};
-		}
-		return {};
-	}
-	parseSort(value) {
-		if (!value) return void 0;
-		const sortStr = String(value);
-		const result = {};
-		for (const field of sortStr.split(",")) {
-			const trimmed = field.trim();
-			if (!trimmed) continue;
-			if (!/^-?[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed)) continue;
-			const fieldName = trimmed.startsWith("-") ? trimmed.slice(1) : trimmed;
-			if (this._allowedSortFields && !this._allowedSortFields.has(fieldName)) continue;
-			if (trimmed.startsWith("-")) result[fieldName] = -1;
-			else result[fieldName] = 1;
+		},
+		required: [
+			"method",
+			"data",
+			"limit",
+			"hasMore",
+			"next"
+		],
+		additionalProperties: true
+	};
+}
+/** Aggregate variant — same shape as offset, discriminated by `method: 'aggregate'`. */
+function aggregateListResponse(itemSchema) {
+	return {
+		type: "object",
+		properties: {
+			method: {
+				type: "string",
+				const: "aggregate",
+				example: "aggregate"
+			},
+			data: {
+				type: "array",
+				items: itemSchema
+			},
+			page: { type: "integer" },
+			limit: { type: "integer" },
+			total: { type: "integer" },
+			pages: { type: "integer" },
+			hasNext: { type: "boolean" },
+			hasPrev: { type: "boolean" }
+		},
+		required: [
+			"method",
+			"data",
+			"page",
+			"limit",
+			"total",
+			"pages",
+			"hasNext",
+			"hasPrev"
+		],
+		additionalProperties: true
+	};
+}
+/** Bare variant — `{ data }`, no `method` discriminant. */
+function bareListResponse(itemSchema) {
+	return {
+		type: "object",
+		properties: { data: {
+			type: "array",
+			items: itemSchema
+		} },
+		required: ["data"],
+		additionalProperties: true
+	};
+}
+/** Delete response — flat shape mirroring the canonical delete envelope. */
+function deleteResponse() {
+	return {
+		type: "object",
+		properties: {
+			message: {
+				type: "string",
+				example: "Deleted successfully"
+			},
+			id: {
+				type: "string",
+				example: "507f1f77bcf86cd799439011"
+			},
+			soft: {
+				type: "boolean",
+				example: false
+			}
+		},
+		additionalProperties: true
+	};
+}
+const ERROR_DESCRIPTIONS = {
+	400: "Bad Request",
+	401: "Unauthorized",
+	403: "Forbidden",
+	404: "Not Found",
+	409: "Conflict",
+	422: "Unprocessable Entity",
+	429: "Too Many Requests",
+	500: "Internal Server Error",
+	503: "Service Unavailable"
+};
+/** Build an OpenAPI response entry for an `ErrorContract` at the given status. */
+function errorResponse(status) {
+	return {
+		description: ERROR_DESCRIPTIONS[status] ?? "Error",
+		content: { "application/json": { schema: errorContractSchema$1 } }
+	};
+}
+const responses = {
+	200: (schema) => ({
+		description: "Successful response",
+		content: { "application/json": { schema } }
+	}),
+	201: (schema) => ({
+		description: "Created successfully",
+		content: { "application/json": { schema: {
+			...schema,
+			additionalProperties: true
+		} } }
+	}),
+	400: errorResponse(400),
+	401: errorResponse(401),
+	403: errorResponse(403),
+	404: errorResponse(404),
+	409: errorResponse(409),
+	500: errorResponse(500)
+};
+const queryParams = {
+	pagination: {
+		page: {
+			type: "integer",
+			minimum: 1,
+			default: 1,
+			description: "Page number"
+		},
+		limit: {
+			type: "integer",
+			minimum: 1,
+			maximum: 100,
+			default: 20,
+			description: "Items per page"
 		}
-		return Object.keys(result).length > 0 ? result : void 0;
-	}
-	parseSearch(value) {
-		if (!value) return void 0;
-		const search = String(value).trim();
-		if (search.length === 0) return void 0;
-		if (search.length > this.maxSearchLength) return search.slice(0, this.maxSearchLength);
-		return search;
-	}
-	parseSelect(value) {
-		if (!value) return void 0;
-		const selectStr = String(value);
-		const result = {};
-		for (const field of selectStr.split(",")) {
-			const trimmed = field.trim();
-			if (!trimmed) continue;
-			if (!/^-?[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed)) continue;
-			if (trimmed.startsWith("-")) result[trimmed.slice(1)] = 0;
-			else result[trimmed] = 1;
+	},
+	sorting: { sort: {
+		type: "string",
+		description: "Sort field (prefix with - for descending)",
+		example: "-createdAt"
+	} },
+	filtering: {
+		select: {
+			description: "Fields to include (space-separated or object)",
+			example: "name email createdAt"
+		},
+		populate: {
+			description: "Relations to populate (comma-separated string or bracket-notation object)",
+			example: "author,category"
 		}
-		return Object.keys(result).length > 0 ? result : void 0;
-	}
-	/**
-	* Check if a value exceeds the maximum nesting depth.
-	* Prevents filter bombs where deeply nested objects consume excessive memory/CPU.
-	*/
-	exceedsDepth(obj, currentDepth = 0) {
-		if (currentDepth > this.maxFilterDepth) return true;
-		if (obj === null || obj === void 0) return false;
-		if (Array.isArray(obj)) return obj.some((v) => this.exceedsDepth(v, currentDepth));
-		if (typeof obj !== "object") return false;
-		return Object.values(obj).some((v) => this.exceedsDepth(v, currentDepth + 1));
-	}
-	/**
-	* Parse all filter entries from the query, supporting BOTH the bare
-	* top-level form and the bracket-wrapped `filter[...]` envelope.
-	*
-	* Two equivalent ways to express the same query:
-	*   - Bare (legacy, arc default): `?status=active&price[gte]=40`
-	*   - Bracket envelope (REST convention): `?filter[status]=active&filter[price][gte]=40`
-	*
-	* Both forms parse to the same `filters: { status: 'active', price: { $gte: 40 } }`.
-	* The envelope form mirrors the convention used by most REST API style
-	* guides (JSON:API, Stripe API, etc.) and disambiguates filter fields
-	* from reserved meta params on busy URLs — a query string with a field
-	* literally named `page` or `sort` can't collide with the framework's
-	* meta keys when wrapped under `filter[...]`. The bare form stays as
-	* the default since it's the shortest path for simple queries; expect
-	* it to remain supported indefinitely.
-	*
-	* Precedence when the same key appears in both forms:
-	*   `?status=closed&filter[status]=active` → bare wins (`status: closed`).
-	* Mixing should be rare; the deterministic rule avoids silent surprises.
-	*/
-	parseFilters(query) {
-		const filters = {};
-		const envelope = query.filter;
-		if (typeof envelope === "object" && envelope !== null && !Array.isArray(envelope)) for (const [key, value] of Object.entries(envelope)) this.applyFilterEntry(filters, key, value);
-		for (const [key, value] of Object.entries(query)) {
-			if (RESERVED_QUERY_PARAMS.has(key)) continue;
-			this.applyFilterEntry(filters, key, value);
-		}
-		return filters;
-	}
-	/**
-	* Apply one filter entry — used by both the bracket-envelope branch and
-	* the bare top-level branch of `parseFilters`. Centralising the field-
-	* validation + operator-conversion logic keeps the two forms in
-	* lockstep; a future regex/security tweak only changes one place.
-	*/
-	applyFilterEntry(filters, key, value) {
-		if (value === void 0 || value === null) return;
-		if (!/^[a-zA-Z_][a-zA-Z0-9_.]*(?:\[[a-z]+\])?$/.test(key)) return;
-		const bareKey = key.replace(/\[[a-z]+\]$/, "");
-		if (this._allowedFilterFields && !this._allowedFilterFields.has(bareKey)) return;
-		if (this.exceedsDepth(value)) return;
-		if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-			const operatorObj = value;
-			const operatorKeys = Object.keys(operatorObj);
-			const allOperators = operatorKeys.every((op) => this.operators[op] && (!this._allowedOperators || this._allowedOperators.has(op)));
-			const allKnownOperators = operatorKeys.every((op) => this.operators[op]);
-			if (allOperators && operatorKeys.length > 0) {
-				const mongoFilters = {};
-				let needsCaseInsensitive = false;
-				for (const [op, opValue] of Object.entries(operatorObj)) {
-					const mongoOp = this.operators[op];
-					if (mongoOp) {
-						mongoFilters[mongoOp] = this.parseFilterValue(opValue, op);
-						if (op === "contains" || op === "like") needsCaseInsensitive = true;
-					}
-				}
-				if (needsCaseInsensitive) mongoFilters.$options = "i";
-				filters[key] = mongoFilters;
-				return;
-			}
-			if (allKnownOperators && this._allowedOperators) return;
-		}
-		const match = key.match(/^([a-zA-Z_][a-zA-Z0-9_.]*)(?:\[([a-z]+)\])?$/);
-		if (!match) return;
-		const [, fieldName, operator] = match;
-		if (!fieldName) return;
-		if (operator && this.operators[operator] && (!this._allowedOperators || this._allowedOperators.has(operator))) {
-			const mongoOp = this.operators[operator];
-			const parsedValue = this.parseFilterValue(value, operator);
-			if (!filters[fieldName]) filters[fieldName] = {};
-			const fieldFilter = filters[fieldName];
-			fieldFilter[mongoOp] = parsedValue;
-			if (operator === "contains" || operator === "like") fieldFilter.$options = "i";
-		} else if (!operator) filters[fieldName] = this.parseFilterValue(value);
-	}
-	parseFilterValue(value, operator) {
-		if (operator === "in" || operator === "nin") {
-			if (Array.isArray(value)) return value.map((v) => this.coerceValue(v));
-			if (typeof value === "string" && value.includes(",")) return value.split(",").map((v) => this.coerceValue(v.trim()));
-			return [this.coerceValue(value)];
-		}
-		if (operator === "like" || operator === "contains" || operator === "regex") return this.sanitizeRegex(String(value));
-		if (operator === "exists") {
-			const str = String(value).toLowerCase();
-			return str === "true" || str === "1";
-		}
-		return this.coerceValue(value);
-	}
-	coerceValue(value) {
-		if (value === "true") return true;
-		if (value === "false") return false;
-		if (value === "null") return null;
-		if (typeof value === "string") {
-			const num = Number(value);
-			if (!Number.isNaN(num) && value.trim() !== "") return num;
-		}
-		return value;
-	}
-	/**
-	* Generate OpenAPI-compatible JSON Schema for query parameters.
-	* Arc's defineResource() auto-detects this method and uses it
-	* to document list endpoint query parameters in OpenAPI/Swagger.
-	*/
-	getQuerySchema() {
-		const operatorLines = Object.entries(this.operators).map(([op, mongoOp]) => {
-			return `  ${op} → ${mongoOp}: ${{
-				eq: "Equal (default when no operator specified)",
-				ne: "Not equal",
-				gt: "Greater than",
-				gte: "Greater than or equal",
-				lt: "Less than",
-				lte: "Less than or equal",
-				in: "In list (comma-separated values)",
-				nin: "Not in list",
-				like: "Pattern match (case-insensitive)",
-				contains: "Contains substring (case-insensitive)",
-				regex: "Regex pattern",
-				exists: "Field exists (true/false)"
-			}[op] || op}`;
-		});
-		return {
-			type: "object",
-			properties: {
-				page: {
-					type: "integer",
-					description: "Page number for offset pagination",
-					default: 1,
-					minimum: 1
-				},
-				limit: {
-					type: "integer",
-					description: "Number of items per page",
-					default: this.defaultLimit,
-					minimum: 1,
-					maximum: this.maxLimit
-				},
-				sort: {
-					type: "string",
-					description: "Sort fields (comma-separated). Prefix with - for descending. Example: -createdAt,name"
-				},
-				search: {
-					type: "string",
-					description: "Full-text search query",
-					maxLength: this.maxSearchLength
-				},
-				select: {
-					type: "string",
-					description: "Fields to include/exclude (comma-separated). Prefix with - to exclude. Example: name,email,-password"
-				},
-				populate: {
-					type: "string",
-					description: "Fields to populate/join (comma-separated). Example: author,category"
-				},
-				after: {
-					type: "string",
-					description: "Cursor value for keyset pagination"
-				},
-				_filterOperators: {
-					type: "string",
-					description: ["Available filter operators (use as field[operator]=value):", ...operatorLines].join("\n")
-				}
-			}
-		};
-	}
-	sanitizeRegex(pattern) {
-		const truncated = pattern.length > this.maxRegexLength;
-		let sanitized = pattern.slice(0, this.maxRegexLength);
-		if (DANGEROUS_REGEX_PATTERNS.test(sanitized)) {
-			sanitized = sanitized.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-			log.warn(`regex pattern matched a ReDoS-dangerous shape and was escaped to a literal string. original="${pattern}" sanitized="${sanitized}"`);
-		} else if (truncated) log.warn(`regex pattern exceeded maxRegexLength (${this.maxRegexLength}) and was truncated. original-length=${pattern.length}`);
-		return sanitized;
 	}
 };
 /**
-* Create a new ArcQueryParser instance
+* Get standard list query parameters schema
 */
-function createQueryParser(options) {
-	return new ArcQueryParser(options);
+function getListQueryParams() {
+	return {
+		type: "object",
+		properties: {
+			...queryParams.pagination,
+			...queryParams.sorting,
+			...queryParams.filtering
+		},
+		additionalProperties: true
+	};
 }
-//#endregion
-//#region src/utils/responseSchemas.ts
 /**
-* JSON Schema definitions for arc API responses.
-*
-* Wire shape (post-2.12): no envelope. HTTP status discriminates success
-* vs error. Success-path schemas describe the data shape directly; the
-* error path uses the canonical `ErrorContract` JSON Schema imported
-* from `@classytic/repo-core/errors` — single source of truth shared
-* with every other consumer in the org.
+* Generic item schema that allows any properties.
+* Used as default when no user schema is provided.
+* Enables fast-json-stringify while still passing through all fields.
 */
+const genericItemSchema = {
+	type: "object",
+	additionalProperties: true
+};
 /**
-* Pagination schema - matches MongoKit/Arc runtime format
+* Recursively strip `example` keys from a schema object.
+* The `example` keyword is OpenAPI metadata — not standard JSON Schema —
+* and triggers Ajv strict mode errors when used on routes without the
+* `keywords: ['example']` AJV config (e.g., raw Fastify without createApp).
+*/
+function stripExamples(schema) {
+	if (schema === null || typeof schema !== "object") return schema;
+	if (Array.isArray(schema)) return schema.map(stripExamples);
+	const result = {};
+	for (const [key, value] of Object.entries(schema)) {
+		if (key === "example") continue;
+		result[key] = stripExamples(value);
+	}
+	return result;
+}
+/**
+* Get default response schemas for all CRUD operations.
 *
-* Runtime format (flat fields):
-* { page, limit, total, pages, hasNext, hasPrev }
+* When routes have response schemas, Fastify compiles them with
+* fast-json-stringify for 2-3x faster serialization and prevents
+* accidental field disclosure.
+*
+* These defaults use `additionalProperties: true` so all fields pass through.
+* Override with specific schemas for full serialization performance + safety.
+*
+* Note: `example` properties are stripped from defaults so they work with
+* any Fastify instance (not just createApp which adds `keywords: ['example']`).
 */
-const paginationSchema = {
-	type: "object",
-	properties: {
-		page: {
-			type: "integer",
-			example: 1
+function getDefaultCrudSchemas() {
+	return stripExamples({
+		list: {
+			querystring: getListQueryParams(),
+			response: { 200: listResponse(genericItemSchema) }
 		},
-		limit: {
-			type: "integer",
-			example: 20
-		},
-		total: {
-			type: "integer",
-			example: 100
-		},
-		pages: {
-			type: "integer",
-			example: 5
-		},
-		hasNext: {
-			type: "boolean",
-			example: true
-		},
-		hasPrev: {
-			type: "boolean",
-			example: false
-		}
-	},
-	required: [
-		"page",
-		"limit",
-		"total",
-		"pages",
-		"hasNext",
-		"hasPrev"
-	]
-};
+		get: { response: { 200: genericItemSchema } },
+		create: { response: { 201: genericItemSchema } },
+		update: { response: { 200: genericItemSchema } },
+		delete: { response: { 200: deleteResponse() } }
+	});
+}
+//#endregion
+//#region src/core/validateResourceConfig.ts
 /**
-* List response schema — full union of every wire shape `toCanonicalList`
-* can emit. Hosts who know their endpoint only ever produces one variant
-* can pin to a narrower helper:
-*   - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
-*   - `keysetListResponse(item)` — `{ method: 'keyset', data, limit, hasMore, next: string|null }`
-*   - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
-*   - `bareListResponse(item)` — `{ data }`
+* Resource Configuration Validator
 *
-* The default `listResponse(item)` is the union (`oneOf`) of all four so
-* Fastify validation accepts any canonical kit shape — pre-2.13 this only
-* modelled offset and rejected keyset/aggregate/bare lists at the
-* response-schema gate.
+* Fail-fast validation at definition time.
+* Invalid configs throw immediately with clear, actionable errors.
+*
+* @example
+* const result = validateResourceConfig(config);
+* if (!result.valid) {
+*   console.error(formatValidationErrors(result.errors));
+* }
 */
-function listResponse(itemSchema) {
-	return { oneOf: [
-		offsetListResponse(itemSchema),
-		keysetListResponse(itemSchema),
-		aggregateListResponse(itemSchema),
-		bareListResponse(itemSchema)
-	] };
-}
-/** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
-function offsetListResponse(itemSchema) {
+/**
+* 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 StandardRepo (see @classytic/repo-core)"
+		});
+	} else if (!config.adapter && !config.routes?.length) warnings.push({
+		field: "config",
+		message: "Resource has no adapter and no routes",
+		suggestion: "Provide either adapter for CRUD or routes 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.routes) validateRouteHandlers(config.controller, config.routes, 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.routes) {
+		validateRoutes(config.routes, errors);
+		validateRouteCrudCollisions(config, errors);
+	}
 	return {
-		type: "object",
-		properties: {
-			method: {
-				type: "string",
-				const: "offset",
-				example: "offset"
-			},
-			data: {
-				type: "array",
-				items: itemSchema
-			},
-			page: {
-				type: "integer",
-				example: 1
-			},
-			limit: {
-				type: "integer",
-				example: 20
-			},
-			total: {
-				type: "integer",
-				example: 100
-			},
-			pages: {
-				type: "integer",
-				example: 5
-			},
-			hasNext: {
-				type: "boolean",
-				example: false
-			},
-			hasPrev: {
-				type: "boolean",
-				example: false
-			}
-		},
-		required: [
-			"method",
-			"data",
-			"page",
-			"limit",
-			"total",
-			"pages",
-			"hasNext",
-			"hasPrev"
-		],
-		additionalProperties: true
+		valid: errors.length === 0,
+		errors,
+		warnings
 	};
 }
-/** Keyset variant — `{ method: 'keyset', data, limit, hasMore, next: string | null }`. */
-function keysetListResponse(itemSchema) {
-	return {
-		type: "object",
-		properties: {
-			method: {
-				type: "string",
-				const: "keyset",
-				example: "keyset"
-			},
-			data: {
-				type: "array",
-				items: itemSchema
-			},
-			limit: {
-				type: "integer",
-				example: 20
-			},
-			hasMore: {
-				type: "boolean",
-				example: true
-			},
-			next: {
-				type: ["string", "null"],
-				description: "Cursor token for the next page, or null."
-			}
-		},
-		required: [
-			"method",
-			"data",
-			"limit",
-			"hasMore",
-			"next"
-		],
-		additionalProperties: true
-	};
+function validateRouteHandlers(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: `routes[${route.method} ${route.path}]`,
+			message: `Handler "${route.handler}" not found on controller`,
+			suggestion: `Add method "${route.handler}" to controller or use a function handler`
+		});
+	}
 }
-/** Aggregate variant — same shape as offset, discriminated by `method: 'aggregate'`. */
-function aggregateListResponse(itemSchema) {
-	return {
-		type: "object",
-		properties: {
-			method: {
-				type: "string",
-				const: "aggregate",
-				example: "aggregate"
-			},
-			data: {
-				type: "array",
-				items: itemSchema
-			},
-			page: { type: "integer" },
-			limit: { type: "integer" },
-			total: { type: "integer" },
-			pages: { type: "integer" },
-			hasNext: { type: "boolean" },
-			hasPrev: { type: "boolean" }
-		},
-		required: [
-			"method",
-			"data",
-			"page",
-			"limit",
-			"total",
-			"pages",
-			"hasNext",
-			"hasPrev"
-		],
-		additionalProperties: true
-	};
-}
-/** Bare variant — `{ data }`, no `method` discriminant. */
-function bareListResponse(itemSchema) {
-	return {
-		type: "object",
-		properties: { data: {
-			type: "array",
-			items: itemSchema
-		} },
-		required: ["data"],
-		additionalProperties: true
-	};
+function validatePermissionKeys(config, options, _errors, warnings) {
+	const validKeys = new Set([...CRUD_OPERATIONS, ...options.additionalPermissionKeys ?? []]);
+	for (const route of config.routes ?? []) 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(", ")}`
+	});
 }
-/** Delete response — flat shape mirroring the canonical delete envelope. */
-function deleteResponse() {
-	return {
-		type: "object",
-		properties: {
-			message: {
-				type: "string",
-				example: "Deleted successfully"
-			},
-			id: {
-				type: "string",
-				example: "507f1f77bcf86cd799439011"
-			},
-			soft: {
-				type: "boolean",
-				example: false
-			}
-		},
-		additionalProperties: true
-	};
+function validatePresets(presets, errors, warnings) {
+	const availablePresets = getAvailablePresets();
+	for (const preset of presets) {
+		if (typeof preset === "object" && ("middlewares" in preset || "routes" 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);
+	}
 }
-const ERROR_DESCRIPTIONS = {
-	400: "Bad Request",
-	401: "Unauthorized",
-	403: "Forbidden",
-	404: "Not Found",
-	409: "Conflict",
-	422: "Unprocessable Entity",
-	429: "Too Many Requests",
-	500: "Internal Server Error",
-	503: "Service Unavailable"
-};
-/** Build an OpenAPI response entry for an `ErrorContract` at the given status. */
-function errorResponse(status) {
-	return {
-		description: ERROR_DESCRIPTIONS[status] ?? "Error",
-		content: { "application/json": { schema: errorContractSchema$1 } }
-	};
+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`
+	});
 }
-const responses = {
-	200: (schema) => ({
-		description: "Successful response",
-		content: { "application/json": { schema } }
-	}),
-	201: (schema) => ({
-		description: "Created successfully",
-		content: { "application/json": { schema: {
-			...schema,
-			additionalProperties: true
-		} } }
-	}),
-	400: errorResponse(400),
-	401: errorResponse(401),
-	403: errorResponse(403),
-	404: errorResponse(404),
-	409: errorResponse(409),
-	500: errorResponse(500)
-};
-const queryParams = {
-	pagination: {
-		page: {
-			type: "integer",
-			minimum: 1,
-			default: 1,
-			description: "Page number"
+/**
+* Detect collisions between user-declared `routes:` entries and the
+* auto-CRUD route table that `createCrudRouter` will register.
+*
+* Without this check, a custom `POST /` on the same prefix as auto-CRUD's
+* `create` boots fine through `defineResource()` and only blows up at
+* `app.register()` time with Fastify's opaque `FST_ERR_DUPLICATED_ROUTE`.
+* That error doesn't mention `disabledRoutes` and doesn't distinguish
+* "you collided with auto-CRUD" from "you collided with yourself" — so
+* the consumer has to grep arc's source to discover the fix.
+*
+* We surface the fix in the error message, naming the conflicting op
+* and the literal line to add.
+*
+* Honored config:
+*   - `disableDefaultRoutes: true` → no auto-CRUD, no collisions possible
+*   - `disabledRoutes: ['create']` → that op's path is free for custom use
+*   - `updateMethod: 'PUT' | 'both'` → update slot covers PUT/PATCH accordingly
+*/
+function validateRouteCrudCollisions(config, errors) {
+	if (config.disableDefaultRoutes) return;
+	if (!config.routes || config.routes.length === 0) return;
+	const updateMethod = config.updateMethod ?? "PATCH";
+	const updateMethods = updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod];
+	const disabled = new Set(config.disabledRoutes ?? []);
+	const crudTable = [
+		{
+			op: "list",
+			method: "GET",
+			path: "/"
 		},
-		limit: {
-			type: "integer",
-			minimum: 1,
-			maximum: 100,
-			default: 20,
-			description: "Items per page"
-		}
-	},
-	sorting: { sort: {
-		type: "string",
-		description: "Sort field (prefix with - for descending)",
-		example: "-createdAt"
-	} },
-	filtering: {
-		select: {
-			description: "Fields to include (space-separated or object)",
-			example: "name email createdAt"
+		{
+			op: "get",
+			method: "GET",
+			path: "/:id"
 		},
-		populate: {
-			description: "Relations to populate (comma-separated string or bracket-notation object)",
-			example: "author,category"
+		{
+			op: "create",
+			method: "POST",
+			path: "/"
+		},
+		...updateMethods.map((m) => ({
+			op: "update",
+			method: m,
+			path: "/:id"
+		})),
+		{
+			op: "delete",
+			method: "DELETE",
+			path: "/:id"
+		}
+	];
+	for (const [i, route] of config.routes.entries()) {
+		if (!route.method || !route.path) continue;
+		for (const crud of crudTable) {
+			if (disabled.has(crud.op)) continue;
+			if (route.method !== crud.method || route.path !== crud.path) continue;
+			errors.push({
+				field: `routes[${i}]`,
+				message: `Route ${route.method} ${route.path} collides with auto-CRUD "${crud.op}"`,
+				suggestion: `Add \`disabledRoutes: ['${crud.op}']\` to suppress the auto-CRUD route, or move your custom handler to a different path. Set \`disableDefaultRoutes: true\` to disable all auto-CRUD on this resource.`
+			});
 		}
 	}
+}
+function validateRoutes(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: `routes[${i}].method`,
+			message: `Invalid HTTP method "${route.method}"`,
+			suggestion: `Valid methods: ${validMethods.join(", ")}`
+		});
+		if (!route.path) errors.push({
+			field: `routes[${i}].path`,
+			message: "Route path is required"
+		});
+		else if (!route.path.startsWith("/")) errors.push({
+			field: `routes[${i}].path`,
+			message: `Route path must start with "/" (got "${route.path}")`,
+			suggestion: `Change to "/${route.path}"`
+		});
+		const routeWithRefs = route;
+		if (!route.handler && typeof routeWithRefs.controllerMethod !== "function") errors.push({
+			field: `routes[${i}].handler`,
+			message: "Route must declare either `handler` (string / function) or `controllerMethod`",
+			suggestion: "Prefer `controllerMethod: (c: MyController) => c.method` for typed handler refs."
+		});
+		const routeKey = `${route.method} ${route.path}`;
+		if (seenRoutes.has(routeKey)) errors.push({
+			field: `routes[${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);
+	}
+}
+//#endregion
+//#region src/utils/circuitBreaker.ts
+/**
+* Circuit Breaker Pattern
+*
+* Wraps external service calls with failure protection.
+* Prevents cascading failures by "opening" the circuit when
+* a service is failing, allowing it time to recover.
+*
+* States:
+* - CLOSED: Normal operation, requests pass through
+* - OPEN: Too many failures, all requests fail fast
+* - HALF_OPEN: Testing if service recovered, limited requests
+*
+* @example
+* import { CircuitBreaker } from '@classytic/arc/utils';
+*
+* const paymentBreaker = new CircuitBreaker(async (amount) => {
+*   return await stripe.charges.create({ amount });
+* }, {
+*   failureThreshold: 5,
+*   resetTimeout: 30000,
+*   timeout: 5000,
+* });
+*
+* try {
+*   const result = await paymentBreaker.call(100);
+* } catch (error) {
+*   // Handle failure or circuit open
+* }
+*/
+const CircuitState = {
+	CLOSED: "CLOSED",
+	OPEN: "OPEN",
+	HALF_OPEN: "HALF_OPEN"
+};
+var CircuitBreakerError = class extends Error {
+	state;
+	constructor(message, state) {
+		super(message);
+		this.name = "CircuitBreakerError";
+		this.state = state;
+	}
+};
+var CircuitBreaker = class {
+	state = CircuitState.CLOSED;
+	failures = 0;
+	successes = 0;
+	totalCalls = 0;
+	nextAttempt = 0;
+	lastCallAt = null;
+	openedAt = null;
+	failureThreshold;
+	resetTimeout;
+	timeout;
+	successThreshold;
+	fallback;
+	onStateChange;
+	onError;
+	name;
+	fn;
+	constructor(fn, options = {}) {
+		this.fn = fn;
+		this.failureThreshold = options.failureThreshold ?? 5;
+		this.resetTimeout = options.resetTimeout ?? 6e4;
+		this.timeout = options.timeout ?? 1e4;
+		this.successThreshold = options.successThreshold ?? 1;
+		this.fallback = options.fallback;
+		this.onStateChange = options.onStateChange;
+		this.onError = options.onError;
+		this.name = options.name ?? "CircuitBreaker";
+	}
+	/**
+	* Call the wrapped function with circuit breaker protection
+	*/
+	async call(...args) {
+		this.totalCalls++;
+		this.lastCallAt = Date.now();
+		if (this.state === CircuitState.OPEN) {
+			if (Date.now() < this.nextAttempt) {
+				const error = new CircuitBreakerError(`Circuit breaker is OPEN for ${this.name}`, CircuitState.OPEN);
+				if (this.fallback) return this.fallback(...args);
+				throw error;
+			}
+			this.setState(CircuitState.HALF_OPEN);
+		}
+		try {
+			const result = await this.executeWithTimeout(args);
+			this.onSuccess();
+			return result;
+		} catch (err) {
+			this.onFailure(err instanceof Error ? err : new Error(String(err)));
+			throw err;
+		}
+	}
+	/**
+	* Execute function with timeout
+	*/
+	async executeWithTimeout(args) {
+		return new Promise((resolve, reject) => {
+			const timeoutId = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
+			}, this.timeout);
+			this.fn(...args).then((result) => {
+				clearTimeout(timeoutId);
+				resolve(result);
+			}).catch((error) => {
+				clearTimeout(timeoutId);
+				reject(error);
+			});
+		});
+	}
+	/**
+	* Handle successful call
+	*/
+	onSuccess() {
+		this.failures = 0;
+		this.successes++;
+		if (this.state === CircuitState.HALF_OPEN) {
+			if (this.successes >= this.successThreshold) {
+				this.setState(CircuitState.CLOSED);
+				this.successes = 0;
+			}
+		}
+	}
+	/**
+	* Handle failed call
+	*/
+	onFailure(error) {
+		this.failures++;
+		this.successes = 0;
+		if (this.onError) this.onError(error);
+		if (this.state === CircuitState.HALF_OPEN || this.failures >= this.failureThreshold) {
+			this.setState(CircuitState.OPEN);
+			this.nextAttempt = Date.now() + this.resetTimeout;
+			this.openedAt = Date.now();
+		}
+	}
+	/**
+	* Change circuit state
+	*/
+	setState(newState) {
+		const oldState = this.state;
+		if (oldState !== newState) {
+			this.state = newState;
+			if (this.onStateChange) this.onStateChange(oldState, newState);
+		}
+	}
+	/**
+	* Manually open the circuit
+	*/
+	open() {
+		this.setState(CircuitState.OPEN);
+		this.nextAttempt = Date.now() + this.resetTimeout;
+		this.openedAt = Date.now();
+	}
+	/**
+	* Manually close the circuit
+	*/
+	close() {
+		this.failures = 0;
+		this.successes = 0;
+		this.setState(CircuitState.CLOSED);
+		this.openedAt = null;
+	}
+	/**
+	* Get current statistics
+	*/
+	getStats() {
+		return {
+			name: this.name,
+			state: this.state,
+			failures: this.failures,
+			successes: this.successes,
+			totalCalls: this.totalCalls,
+			openedAt: this.openedAt,
+			lastCallAt: this.lastCallAt
+		};
+	}
+	/**
+	* Get current state
+	*/
+	getState() {
+		return this.state;
+	}
+	/**
+	* Check if circuit is open
+	*/
+	isOpen() {
+		return this.state === CircuitState.OPEN;
+	}
+	/**
+	* Check if circuit is closed
+	*/
+	isClosed() {
+		return this.state === CircuitState.CLOSED;
+	}
+	/**
+	* Reset statistics
+	*/
+	reset() {
+		this.failures = 0;
+		this.successes = 0;
+		this.totalCalls = 0;
+		this.lastCallAt = null;
+		this.openedAt = null;
+		this.setState(CircuitState.CLOSED);
+	}
+};
+/**
+* Create a circuit breaker with sensible defaults
+*
+* @example
+* const emailBreaker = createCircuitBreaker(
+*   async (to, subject, body) => sendEmail(to, subject, body),
+*   { name: 'email-service' }
+* );
+*/
+function createCircuitBreaker(fn, options) {
+	return new CircuitBreaker(fn, options);
+}
+/**
+* Circuit breaker registry for managing multiple breakers
+*/
+var CircuitBreakerRegistry = class {
+	breakers = /* @__PURE__ */ new Map();
+	/**
+	* Register a circuit breaker
+	*/
+	register(name, fn, options) {
+		const breaker = new CircuitBreaker(fn, {
+			...options,
+			name
+		});
+		this.breakers.set(name, breaker);
+		return breaker;
+	}
+	/**
+	* Get a circuit breaker by name
+	*/
+	get(name) {
+		return this.breakers.get(name);
+	}
+	/**
+	* Get all breakers
+	*/
+	getAll() {
+		return this.breakers;
+	}
+	/**
+	* Get statistics for all breakers
+	*/
+	getAllStats() {
+		const stats = {};
+		for (const [name, breaker] of this.breakers.entries()) stats[name] = breaker.getStats();
+		return stats;
+	}
+	/**
+	* Reset all breakers
+	*/
+	resetAll() {
+		for (const breaker of this.breakers.values()) breaker.reset();
+	}
+	/**
+	* Open all breakers
+	*/
+	openAll() {
+		for (const breaker of this.breakers.values()) breaker.open();
+	}
+	/**
+	* Close all breakers
+	*/
+	closeAll() {
+		for (const breaker of this.breakers.values()) breaker.close();
+	}
 };
 /**
-* Get standard list query parameters schema
+* Create a new CircuitBreakerRegistry instance.
+* Use this instead of a global singleton — attach to fastify.arc or pass explicitly.
 */
-function getListQueryParams() {
-	return {
-		type: "object",
-		properties: {
-			...queryParams.pagination,
-			...queryParams.sorting,
-			...queryParams.filtering
-		},
-		additionalProperties: true
-	};
+function createCircuitBreakerRegistry() {
+	return new CircuitBreakerRegistry();
 }
+//#endregion
+//#region src/utils/compensation.ts
 /**
-* Generic item schema that allows any properties.
-* Used as default when no user schema is provided.
-* Enables fast-json-stringify while still passing through all fields.
-*/
-const genericItemSchema = {
-	type: "object",
-	additionalProperties: true
-};
-/**
-* Recursively strip `example` keys from a schema object.
-* The `example` keyword is OpenAPI metadata — not standard JSON Schema —
-* and triggers Ajv strict mode errors when used on routes without the
-* `keywords: ['example']` AJV config (e.g., raw Fastify without createApp).
+* Run steps in order with automatic compensation on failure.
+*
+* @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
 */
-function stripExamples(schema) {
-	if (schema === null || typeof schema !== "object") return schema;
-	if (Array.isArray(schema)) return schema.map(stripExamples);
-	const result = {};
-	for (const [key, value] of Object.entries(schema)) {
-		if (key === "example") continue;
-		result[key] = stripExamples(value);
+async function withCompensation(_name, steps, initialContext, hooks) {
+	const ctx = { ...initialContext };
+	const completedSteps = [];
+	const results = {};
+	const completed = [];
+	for (const step of steps) {
+		if (step.fireAndForget) {
+			completedSteps.push(step.name);
+			step.execute(ctx).then((result) => hooks?.onStepComplete?.(step.name, result), () => {});
+			continue;
+		}
+		try {
+			const result = await step.execute(ctx);
+			completedSteps.push(step.name);
+			results[step.name] = result;
+			completed.push({
+				step,
+				result
+			});
+			hooks?.onStepComplete?.(step.name, result);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			hooks?.onStepFailed?.(step.name, error);
+			const compensationErrors = await rollback(ctx, completed, hooks);
+			return {
+				success: false,
+				completedSteps,
+				results,
+				failedStep: step.name,
+				error: error.message,
+				...compensationErrors.length > 0 ? { compensationErrors } : {}
+			};
+		}
 	}
-	return result;
+	return {
+		success: true,
+		completedSteps,
+		results
+	};
+}
+async function rollback(ctx, completed, hooks) {
+	const errors = [];
+	for (let i = completed.length - 1; i >= 0; i--) {
+		const entry = completed[i];
+		if (!entry?.step.compensate) continue;
+		const compensateFn = entry.step.compensate;
+		try {
+			await compensateFn(ctx, entry.result);
+			hooks?.onCompensate?.(entry.step.name);
+		} catch (err) {
+			errors.push({
+				step: entry.step.name,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	return errors;
 }
+function defineCompensation(name, steps) {
+	return {
+		name,
+		execute: (initialContext, hooks) => withCompensation(name, steps, initialContext, hooks)
+	};
+}
+//#endregion
+//#region src/utils/defineErrorMapper.ts
 /**
-* Get default response schemas for all CRUD operations.
-*
-* When routes have response schemas, Fastify compiles them with
-* fast-json-stringify for 2-3x faster serialization and prevents
-* accidental field disclosure.
+* Register an `ErrorMapper` with its domain-specific generic argument and
+* have it assign cleanly into `ErrorMapper[]` (no `as unknown as ErrorMapper`).
 *
-* These defaults use `additionalProperties: true` so all fields pass through.
-* Override with specific schemas for full serialization performance + safety.
+* The returned mapper is identical at runtime — `type` and `toResponse` are
+* passed through untouched. Only the declared type widens from
+* `ErrorMapper<T>` to `ErrorMapper` so the array inference works.
 *
-* Note: `example` properties are stripped from defaults so they work with
-* any Fastify instance (not just createApp which adds `keywords: ['example']`).
+* Safety: the `errorHandlerPlugin` dispatches via `error instanceof mapper.type`
+* before invoking `toResponse`, so the widened callback signature is never
+* called with a non-`T` error at runtime. This helper codifies that invariant
+* in one place.
 */
-function getDefaultCrudSchemas() {
-	return stripExamples({
-		list: {
-			querystring: getListQueryParams(),
-			response: { 200: listResponse(genericItemSchema) }
-		},
-		get: { response: { 200: genericItemSchema } },
-		create: { response: { 201: genericItemSchema } },
-		update: { response: { 200: genericItemSchema } },
-		delete: { response: { 200: deleteResponse() } }
-	});
+function defineErrorMapper(mapper) {
+	return mapper;
 }
 //#endregion
-//#region src/utils/runtime.ts
+//#region src/utils/defineGuard.ts
+/** Hidden property key for guard context storage on the request object. */
+const GUARD_STORE_KEY = "__arcGuardContext";
 /**
-* Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
-* available in Bun workers, Deno, Cloudflare Workers, or edge runtimes.
+* Create a typed guard. See module JSDoc for usage.
 */
-const scheduleBackground = typeof setImmediate === "function" ? (cb) => void setImmediate(cb) : (cb) => queueMicrotask(cb);
+function defineGuard(config) {
+	const { name, resolve } = config;
+	const preHandler = async (req, reply) => {
+		const ctx = await resolve(req, reply);
+		if (!reply.sent) {
+			const store = req[GUARD_STORE_KEY] ?? {};
+			store[name] = ctx;
+			req[GUARD_STORE_KEY] = store;
+		}
+	};
+	return {
+		preHandler,
+		name,
+		from(req) {
+			const store = req[GUARD_STORE_KEY];
+			if (!store || !(name in store)) throw new Error(`Guard '${name}' not resolved on this request. Add it to routeGuards or the route's preHandler array.`);
+			return store[name];
+		}
+	};
+}
+//#endregion
+//#region src/utils/handleRaw.ts
+/**
+* Wrap a raw Fastify handler with Arc's response shape and error handling.
+*
+* @param handler - Async function that receives `(request, reply)` and returns data.
+*   The return value is sent raw (no envelope). If it returns `undefined`,
+*   the response body is empty (HTTP status only).
+* @param statusCode - HTTP status code for successful responses (default: 200)
+*/
+function handleRaw(handler, statusCode = 200) {
+	return async (request, reply) => {
+		try {
+			const result = await handler(request, reply);
+			if (reply.sent) return;
+			if (result === void 0 || result === null) reply.code(statusCode).send();
+			else reply.code(statusCode).send(result);
+		} catch (err) {
+			if (reply.sent) return;
+			if (err instanceof ArcError) {
+				reply.code(err.statusCode).send({
+					error: err.message,
+					code: err.code,
+					...err.details ? { details: err.details } : {}
+				});
+				return;
+			}
+			const error = err;
+			const code = error.statusCode ?? error.status ?? 500;
+			reply.code(code).send({
+				error: error.message ?? "Internal server error",
+				...error.code && { code: error.code }
+			});
+		}
+	};
+}
 //#endregion
 //#region src/utils/stateMachine.ts
 /**
@@ -1671,130 +1688,4 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
-//#region src/utils/streaming.ts
-/**
-* Streaming helpers — adapters between Web `ReadableStream` producers
-* (Vercel AI SDK, OpenAI SDK, `fetch().body`, hand-built `TransformStream`s)
-* and Fastify's raw Node-stream reply.
-*
-* Why this exists: returning a `ReadableStream<UIMessageChunk>` from a
-* `streamResponse: true` arc route used to crash with
-* `chunk must be a string or Buffer` because Fastify cannot serialise
-* `UIMessageChunk` JSON objects directly. Every arc-ai host (sniffer,
-* spawn, downstream) reimplemented the same `JsonToSseTransformStream` +
-* SSE header boilerplate. `pipeUIMessageStreamToReply()` is that
-* boilerplate, owned once.
-*
-* arc stays peer-coupled to nothing: the helper accepts any
-* `ReadableStream<unknown>` and JSON-stringifies each chunk. It works
-* with `UIMessageChunk` from the AI SDK without importing it.
-*/
-/**
-* Canonical SSE headers for AI-SDK-style UI message streams.
-*
-* `x-vercel-ai-ui-message-stream: v1` is the marker the Vercel AI SDK
-* client uses to detect the v1 UI message stream protocol (vs the older
-* data stream protocol). Surfaced as a constant so hosts don't memorise it.
-*/
-const UI_MESSAGE_STREAM_HEADERS = {
-	"content-type": "text/event-stream",
-	"cache-control": "no-cache",
-	connection: "keep-alive",
-	"x-accel-buffering": "no",
-	"x-vercel-ai-ui-message-stream": "v1"
-};
-/**
-* Pipe a Web `ReadableStream` of JSON-serialisable chunks (typically
-* `UIMessageChunk` from the Vercel AI SDK) into a Fastify reply as an
-* SSE event stream.
-*
-* - Sets {@link UI_MESSAGE_STREAM_HEADERS} (or the caller's override)
-*   before the first chunk.
-* - Writes each chunk as `data: ${JSON.stringify(chunk)}\n\n`.
-* - Cancels the source and closes the reply when the client disconnects.
-* - Resolves once the stream is fully written.
-*
-* @example
-* ```ts
-* import { pipeUIMessageStreamToReply } from '@classytic/arc/utils';
-* import { streamText, convertToUIMessageStream } from 'ai';
-*
-* defineResource({
-*   name: 'chat',
-*   routes: [{
-*     method: 'POST', path: '/', streamResponse: true,
-*     handler: async (req, reply) => {
-*       const result = streamText({ model, messages: req.body.messages });
-*       await pipeUIMessageStreamToReply(reply, result.toUIMessageStream());
-*     },
-*   }],
-* });
-* ```
-*/
-async function pipeUIMessageStreamToReply(reply, stream, options = {}) {
-	const serialize = options.serialize ?? defaultSerialize;
-	const headers = options.headers ?? UI_MESSAGE_STREAM_HEADERS;
-	for (const [key, value] of Object.entries(headers)) reply.header(key, value);
-	const reader = stream.getReader();
-	let cancelled = false;
-	const onAbort = () => {
-		cancelled = true;
-		reader.cancel().catch(() => {});
-	};
-	reply.request.raw.once("close", onAbort);
-	options.signal?.addEventListener("abort", onAbort, { once: true });
-	async function* sseFrames() {
-		try {
-			while (true) {
-				const { value, done } = await reader.read();
-				if (done) break;
-				yield `data: ${serialize(value)}\n\n`;
-			}
-		} catch (err) {
-			if (!cancelled) yield `event: error\ndata: ${JSON.stringify({ message: String(err) })}\n\n`;
-		} finally {
-			reply.request.raw.removeListener("close", onAbort);
-			options.signal?.removeEventListener("abort", onAbort);
-			reader.releaseLock?.();
-		}
-	}
-	const nodeStream = Readable.from(sseFrames());
-	await reply.send(nodeStream);
-}
-function defaultSerialize(chunk) {
-	return typeof chunk === "string" ? chunk : JSON.stringify(chunk);
-}
-/**
-* Heuristic — does this value look like a Web `ReadableStream`?
-*
-* Used by `createCrudRouter` to auto-pipe `streamResponse: true` handlers
-* that return a UI message stream instead of writing to `reply.raw`
-* directly. Cross-realm safe (no `instanceof`) — checks the duck shape
-* the Streams spec mandates: `getReader`, `cancel`, and the `locked`
-* getter.
-*/
-function isReadableStream(value) {
-	if (value === null || typeof value !== "object") return false;
-	const obj = value;
-	return typeof obj.getReader === "function" && typeof obj.cancel === "function" && typeof obj.locked === "boolean";
-}
-//#endregion
-//#region src/utils/userHelpers.ts
-/**
-* Extract a user ID from a user object. Accepts `id` or `_id` — returns
-* `undefined` when neither is present. Used by arc's controllers to
-* populate `createdBy` / `updatedBy` fields and for cache scoping.
-*
-* @example
-* ```ts
-* import { getUserId } from '@classytic/arc/utils';
-* const uid = getUserId(request.user);
-* ```
-*/
-function getUserId(user) {
-	if (!user) return void 0;
-	const id = user.id ?? user._id;
-	return id ? String(id) : void 0;
-}
-//#endregion
-export { CircuitState as A, defineGuard as C, CircuitBreaker as D, withCompensation as E, validateResourceConfig as F, simpleEqualityMatcher as I, createCircuitBreakerRegistry as M, assertValidConfig as N, CircuitBreakerError as O, formatValidationErrors as P, handleRaw as S, defineCompensation as T, paginationSchema as _, createStateMachine as a, ArcQueryParser as b, bareListResponse as c, errorDetailSchema$1 as d, getDefaultCrudSchemas as f, offsetListResponse as g, listResponse as h, pipeUIMessageStreamToReply as i, createCircuitBreaker as j, CircuitBreakerRegistry as k, deleteResponse as l, keysetListResponse as m, UI_MESSAGE_STREAM_HEADERS as n, scheduleBackground as o, getListQueryParams as p, isReadableStream as r, aggregateListResponse as s, getUserId as t, errorContractSchema$1 as u, queryParams as v, defineErrorMapper as w, createQueryParser as x, responses as y };
+export { createQueryParser as A, keysetListResponse as C, queryParams as D, paginationSchema as E, scheduleBackground as M, simpleEqualityMatcher as N, responses as O, getListQueryParams as S, offsetListResponse as T, bareListResponse as _, defineCompensation as a, errorDetailSchema$1 as b, CircuitBreakerError as c, createCircuitBreaker as d, createCircuitBreakerRegistry as f, aggregateListResponse as g, validateResourceConfig as h, defineErrorMapper as i, getUserId as j, ArcQueryParser as k, CircuitBreakerRegistry as l, formatValidationErrors as m, handleRaw as n, withCompensation as o, assertValidConfig as p, defineGuard as r, CircuitBreaker as s, createStateMachine as t, CircuitState as u, deleteResponse as v, listResponse as w, getDefaultCrudSchemas as x, errorContractSchema$1 as y };