@classytic/mongokit 3.39.0 → 3.40.0

package/dist/index.mjs

@@ -1,23 +1,24 @@
 import { n as idVariants } from "./id-resolution-BqDrk0S2.mjs";
-import { _ as resetCapabilityProbeCache, a as supportsTransactions, b as transactionResolutionOf, c as ALL_OPERATIONS, d as READ_OPERATIONS, f as operationsByPolicyKey, g as probeMongoCapabilities, h as classifyHelloReply, i as isTransactionUnsupported, l as MUTATING_OPERATIONS, m as capabilitiesForSupport, n as Repository, o as withTransaction, p as MONGOKIT_CAPABILITIES, r as batchTransaction, s as AggregationBuilder, t as HOOK_PRIORITY, u as OP_REGISTRY, v as resolveMongoCapabilities, x as createMongoPurgePort, y as resolveTransactionSupport } from "./Repository-D7fDpyFx.mjs";
-import { _ as compileFilterToMongo, g as LookupBuilder, x as isCreateManyPartialError } from "./update-c_01A0if.mjs";
+import { a as MUTATING_OPERATIONS, c as operationsByPolicyKey, i as ALL_OPERATIONS, l as createMongoPurgePort, n as Repository, o as OP_REGISTRY, r as AggregationBuilder, s as READ_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-BMgPSkqZ.mjs";
+import { C as isCreateManyPartialError, g as LookupBuilder, v as compileFilterToMongo } from "./update-DG0fCwRJ.mjs";
 import { n as warn, t as configureLogger } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, r as adminBypass, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-B5eiaItQ.mjs";
+import { c as classifyHelloReply, d as resolveMongoCapabilities, f as resolveTransactionSupport, i as withTransaction, l as probeMongoCapabilities, n as isTransactionUnsupported, o as MONGOKIT_CAPABILITIES, p as transactionResolutionOf, r as supportsTransactions, s as capabilitiesForSupport, t as batchTransaction, u as resetCapabilityProbeCache } from "./transaction-B5L9glO0.mjs";
+import { _ as AuditTrailQuery, a as declareTenantContextKey, b as auditLogPlugin, c as tenantContextKeysOf, d as ensureSequenceAtLeast, f as getNextSequence, g as cachePlugin, h as sequentialId, i as multiTenantPlugin, l as customIdPlugin, m as readSequence, n as softDeletePlugin, o as forwardScope, p as prefixedId, r as adminBypass, s as isScopeKey, t as timestampPlugin, u as dateSequentialId, v as auditTrailPlugin, y as ensureAuditTrailReady } from "./timestamp.plugin-DF0gJB6p.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-C63pGn1d.mjs";
-import { a as getPaginationDefaults, i as configurePaginationDefaults, o as resetPaginationDefaults, t as PaginationEngine } from "./PaginationEngine-DQ7beTCR.mjs";
-import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
-import { t as createRepository } from "./create-repository-DOe9E_5F.mjs";
+import { a as getPaginationDefaults, i as configurePaginationDefaults, o as resetPaginationDefaults, t as PaginationEngine } from "./PaginationEngine-Dvl8jcRY.mjs";
+import { GEO_OPERATORS, parseGeoFilter } from "./query/primitives/geo.mjs";
+import { t as createRepository } from "./create-repository-BzBUMvd1.mjs";
 import { n as defineModel, r as isModelRegistered, t as ModelCollisionError } from "./model-registry-ClKtWiHa.mjs";
-import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "./validation-chain.plugin-Bju1D1Sn.mjs";
+import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "./validation-chain.plugin-BLY2gLEk.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-FSQFLpsU.mjs";
-import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
+import { buildFieldTypeMap, coerceHeuristic } from "./query/primitives/coercion.mjs";
 import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
 import { n as createMemoryCache, t as toPlain } from "./to-plain-vksRrLtc.mjs";
 import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-waUVQwK4.mjs";
 import { runChunkedPurge } from "@classytic/repo-core/repository";
-import { isControlParam } from "@classytic/repo-core/query-parser";
+import { OPERATOR_DESCRIPTIONS, QueryGrammarError, URL_OPERATORS, clausesToFilter, escapeRegex, isQueryGrammarError, readFilterClauses, readPageRequest, readSearch, readSelect, readSort } from "@classytic/repo-core/query-parser";
 //#region src/actions/cascade-references.ts
 /**
 * cascadePurgeReferences — imperative, multi-relation "purge by reference".
@@ -357,410 +358,134 @@ function parseAggregation(rt, aggregate) {
 	return pipeline.length > 0 ? pipeline : void 0;
 }
 //#endregion
-//#region src/query/parser/regex-safety.ts
-/**
-* Regex safety — ReDoS protection for user-supplied patterns.
-*
-* Two independent detectors feed the decision:
-*  1. A heuristic pattern for classic catastrophic-backtracking shapes
-*     (nested quantifiers, possessive quantifiers, backreferences, …).
-*  2. A deterministic static complexity budget, so patterns that evade the
-*     heuristic still fail over when their unbounded-quantifier density is
-*     pathological.
-*
-* Unsafe input is never executed as a regex: depending on the caller's
-* intent it is either escaped to a literal match or rejected through the
-* `invalidInput` policy.
-*/
-/**
-* Regex patterns that can cause catastrophic backtracking (ReDoS attacks).
-* Detects common footguns:
-* - Quantifiers: {n,m}
-* - Possessive quantifiers: *+, ++, ?+
-* - Nested quantifiers: (a+)+, (a*)*
-* - Backreferences: \1, \2, etc.
-* - Complex character classes: [...]...[...]
-*/
-const DANGEROUS_REGEX_PATTERNS = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
-/**
-* Static complexity budget for user-supplied regex patterns.
-* Returns `true` if the pattern crosses a budget that empirically correlates
-* with ReDoS risk — independent of the heuristic regex detector.
-*
-* Budget components (any single threshold crossed → over budget):
-*   - unbounded quantifiers (`*`, `+`, `?`) — hard cap 20
-*   - nested groups `(` — hard cap 8
-*   - alternations `|` — hard cap 10
-*   - combined: (quantifiers * groups) — hard cap 40
-*/
-function regexComplexityExceedsBudget(patternStr) {
-	const stripped = patternStr.replace(/\\[^\\]/g, "");
-	const unboundedQuantifiers = (stripped.match(/[*+?]/g) ?? []).length;
-	const groups = (stripped.match(/\(/g) ?? []).length;
-	const alternations = (stripped.match(/\|/g) ?? []).length;
-	if (unboundedQuantifiers > 20) return true;
-	if (groups > 8) return true;
-	if (alternations > 10) return true;
-	if (unboundedQuantifiers * groups > 40) return true;
-	return false;
-}
-/** Escape special regex characters (backslash first, then other metas). */
-function escapeRegex(str) {
-	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-/**
-* Build a safe RegExp from user input.
-*
-* `onUnsafe` selects what happens when the pattern is over-long,
-* pathological, or syntactically invalid:
-* - `'reject'`: route through the `invalidInput` policy — HTTP 400 in
-*   `'throw'` mode, warn + escape-to-literal in `'drop'` mode. Used for
-*   the explicit `regex` operator, where the caller claims to be sending
-*   a real regex.
-* - `'escape'`: always warn + escape-to-literal, never throw. Used for
-*   `search` terms and the `like`/`contains` operators, whose documented
-*   semantic is a literal substring match — `?search=c++` must not 400.
-*/
-function createSafeRegex(rt, pattern, flags = "i", onUnsafe = "reject") {
-	if (pattern === null || pattern === void 0) return null;
-	const flag = (message, meta) => {
-		if (onUnsafe === "reject") rt.reject(message, meta);
-		else warn(`[mongokit] ${message}`);
-	};
-	const patternStr = String(pattern);
-	if (patternStr.length > rt.options.maxRegexLength) {
-		flag(`Regex pattern too long, truncating`, {
-			length: patternStr.length,
-			maxRegexLength: rt.options.maxRegexLength
-		});
-		return new RegExp(escapeRegex(patternStr.substring(0, rt.options.maxRegexLength)), flags);
-	}
-	if (DANGEROUS_REGEX_PATTERNS.test(patternStr)) {
-		flag("Potentially dangerous regex pattern, escaping");
-		return new RegExp(escapeRegex(patternStr), flags);
-	}
-	if (regexComplexityExceedsBudget(patternStr)) {
-		flag("Regex complexity budget exceeded, escaping");
-		return new RegExp(escapeRegex(patternStr), flags);
-	}
-	try {
-		return new RegExp(patternStr, flags);
-	} catch {
-		flag("Invalid regex pattern syntax, escaping to literal match");
-		return new RegExp(escapeRegex(patternStr), flags);
-	}
-}
-//#endregion
 //#region src/query/parser/filter-compiler.ts
 /**
-* Filter compiler — URL filter parameters → MongoDB filter query.
-*
-* Owns the three entry shapes (flat `field=value`, flat operator syntax
-* `field[gte]=10`, nested bracket objects from qs), the `$or` group router,
-* and the `between` range expander. Every invalid or disallowed fragment
-* routes through the runtime's `invalidInput` policy.
+* URL filters → a MongoDB filter. The grammar (keys, operators, value coercion, refusals) is
+* repo-core's `readFilterClauses`; its clauses compile through the Filter IR compiler every
+* repository query uses, so URL and programmatic filters mean the same thing. Only mongokit's own
+* operators (`size`, `type`, geo) are emitted here, natively.
 */
+/** mongokit-native operators, beyond the shared grammar. */
+const MONGOKIT_EXTENSION_OPERATORS = [
+	"size",
+	"type",
+	...GEO_OPERATORS
+];
+/** Group params — `or[0][status]=a&or[1][qty][gte]=5` — compiled branch by branch. */
+const GROUP_PARAMS = [
+	"or",
+	"OR",
+	"$or",
+	"$and"
+];
+/** mongokit control params that are not filters. */
+const MONGOKIT_RESERVED_PARAMS = [
+	"lean",
+	"includeDeleted",
+	"lookup",
+	"aggregate",
+	"cursor",
+	...GROUP_PARAMS
+];
+const BSON_TYPE_RE = /^(?:[a-zA-Z]+|\d{1,3})$/;
+/** Compile every filter in `query` (group params excluded — see {@link compileGroups}). */
+function compileUrlFilters(rt, query) {
+	const { clauses, extensions } = readFilterClauses(query, grammarOptions(rt));
+	return conjoin([compileFilterToMongo(clausesToFilter(clauses)), ...extensions.map((clause) => compileExtension(rt, clause)).filter((part) => part !== void 0)]);
+}
 /**
-* Top-level query parameters that mongokit handles outside the filter
-* pipeline. Used by `handleBracketSyntax` to detect a common typo where a
-* caller wrote `?filters[limit]=5` instead of `?limit=5` and the qs parser
-* nested the key under a filter object — the value is silently dropped
-* without this guard. Kept as a Set for O(1) lookup; values mirror the
-* reserved-key list at the top of `parseFilters`.
+* `or` / `$or` and `$and` groups. Each branch is a full filter through the same grammar. An empty
+* branch is refused — inside an OR it would match every document — and groups do not nest.
 */
-const RESERVED_PAGINATION_KEYS = /* @__PURE__ */ new Set([
-	"page",
-	"limit",
-	"sort",
-	"select"
-]);
-function toMongoOperator(operator) {
-	const op = operator.toLowerCase();
-	return op.startsWith("$") ? op : `$${op}`;
+function compileGroups(rt, query) {
+	const out = {};
+	const orRaw = query?.or ?? query?.OR ?? query?.$or;
+	const orBranches = orRaw === void 0 ? [] : compileBranches(rt, "or", orRaw);
+	if (orBranches.length > 0) out.$or = orBranches;
+	const andBranches = query?.$and === void 0 ? [] : compileBranches(rt, "$and", query.$and);
+	if (andBranches.length > 0) out.$and = andBranches;
+	return out;
 }
-/** Parse filter parameters into a MongoDB filter query. */
-function parseFilters(rt, filters, depth = 0) {
-	if (depth > rt.options.maxFilterDepth) {
-		rt.reject(`Filter depth ${depth} exceeds maximum ${rt.options.maxFilterDepth}, truncating`, {
-			depth,
-			maxFilterDepth: rt.options.maxFilterDepth
-		});
-		return {};
+function compileBranches(rt, param, raw) {
+	const items = Array.isArray(raw) ? raw : isRecord(raw) ? Object.values(raw) : void 0;
+	if (!items) {
+		rt.reject(`${param} takes branches: ${param}[0][field]=value`, { param });
+		return [];
 	}
-	const parsedFilters = {};
-	const regexFields = {};
-	for (const [key, value] of Object.entries(filters)) {
-		if (rt.dangerousOperators.includes(key) || key.startsWith("$") && !["$or", "$and"].includes(key)) {
-			rt.reject(`Blocked dangerous operator: ${key}`, { key });
+	const branches = [];
+	for (const item of items) {
+		if (!isRecord(item)) {
+			rt.reject(`each ${param} branch is a set of filters`, { param });
 			continue;
 		}
-		if (isControlParam(key) || [
-			"lean",
-			"includeDeleted",
-			"lookup",
-			"aggregate",
-			"or",
-			"OR",
-			"$or"
-		].includes(key)) continue;
-		const operatorMatch = key.match(/^(.+)\[(.+)\]$/);
-		const baseField = operatorMatch ? operatorMatch[1] : key;
-		if (rt.options.allowedFilterFields && !rt.options.allowedFilterFields.includes(baseField)) {
-			rt.reject(`Blocked filter field not in allowlist: ${baseField}`, { field: baseField });
+		if (GROUP_PARAMS.some((group) => group in item)) {
+			rt.reject(`${param} groups do not nest`, { param });
 			continue;
 		}
-		if (key === "$and") {
-			const branches = parseCompoundBranches(rt, value, depth);
-			if (branches.length > 0) parsedFilters.$and = branches;
+		const branch = compileUrlFilters(rt, item);
+		if (Object.keys(branch).length === 0) {
+			rt.reject(`an empty ${param} branch would match every document`, { param });
 			continue;
 		}
-		if (operatorMatch) {
-			const [, , operator] = operatorMatch;
-			if (rt.dangerousOperators.includes(`$${operator}`)) {
-				rt.reject(`Blocked dangerous operator: ${operator}`, { operator });
-				continue;
-			}
-			handleOperatorSyntax(rt, parsedFilters, regexFields, operatorMatch, value);
-			continue;
-		}
-		if (typeof value === "object" && value !== null && !Array.isArray(value)) handleBracketSyntax(rt, key, value, parsedFilters, depth + 1);
-		else parsedFilters[key] = coerceFieldValue(key, value, rt.fieldTypes);
+		branches.push(branch);
 	}
-	return parsedFilters;
+	return branches;
 }
-/** Handle flat operator syntax: field[operator]=value */
-function handleOperatorSyntax(rt, filters, regexFields, operatorMatch, value) {
-	const [, field, operator] = operatorMatch;
-	if (value === "" || value === null || value === void 0) return;
-	if (rt.options.allowedOperators && !rt.options.allowedOperators.includes(operator.toLowerCase())) {
-		rt.reject(`Operator not in allowlist: ${operator}`, {
-			field,
-			operator
-		});
-		return;
-	}
-	if (operator.toLowerCase() === "options" && regexFields[field]) {
-		const fieldValue = filters[field];
-		if (typeof fieldValue === "object" && fieldValue !== null && "$regex" in fieldValue) {
-			if (typeof value === "string" && /^[imsx]+$/.test(value)) fieldValue.$options = value;
-			else rt.reject(`Blocked invalid regex $options value: ${String(value)}. Allowed flags: i, m, s, x`, {
-				field,
-				value: String(value)
-			});
-		}
-		return;
-	}
-	if (operator.toLowerCase() === "between") {
-		if (typeof filters[field] !== "object" || filters[field] === null || Array.isArray(filters[field])) filters[field] = {};
-		filters[field].between = value;
-		return;
-	}
-	if (operator.toLowerCase() === "contains" || operator.toLowerCase() === "like") {
-		const safeRegex = createSafeRegex(rt, value, "i", "escape");
-		if (safeRegex) {
-			filters[field] = { $regex: safeRegex };
-			regexFields[field] = true;
-		}
-		return;
-	}
-	if (isGeoOperator(operator)) {
-		const geoFilter = parseGeoFilter(operator, value);
-		if (geoFilter) filters[field] = geoFilter;
-		else rt.reject(`Invalid geo operator value for ${field}[${operator}]; dropping filter`, {
-			field,
-			operator
-		});
-		return;
-	}
-	const mongoOperator = toMongoOperator(operator);
-	if (rt.dangerousOperators.includes(mongoOperator)) {
-		rt.reject(`Blocked dangerous operator: ${mongoOperator}`, { operator: mongoOperator });
-		return;
-	}
-	if (mongoOperator === "$eq") filters[field] = coerceFieldValue(field, value, rt.fieldTypes);
-	else if (mongoOperator === "$regex") {
-		const safeRegex = createSafeRegex(rt, value);
-		if (safeRegex) {
-			filters[field] = { $regex: safeRegex };
-			regexFields[field] = true;
-		}
-	} else {
-		let processedValue;
-		const op = operator.toLowerCase();
-		if (op === "size") {
-			processedValue = parseFloat(String(value));
-			if (Number.isNaN(processedValue)) {
-				rt.reject(`Non-numeric value for ${field}[${op}]: ${String(value)}`, {
-					field,
-					op
-				});
-				return;
-			}
-		} else if ([
-			"gt",
-			"gte",
-			"lt",
-			"lte"
-		].includes(op)) {
-			if (rt.fieldTypes.has(field)) {
-				processedValue = coerceFieldValue(field, value, rt.fieldTypes);
-				if (typeof processedValue === "number" && Number.isNaN(processedValue)) {
-					rt.reject(`Invalid value for ${field}[${op}]: ${String(value)}`, {
-						field,
-						op
-					});
-					return;
-				}
-			} else {
-				processedValue = parseFloat(String(value));
-				if (Number.isNaN(processedValue)) {
-					rt.reject(`Non-numeric value for ${field}[${op}]: ${String(value)}`, {
-						field,
-						op
-					});
-					return;
-				}
-			}
-		} else if (op === "in" || op === "nin") processedValue = (Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim())).map((elem) => coerceFieldValue(field, elem, rt.fieldTypes));
-		else processedValue = coerceFieldValue(field, value, rt.fieldTypes);
-		if (typeof filters[field] !== "object" || filters[field] === null || Array.isArray(filters[field])) filters[field] = {};
-		filters[field][mongoOperator] = processedValue;
-	}
+function grammarOptions(rt) {
+	return {
+		allowedFilterFields: rt.options.allowedFilterFields,
+		allowedOperators: rt.options.allowedOperators,
+		fieldTypes: rt.grammarFieldTypes,
+		extensionOperators: MONGOKIT_EXTENSION_OPERATORS,
+		reservedParams: MONGOKIT_RESERVED_PARAMS,
+		maxTextLength: rt.options.maxRegexLength,
+		onInvalid: rt.options.invalidInput === "drop" ? (error) => rt.reject(error.message) : void 0
+	};
 }
-/** Handle bracket syntax with object value (qs-parsed nested operators). */
-function handleBracketSyntax(rt, field, operators, parsedFilters, depth = 0) {
-	if (depth > rt.options.maxFilterDepth) {
-		rt.reject(`Nested filter depth exceeds maximum, skipping field: ${field}`, {
-			field,
-			maxFilterDepth: rt.options.maxFilterDepth
-		});
-		return;
-	}
-	for (const op of Object.keys(operators)) if (RESERVED_PAGINATION_KEYS.has(op)) warn(`[mongokit] Nested filter contains reserved key '${op}' at '${field}.${op}' — did you mean ?${op}=... at the top level? The nested value is ignored.`);
-	if (!parsedFilters[field]) parsedFilters[field] = {};
-	for (const [operator, value] of Object.entries(operators)) {
-		if (value === "" || value === null || value === void 0) continue;
-		if (operator === "between") {
-			parsedFilters[field].between = value;
-			continue;
-		}
-		if (isGeoOperator(operator)) {
-			const geoFilter = parseGeoFilter(operator, value);
-			if (geoFilter) parsedFilters[field] = geoFilter;
-			else {
-				rt.reject(`Invalid geo operator value for ${field}[${operator}]; dropping filter`, {
-					field,
-					operator
-				});
-				delete parsedFilters[field];
+function compileExtension(rt, clause) {
+	const param = `${clause.field}[${clause.op}]`;
+	try {
+		switch (clause.op) {
+			case "size":
+				if (!/^\d+$/.test(clause.raw)) throw new QueryGrammarError(param, "size takes a whole number");
+				return { [clause.field]: { $size: Number(clause.raw) } };
+			case "type": {
+				if (!BSON_TYPE_RE.test(clause.raw)) throw new QueryGrammarError(param, "not a BSON type");
+				const code = Number(clause.raw);
+				return { [clause.field]: { $type: Number.isInteger(code) ? code : clause.raw } };
+			}
+			default: {
+				const geo = parseGeoFilter(clause.op, clause.raw);
+				if (!geo) throw new QueryGrammarError(param, `invalid ${clause.op} coordinates`);
+				return { [clause.field]: geo };
 			}
-			continue;
-		}
-		if (rt.options.allowedOperators && !rt.options.allowedOperators.includes(operator)) {
-			rt.reject(`Operator not in allowlist: ${operator}`, {
-				field,
-				operator
-			});
-			continue;
-		}
-		if (rt.operators[operator]) {
-			const mongoOperator = rt.operators[operator];
-			let processedValue;
-			if (operator === "size") {
-				processedValue = parseFloat(String(value));
-				if (Number.isNaN(processedValue)) {
-					rt.reject(`Non-numeric value for ${field}[${operator}]: ${String(value)}`, {
-						field,
-						operator
-					});
-					continue;
-				}
-			} else if ([
-				"gt",
-				"gte",
-				"lt",
-				"lte"
-			].includes(operator)) {
-				if (rt.fieldTypes.has(field)) {
-					processedValue = coerceFieldValue(field, value, rt.fieldTypes);
-					if (typeof processedValue === "number" && Number.isNaN(processedValue)) {
-						rt.reject(`Invalid value for ${field}[${operator}]: ${String(value)}`, {
-							field,
-							operator
-						});
-						continue;
-					}
-				} else {
-					processedValue = parseFloat(String(value));
-					if (Number.isNaN(processedValue)) {
-						rt.reject(`Non-numeric value for ${field}[${operator}]: ${String(value)}`, {
-							field,
-							operator
-						});
-						continue;
-					}
-				}
-			} else if (operator === "in" || operator === "nin") processedValue = (Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim())).map((elem) => coerceFieldValue(field, elem, rt.fieldTypes));
-			else if (operator === "like" || operator === "contains" || operator === "regex") {
-				const safeRegex = createSafeRegex(rt, value, "i", operator === "regex" ? "reject" : "escape");
-				if (!safeRegex) continue;
-				processedValue = safeRegex;
-			} else processedValue = coerceFieldValue(field, value, rt.fieldTypes);
-			parsedFilters[field][mongoOperator] = processedValue;
 		}
+	} catch (error) {
+		if (!(error instanceof QueryGrammarError) || rt.options.invalidInput !== "drop") throw error;
+		rt.reject(error.message);
+		return;
 	}
-	if (typeof parsedFilters[field] === "object" && Object.keys(parsedFilters[field]).length === 0) delete parsedFilters[field];
 }
-/** Parse `?or=[...]` / `?OR=[...]` / `?$or=[...]` groups into an $or array. */
-/**
-* Parse the branches of a compound operator (`$and`, and the body of `$or`).
-*
-* Every branch goes back through `parseFilters`, so the operator block, the allowlist and the
-* regex budget all apply inside it. Branches that parse to `{}` are DROPPED: a branch holding
-* only a blocked operator would otherwise become match-all, which widens the query instead of
-* failing it — the exact shape `parseOr` documents below.
-*/
-function parseCompoundBranches(rt, raw, depth) {
-	const items = Array.isArray(raw) ? raw : typeof raw === "object" && raw ? Object.values(raw) : [];
-	const branches = [];
-	for (const item of items) {
-		if (typeof item !== "object" || !item) continue;
-		const parsed = parseFilters(rt, item, depth + 1);
-		if (Object.keys(parsed).length > 0) branches.push(parsed);
+/** AND compiled parts: one object when fields don't collide, `$and` when they do. */
+function conjoin(parts) {
+	const nonEmpty = parts.filter((part) => Object.keys(part).length > 0);
+	if (nonEmpty.length <= 1) return { ...nonEmpty[0] ?? {} };
+	const merged = {};
+	for (const part of nonEmpty) {
+		for (const key of Object.keys(part)) if (key in merged) return { $and: nonEmpty };
+		Object.assign(merged, part);
 	}
-	return branches;
+	return merged;
 }
-function parseOr(rt, query) {
-	const orArray = [];
-	const raw = query?.or || query?.OR || query?.$or;
-	if (!raw) return void 0;
-	const items = Array.isArray(raw) ? raw : typeof raw === "object" ? Object.values(raw) : [];
-	for (const item of items) if (typeof item === "object" && item) {
-		const parsedBranch = parseFilters(rt, item, 1);
-		if (Object.keys(parsedBranch).length > 0) orArray.push(parsedBranch);
-	}
-	return orArray.length ? orArray : void 0;
+/** mongokit's schema-derived field types, narrowed to the grammar's portable set. */
+function toGrammarFieldTypes(types) {
+	const out = {};
+	for (const [path, type] of types) if (type === "string" || type === "objectid") out[path] = "string";
+	else if (type === "number" || type === "boolean" || type === "date") out[path] = type;
+	return out;
 }
-/** Expand `{ field: { between: 'a,b' } }` markers into `$gte`/`$lte` date ranges. */
-function enhanceWithBetween(rt, filters) {
-	const output = { ...filters };
-	for (const [key, value] of Object.entries(filters || {})) if (value && typeof value === "object" && "between" in value) {
-		const between = value.between;
-		const [from, to] = String(between).split(",").map((s) => s.trim());
-		const fromDate = from ? new Date(from) : void 0;
-		const toDate = to ? new Date(to) : void 0;
-		const range = {};
-		if (fromDate && !Number.isNaN(fromDate.getTime())) range.$gte = fromDate;
-		if (toDate && !Number.isNaN(toDate.getTime())) range.$lte = toDate;
-		if (Object.keys(range).length === 0) {
-			rt.reject(`Invalid 'between' value for ${key}: ${String(between)}`, {
-				field: key,
-				value: String(between)
-			});
-			delete output[key];
-		} else output[key] = range;
-	}
-	return output;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
 //#region src/query/parser/lookup.ts
@@ -838,97 +563,70 @@ function parseSingleLookup(rt, collectionName, config) {
 	return null;
 }
 //#endregion
-//#region src/query/parser/pagination-input.ts
+//#region src/query/parser/runtime.ts
 /**
-* Parse a pagination input to a positive integer, or `undefined` when the
-* value is absent, empty, or rejected under `'drop'` mode. Rejects (per
-* policy) on non-integers, negatives, zero, decimals, and trailing garbage.
+* Parser runtime — the shared context every parser module receives.
+*
+* The `QueryParser` facade resolves options once at construction and builds a
+* single `ParserRuntime`; the extracted modules (filter compiler, sanitizers,
+* populate/lookup/sort parsers, …) are pure functions over it. This keeps the
+* modules independently testable and the facade thin, without threading six
+* separate arguments through every call.
 */
-function parsePositiveInt(rt, raw, label) {
-	if (raw === void 0 || raw === null || raw === "") return void 0;
-	let n;
-	if (typeof raw === "number") n = raw;
-	else {
-		const s = String(raw).trim();
-		if (!/^\d+$/.test(s)) {
-			rt.reject(`Invalid ${label} value: ${String(raw)} (expected a positive integer)`, { [label]: String(raw) });
-			return;
-		}
-		n = Number(s);
-	}
-	if (!Number.isInteger(n) || n < 1) {
-		rt.reject(`Invalid ${label} value: ${String(raw)} (expected a positive integer)`, { [label]: String(raw) });
-		return;
+/** Always-blocked MongoDB operators (extended via `additionalDangerousOperators`). */
+const BASE_DANGEROUS_OPERATORS = [
+	"$where",
+	"$function",
+	"$accumulator",
+	"$expr"
+];
+function createReject(mode) {
+	return (message, meta) => {
+		if (mode === "throw") throw createError(400, `[mongokit] ${message}`, {
+			code: "INVALID_QUERY_INPUT",
+			meta
+		});
+		warn(`[mongokit] ${message}`);
+	};
+}
+/**
+* Run a grammar reader under the `invalidInput` policy: `'throw'` lets its 400 through untouched;
+* `'drop'` warns and returns `fallback`.
+*/
+function guarded(rt, read, fallback) {
+	try {
+		return read();
+	} catch (error) {
+		if (!isQueryGrammarError(error) || rt.options.invalidInput !== "drop") throw error;
+		rt.reject(error.message);
+		return fallback;
 	}
-	return n;
 }
 //#endregion
 //#region src/query/parser/sort-select.ts
 /**
-* The sort applied when a request names none. Mongo/mongokit convention.
-*
-* Exported so `parse()` can ask whether it is PERMITTED before applying it,
-* rather than substituting it and then validating it like caller input.
+* `?sort=-createdAt,name` and `?select=name,-password` — read through the shared grammar
+* (`readSort` / `readSelect`), so an invalid or disallowed field is refused like any filter.
 */
-const DEFAULT_PARSER_SORT = "-createdAt";
 /**
-* Is every field of `sort` inside `allowedSortFields`? True when no allowlist
-* is configured. Pure predicate — never rejects, never warns, so it is safe to
-* ask about a default the caller did not send.
+* The sort applied when a request names none. Exported so `parse()` can ask whether it is
+* PERMITTED before applying it, rather than validating it like caller input.
 */
+const DEFAULT_PARSER_SORT = "-createdAt";
+/** Is every field of `sort` inside `allowedSortFields`? Pure — never rejects. */
 function isSortFieldAllowed(rt, sort) {
 	const allowed = rt.options.allowedSortFields;
 	if (!allowed || allowed.length === 0) return true;
-	return sort.split(",").map((s) => s.trim()).filter(Boolean).every((field) => allowed.includes(field.startsWith("-") ? field.substring(1) : field));
+	return sort.split(",").map((s) => s.trim()).filter(Boolean).every((field) => allowed.includes(field.replace(/^[+-]/, "")));
 }
-/** Parse a sort spec (string or object form), honoring `allowedSortFields`. */
 function parseSort(rt, sort) {
-	if (!sort) return void 0;
-	if (typeof sort === "object") {
-		const sortObj = {};
-		for (const [key, value] of Object.entries(sort)) {
-			if (rt.options.allowedSortFields && !rt.options.allowedSortFields.includes(key)) {
-				rt.reject(`Blocked sort field not in allowlist: ${key}`, { field: key });
-				continue;
-			}
-			const strVal = String(value).toLowerCase();
-			sortObj[key] = strVal === "desc" || strVal === "-1" || value === -1 ? -1 : 1;
-		}
-		return Object.keys(sortObj).length > 0 ? sortObj : void 0;
-	}
-	const sortObj = {};
-	const fields = sort.split(",").map((s) => s.trim());
-	for (const field of fields) {
-		if (!field) continue;
-		const cleanField = field.startsWith("-") ? field.substring(1) : field;
-		if (rt.options.allowedSortFields && !rt.options.allowedSortFields.includes(cleanField)) {
-			rt.reject(`Blocked sort field not in allowlist: ${cleanField}`, { field: cleanField });
-			continue;
-		}
-		if (field.startsWith("-")) sortObj[field.substring(1)] = -1;
-		else sortObj[field] = 1;
-	}
-	return Object.keys(sortObj).length > 0 ? sortObj : void 0;
+	return readSort(sort, {
+		allowedSortFields: rt.options.allowedSortFields,
+		onInvalid: rt.options.invalidInput === "drop" ? (error) => rt.reject(error.message) : void 0
+	});
 }
-/**
-* Parse select/project fields.
-*
-* @example
-* ```typescript
-* // URL: ?select=name,email,-password
-* // Returns: { name: 1, email: 1, password: 0 }
-* ```
-*/
-function parseSelect(select) {
-	if (!select) return void 0;
-	if (typeof select === "string") {
-		const projection = {};
-		const fields = select.split(",").map((f) => f.trim());
-		for (const field of fields) if (field.startsWith("-")) projection[field.substring(1)] = 0;
-		else projection[field] = 1;
-		return projection;
-	}
-	if (typeof select === "object" && select !== null) return select;
+function parseSelect(rt, select) {
+	return guarded(rt, () => readSelect(select), void 0);
 }
 //#endregion
 //#region src/query/parser/populate.ts
@@ -992,7 +690,10 @@ function parseSinglePopulate(rt, path, config, depth = 0) {
 		const opts = config;
 		const option = { path };
 		if (opts.select && typeof opts.select === "string") option.select = opts.select.split(",").map((s) => s.trim()).join(" ");
-		if (opts.match && typeof opts.match === "object") option.match = convertPopulateMatch(opts.match);
+		if (opts.match && typeof opts.match === "object") {
+			const match = convertPopulateMatch(rt, path, opts.match);
+			if (match) option.match = match;
+		}
 		if (opts.limit !== void 0) {
 			const limit = parseInt(String(opts.limit), 10);
 			if (!Number.isNaN(limit) && limit > 0) {
@@ -1027,112 +728,56 @@ function parseSinglePopulate(rt, path, config, depth = 0) {
 	}
 	return null;
 }
-/** Convert populate match values (handles boolean strings, etc.) */
-function convertPopulateMatch(match) {
+/**
+* A populate `match` is plain field EQUALITY: a `$` key (`$where`) or a nested object — the same
+* operator-smuggling route — is refused through the invalid-input policy, never passed to mongoose.
+*/
+function convertPopulateMatch(rt, path, match) {
 	const converted = {};
-	for (const [key, value] of Object.entries(match)) converted[key] = coerceHeuristic(value);
+	for (const [key, value] of Object.entries(match)) {
+		if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(key) || value !== null && typeof value === "object") {
+			rt.reject(`Populate match on "${path}" accepts field equality only: "${key}"`, {
+				path,
+				key
+			});
+			return null;
+		}
+		converted[key] = coerceHeuristic(value);
+	}
 	return converted;
 }
 //#endregion
-//#region src/query/parser/runtime.ts
+//#region src/query/parser/schema-docs.ts
 /**
-* Parser runtime — the shared context every parser module receives.
-*
-* The `QueryParser` facade resolves options once at construction and builds a
-* single `ParserRuntime`; the extracted modules (filter compiler, sanitizers,
-* populate/lookup/sort parsers, …) are pure functions over it. This keeps the
-* modules independently testable and the facade thin, without threading six
-* separate arguments through every call.
+* OpenAPI query-schema generation — Arc's `defineResource()` auto-detects
+* `getQuerySchema()` on the parser and uses it to document list-endpoint
+* query parameters in OpenAPI/Swagger.
 */
-/** URL operator key → MongoDB operator. */
-const OPERATOR_MAP = {
-	eq: "$eq",
-	ne: "$ne",
-	gt: "$gt",
-	gte: "$gte",
-	lt: "$lt",
-	lte: "$lte",
-	in: "$in",
-	nin: "$nin",
-	like: "$regex",
-	contains: "$regex",
-	regex: "$regex",
-	exists: "$exists",
-	size: "$size",
-	type: "$type"
+/** mongokit's own operators, described alongside the shared grammar's. */
+const EXTENSION_DESCRIPTIONS = {
+	size: "Array has exactly N elements",
+	type: "Field is of a BSON type (name or number)",
+	near: "Nearest to lng,lat[,maxDistanceMeters]",
+	nearSphere: "Nearest on a sphere to lng,lat[,maxDistanceMeters]",
+	geoWithin: "Inside the box minLng,minLat,maxLng,maxLat",
+	withinRadius: "Within lng,lat,radiusMeters"
 };
-/** Always-blocked MongoDB operators (extended via `additionalDangerousOperators`). */
-const BASE_DANGEROUS_OPERATORS = [
-	"$where",
-	"$function",
-	"$accumulator",
-	"$expr"
-];
-function createReject(mode) {
-	return (message, meta) => {
-		if (mode === "throw") throw createError(400, `[mongokit] ${message}`, {
-			code: "INVALID_QUERY_INPUT",
-			meta
-		});
-		warn(`[mongokit] ${message}`);
-	};
+function describeOperator(op) {
+	if (op in OPERATOR_DESCRIPTIONS) return OPERATOR_DESCRIPTIONS[op];
+	return EXTENSION_DESCRIPTIONS[op] ?? op;
 }
-//#endregion
-//#region src/query/parser/schema-docs.ts
 function availableOperators(rt) {
-	return rt.options.allowedOperators ? Object.entries(rt.operators).filter(([key]) => rt.options.allowedOperators?.includes(key)) : Object.entries(rt.operators);
+	const allowed = rt.options.allowedOperators;
+	return allowed ? rt.urlOperators.filter((op) => allowed.includes(op)) : rt.urlOperators;
 }
-/** Get the JSON Schema type for a filter operator. */
+/** JSON Schema type of an operator's value. */
 function operatorSchemaType(op) {
-	if ([
-		"gt",
-		"gte",
-		"lt",
-		"lte",
-		"size"
-	].includes(op)) return "number";
-	if (["exists"].includes(op)) return "boolean";
+	if (op === "size") return "integer";
+	if (op === "exists") return "boolean";
 	return "string";
 }
-/** Get a human-readable description for a filter operator. */
-function operatorDescription(op, field, mongoOp) {
-	return {
-		ne: `${field} not equal to value (${mongoOp})`,
-		gt: `${field} greater than value (${mongoOp})`,
-		gte: `${field} greater than or equal to value (${mongoOp})`,
-		lt: `${field} less than value (${mongoOp})`,
-		lte: `${field} less than or equal to value (${mongoOp})`,
-		in: `${field} in comma-separated list (${mongoOp}). Example: value1,value2`,
-		nin: `${field} not in comma-separated list (${mongoOp})`,
-		like: `${field} matches pattern (case-insensitive regex)`,
-		contains: `${field} contains substring (case-insensitive regex)`,
-		regex: `${field} matches regex pattern (${mongoOp})`,
-		exists: `Field ${field} exists (true/false)`,
-		size: `Array field ${field} has exactly N elements (${mongoOp})`,
-		type: `Field ${field} is of BSON type (${mongoOp})`
-	}[op] || `Filter ${field} with ${mongoOp}`;
-}
-/** Build a summary description of all available filter operators. */
 function buildOperatorSummary(operators) {
-	const lines = ["Available filter operators (use as field[operator]=value):"];
-	const desc = {
-		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)",
-		size: "Array size equals",
-		type: "BSON type check"
-	};
-	for (const [op, mongoOp] of operators) lines.push(`  ${op} → ${mongoOp}: ${desc[op] || op}`);
-	return lines.join("\n");
+	return ["Available filter operators (use as field[operator]=value):", ...operators.map((op) => `  ${op}: ${describeOperator(op)}`)].join("\n");
 }
 /**
 * Generate OpenAPI-compatible JSON Schema for query parameters.
@@ -1216,11 +861,11 @@ function buildQuerySchema(rt) {
 			type: "string",
 			description: `Filter by ${field} (exact match)`
 		};
-		for (const [op, mongoOp] of operators) {
+		for (const op of operators) {
 			if (op === "eq") continue;
 			properties[`${field}[${op}]`] = {
 				type: operatorSchemaType(op),
-				description: operatorDescription(op, field, mongoOp)
+				description: `${field}: ${describeOperator(op)}`
 			};
 		}
 	}
@@ -1246,39 +891,17 @@ function buildOpenAPIQuerySchema(rt) {
 //#endregion
 //#region src/query/parser/search.ts
 /**
-* Search-term handling — length-capped sanitization plus the regex-mode
-* multi-field `$or` builder. Search terms are literal text, never regex
-* patterns: special characters are escaped, not rejected.
+* `?search=` — length-checked through the shared grammar. Regex mode matches the term as LITERAL
+* text across `searchFields` (`c++` and `a.b` mean exactly those characters).
 */
-/** Trim + length-cap the raw search term (reject over-long input per policy). */
 function sanitizeSearch(rt, search) {
-	if (search === null || search === void 0 || search === "") return void 0;
-	let searchStr = String(search).trim();
-	if (!searchStr) return void 0;
-	if (searchStr.length > rt.options.maxSearchLength) {
-		rt.reject(`Search query too long, truncating`, {
-			length: searchStr.length,
-			maxSearchLength: rt.options.maxSearchLength
-		});
-		searchStr = searchStr.substring(0, rt.options.maxSearchLength);
-	}
-	return searchStr;
+	return guarded(rt, () => readSearch(search, { maxSearchLength: rt.options.maxSearchLength }), void 0);
 }
-/**
-* Build regex-based multi-field search filters: an $or with case-insensitive
-* regex across all searchFields.
-*
-* @example
-* // searchFields: ['name', 'description', 'sku'], search: 'azure'
-* // Returns: [{ name: {$regex:/azure/i} }, { description: {...} }, { sku: {...} }]
-*/
 function buildRegexSearch(rt, searchTerm) {
-	if (!rt.options.searchFields || rt.options.searchFields.length === 0) return null;
-	const safeRegex = createSafeRegex(rt, searchTerm, "i", "escape");
-	if (!safeRegex) return null;
-	const orConditions = [];
-	for (const field of rt.options.searchFields) orConditions.push({ [field]: { $regex: safeRegex } });
-	return orConditions.length > 0 ? orConditions : null;
+	const fields = rt.options.searchFields;
+	if (!fields || fields.length === 0) return null;
+	const pattern = new RegExp(escapeRegex(searchTerm), "i");
+	return fields.map((field) => ({ [field]: { $regex: pattern } }));
 }
 //#endregion
 //#region src/query/QueryParser.ts
@@ -1293,8 +916,7 @@ function buildRegexSearch(rt, searchTerm) {
 * orchestration, and the OpenAPI schema surface. The implementation lives in
 * focused modules under `./parser/`:
 *
-* - `parser/filter-compiler`    — filters, operator syntax, $or, between
-* - `parser/regex-safety`       — ReDoS protection (escape/reject)
+* - `parser/filter-compiler`    — filters (repo-core's shared grammar → Filter IR → Mongo), groups
 * - `parser/pipeline-sanitizer` — $match / $lookup-pipeline / expression sanitizing
 * - `parser/lookup`             — ?lookup[...] parsing + collection allowlist
 * - `parser/aggregation`        — ?aggregate[...] parsing (opt-in)
@@ -1319,9 +941,9 @@ function buildRegexSearch(rt, searchTerm) {
 *   being silently dropped (which broadens the result set). Opt into
 *   `'drop'` only for trusted compat tooling.
 * - Dangerous operators blocked everywhere ($where, $function, $accumulator, $expr).
-* - Regex patterns validated (ReDoS protection); search/like/contains are
-*   literal text (escaped, never rejected).
-* - Max filter depth + max limit enforced.
+* - Filters, paging, sort and select follow repo-core's shared query grammar — the same
+*   contract as arc's parser and `parseUrl` (`runQueryGrammarConformance` holds all three).
+* - Text operators and search are literal text; only `regex` is a pattern, checked for ReDoS.
 * - Lookup pipelines sanitized; `enableAggregations` is opt-in — keep it off
 *   for public endpoints or pair with per-route allowlists.
 *
@@ -1366,11 +988,13 @@ var QueryParser = class {
 			warn("[mongokit] searchMode \"regex\" requires searchFields to be specified. Falling back to \"text\" mode.");
 			resolved.searchMode = "text";
 		}
+		const fieldTypes = buildFieldTypeMap(options.schema, options.fieldTypes);
 		this.rt = {
 			options: resolved,
-			operators: OPERATOR_MAP,
+			urlOperators: [...URL_OPERATORS, ...MONGOKIT_EXTENSION_OPERATORS],
 			dangerousOperators: [...BASE_DANGEROUS_OPERATORS, ...resolved.additionalDangerousOperators],
-			fieldTypes: buildFieldTypeMap(options.schema, options.fieldTypes),
+			fieldTypes,
+			grammarFieldTypes: toGrammarFieldTypes(fieldTypes),
 			reject: createReject(resolved.invalidInput)
 		};
 		this._schemaIndexes = extractSchemaIndexes(options.schema);
@@ -1434,67 +1058,41 @@ var QueryParser = class {
 	*/
 	parse(query) {
 		const rt = this.rt;
-		const { page, limit = 20, sort, populate, search, after, cursor, select, lookup, aggregate, ...filters } = query || {};
-		let parsedLimit = parsePositiveInt(rt, limit, "limit") ?? 20;
-		if (parsedLimit > rt.options.maxLimit) {
-			warn(`[mongokit] Limit ${parsedLimit} exceeds maximum ${rt.options.maxLimit}, capping to max`);
-			parsedLimit = rt.options.maxLimit;
-		}
-		/**
-		* The DEFAULT sort applies only when the allowlist permits it.
-		*
-		* `sort = '-createdAt'` was a DESTRUCTURING default, so an absent `?sort=`
-		* became `-createdAt` and was then validated exactly like caller input. With
-		* `allowedSortFields` set and `createdAt` not among them, the parser
-		* REJECTED ITS OWN DEFAULT — and since 3.25 rejection throws, so `parse({})`
-		* threw on an empty query. Every list call on such a resource answered 400
-		* (`Blocked sort field not in allowlist: createdAt`), REST and MCP alike,
-		* and no request the caller could make would avoid it.
-		*
-		* A default the resource forbade must simply not be applied: it is not a
-		* caller error, and there is nobody to report it to. A sort the caller DID
-		* send still rejects — that is the fail-closed behaviour 3.25 added, and it
-		* is deliberately unchanged.
-		*/
+		const q = query ?? {};
+		const { page, limit, sort, populate, search, after, cursor, select, lookup, aggregate } = q;
+		const pageRequest = guarded(rt, () => readPageRequest({
+			page,
+			limit,
+			after,
+			cursor
+		}, { maxLimit: rt.options.maxLimit }), readPageRequest({}, { maxLimit: rt.options.maxLimit }));
 		const effectiveSort = sort === void 0 && isSortFieldAllowed(rt, "-createdAt") ? DEFAULT_PARSER_SORT : sort;
 		const sanitizedSearch = sanitizeSearch(rt, search);
 		const { simplePopulate, populateOptions } = parsePopulate(rt, populate);
 		const parsed = {
-			filters: parseFilters(rt, filters),
-			limit: parsedLimit,
+			filters: compileUrlFilters(rt, q),
+			limit: pageRequest.limit,
 			sort: parseSort(rt, effectiveSort),
 			populate: simplePopulate,
 			populateOptions,
 			search: sanitizedSearch
 		};
 		if (sanitizedSearch && rt.options.searchMode === "regex" && rt.options.searchFields) {
-			const regexSearchFilters = buildRegexSearch(rt, sanitizedSearch);
-			if (regexSearchFilters) {
-				if (parsed.filters.$or) {
-					parsed.filters = {
-						...parsed.filters,
-						$and: [{ $or: parsed.filters.$or }, { $or: regexSearchFilters }]
-					};
-					delete parsed.filters.$or;
-				} else parsed.filters.$or = regexSearchFilters;
+			const regexSearch = buildRegexSearch(rt, sanitizedSearch);
+			if (regexSearch) {
+				parsed.filters = attachCondition(parsed.filters, { $or: regexSearch });
 				parsed.search = void 0;
 			}
 		}
-		if (select) parsed.select = parseSelect(select);
+		const groups = compileGroups(rt, q);
+		if (groups.$or) parsed.filters = attachCondition(parsed.filters, { $or: groups.$or });
+		if (groups.$and) parsed.filters = attachCondition(parsed.filters, { $and: groups.$and });
+		const projection = parseSelect(rt, select);
+		if (projection) parsed.select = projection;
 		if (rt.options.enableLookups && lookup) parsed.lookups = parseLookups(rt, lookup);
 		if (rt.options.enableAggregations && aggregate) parsed.aggregation = parseAggregation(rt, aggregate);
-		if (after || cursor) parsed.after = String(after || cursor);
-		const parsedPage = parsePositiveInt(rt, page, "page");
-		if (parsedPage !== void 0) parsed.page = parsedPage;
-		const orGroup = parseOr(rt, query);
-		if (orGroup) {
-			if (parsed.filters.$or) {
-				const existingOr = parsed.filters.$or;
-				delete parsed.filters.$or;
-				parsed.filters.$and = [{ $or: existingOr }, { $or: orGroup }];
-			} else parsed.filters.$or = orGroup;
-		}
-		parsed.filters = enhanceWithBetween(rt, parsed.filters);
+		if (pageRequest.after !== void 0) parsed.after = pageRequest.after;
+		if (pageRequest.page !== void 0) parsed.page = pageRequest.page;
 		return parsed;
 	}
 	/**
@@ -1515,6 +1113,29 @@ var QueryParser = class {
 		return buildOpenAPIQuerySchema(this.rt);
 	}
 };
+/**
+* AND a top-level condition (`{ $or }` / `{ $and }`) into `filters`: alongside when its key is
+* free, otherwise both go under one `$and` so neither overwrites the other.
+*/
+function attachCondition(filters, condition) {
+	const [key] = Object.keys(condition);
+	if (!(key in filters)) return {
+		...filters,
+		...condition
+	};
+	const { [key]: existing, ...rest } = filters;
+	const prior = key === "$and" ? existing : [{ [key]: existing }];
+	const next = key === "$and" ? condition.$and : [condition];
+	const and = rest.$and ? [
+		...rest.$and,
+		...prior,
+		...next
+	] : [...prior, ...next];
+	return {
+		...rest,
+		$and: and
+	};
+}
 //#endregion
 //#region src/utils/repo-options.ts
 /**
@@ -1562,31 +1183,21 @@ var QueryParser = class {
 * });
 * ```
 *
-* The fields read (all optional — extracted only when present and not
-* `undefined`):
+* It is `forwardScope` (see `./scope.ts`), the same rule every internal
+* hop uses, so a request context and a cascade forward identically:
 *
-* - `organizationId` — multi-tenant scope key. The
-*   `multiTenantPlugin` casts to `ObjectId` automatically when
-*   configured with `fieldType: 'objectId'`; do NOT pre-cast.
-* - `userId` / `user` — audit attribution (audit-log + audit-trail
-*   plugins read these for the `who` column).
-* - `session` — mongoose `ClientSession` for transaction threading.
-* - `requestId` — observability correlation id.
+* - the tenant (`organizationId`, `tenantId`) — `multiTenantPlugin` casts
+*   to `ObjectId` itself when configured with `fieldType: 'objectId'`;
+*   do NOT pre-cast;
+* - `bypassTenant`, only when literally `true` AND no tenant is present
+*   (the tenant plugin honours a bypass before a tenant, so carrying both
+*   would widen a scoped call to every tenant);
+* - `session`, and `user` / `userId` / `requestId` for attribution.
 *
-* Fields beyond this set should be added inline at the call site —
-* `repoOptionsFromCtx` deliberately stays narrow so adding a new
-* convention to the canonical set is a deliberate API decision, not
-* a quiet drift.
+* Domain fields beyond this set belong to `createOptionsExtractor`.
 */
 function repoOptionsFromCtx(ctx) {
-	if (!ctx) return {};
-	const out = {};
-	if (ctx.organizationId !== void 0) out.organizationId = ctx.organizationId;
-	if (ctx.userId !== void 0) out.userId = ctx.userId;
-	if (ctx.user !== void 0) out.user = ctx.user;
-	if (ctx.session !== void 0) out.session = ctx.session;
-	if (ctx.requestId !== void 0) out.requestId = ctx.requestId;
-	return out;
+	return forwardScope(ctx);
 }
 /**
 * Build a typed extractor for **consumer-defined** ctx → options
@@ -1608,12 +1219,11 @@ function repoOptionsFromCtx(ctx) {
 * output keys are inferred from the input field tuple — you can
 * destructure with full autocomplete.
 *
-* **Difference from `repoOptionsFromCtx`.** That helper hardcodes the
-* fields **mongokit's bundled plugins** read (`organizationId`,
-* `userId`, `user`, `session`, `requestId`). Use it when those are
-* sufficient. Reach for `createOptionsExtractor` when your domain has
-* its own canonical fields (`actorRef`, `actorKind`, `correlationId`,
-* `idempotencyKey`, `sagaRunId`, ...) that should also forward.
+* **Scope is always included, and never from `fields`.** The extractor
+* returns `forwardScope(ctx)` plus the declared DOMAIN fields. Listing a
+* scope key (`organizationId`, `bypassTenant`, `session`, …) in `fields`
+* changes nothing: those follow the one scope rule, so an extractor cannot
+* forget the bypass, or carry a bypass beside a tenant.
 *
 * @example Per-package canonical extractor
 * ```ts
@@ -1628,12 +1238,12 @@ function repoOptionsFromCtx(ctx) {
 *   idempotencyKey?: string;
 * };
 *
+* // Domain fields only: the scope (organizationId, session, bypass) is
+* // always included by the one scope rule.
 * export const repoOptionsFromCtx = createOptionsExtractor<CommissionCtx>([
-*   'organizationId',
 *   'actorRef',
 *   'actorKind',
 *   'correlationId',
-*   'session',
 *   'idempotencyKey',
 * ]);
 *
@@ -1649,11 +1259,11 @@ function repoOptionsFromCtx(ctx) {
 *   options bag never erases inherited values).
 */
 function createOptionsExtractor(fields) {
-	const frozen = Object.freeze([...fields]);
+	const domainFields = Object.freeze(fields.filter((field) => !isScopeKey(field)));
 	return function extractRepoOptions(ctx) {
 		if (!ctx) return {};
-		const out = {};
-		for (const field of frozen) {
+		const out = forwardScope(ctx);
+		for (const field of domainFields) {
 			const v = ctx[field];
 			if (v !== void 0) out[field] = v;
 		}
@@ -1781,4 +1391,4 @@ function systemContext(extra) {
 */
 var src_default = Repository;
 //#endregion
-export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, ModelCollisionError, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, capabilitiesForSupport, cascadePlugin, cascadePurgeReferences, classifyHelloReply, compileFilterToMongo, configureLogger, configurePaginationDefaults, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, defineModel, defineModels, elasticSearchPlugin, ensureAuditTrailReady, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, getPaginationDefaults, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isCreateManyPartialError, isDuplicateKeyError, isModelRegistered, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, probeMongoCapabilities, repoOptionsFromCtx, requireField, resetCapabilityProbeCache, resetPaginationDefaults, resolveMongoCapabilities, resolveTransactionSupport, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, timestampPlugin, toPlain, transactionResolutionOf, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, ModelCollisionError, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, capabilitiesForSupport, cascadePlugin, cascadePurgeReferences, classifyHelloReply, compileFilterToMongo, configureLogger, configurePaginationDefaults, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, declareTenantContextKey, src_default as default, defineModel, defineModels, elasticSearchPlugin, ensureAuditTrailReady, ensureSequenceAtLeast, fieldFilterPlugin, filterResponseData, forwardScope, getFieldsForUser, getMongooseProjection, getNextSequence, getPaginationDefaults, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isCreateManyPartialError, isDuplicateKeyError, isModelRegistered, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, probeMongoCapabilities, readSequence, repoOptionsFromCtx, requireField, resetCapabilityProbeCache, resetPaginationDefaults, resolveMongoCapabilities, resolveTransactionSupport, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, tenantContextKeysOf, timestampPlugin, toPlain, transactionResolutionOf, uniqueField, validationChainPlugin, withTransaction };