@classytic/arc 2.41.1 → 2.43.0

package/dist/{utils-CxcctrAh.mjs → utils-ec1oTo1n.mjs}

@@ -1,215 +1,239 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { m as RESERVED_QUERY_PARAMS } from "./constants-D5Ubn1fe.mjs";
-import { arcLog } from "./logger/index.mjs";
-import { t as ArcError, u as ValidationError } from "./errors-BH7YU_9O.mjs";
-import { scheduleBackground } from "@classytic/repo-core/cache";
-import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { h as RESERVED_QUERY_PARAMS } from "./constants-Cu7Mx7_U.mjs";
+import { t as arcLog } from "./logger-DXjfIqjV.mjs";
+import { t as ArcError, u as ValidationError } from "./errors-CtrywMHP.mjs";
+import { errorContractSchema as errorContractSchema$1 } from "@classytic/repo-core/errors";
+import { readEnv } from "@classytic/primitives/environment";
+import { OPERATOR_DESCRIPTIONS, URL_OPERATORS, escapeRegex, isQueryGrammarError, readFilterClauses, readPageRequest, readSearch, readSelect, readSort } from "@classytic/repo-core/query-parser";
 //#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.
+* Filter dialects — what `ArcQueryParser` EMITS. Reading a URL (keys, operators, coercion,
+* refusals) is repo-core's shared grammar; a dialect turns its canonical clauses into one store's
+* filter shape. The default is the Mongo record dialect arc's pipeline already speaks
+* (`toRepositoryFilter` → Filter IR), so its meaning matches `parseUrl` and mongokit exactly —
+* `runQueryGrammarConformance` holds all three to the same rows.
 */
+/** One clause → one field condition, in Mongo record syntax with the Filter IR's meaning. */
+function mongoCondition(clause) {
+	switch (clause.op) {
+		case "eq": return clause.value;
+		case "ne": return clause.value === null ? { $ne: null } : { $nin: [clause.value, null] };
+		case "nin": return { $nin: clause.values.includes(null) ? [...clause.values] : [...clause.values, null] };
+		case "in": return { $in: [...clause.values] };
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte": return { [`$${clause.op}`]: clause.value };
+		case "exists": return clause.value ? { $ne: null } : null;
+		case "contains": return {
+			$regex: escapeRegex(clause.text),
+			$options: "i"
+		};
+		case "startsWith": return {
+			$regex: `^${escapeRegex(clause.text)}`,
+			$options: "i"
+		};
+		case "endsWith": return {
+			$regex: `${escapeRegex(clause.text)}$`,
+			$options: "i"
+		};
+		case "ieq": return {
+			$regex: `^${escapeRegex(clause.text)}$`,
+			$options: "i"
+		};
+		case "regex": return clause.flags ? {
+			$regex: clause.pattern,
+			$options: clause.flags
+		} : { $regex: clause.pattern };
+	}
+}
+/** Merge conditions on one field into one operator object; `$and` when an operator repeats. */
+function mergeByField(clauses, condition, eqToken) {
+	const merged = {};
+	const overflow = [];
+	for (const clause of clauses) {
+		const next = condition(clause);
+		if (!(clause.field in merged)) {
+			merged[clause.field] = next;
+			continue;
+		}
+		const left = asOperators(merged[clause.field], eqToken);
+		const right = asOperators(next, eqToken);
+		if (left && right && !Object.keys(right).some((op) => op in left)) merged[clause.field] = {
+			...left,
+			...right
+		};
+		else overflow.push({ [clause.field]: next });
+	}
+	return overflow.length > 0 ? {
+		...merged,
+		$and: overflow
+	} : merged;
+}
+function asOperators(condition, eqToken) {
+	if (condition === null || Array.isArray(condition) || condition instanceof Date) return condition === null ? void 0 : { [eqToken]: condition };
+	if (typeof condition === "object") return condition;
+	return { [eqToken]: condition };
+}
 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" })
+	emit: (clauses) => mergeByField(clauses, mongoCondition, "$eq"),
+	tokens: [
+		"$eq",
+		"$ne",
+		"$gt",
+		"$gte",
+		"$lt",
+		"$lte",
+		"$in",
+		"$nin",
+		"$regex",
+		"$options",
+		"$and"
+	]
 };
 /**
-* 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.
+* Store-neutral: `{ field: { <op>: value } }` with the grammar's own operator names, for a host
+* that compiles the canonical clauses itself.
 */
 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 })
