@classytic/arc 2.37.0 → 2.38.0

package/dist/{utils-sXGFLegw.mjs → utils-BbGG8XNT.mjs}

@@ -1,1374 +1,1374 @@
-/*! @classytic/arc v2.37.0 | MIT | https://classytic.com */
-import { m as RESERVED_QUERY_PARAMS } from "./constants-CUpamQMJ.mjs";
+/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
+import { m as RESERVED_QUERY_PARAMS } from "./constants-BONghE1Y.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { t as ArcError, u as ValidationError } from "./errors-DsdZc1Xv.mjs";
-import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
+import { t as ArcError, u as ValidationError } from "./errors-2ExmOgIJ.mjs";
 import { scheduleBackground } from "@classytic/repo-core/cache";
-//#region src/utils/circuitBreaker.ts
+import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
+//#region src/utils/filter-dialect.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.
+* Default dialect — MongoDB / MongoKit operator shape. Emits `$`-prefixed
+* tokens and the `$options: 'i'` case-insensitive sibling. This is what
+* `ArcQueryParser` uses when no dialect is supplied, so behaviour is identical
+* to every prior arc version.
+*/
+const MONGO_DIALECT = {
+	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"
+	},
+	caseInsensitiveModifier: () => ({ $options: "i" })
+};
+/**
+* Store-neutral reference dialect — emits UN-prefixed operator tokens as a
+* translation AST (`?price[gte]=40` → `{ price: { gte: 40 } }`, with
+* `{ caseInsensitive: true }` for `like`/`contains`). A non-Mongo adapter can
+* consume this directly instead of writing a full `QueryParserInterface`. Use
+* as a starting point; adjust the token names to your store's vocabulary.
+*/
+const NEUTRAL_DIALECT = {
+	operators: {
+		eq: "eq",
+		ne: "ne",
+		gt: "gt",
+		gte: "gte",
+		lt: "lt",
+		lte: "lte",
+		in: "in",
+		nin: "nin",
+		like: "like",
+		contains: "contains",
+		regex: "regex",
+		exists: "exists"
+	},
+	caseInsensitiveModifier: () => ({ caseInsensitive: true })
+};
+//#endregion
+//#region src/utils/queryParser.ts
+/**
+* Arc Query Parser - Default URL-to-Query Parser
 *
-* States:
-* - CLOSED: Normal operation, requests pass through
-* - OPEN: Too many failures, all requests fail fast
-* - HALF_OPEN: Testing if service recovered, limited requests
+* 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
-* import { CircuitBreaker } from '@classytic/arc/utils';
+* // Use Arc default parser (auto-applied if no queryParser option)
+* defineResource({ name: 'product', adapter: ... });
 *
-* const paymentBreaker = new CircuitBreaker(async (amount) => {
-*   return await stripe.charges.create({ amount });
-* }, {
-*   failureThreshold: 5,
-*   resetTimeout: 30000,
-*   timeout: 5000,
+* // Use MongoKit's QueryParser (recommended for MongoDB - has $lookup, aggregations, etc.)
+* // Fail-closed by default (mongokit >=3.25): invalid/blocked query input
+* // becomes HTTP 400 instead of a silently broadened result set.
+* import { QueryParser } from '@classytic/mongokit';
+* defineResource({
+*   name: 'product',
+*   adapter: ...,
+*   queryParser: new QueryParser(),
 * });
 *
-* try {
-*   const result = await paymentBreaker.call(100);
-* } catch (error) {
-*   // Handle failure or circuit open
-* }
+* // Use custom parser for SQL databases
+* defineResource({
+*   name: 'user',
+*   adapter: ...,
+*   queryParser: new PgQueryParser(),
+* });
 */
-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;
-	halfOpenInFlight = 0;
-	failureThreshold;
-	resetTimeout;
-	timeout;
-	successThreshold;
-	halfOpenMaxProbes;
-	propagateAbort;
-	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.halfOpenMaxProbes = options.halfOpenMaxProbes ?? 1;
-		this.propagateAbort = options.propagateAbort ?? false;
-		this.fallback = options.fallback;
-		this.onStateChange = options.onStateChange;
-		this.onError = options.onError;
-		this.name = options.name ?? "CircuitBreaker";
-	}
+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]|(\[.+\]).+(\[.+\]))/;
+/**
+* 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.
+*
+* For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
+*/
+var ArcQueryParser = class {
 	/**
-	* Call the wrapped function with circuit breaker protection
+	* PUBLIC, deliberately: `QueryResolver` reads it so it does not apply a second cap
+	* on top of this one. Three layers capping independently, lowest winning silently,
+	* is what made a 696-row chart of accounts render as 100.
 	*/
-	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);
+	maxLimit;
+	defaultLimit;
+	maxRegexLength;
+	maxSearchLength;
+	maxFilterDepth;
+	_allowedFilterFields;
+	_allowedSortFields;
+	_allowedOperators;
+	strictFilterFields;
+	/** 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;
+	/**
+	* Datastore dialect — owns the store-specific operator tokens + the
+	* case-insensitive modifier. Defaults to Mongo (backward-compatible).
+	*/
+	dialect;
+	/** Supported filter operators (neutral name → emitted token), from the dialect. */
+	get operators() {
+		return this.dialect.operators;
+	}
+	constructor(options = {}) {
+		this.dialect = options.dialect ?? MONGO_DIALECT;
+		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;
+		this.strictFilterFields = options.strictFilterFields ?? process.env.ARC_STRICT_QUERY_PARAMS === "true";
+		if (options.allowedFilterFields) {
+			this._allowedFilterFields = new Set(options.allowedFilterFields);
+			this.allowedFilterFields = options.allowedFilterFields;
 		}
-		let isProbe = false;
-		if (this.state === CircuitState.HALF_OPEN) {
-			if (this.halfOpenInFlight >= this.halfOpenMaxProbes) {
-				if (this.fallback) return this.fallback(...args);
-				throw new CircuitBreakerError(`Circuit breaker is HALF_OPEN for ${this.name} — probe slots full`, CircuitState.HALF_OPEN);
-			}
-			this.halfOpenInFlight++;
-			isProbe = true;
+		if (options.allowedSortFields) {
+			this._allowedSortFields = new Set(options.allowedSortFields);
+			this.allowedSortFields = options.allowedSortFields;
 		}
-		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;
-		} finally {
-			if (isProbe) this.halfOpenInFlight--;
+		if (options.allowedOperators) {
+			this._allowedOperators = new Set(options.allowedOperators);
+			this.allowedOperators = options.allowedOperators;
 		}
 	}
 	/**
-	* Execute function with timeout. With `propagateAbort`, the wrapped fn
-	* receives a trailing AbortSignal that fires on timeout — the breaker's
-	* timeout otherwise only rejects the CALLER while the underlying work
-	* keeps consuming sockets/pool slots to completion.
+	* Parse URL query parameters into structured query options
 	*/
-	async executeWithTimeout(args) {
-		const controller = this.propagateAbort ? new AbortController() : void 0;
-		return new Promise((resolve, reject) => {
-			const timeoutId = setTimeout(() => {
-				controller?.abort(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
-				reject(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
-			}, this.timeout);
-			(controller ? this.fn(...args, controller.signal) : this.fn(...args)).then((result) => {
-				clearTimeout(timeoutId);
-				resolve(result);
-			}).catch((error) => {
-				clearTimeout(timeoutId);
-				reject(error);
-			});
-		});
+	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;
 	}
 	/**
-	* Handle successful call
+	* 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' }] }
 	*/
-	onSuccess() {
-		this.failures = 0;
-		this.successes++;
-		if (this.state === CircuitState.HALF_OPEN) {
-			if (this.successes >= this.successThreshold) {
-				this.setState(CircuitState.CLOSED);
-				this.successes = 0;
+	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 });
 			}
+			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;
+	}
+	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 open the circuit
+	* Check if a value exceeds the maximum nesting depth.
+	* Prevents filter bombs where deeply nested objects consume excessive memory/CPU.
 	*/
-	open() {
-		this.setState(CircuitState.OPEN);
-		this.nextAttempt = Date.now() + this.resetTimeout;
-		this.openedAt = Date.now();
+	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));
 	}
 	/**
-	* Manually close the circuit
+	* 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.
 	*/