+	emit: (clauses) => mergeByField(clauses, (clause) => {
+		switch (clause.op) {
+			case "in":
+			case "nin": return { [clause.op]: clause.values };
+			case "contains":
+			case "startsWith":
+			case "endsWith":
+			case "ieq": return { [clause.op]: clause.text };
+			case "regex": return clause.flags ? {
+				regex: clause.pattern,
+				flags: clause.flags
+			} : { regex: clause.pattern };
+			default: return { [clause.op]: clause.value };
+		}
+	}, "eq"),
+	tokens: [
+		"eq",
+		"ne",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"in",
+		"nin",
+		"exists",
+		"contains",
+		"startsWith",
+		"endsWith",
+		"ieq",
+		"regex",
+		"flags",
+		"$and"
+	]
 };
 //#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.)
-* // 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(),
-* });
-*
-* // Use custom parser for SQL databases
-* defineResource({
-*   name: 'user',
-*   adapter: ...,
-*   queryParser: new PgQueryParser(),
-* });
+* Arc's default URL-to-query parser. Reading the URL is repo-core's shared grammar (the same
+* contract as mongokit's `QueryParser` and `parseUrl`); this adds arc's populate handling and
+* emits filters through a {@link FilterDialect}. Swap in any `QueryParserInterface` via
+* `defineResource({ queryParser })`.
 */
 const log = arcLog("queryParser");
+const FIELD_RE = /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)*$/;
 /**
-* 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.
+* Arc's default query parser:
+* - Paging `?page=1&limit=20`, keyset `?after=cursor`; sort `?sort=-createdAt,name`
+* - Filters bare (`?status=active&price[gte]=100`) or in the `?filter[...]` envelope, which
+*   avoids collisions with reserved keys (`page`, `sort`, ...)
+* - Search `?search=`, populate `?populate=a,b`, select `?select=a,-b`
 */
 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.
+	* Public so `QueryResolver` reuses this cap instead of stacking its own
+	* (independent caps silently truncate to the lowest).
 	*/
 	maxLimit;
 	defaultLimit;
 	maxRegexLength;
 	maxSearchLength;
-	maxFilterDepth;
-	_allowedFilterFields;
-	_allowedSortFields;
-	_allowedOperators;
-	strictFilterFields;
+	strict;
+	dialect;
 	/** 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;
-		}
-		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;
-		}
+		this.strict = options.strictFilterFields ?? readEnv(process.env).bool("ARC_STRICT_QUERY_PARAMS", true);
+		if (options.allowedFilterFields) this.allowedFilterFields = options.allowedFilterFields;
+		if (options.allowedSortFields) this.allowedSortFields = options.allowedSortFields;
+		if (options.allowedOperators) this.allowedOperators = options.allowedOperators;
 	}
-	/**
-	* Parse URL query parameters into structured query options
-	*/
+	/** Parse URL query parameters into structured query options. Invalid input is a 400. */
 	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 onInvalid = this.strict ? void 0 : (error) => {
+			if (error.meta.kind !== "policy") throw error;
+			this.drop(error);
+		};
+		const page = this.read(() => readPageRequest({
+			page: q.page,
+			limit: q.limit,
+			after: q.after,
+			cursor: q.cursor
+		}, {
+			defaultLimit: this.defaultLimit,
+			maxLimit: this.maxLimit
+		}), { limit: Math.min(this.defaultLimit, this.maxLimit) });
+		const { clauses } = this.read(() => readFilterClauses(q, {
+			allowedFilterFields: this.allowedFilterFields,
+			allowedOperators: this.allowedOperators,
+			maxTextLength: this.maxRegexLength,
+			reservedParams: [...RESERVED_QUERY_PARAMS],
+			onInvalid
+		}), {
+			clauses: [],
+			extensions: []
+		});
 		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,
+			filters: this.dialect.emit(clauses),
+			limit: page.limit,
+			sort: this.read(() => readSort(q.sort, {
+				allowedSortFields: this.allowedSortFields,
+				onInvalid
+			}), void 0),
 			populate,
 			populateOptions,