-	close() {
-		this.failures = 0;
-		this.successes = 0;
-		this.setState(CircuitState.CLOSED);
-		this.openedAt = null;
+	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 statistics
+	* 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.
 	*/
-	getStats() {
-		return {
-			name: this.name,
-			state: this.state,
-			failures: this.failures,
-			successes: this.successes,
-			totalCalls: this.totalCalls,
-			openedAt: this.openedAt,
-			lastCallAt: this.lastCallAt
-		};
+	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)) {
+			if (this.strictFilterFields) throw new ValidationError(`Unknown filter field: ${bareKey}. Allowed: ${[...this._allowedFilterFields].sort().join(", ")}`);
+			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 fieldOps = {};
+				let needsCaseInsensitive = false;
+				for (const [op, opValue] of Object.entries(operatorObj)) {
+					const token = this.operators[op];
+					if (token) {
+						fieldOps[token] = this.parseFilterValue(opValue, op);
+						if (op === "contains" || op === "like") needsCaseInsensitive = true;
+					}
+				}
+				if (needsCaseInsensitive) Object.assign(fieldOps, this.dialect.caseInsensitiveModifier());
+				filters[key] = fieldOps;
+				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 token = this.operators[operator];
+			const parsedValue = this.parseFilterValue(value, operator);
+			if (!filters[fieldName]) filters[fieldName] = {};
+			const fieldFilter = filters[fieldName];
+			fieldFilter[token] = parsedValue;
+			if (operator === "contains" || operator === "like") Object.assign(fieldFilter, this.dialect.caseInsensitiveModifier());
+		} else if (!operator) filters[fieldName] = this.parseFilterValue(value);
 	}
-	/**
-	* Get current state
-	*/
-	getState() {
-		return this.state;
+	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 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);
+	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;
 	}
-};
-/**
-* 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
+	* 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.
 	*/
-	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",
+					/**
+					* The cap is DOCUMENTED here, not enforced — deliberately.
+					*
+					* Both layers that handle `limit` CLAMP it: this parser
+					* (`Math.min(…, this.maxLimit)`) and `QueryResolver`. Emitting
+					* `maximum` contradicted them, because arc layers this schema as the
+					* route's `listQuery` and Fastify validates the querystring BEFORE
+					* either runs — so the clamp was unreachable and `?limit=200` became a
+					* hard 400.
+					*
+					* That combination is worse than either policy alone. Asking for more
+					* rows than allowed is a benign over-ask with an obvious right answer
+					* (give the maximum); turning it into a validation failure means a UI
+					* passing a generous page size gets NOTHING, and a caller that does not
+					* inspect the error body renders it as an empty list — a 400 disguised
+					* as "no results", which is the hardest kind to find.
+					*
+					* A deployment wanting refusal instead of clamping should say so in the
+					* parser's policy, where both halves can agree, not in a schema that
+					* silently outranks them. Mirrors the same fix in mongokit's
+					* `buildQuerySchema`.
+					*/
+					description: `Number of items per page (values above ${this.maxLimit} are capped to ${this.maxLimit})`,
+					default: this.defaultLimit,
+					minimum: 1
+				},
+				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
 /**
-* Observability hooks must never alter the transaction: a throwing metrics
-* sink must not fail a step that succeeded, trigger compensation, or become
-* an unhandled rejection from a detached fire-and-forget chain. Containment
-* is reported via `hooks.onHookError` so broken sinks stay visible.
+* 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.
 */
-function safeHook(name, invoke, hooks) {
-	try {
-		invoke();
-	} catch (err) {
-		try {
-			hooks?.onHookError?.(name, err instanceof Error ? err : new Error(String(err)));
-		} catch {}
-	}
-}
 /**
-* Run steps in order with automatic compensation on failure.
+* Pagination schema - matches MongoKit/Arc runtime format
 *
-* @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
+* Runtime format (flat fields):
+* { page, limit, total, pages, hasNext, hasPrev }
 */
-async function withCompensation(_name, steps, initialContext, hooks) {
-	const ctx = { ...initialContext };
-	const completedSteps = [];
-	const results = {};
-	const completed = [];
-	for (const step of steps) {
-		if (step.fireAndForget) {
-			step.execute(ctx).then((result) => safeHook("onStepComplete", () => hooks?.onStepComplete?.(step.name, result), hooks), (err) => safeHook("onStepFailed", () => hooks?.onStepFailed?.(step.name, err instanceof Error ? err : new Error(String(err))), hooks)).catch(() => {});
-			continue;
+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
 		}
-		try {
-			const result = await step.execute(ctx);
-			completedSteps.push(step.name);
-			results[step.name] = result;
-			completed.push({
-				step,
-				result
-			});
-			safeHook("onStepComplete", () => hooks?.onStepComplete?.(step.name, result), hooks);
-		} catch (err) {
-			const error = err instanceof Error ? err : new Error(String(err));
-			safeHook("onStepFailed", () => hooks?.onStepFailed?.(step.name, error), hooks);
-			const compensationErrors = await rollback(ctx, completed, hooks);
-			return {
-				success: false,
-				completedSteps,
-				results,
-				failedStep: step.name,
-				error: error.message,
-				...compensationErrors.length > 0 ? { compensationErrors } : {}
-			};
-		}
-	}
+	},
+	required: [
+		"page",
+		"limit",
+		"total",
+		"pages",
+		"hasNext",
+		"hasPrev"
+	]
+};
+/**
+* List response schema — accepts every wire shape `toCanonicalList` can
+* emit. Hosts who know their endpoint only ever produces one variant can
+* pin to a narrower helper (sharper OpenAPI docs, same serializer speed):
+*   - `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 }`
+*
+* SHAPE: one merged permissive object, NOT a `oneOf` union (2.22). The
+* pre-2.22 union was semantically identical on the wire — every variant is
+* `additionalProperties: true` and the property definitions never conflict
+* (`next` only exists on keyset, the offset counters only on offset/
+* aggregate; fast-json-stringify skips undefined optionals) — but
+* fast-json-stringify implements top-level `oneOf` by running full AJV
+* validation PER RESPONSE to pick the branch, on the hottest route of
+* every arc app. The merge keeps the exact bytes (pinned by
+* `tests/utils/list-response-serialization.test.ts`) and drops the
+* per-response branch validation. Only `data` is required — the one field
+* all four variants share.
+*/
+function listResponse(itemSchema) {
 	return {
-		success: true,
-		completedSteps,
-		results
+		type: "object",
+		properties: {
+			method: {
+				type: "string",
+				description: "Pagination method discriminant — 'offset' | 'keyset' | 'aggregate'; absent on bare lists.",
+				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
+			},
+			hasMore: { type: "boolean" },
+			next: {
+				type: ["string", "null"],
+				description: "Cursor token for the next page, or null."
+			}
+		},
+		required: ["data"],
+		additionalProperties: true
 	};
 }
-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);
-			safeHook("onCompensate", () => hooks?.onCompensate?.(entry.step.name), hooks);
-		} catch (err) {
-			errors.push({
-				step: entry.step.name,
-				error: err instanceof Error ? err.message : String(err)
-			});
-		}
-	}
-	return errors;
-}
-function defineCompensation(name, steps) {
+/** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
+function offsetListResponse(itemSchema) {
 	return {
-		name,
-		execute: (initialContext, hooks) => withCompensation(name, steps, initialContext, hooks)
+		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
 	};
 }
-//#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.
-*
-* 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.
-*/
-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;
-		}
-	};
+/** Keyset variant — `{ method: 'keyset', data, limit, hasMore, next: string | null }`. */
+function keysetListResponse(itemSchema) {
 	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];
-		}
+		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
 	};
 }
-//#endregion
-//#region src/utils/filter-dialect.ts
-/**
-* Default dialect — MongoDB / MongoKit operator shape. Emits `$`-prefixed
-* tokens and the `$options: 'i'` case-insensitive sibling. This is what
-* `ArcQueryParser` uses when no dialect is supplied, so behaviour is identical
-* to every prior arc version.
-*/
-const MONGO_DIALECT = {
-	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"
+/** 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"
+		}
 	},
-	caseInsensitiveModifier: () => ({ $options: "i" })
+	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"
+		}
+	}
 };
 /**
-* Store-neutral reference dialect — emits UN-prefixed operator tokens as a
-* translation AST (`?price[gte]=40` → `{ price: { gte: 40 } }`, with
-* `{ caseInsensitive: true }` for `like`/`contains`). A non-Mongo adapter can
-* consume this directly instead of writing a full `QueryParserInterface`. Use
-* as a starting point; adjust the token names to your store's vocabulary.
+* Get standard list query parameters schema
 */
-const NEUTRAL_DIALECT = {
-	operators: {
-		eq: "eq",
-		ne: "ne",
-		gt: "gt",
-		gte: "gte",
-		lt: "lt",
-		lte: "lte",
-		in: "in",
-		nin: "nin",
-		like: "like",
-		contains: "contains",
-		regex: "regex",
-		exists: "exists"
-	},
-	caseInsensitiveModifier: () => ({ caseInsensitive: true })
+function getListQueryParams() {
+	return {
+		type: "object",
+		properties: {
+			...queryParams.pagination,
+			...queryParams.sorting,
+			...queryParams.filtering
+		},
+		additionalProperties: true
+	};
+}
+/**
+* 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
 };
-//#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)
+* 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 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 }
-			});
-		}
-	};
+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;
 }
-//#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.
+* Get default response schemas for all CRUD operations.
 *
-* @example
-* // Use Arc default parser (auto-applied if no queryParser option)
-* defineResource({ name: 'product', adapter: ... });
+* When routes have response schemas, Fastify compiles them with
+* fast-json-stringify for 2-3x faster serialization and prevents
+* accidental field disclosure.
 *
-* // Use MongoKit's QueryParser (recommended for MongoDB - has $lookup, aggregations, etc.)
-* // Fail-closed by default (mongokit >=3.25): invalid/blocked query input
-* // becomes HTTP 400 instead of a silently broadened result set.
-* import { QueryParser } from '@classytic/mongokit';
-* defineResource({
-*   name: 'product',
-*   adapter: ...,
-*   queryParser: new QueryParser(),
-* });
+* These defaults use `additionalProperties: true` so all fields pass through.
+* Override with specific schemas for full serialization performance + safety.
 *
-* // 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.
+* Note: `example` properties are stripped from defaults so they work with
+* any Fastify instance (not just createApp which adds `keywords: ['example']`).
 */
-const DANGEROUS_REGEX_PATTERNS = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
+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() } }
+	});
+}
+//#endregion
+//#region src/utils/circuitBreaker.ts
 /**
-* Arc's default query parser
+* Circuit Breaker Pattern
 *
-* 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
+* Wraps external service calls with failure protection.
+* Prevents cascading failures by "opening" the circuit when
+* a service is failing, allowing it time to recover.
 *
-* **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.
+* States:
+* - CLOSED: Normal operation, requests pass through
+* - OPEN: Too many failures, all requests fail fast
+* - HALF_OPEN: Testing if service recovered, limited requests
 *
-* For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
+* @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
+* }
 */