-			search,
-			page: after ? void 0 : page,
-			after,
-			select
+			search: this.read(() => readSearch(q.search, { maxSearchLength: this.maxSearchLength }), void 0),
+			page: page.after ? void 0 : page.page ?? 1,
+			after: page.after,
+			select: this.read(() => readSelect(q.select, { onInvalid }), void 0)
 		};
 	}
-	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);
+	/** A grammar refusal is a 400 (`ValidationError`) — unless lenient and only an allowlist miss. */
+	read(fn, fallback) {
+		try {
+			return fn();
+		} catch (error) {
+			if (!isQueryGrammarError(error)) throw error;
+			if (this.strict || error.meta.kind !== "policy") throw toValidationError(error);
+			this.drop(error);
+			return fallback;
+		}
 	}
-	parseString(value) {
-		if (value === void 0 || value === null) return void 0;
-		const str = String(value).trim();
-		return str.length > 0 ? str : void 0;
+	drop(error) {
+		log.warn(`query input dropped (ARC_STRICT_QUERY_PARAMS=false): ${error.message}`);
 	}
 	/**
-	* 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' }] }
+	* Simple `?populate=author,category`, or bracket `?populate[author][select]=name,email` and
+	* `?populate[author][match][field]=value` (field equality only).
 	*/
 	parsePopulate(value) {
 		if (value === void 0 || value === null) return {};
@@ -218,18 +242,14 @@ var ArcQueryParser = class {
 			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];
+			for (const [path, config] of Object.entries(value)) {
+				if (!FIELD_RE.test(path)) throw new ValidationError(`Populate path "${path}" is not a field 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;
+					if (cfg.match !== void 0) option.match = this.parsePopulateMatch(path, cfg.match);
 					options.push(option);
 				} else options.push({ path });
 			}
@@ -237,177 +257,20 @@ var ArcQueryParser = class {
 		}
 		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;
-		}
-		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;
-		}
-		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.
+	* A populate `match` is plain field EQUALITY in bracket form (`populate[p][match][f]=v`). A `$`
+	* key, a nested object or a non-object `match` (a JSON string) is refused, never passed to the
+	* driver or dropped — a dropped match populates every document.
 	*/
-	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);
-	}
-	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;
+	parsePopulateMatch(path, match) {
+		if (typeof match !== "object" || match === null || Array.isArray(match)) throw new ValidationError(`Populate match on "${path}" must use bracket form: populate[${path}][match][field]=value`);
+		for (const [key, value] of Object.entries(match)) if (!FIELD_RE.test(key) || typeof value === "object" && value !== null) throw new ValidationError(`Populate match on "${path}" accepts field equality only: "${key}"`);
+		return match;
 	}
-	/**
-	* 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.
-	*/
+	/** JSON Schema for list query parameters (auto-detected by `defineResource`). */
 	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}`;
-		});
+		const allowed = this.allowedOperators;
+		const operators = allowed ? URL_OPERATORS.filter((op) => allowed.includes(op)) : URL_OPERATORS;
 		return {
 			type: "object",
 			properties: {
@@ -420,26 +283,9 @@ var ArcQueryParser = class {
 				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`.
+					* No `maximum` — deliberately. This schema validates the querystring
+					* BEFORE the parser/QueryResolver clamp runs, so a `maximum` would turn
+					* a benign over-ask into a 400 instead of capping it.
 					*/
 					description: `Number of items per page (values above ${this.maxLimit} are capped to ${this.maxLimit})`,
 					default: this.defaultLimit,
@@ -466,29 +312,34 @@ var ArcQueryParser = class {
 					type: "string",
 					description: "Cursor value for keyset pagination"
 				},
+				before: {
+					type: "string",
+					description: "Cursor from a page's `prev` — fetch the page before it"
+				},
+				mode: {
+					type: "string",
+					enum: ["offset", "keyset"],
+					description: "Pagination mode (default offset). `keyset` walks by cursor"
+				},
 				_filterOperators: {
 					type: "string",
-					description: ["Available filter operators (use as field[operator]=value):", ...operatorLines].join("\n")
+					description: ["Available filter operators (use as field[operator]=value):", ...operators.map((op) => `  ${op}: ${OPERATOR_DESCRIPTIONS[op] ?? op}`)].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
-*/
+/** Create a new ArcQueryParser instance. */
 function createQueryParser(options) {
 	return new ArcQueryParser(options);
 }
+/** The grammar's refusal as arc's 400, keeping the offending parameter for `details[]`. */
+function toValidationError(error) {
+	return new ValidationError(error.message, [{
+		field: error.meta.param,
+		message: error.meta.reason
+	}]);
+}
 //#endregion
 //#region src/utils/responseSchemas.ts
 /**
@@ -614,6 +465,19 @@ function listResponse(itemSchema) {
 			next: {
 				type: ["string", "null"],
 				description: "Cursor token for the next page, or null."
+			},
+			prev: {
+				type: ["string", "null"],
+				description: "Cursor token for the previous page, or null."
+			},
+			end: {
+				type: ["string", "null"],
+				description: "Cursor at the page's last row."
+			},
+			totalIsEstimate: { type: "boolean" },
+			countedAt: {
+				type: ["string", "null"],
+				format: "date-time"
 			}
 		},
 		additionalProperties: true
@@ -656,6 +520,14 @@ function offsetListResponse(itemSchema) {
 			hasPrev: {
 				type: "boolean",
 				example: false
+			},
+			totalIsEstimate: {
+				type: "boolean",
+				example: false
+			},
+			countedAt: {
+				type: ["string", "null"],
+				format: "date-time"
 			}
 		},
 		required: [
@@ -696,6 +568,15 @@ function keysetListResponse(itemSchema) {
 			next: {
 				type: ["string", "null"],
 				description: "Cursor token for the next page, or null."
+			},
+			prev: {
+				type: ["string", "null"],
+				description: "Cursor token for the previous page, or null."
+			},
+			hasPrev: { type: "boolean" },
+			end: {
+				type: ["string", "null"],
+				description: "Cursor at the page's last row."
 			}
 		},
 		required: [
@@ -859,14 +740,17 @@ function getListQueryParams() {
 	};
 }
 /**
-* 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.
+* Default row/document schema when the resource declares none: `{}`, which
+* fast-json-stringify hands to `JSON.stringify`.
+*
+* NOT `{ type: 'object', additionalProperties: true }`: with no declared
+* properties that form walks every key of every row through fjs's generic
+* path — ~3.5x slower than `JSON.stringify` for the same bytes (pinned in
+* `tests/utils/default-crud-serialization.test.ts`). It never filtered a field
+* either, so it bought nothing. This is serializer-only: published OpenAPI
+* builds CRUD responses from the resource's own component schema.
 */
-const genericItemSchema = {
-	type: "object",
-	additionalProperties: true
-};
+const genericItemSchema = {};
 /**
 * Recursively strip `example` keys from a schema object.
 * The `example` keyword is OpenAPI metadata — not standard JSON Schema —
@@ -886,12 +770,10 @@ function stripExamples(schema) {
 /**
 * 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.
+* The envelope is typed (its fields are known); rows and single documents
+* pass through as `{}` — see `genericItemSchema`. A resource that declares a
+* response schema with real `properties` gets typed row serialization, which
+* also drops undeclared fields.
 *
 * Note: `example` properties are stripped from defaults so they work with
 * any Fastify instance (not just createApp which adds `keywords: ['example']`).
@@ -944,14 +826,44 @@ const CircuitState = {
 	OPEN: "OPEN",
 	HALF_OPEN: "HALF_OPEN"
 };
-var CircuitBreakerError = class extends Error {
+/**
+* Thrown when a call is refused because the circuit is OPEN (or HALF_OPEN with
+* every probe slot taken).
+*
+* An `ArcError` with status **503**, code `arc.circuit_open`. It extended plain
+* `Error` and carried no status, so an open circuit reaching arc's error
+* handler was classified `arc.internal_error`: a 500, logged at error level
+* with a stack trace, once per fast-failed call. That is the opposite of what
+* a breaker is for — it turned deliberate, cheap load shedding into the
+* loudest failure in the logs, during exactly the outage where it fires
+* thousands of times a minute.
+*
+* `retryAfter` (seconds, rounded up) is when the circuit next probes; the
+* error handler sends it as `Retry-After`, so well-behaved clients back off
+* for as long as the breaker is actually going to refuse them.
+*/
+var CircuitBreakerError = class extends ArcError {
 	state;
-	constructor(message, state) {
-		super(message);
+	/** Seconds until the circuit next probes, when known. */
+	retryAfter;
+	constructor(message, state, retryAfter) {
+		super(message, {
+			code: "arc.circuit_open",
+			statusCode: 503,
+			details: {
+				state,
+				...retryAfter !== void 0 ? { retryAfter } : {}
+			}
+		});
 		this.name = "CircuitBreakerError";
 		this.state = state;
+		if (retryAfter !== void 0) this.retryAfter = retryAfter;
 	}
 };
+/** Whole seconds until `until` (epoch ms), never below 1 — `Retry-After: 0` invites a stampede. */
+function secondsUntil(until) {
+	return Math.max(1, Math.ceil((until - Date.now()) / 1e3));
+}
 var CircuitBreaker = class {
 	state = CircuitState.CLOSED;
 	failures = 0;
@@ -996,7 +908,7 @@ var CircuitBreaker = class {
 		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);
+				const error = new CircuitBreakerError(`Circuit breaker is OPEN for ${this.name}`, CircuitState.OPEN, secondsUntil(this.nextAttempt));
 				if (this.fallback) return this.fallback(...args);
 				throw error;
 			}
@@ -1006,7 +918,7 @@ var CircuitBreaker = class {
 		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);
+				throw new CircuitBreakerError(`Circuit breaker is HALF_OPEN for ${this.name} — probe slots full`, CircuitState.HALF_OPEN, Math.max(1, Math.ceil(this.timeout / 1e3)));
 			}
 			this.halfOpenInFlight++;
 			isProbe = true;
@@ -1392,27 +1304,26 @@ function defineGuard(config) {
 *   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)
+* @returns The reply, so Fastify waits for it: resolving `undefined` after `reply.send()` while an
+*   async `preSerialization` hook (idempotency, encryption) is pending re-sends an empty body.
 */
 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);
+			if (reply.sent) return reply;
+			if (result === void 0 || result === null) return reply.code(statusCode).send();
+			return 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;
-			}
+			if (reply.sent) return reply;
+			if (err instanceof ArcError) return reply.code(err.statusCode).send({
+				error: err.message,
+				code: err.code,
+				...err.details ? { details: err.details } : {}
+			});
 			const error = err;
 			const code = error.statusCode ?? error.status ?? 500;
-			reply.code(code).send({
+			return reply.code(code).send({
 				error: error.message ?? "Internal server error",
 				...error.code && { code: error.code }
 			});
@@ -1521,4 +1432,4 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
-export { NEUTRAL_DIALECT as A, offsetListResponse as C, ArcQueryParser as D, responses as E, createQueryParser as O, listResponse as S, queryParams as T, errorContractSchema$1 as _, defineCompensation as a, getListQueryParams as b, CircuitBreaker as c, CircuitState as d, createCircuitBreaker as f, deleteResponse as g, bareListResponse as h, defineErrorMapper as i, scheduleBackground as j, MONGO_DIALECT as k, CircuitBreakerError as l, aggregateListResponse as m, handleRaw as n, withCompensation as o, createCircuitBreakerRegistry as p, defineGuard as r, RedisCircuitBreakerState as s, createStateMachine as t, CircuitBreakerRegistry as u, errorDetailSchema$1 as v, paginationSchema as w, keysetListResponse as x, getDefaultCrudSchemas as y };
+export { paginationSchema as C, createQueryParser as D, ArcQueryParser as E, MONGO_DIALECT as O, offsetListResponse as S, responses as T, errorContractSchema$1 as _, defineCompensation as a, keysetListResponse as b, CircuitBreaker as c, CircuitState as d, createCircuitBreaker as f, deleteResponse as g, bareListResponse as h, defineErrorMapper as i, NEUTRAL_DIALECT as k, CircuitBreakerError as l, aggregateListResponse as m, handleRaw as n, withCompensation as o, createCircuitBreakerRegistry as p, defineGuard as r, RedisCircuitBreakerState as s, createStateMachine as t, CircuitBreakerRegistry as u, getDefaultCrudSchemas as v, queryParams as w, listResponse as x, getListQueryParams as y };