-var ArcQueryParser = class {
-	/**
-	* PUBLIC, deliberately: `QueryResolver` reads it so it does not apply a second cap
-	* on top of this one. Three layers capping independently, lowest winning silently,
-	* is what made a 696-row chart of accounts render as 100.
-	*/
-	maxLimit;
-	defaultLimit;
-	maxRegexLength;
-	maxSearchLength;
-	maxFilterDepth;
-	_allowedFilterFields;
-	_allowedSortFields;
-	_allowedOperators;
-	strictFilterFields;
-	/** 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;
+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;
+	halfOpenInFlight = 0;
+	failureThreshold;
+	resetTimeout;
+	timeout;
+	successThreshold;
+	halfOpenMaxProbes;
+	propagateAbort;
+	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.halfOpenMaxProbes = options.halfOpenMaxProbes ?? 1;
+		this.propagateAbort = options.propagateAbort ?? false;
+		this.fallback = options.fallback;
+		this.onStateChange = options.onStateChange;
+		this.onError = options.onError;
+		this.name = options.name ?? "CircuitBreaker";
+	}
 	/**
-	* Datastore dialect — owns the store-specific operator tokens + the
-	* case-insensitive modifier. Defaults to Mongo (backward-compatible).
+	* Call the wrapped function with circuit breaker protection
 	*/
-	dialect;
-	/** Supported filter operators (neutral name → emitted token), from the dialect. */
-	get operators() {
-		return this.dialect.operators;
-	}
-	constructor(options = {}) {
-		this.dialect = options.dialect ?? MONGO_DIALECT;
-		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;
-		this.strictFilterFields = options.strictFilterFields ?? process.env.ARC_STRICT_QUERY_PARAMS === "true";
-		if (options.allowedFilterFields) {
-			this._allowedFilterFields = new Set(options.allowedFilterFields);
-			this.allowedFilterFields = options.allowedFilterFields;
+	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);
 		}
-		if (options.allowedSortFields) {
-			this._allowedSortFields = new Set(options.allowedSortFields);
-			this.allowedSortFields = options.allowedSortFields;
+		let isProbe = false;
+		if (this.state === CircuitState.HALF_OPEN) {
+			if (this.halfOpenInFlight >= this.halfOpenMaxProbes) {
+				if (this.fallback) return this.fallback(...args);
+				throw new CircuitBreakerError(`Circuit breaker is HALF_OPEN for ${this.name} — probe slots full`, CircuitState.HALF_OPEN);
+			}
+			this.halfOpenInFlight++;
+			isProbe = true;
 		}
-		if (options.allowedOperators) {
-			this._allowedOperators = new Set(options.allowedOperators);
-			this.allowedOperators = options.allowedOperators;
+		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;
+		} finally {
+			if (isProbe) this.halfOpenInFlight--;
 		}
 	}
 	/**
-	* Parse URL query parameters into structured query options
+	* Execute function with timeout. With `propagateAbort`, the wrapped fn
+	* receives a trailing AbortSignal that fires on timeout — the breaker's
+	* timeout otherwise only rejects the CALLER while the underlying work
+	* keeps consuming sockets/pool slots to completion.
 	*/
-	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;
+	async executeWithTimeout(args) {
+		const controller = this.propagateAbort ? new AbortController() : void 0;
+		return new Promise((resolve, reject) => {
+			const timeoutId = setTimeout(() => {
+				controller?.abort(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
+				reject(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
+			}, this.timeout);
+			(controller ? this.fn(...args, controller.signal) : this.fn(...args)).then((result) => {
+				clearTimeout(timeoutId);
+				resolve(result);
+			}).catch((error) => {
+				clearTimeout(timeoutId);
+				reject(error);
+			});
+		});
 	}
 	/**
-	* 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' }] }
+	* Handle successful call
 	*/
-	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 });
+	onSuccess() {
+		this.failures = 0;
+		this.successes++;
+		if (this.state === CircuitState.HALF_OPEN) {
+			if (this.successes >= this.successThreshold) {
+				this.setState(CircuitState.CLOSED);
+				this.successes = 0;
 			}
-			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;
+	/**
+	* 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();
 		}
-		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;
+	/**
+	* Change circuit state
+	*/
+	setState(newState) {
+		const oldState = this.state;
+		if (oldState !== newState) {
+			this.state = newState;
+			if (this.onStateChange) this.onStateChange(oldState, newState);
 		}
-		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.
+	* Manually open the circuit
 	*/
-	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));
+	open() {
+		this.setState(CircuitState.OPEN);
+		this.nextAttempt = Date.now() + this.resetTimeout;
+		this.openedAt = Date.now();
 	}
 	/**
-	* 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.
+	* Manually close the circuit
 	*/
-	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;
+	close() {
+		this.failures = 0;
+		this.successes = 0;
+		this.setState(CircuitState.CLOSED);
+		this.openedAt = null;
 	}
 	/**
-	* 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.
+	* Get current statistics
 	*/
-	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)) {
-			if (this.strictFilterFields) throw new ValidationError(`Unknown filter field: ${bareKey}. Allowed: ${[...this._allowedFilterFields].sort().join(", ")}`);
-			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 fieldOps = {};
-				let needsCaseInsensitive = false;
-				for (const [op, opValue] of Object.entries(operatorObj)) {
-					const token = this.operators[op];
-					if (token) {
-						fieldOps[token] = this.parseFilterValue(opValue, op);
-						if (op === "contains" || op === "like") needsCaseInsensitive = true;
-					}
-				}
-				if (needsCaseInsensitive) Object.assign(fieldOps, this.dialect.caseInsensitiveModifier());
-				filters[key] = fieldOps;
-				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 token = this.operators[operator];
-			const parsedValue = this.parseFilterValue(value, operator);
-			if (!filters[fieldName]) filters[fieldName] = {};
-			const fieldFilter = filters[fieldName];
-			fieldFilter[token] = parsedValue;
-			if (operator === "contains" || operator === "like") Object.assign(fieldFilter, this.dialect.caseInsensitiveModifier());
-		} else if (!operator) filters[fieldName] = this.parseFilterValue(value);
+	getStats() {
+		return {
+			name: this.name,
+			state: this.state,
+			failures: this.failures,
+			successes: this.successes,
+			totalCalls: this.totalCalls,
+			openedAt: this.openedAt,
+			lastCallAt: this.lastCallAt
+		};
 	}
-	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);
+	/**
+	* Get current state
+	*/
+	getState() {
+		return this.state;
 	}
-	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;
+	/**
+	* Check if circuit is open
+	*/
+	isOpen() {
+		return this.state === CircuitState.OPEN;
 	}
 	/**
-	* 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.
+	* Check if circuit is closed
 	*/
-	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",
-					/**
-					* The cap is DOCUMENTED here, not enforced — deliberately.
-					*
-					* Both layers that handle `limit` CLAMP it: this parser
-					* (`Math.min(…, this.maxLimit)`) and `QueryResolver`. Emitting
-					* `maximum` contradicted them, because arc layers this schema as the
-					* route's `listQuery` and Fastify validates the querystring BEFORE
-					* either runs — so the clamp was unreachable and `?limit=200` became a
-					* hard 400.
-					*
-					* That combination is worse than either policy alone. Asking for more
-					* rows than allowed is a benign over-ask with an obvious right answer
-					* (give the maximum); turning it into a validation failure means a UI
-					* passing a generous page size gets NOTHING, and a caller that does not
-					* inspect the error body renders it as an empty list — a 400 disguised
-					* as "no results", which is the hardest kind to find.
-					*
-					* A deployment wanting refusal instead of clamping should say so in the
-					* parser's policy, where both halves can agree, not in a schema that
-					* silently outranks them. Mirrors the same fix in mongokit's
-					* `buildQuerySchema`.
-					*/
-					description: `Number of items per page (values above ${this.maxLimit} are capped to ${this.maxLimit})`,
-					default: this.defaultLimit,
-					minimum: 1
-				},
-				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")
-				}
-			}
-		};
+	isClosed() {
+		return this.state === CircuitState.CLOSED;
 	}
-	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;
+	/**
+	* Reset statistics
+	*/
+	reset() {
+		this.failures = 0;
+		this.successes = 0;
+		this.totalCalls = 0;
+		this.lastCallAt = null;
+		this.openedAt = null;
+		this.setState(CircuitState.CLOSED);
 	}
 };
 /**
-* Create a new ArcQueryParser instance
-*/
-function createQueryParser(options) {
-	return new ArcQueryParser(options);
-}
-//#endregion
-//#region src/utils/responseSchemas.ts
-/**
-* JSON Schema definitions for arc API responses.
+* Create a circuit breaker with sensible defaults
 *
-* 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.
+* @example
+* const emailBreaker = createCircuitBreaker(
+*   async (to, subject, body) => sendEmail(to, subject, body),
+*   { name: 'email-service' }
+* );
 */
+function createCircuitBreaker(fn, options) {
+	return new CircuitBreaker(fn, options);
+}
 /**
-* Pagination schema - matches MongoKit/Arc runtime format
-*
-* Runtime format (flat fields):
-* { page, limit, total, pages, hasNext, hasPrev }
+* Circuit breaker registry for managing multiple breakers
 */
-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
-		}
-	},
-	required: [
-		"page",
-		"limit",
-		"total",
-		"pages",
-		"hasNext",
-		"hasPrev"
-	]
+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();
+	}
 };
 /**
-* List response schema — accepts every wire shape `toCanonicalList` can
-* emit. Hosts who know their endpoint only ever produces one variant can
-* pin to a narrower helper (sharper OpenAPI docs, same serializer speed):
-*   - `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 }`
-*
-* SHAPE: one merged permissive object, NOT a `oneOf` union (2.22). The
-* pre-2.22 union was semantically identical on the wire — every variant is
-* `additionalProperties: true` and the property definitions never conflict
-* (`next` only exists on keyset, the offset counters only on offset/
-* aggregate; fast-json-stringify skips undefined optionals) — but
-* fast-json-stringify implements top-level `oneOf` by running full AJV
-* validation PER RESPONSE to pick the branch, on the hottest route of
-* every arc app. The merge keeps the exact bytes (pinned by
-* `tests/utils/list-response-serialization.test.ts`) and drops the
-* per-response branch validation. Only `data` is required — the one field
-* all four variants share.
+* Create a new CircuitBreakerRegistry instance.
+* Use this instead of a global singleton — attach to fastify.arc or pass explicitly.
 */
-function listResponse(itemSchema) {
-	return {
-		type: "object",
-		properties: {
-			method: {
-				type: "string",
-				description: "Pagination method discriminant — 'offset' | 'keyset' | 'aggregate'; absent on bare lists.",
-				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
-			},
-			hasMore: { type: "boolean" },
-			next: {
-				type: ["string", "null"],
-				description: "Cursor token for the next page, or null."
-			}
-		},
-		required: ["data"],
-		additionalProperties: true
-	};
-}
-/** 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
-	};
-}
-/** 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
-	};
-}
-/** 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 createCircuitBreakerRegistry() {
+	return new CircuitBreakerRegistry();
 }
-/** 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
-	};
+//#endregion
+//#region src/utils/compensation.ts
+/**
+* Observability hooks must never alter the transaction: a throwing metrics
+* sink must not fail a step that succeeded, trigger compensation, or become
+* an unhandled rejection from a detached fire-and-forget chain. Containment
+* is reported via `hooks.onHookError` so broken sinks stay visible.
+*/
+function safeHook(name, invoke, hooks) {
+	try {
+		invoke();
+	} catch (err) {
+		try {
+			hooks?.onHookError?.(name, err instanceof Error ? err : new Error(String(err)));
+		} catch {}
+	}
 }
-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) {
+/**
+* Run steps in order with automatic compensation on failure.
+*
+* @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
+*/
+async function withCompensation(_name, steps, initialContext, hooks) {
+	const ctx = { ...initialContext };
+	const completedSteps = [];
+	const results = {};
+	const completed = [];
+	for (const step of steps) {
+		if (step.fireAndForget) {
+			step.execute(ctx).then((result) => safeHook("onStepComplete", () => hooks?.onStepComplete?.(step.name, result), hooks), (err) => safeHook("onStepFailed", () => hooks?.onStepFailed?.(step.name, err instanceof Error ? err : new Error(String(err))), hooks)).catch(() => {});
+			continue;
+		}
+		try {
+			const result = await step.execute(ctx);
+			completedSteps.push(step.name);
+			results[step.name] = result;
+			completed.push({
+				step,
+				result
+			});
+			safeHook("onStepComplete", () => hooks?.onStepComplete?.(step.name, result), hooks);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			safeHook("onStepFailed", () => hooks?.onStepFailed?.(step.name, error), hooks);
+			const compensationErrors = await rollback(ctx, completed, hooks);
+			return {
+				success: false,
+				completedSteps,
+				results,
+				failedStep: step.name,
+				error: error.message,
+				...compensationErrors.length > 0 ? { compensationErrors } : {}
+			};
+		}
+	}
 	return {
-		description: ERROR_DESCRIPTIONS[status] ?? "Error",
-		content: { "application/json": { schema: errorContractSchema$1 } }
+		success: true,
+		completedSteps,
+		results
 	};
 }
-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"
-		}
-	},
-	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"
+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);
+			safeHook("onCompensate", () => hooks?.onCompensate?.(entry.step.name), hooks);
+		} catch (err) {
+			errors.push({
+				step: entry.step.name,
+				error: err instanceof Error ? err.message : String(err)
+			});
 		}
 	}
-};
-/**
-* Get standard list query parameters schema
-*/
-function getListQueryParams() {
+	return errors;
+}
+function defineCompensation(name, steps) {
 	return {
-		type: "object",
-		properties: {
-			...queryParams.pagination,
-			...queryParams.sorting,
-			...queryParams.filtering
-		},
-		additionalProperties: true
+		name,
+		execute: (initialContext, hooks) => withCompensation(name, steps, initialContext, hooks)
 	};
 }
+//#endregion
+//#region src/utils/defineErrorMapper.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.
+* 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.
+*
+* 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.
 */
-const genericItemSchema = {
-	type: "object",
-	additionalProperties: true
-};
+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";
 /**
-* 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).
+* Create a typed guard. See module JSDoc for usage.
 */
-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;
+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
 /**
-* 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.
-*
-* These defaults use `additionalProperties: true` so all fields pass through.
-* Override with specific schemas for full serialization performance + safety.
+* Wrap a raw Fastify handler with Arc's response shape and error handling.
 *
-* Note: `example` properties are stripped from defaults so they work with
-* any Fastify instance (not just createApp which adds `keywords: ['example']`).
+* @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 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 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
@@ -1472,4 +1472,4 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
-export { createCircuitBreakerRegistry as A, defineCompensation as C, CircuitBreakerRegistry as D, CircuitBreakerError as E, CircuitState as O, defineErrorMapper as S, CircuitBreaker as T, createQueryParser as _, deleteResponse as a, NEUTRAL_DIALECT as b, getDefaultCrudSchemas as c, listResponse as d, offsetListResponse as f, ArcQueryParser as g, responses as h, bareListResponse as i, createCircuitBreaker as k, getListQueryParams as l, queryParams as m, scheduleBackground as n, errorContractSchema$1 as o, paginationSchema as p, aggregateListResponse as r, errorDetailSchema$1 as s, createStateMachine as t, keysetListResponse as u, handleRaw as v, withCompensation as w, defineGuard as x, MONGO_DIALECT as y };
+export { scheduleBackground as A, paginationSchema as C, createQueryParser as D, ArcQueryParser as E, MONGO_DIALECT as O, offsetListResponse as S, responses as T, errorDetailSchema$1 as _, defineCompensation as a, keysetListResponse as b, CircuitBreakerError as c, createCircuitBreaker as d, createCircuitBreakerRegistry as f, errorContractSchema$1 as g, deleteResponse as h, defineErrorMapper as i, NEUTRAL_DIALECT as k, CircuitBreakerRegistry as l, bareListResponse as m, handleRaw as n, withCompensation as o, aggregateListResponse as p, defineGuard as r, CircuitBreaker as s, createStateMachine as t, CircuitState as u, getDefaultCrudSchemas as v, queryParams as w, listResponse as x, getListQueryParams as y };