@classytic/repo-core 0.3.0 → 0.4.0

package/dist/filter/match.mjs

@@ -30,12 +30,12 @@ function matchFilter(doc, filter) {
 			const v = getField(doc, filter.field);
 			if (typeof v !== "string") return false;
 			const flags = filter.caseSensitivity === "sensitive" ? "" : "i";
-			return new RegExp(`^${likeToRegex(filter.pattern)}$`, flags).test(v);
+			return getOrCompileLike(filter.pattern, flags).test(v);
 		}
 		case "regex": {
 			const v = getField(doc, filter.field);
 			if (typeof v !== "string") return false;
-			return new RegExp(filter.pattern, filter.flags).test(v);
+			return getOrCompileRegex(filter.pattern, filter.flags).test(v);
 		}
 		case "raw": return false;
 	}
@@ -78,6 +78,42 @@ function toComparable(value) {
 	if (typeof value === "number" || typeof value === "string") return value;
 	if (typeof value === "boolean") return value ? 1 : 0;
 }
+/**
+* Compiled-RegExp caches keyed by `pattern|flags`. Without these, a
+* filter run via `asPredicate(filter)` over an N-doc array compiles a
+* fresh `new RegExp(...)` on every doc — at 100k docs and a non-trivial
+* pattern, that's measurable. Bounded LRU eviction keeps the cache
+* from growing unboundedly when callers hand us thousands of distinct
+* patterns (e.g. "name LIKE %" personalization at scale).
+*/
+const REGEX_CACHE_LIMIT = 256;
+const likeCache = /* @__PURE__ */ new Map();
+const regexCache = /* @__PURE__ */ new Map();
+function getOrCompileLike(pattern, flags) {
+	const key = `${flags}|${pattern}`;
+	let re = likeCache.get(key);
+	if (re) return re;
+	re = new RegExp(`^${likeToRegex(pattern)}$`, flags);
+	if (likeCache.size >= REGEX_CACHE_LIMIT) {
+		const oldest = likeCache.keys().next().value;
+		if (oldest !== void 0) likeCache.delete(oldest);
+	}
+	likeCache.set(key, re);
+	return re;
+}
+function getOrCompileRegex(pattern, flags) {
+	const f = flags ?? "";
+	const key = `${f}|${pattern}`;
+	let re = regexCache.get(key);
+	if (re) return re;
+	re = new RegExp(pattern, f);
+	if (regexCache.size >= REGEX_CACHE_LIMIT) {
+		const oldest = regexCache.keys().next().value;
+		if (oldest !== void 0) regexCache.delete(oldest);
+	}
+	regexCache.set(key, re);
+	return re;
+}
 /** SQL `LIKE` pattern → JS regex body. Escapes regex metachars; `%` → `.*`, `_` → `.`. */
 function likeToRegex(pattern) {
 	let out = "";

package/dist/pagination/canonical.d.mts

@@ -1,4 +1,4 @@
-import { AnyPaginationResult, BareListResponse, PaginatedResponse } from "./types.mjs";
+import { AnyPaginationResult, BareListResult, PaginatedResult } from "./types.mjs";
 
 //#region src/pagination/canonical.d.ts
 /**
@@ -11,7 +11,7 @@ import { AnyPaginationResult, BareListResponse, PaginatedResponse } from "./type
  *
  * Accepts `unknown` (rather than `T[] | AnyPaginationResult<T>`) so wire-
  * boundary callers can guard arbitrary inputs without pre-narrowing — the
- * arc / arc-next response pipeline routinely sees `{ docs: unknown[] }`
+ * arc / arc-next response pipeline routinely sees `{ data: unknown[] }`
  * shapes that are neither a bare array nor a paginated result, and forcing
  * those callers to cast first defeats the guard's purpose.
  */
@@ -20,16 +20,16 @@ declare function isPaginatedResult<TDoc>(input: unknown): input is AnyPagination
  * Normalise a list-shaped value into the canonical wire envelope.
  *
  * Overloads keep the return type tight:
- *   - bare array  → {@link BareListResponse}
- *   - paginated   → {@link PaginatedResponse} (preserves method discriminant)
+ *   - bare array  → {@link BareListResult}
+ *   - paginated   → {@link PaginatedResult} (preserves method discriminant)
  *
  * The mutable-array overload widens to `TDoc[]` because that's the most
  * common server input (kit results return `TDoc[]` for `docs`); the
  * readonly overload covers callers passing `readonly TDoc[]`.
  */
-declare function toCanonicalList<TDoc>(input: TDoc[]): BareListResponse<TDoc>;
-declare function toCanonicalList<TDoc>(input: readonly TDoc[]): BareListResponse<TDoc>;
-declare function toCanonicalList<TDoc, TExtra extends Record<string, unknown>>(input: AnyPaginationResult<TDoc, TExtra>): PaginatedResponse<TDoc, TExtra>;
-declare function toCanonicalList<TDoc>(input: readonly TDoc[] | AnyPaginationResult<TDoc>): PaginatedResponse<TDoc>;
+declare function toCanonicalList<TDoc>(input: TDoc[]): BareListResult<TDoc>;
+declare function toCanonicalList<TDoc>(input: readonly TDoc[]): BareListResult<TDoc>;
+declare function toCanonicalList<TDoc, TExtra extends Record<string, unknown>>(input: AnyPaginationResult<TDoc, TExtra>): PaginatedResult<TDoc, TExtra>;
+declare function toCanonicalList<TDoc>(input: readonly TDoc[] | AnyPaginationResult<TDoc>): PaginatedResult<TDoc>;
 //#endregion
 export { isPaginatedResult, toCanonicalList };

package/dist/pagination/canonical.mjs

@@ -9,7 +9,7 @@
 *
 * Accepts `unknown` (rather than `T[] | AnyPaginationResult<T>`) so wire-
 * boundary callers can guard arbitrary inputs without pre-narrowing — the
-* arc / arc-next response pipeline routinely sees `{ docs: unknown[] }`
+* arc / arc-next response pipeline routinely sees `{ data: unknown[] }`
 * shapes that are neither a bare array nor a paginated result, and forcing
 * those callers to cast first defeats the guard's purpose.
 */
@@ -19,14 +19,8 @@ function isPaginatedResult(input) {
 	return method === "offset" || method === "keyset" || method === "aggregate";
 }
 function toCanonicalList(input) {
-	if (isPaginatedResult(input)) return {
-		...input,
-		success: true
-	};
-	return {
-		success: true,
-		docs: [...input]
-	};
+	if (isPaginatedResult(input)) return { ...input };
+	return { data: [...input] };
 }
 //#endregion
 export { isPaginatedResult, toCanonicalList };

package/dist/pagination/cursor.mjs

@@ -104,7 +104,10 @@ function validateCursorVersion(cursorVersion, expectedVersion, minVersion = 1) {
 function isValidPayload(payload) {
 	if (!payload || typeof payload !== "object") return false;
 	const p = payload;
-	return "v" in p && typeof p["t"] === "string" && typeof p["id"] === "string" && typeof p["idType"] === "string" && typeof p["sort"] === "object" && p["sort"] !== null && typeof p["ver"] === "number";
+	return isSerializedScalar(p["v"]) && typeof p["t"] === "string" && typeof p["id"] === "string" && typeof p["idType"] === "string" && typeof p["sort"] === "object" && p["sort"] !== null && !Array.isArray(p["sort"]) && typeof p["ver"] === "number" && Number.isFinite(p["ver"]);
+}
+function isSerializedScalar(v) {
+	return v === null || typeof v === "string" || typeof v === "number" && Number.isFinite(v) || typeof v === "boolean";
 }
 function serializeValue(value) {
 	if (value === null || value === void 0) return null;

package/dist/pagination/index.d.mts

@@ -1,6 +1,6 @@
-import { AggregatePaginationResponse, AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResponse, CursorPayload, DecodedCursor, KeysetPaginationResponse, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResponse, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResponse, PaginationConfig, SortDirection, SortSpec, ValueType } from "./types.mjs";
+import { AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResult, CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResult, PaginationConfig, SortDirection, SortSpec, ValueType } from "./types.mjs";
 import { isPaginatedResult, toCanonicalList } from "./canonical.mjs";
 import { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion } from "./cursor.mjs";
 import { getPrimaryField, invertSort, normalizeSort, validateKeysetSort } from "./keyset.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./offset.mjs";
-export { type AggregatePaginationResponse, type AggregatePaginationResult, type AggregatePaginationResultCore, type AnyPaginationResult, type BareListResponse, type CursorPayload, type DecodedCursor, type KeysetPaginationResponse, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResponse, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginatedResponse, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };
+export { type AggregatePaginationResult, type AggregatePaginationResultCore, type AnyPaginationResult, type BareListResult, type CursorPayload, type DecodedCursor, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginatedResult, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };

package/dist/pagination/types.d.mts

@@ -87,7 +87,7 @@ interface DecodedCursor {
  */
 interface OffsetPaginationResultCore<TDoc> {
   method: 'offset';
-  docs: TDoc[];
+  data: TDoc[];
   page: number;
   limit: number;
   total: number;
@@ -119,7 +119,7 @@ type OffsetPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> =
  */
 interface KeysetPaginationResultCore<TDoc> {
   method: 'keyset';
-  docs: TDoc[];
+  data: TDoc[];
   limit: number;
   hasMore: boolean;
   /** Cursor token for the next page, or `null` when there is none. */
@@ -145,7 +145,7 @@ type KeysetPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> =
  */
 interface AggregatePaginationResultCore<TDoc> {
   method: 'aggregate';
-  docs: TDoc[];
+  data: TDoc[];
   page: number;
   limit: number;
   total: number;
@@ -168,33 +168,23 @@ type AggregatePaginationResult<TDoc, TExtra extends Record<string, unknown> = {}
  * see {@link toCanonicalList}.
  */
 type AnyPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra> | AggregatePaginationResult<TDoc, TExtra>;
-/** HTTP success envelope wrapping {@link OffsetPaginationResult}. */
-type OffsetPaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
-  success: true;
-} & OffsetPaginationResult<TDoc, TExtra>;
-/** HTTP success envelope wrapping {@link KeysetPaginationResult}. */
-type KeysetPaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
-  success: true;
-} & KeysetPaginationResult<TDoc, TExtra>;
-/** HTTP success envelope wrapping {@link AggregatePaginationResult}. */
-type AggregatePaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
-  success: true;
-} & AggregatePaginationResult<TDoc, TExtra>;
 /**
- * Bare list envelope — a successful response that wasn't paginated (raw
- * array result). No `method` discriminant; consumers branch on the absence
- * of pagination fields. Most useful when an endpoint sometimes paginates
- * and sometimes returns a fixed-size list.
+ * Bare list shape — an endpoint that doesn't paginate (raw array wrapped
+ * in `{data}` for consistency with paginated shapes). Consumers narrow on
+ * the absence of `method`. The `{data}` wrapper (vs returning the raw
+ * array) leaves room to add pagination metadata later without breaking
+ * the consumer contract.
  */
-interface BareListResponse<TDoc> {
-  success: true;
-  docs: TDoc[];
+interface BareListResult<TDoc> {
+  data: TDoc[];
 }
 /**
- * Union of every wire envelope a paginated/list endpoint can emit. Locked
- * to `success: true` because errors take a separate envelope shape — a
- * client-side type guard checks `success` first, then `method`.
+ * Union of every list shape an endpoint can emit — paginated (offset,
+ * keyset, aggregate) OR bare (`{data}` only). Discriminate via
+ * `'method' in result` — `method === 'offset' | 'keyset' | 'aggregate'`
+ * for paginated, absent for bare lists. Errors live on a separate path
+ * (HTTP status >= 400 → `ErrorContract`).
  */
-type PaginatedResponse<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResponse<TDoc, TExtra> | KeysetPaginationResponse<TDoc, TExtra> | AggregatePaginationResponse<TDoc, TExtra> | BareListResponse<TDoc>;
+type PaginatedResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra> | AggregatePaginationResult<TDoc, TExtra> | BareListResult<TDoc>;
 //#endregion
-export { AggregatePaginationResponse, AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResponse, CursorPayload, DecodedCursor, KeysetPaginationResponse, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResponse, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResponse, PaginationConfig, SortDirection, SortSpec, ValueType };
+export { AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResult, CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResult, PaginationConfig, SortDirection, SortSpec, ValueType };

package/dist/plugins/index.d.mts

@@ -0,0 +1,2 @@
+import { TenantPolicyContext, adminBypass, payloadHasTenantField } from "./tenant-helpers.mjs";
+export { type TenantPolicyContext, adminBypass, payloadHasTenantField };

package/dist/plugins/index.mjs

@@ -0,0 +1,2 @@
+import { adminBypass, payloadHasTenantField } from "./tenant-helpers.mjs";
+export { adminBypass, payloadHasTenantField };

package/dist/plugins/tenant-helpers.d.mts

@@ -0,0 +1,63 @@
+import { PolicyKey } from "../operations/types.mjs";
+
+//#region src/plugins/tenant-helpers.d.ts
+/**
+ * Minimal context shape this module reads. Kits' richer
+ * `RepositoryContext` types extend this — by accepting only the slots
+ * we touch, we avoid coupling repo-core to any kit's typing.
+ */
+interface TenantPolicyContext {
+  readonly data?: Record<string, unknown>;
+  readonly dataArray?: readonly Record<string, unknown>[];
+  readonly query?: unknown;
+  readonly filters?: unknown;
+  readonly operations?: unknown;
+}
+/**
+ * True when the op's policy target already has `tenantField` set by
+ * the caller. Used to decide whether the plugin can safely skip
+ * injecting a tenant scope rather than throwing on a missing context.
+ *
+ * - `data`       — `context.data[tenantField]` is present
+ * - `dataArray`  — every row in `context.dataArray` has `tenantField`
+ * - `query`      — `context.query[tenantField]` is present
+ * - `filters`    — `context.filters[tenantField]` is present
+ * - `operations` — every bulkWrite sub-op's filter/document has `tenantField`
+ * - `none`       — unreachable (the hook isn't registered for these ops)
+ *
+ * For multi-row targets (`dataArray`, `operations`) we require EVERY
+ * row to be stamped. Partial stamping is ambiguous (we have no
+ * resolver value to fill in the gaps) and is safer to treat as "not
+ * stamped" so the caller either stamps all rows or supplies a
+ * context/resolver.
+ */
+declare function payloadHasTenantField(context: TenantPolicyContext, policyKey: PolicyKey, tenantField: string): boolean;
+/**
+ * Build a `skipWhen`-compatible callback that bypasses tenant scoping
+ * when the caller's role is in `adminRoles`. Composable with any
+ * kit's multi-tenant plugin shape.
+ *
+ * The factory does an exact-match `Set.has` check — case-sensitive,
+ * no fuzzy matching. Lowercase your role vocabulary upstream.
+ *
+ * @example
+ * ```ts
+ * multiTenantPlugin({
+ *   resolveTenantId: ctx => ctx.organizationId,
+ *   skipWhen: adminBypass({ adminRoles: ['superadmin', 'support'] }),
+ * });
+ * ```
+ *
+ * @param options.roleField  Context key holding the role string (default: `'role'`)
+ * @param options.adminRoles Roles that bypass tenant scope. Frozen on
+ *   factory construction so callers can't mutate the list afterward
+ *   and silently change bypass semantics across plugin instances
+ *   sharing the array reference.
+ * @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+ */
+declare function adminBypass(options: {
+  roleField?: string;
+  adminRoles: readonly string[];
+}): (context: Record<string, unknown>, operation: string) => boolean;
+//#endregion
+export { TenantPolicyContext, adminBypass, payloadHasTenantField };

package/dist/plugins/tenant-helpers.mjs

@@ -0,0 +1,84 @@
+//#region src/plugins/tenant-helpers.ts
+/**
+* True when the op's policy target already has `tenantField` set by
+* the caller. Used to decide whether the plugin can safely skip
+* injecting a tenant scope rather than throwing on a missing context.
+*
+* - `data`       — `context.data[tenantField]` is present
+* - `dataArray`  — every row in `context.dataArray` has `tenantField`
+* - `query`      — `context.query[tenantField]` is present
+* - `filters`    — `context.filters[tenantField]` is present
+* - `operations` — every bulkWrite sub-op's filter/document has `tenantField`
+* - `none`       — unreachable (the hook isn't registered for these ops)
+*
+* For multi-row targets (`dataArray`, `operations`) we require EVERY
+* row to be stamped. Partial stamping is ambiguous (we have no
+* resolver value to fill in the gaps) and is safer to treat as "not
+* stamped" so the caller either stamps all rows or supplies a
+* context/resolver.
+*/
+function payloadHasTenantField(context, policyKey, tenantField) {
+	switch (policyKey) {
+		case "data": return context.data?.[tenantField] != null;
+		case "dataArray": {
+			const arr = context.dataArray;
+			if (!Array.isArray(arr) || arr.length === 0) return false;
+			return arr.every((row) => row && row[tenantField] != null);
+		}
+		case "query": return context.query?.[tenantField] != null;
+		case "filters": return context.filters?.[tenantField] != null;
+		case "operations": {
+			const ops = context.operations;
+			if (!Array.isArray(ops) || ops.length === 0) return false;
+			return ops.every((subOp) => {
+				for (const key of [
+					"updateOne",
+					"updateMany",
+					"deleteOne",
+					"deleteMany",
+					"replaceOne"
+				]) {
+					const body = subOp[key];
+					if (body) return body["filter"]?.[tenantField] != null;
+				}
+				const ins = subOp["insertOne"];
+				if (ins) return ins["document"]?.[tenantField] != null;
+				return false;
+			});
+		}
+		default: return false;
+	}
+}
+/**
+* Build a `skipWhen`-compatible callback that bypasses tenant scoping
+* when the caller's role is in `adminRoles`. Composable with any
+* kit's multi-tenant plugin shape.
+*
+* The factory does an exact-match `Set.has` check — case-sensitive,
+* no fuzzy matching. Lowercase your role vocabulary upstream.
+*
+* @example
+* ```ts
+* multiTenantPlugin({
+*   resolveTenantId: ctx => ctx.organizationId,
+*   skipWhen: adminBypass({ adminRoles: ['superadmin', 'support'] }),
+* });
+* ```
+*
+* @param options.roleField  Context key holding the role string (default: `'role'`)
+* @param options.adminRoles Roles that bypass tenant scope. Frozen on
+*   factory construction so callers can't mutate the list afterward
+*   and silently change bypass semantics across plugin instances
+*   sharing the array reference.
+* @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+*/
+function adminBypass(options) {
+	const { roleField = "role", adminRoles } = options;
+	const allowed = new Set(adminRoles);
+	return function skipWhenAdmin(context) {
+		const role = context[roleField];
+		return typeof role === "string" && allowed.has(role);
+	};
+}
+//#endregion
+export { adminBypass, payloadHasTenantField };

package/dist/query-parser/index.d.mts

@@ -1,4 +1,5 @@
 import { BracketOperator, ParsedPopulate, ParsedQuery, ParsedSelect, ParsedSort, ParsedSortDirection, QueryParserInput, QueryParserOptions } from "./types.mjs";
 import { coerceList, coerceValue } from "./coerce.mjs";
 import { parseUrl } from "./parse-url.mjs";
-export { type BracketOperator, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryParserInput, type QueryParserOptions, coerceList, coerceValue, parseUrl };
+import { STANDARD_RESERVED_PARAMS, isControlParam } from "./reserved.mjs";
+export { type BracketOperator, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryParserInput, type QueryParserOptions, STANDARD_RESERVED_PARAMS, coerceList, coerceValue, isControlParam, parseUrl };

package/dist/query-parser/index.mjs

@@ -1,3 +1,4 @@
 import { coerceList, coerceValue } from "./coerce.mjs";
+import { STANDARD_RESERVED_PARAMS, isControlParam } from "./reserved.mjs";
 import { parseUrl } from "./parse-url.mjs";
-export { coerceList, coerceValue, parseUrl };
+export { STANDARD_RESERVED_PARAMS, coerceList, coerceValue, isControlParam, parseUrl };

package/dist/query-parser/parse-url.mjs

@@ -1,21 +1,21 @@
 import { TRUE, and, between, contains, endsWith, eq, gt, gte, iEq, in_, isNotNull, isNull, like, lt, lte, ne, nin, regex, startsWith } from "../filter/builders.mjs";
 import { coerceList, coerceValue } from "./coerce.mjs";
+import { isControlParam } from "./reserved.mjs";
 //#region src/query-parser/parse-url.ts
 const DEFAULT_LIMIT = 20;
 const DEFAULT_MAX_LIMIT = 200;
 const DEFAULT_MAX_DEPTH = 10;
 const DEFAULT_MAX_REGEX = 500;
 const DEFAULT_MAX_SEARCH = 200;
-/** Reserved top-level URL keys the parser handles specially. */
-const RESERVED_KEYS = new Set([
-	"page",
-	"limit",
-	"after",
-	"sort",
-	"select",
-	"populate",
-	"search"
-]);
+/**
+* Hard cap on URL parameter KEY length. Param keys land in regex-based
+* bracket parsing (`/^([^[\]]+)\[([^\]]+)\]$/` and friends); without a
+* length bound, a hostile caller can submit a 1MB key and force the
+* parser to scan the entire string for every regex try. Keys that
+* exceed this cap are silently skipped — legitimate URL params don't
+* approach this bound.
+*/
+const MAX_PARAM_KEY_LENGTH = 256;
 const ALL_OPERATORS = new Set([
 	"eq",
 	"ne",
@@ -134,6 +134,7 @@ function parseSelect(raw) {
 function parsePopulate(params) {
 	const byField = /* @__PURE__ */ new Map();
 	for (const [key, value] of params.entries()) {
+		if (key.length > MAX_PARAM_KEY_LENGTH) continue;
 		if (!key.startsWith("populate[")) continue;
 		const match = /^populate\[([^\]]+)\](?:\[([^\]]+)\](?:\[([^\]]+)\])?)?$/.exec(key);
 		if (!match) continue;
@@ -163,7 +164,8 @@ function parseFilters(params, ctx) {
 	const leaves = [];
 	const fieldGroups = /* @__PURE__ */ new Map();
 	for (const [key, rawValue] of params.entries()) {
-		if (RESERVED_KEYS.has(key) || key.startsWith("populate[")) continue;
+		if (key.length > MAX_PARAM_KEY_LENGTH) continue;
+		if (isControlParam(key) || key.startsWith("populate[")) continue;
 		const bracket = /^([^[\]]+)\[([^\]]+)\]$/.exec(key);
 		let field;
 		let op;

package/dist/query-parser/reserved.d.mts

@@ -0,0 +1,43 @@
+//#region src/query-parser/reserved.d.ts
+/**
+ * URL parameter keys reserved by the framework — never parsed as
+ * filter predicates. Two categories:
+ *
+ * 1. **Pagination / list-control params** — `page`, `limit`, `after`,
+ *    `sort`, `select`, `populate`, `search`. Universal across kits;
+ *    every backend agrees on their meaning.
+ *
+ * 2. **Resource-dispatch verbs** — `_count`, `_distinct`, `_exists`.
+ *    Arc-style frameworks pick the repo method from these URL keys
+ *    (list vs count vs distinct vs exists).
+ *
+ * **Why an explicit allowlist, not a `_*` namespace.** MongoDB's `_id`
+ * (and every kit's analog) is a legitimate filter field; user-defined
+ * `_internal`, `_meta`, `_v` fields are common in real schemas. A
+ * blanket `key.startsWith('_')` rule silently drops filters on these.
+ * Adding a new dispatch verb here is a deliberate ecosystem-wide
+ * change — small, audited, and only needed every few major versions.
+ */
+/**
+ * Reserved top-level URL keys handled outside the filter pipeline.
+ * Pagination + sort + select + populate + search + resource-dispatch
+ * verbs (`_count`, `_distinct`, `_exists`).
+ */
+declare const STANDARD_RESERVED_PARAMS: ReadonlySet<string>;
+/**
+ * True when `key` is a framework-reserved URL parameter and should be
+ * skipped during filter parsing.
+ *
+ * Use in any URL-parser implementation that decides "is this a filter
+ * predicate or a control flag?":
+ *
+ * ```ts
+ * for (const [key, value] of params.entries()) {
+ *   if (isControlParam(key)) continue;  // skip page, limit, _count, ...
+ *   // … parse as filter predicate
+ * }
+ * ```
+ */
+declare function isControlParam(key: string): boolean;
+//#endregion
+export { STANDARD_RESERVED_PARAMS, isControlParam };

package/dist/query-parser/reserved.mjs

@@ -0,0 +1,56 @@
+//#region src/query-parser/reserved.ts
+/**
+* URL parameter keys reserved by the framework — never parsed as
+* filter predicates. Two categories:
+*
+* 1. **Pagination / list-control params** — `page`, `limit`, `after`,
+*    `sort`, `select`, `populate`, `search`. Universal across kits;
+*    every backend agrees on their meaning.
+*
+* 2. **Resource-dispatch verbs** — `_count`, `_distinct`, `_exists`.
+*    Arc-style frameworks pick the repo method from these URL keys
+*    (list vs count vs distinct vs exists).
+*
+* **Why an explicit allowlist, not a `_*` namespace.** MongoDB's `_id`
+* (and every kit's analog) is a legitimate filter field; user-defined
+* `_internal`, `_meta`, `_v` fields are common in real schemas. A
+* blanket `key.startsWith('_')` rule silently drops filters on these.
+* Adding a new dispatch verb here is a deliberate ecosystem-wide
+* change — small, audited, and only needed every few major versions.
+*/
+/**
+* Reserved top-level URL keys handled outside the filter pipeline.
+* Pagination + sort + select + populate + search + resource-dispatch
+* verbs (`_count`, `_distinct`, `_exists`).
+*/
+const STANDARD_RESERVED_PARAMS = new Set([
+	"page",
+	"limit",
+	"after",
+	"sort",
+	"select",
+	"populate",
+	"search",
+	"_count",
+	"_distinct",
+	"_exists"
+]);
+/**
+* True when `key` is a framework-reserved URL parameter and should be
+* skipped during filter parsing.
+*
+* Use in any URL-parser implementation that decides "is this a filter
+* predicate or a control flag?":
+*
+* ```ts
+* for (const [key, value] of params.entries()) {
+*   if (isControlParam(key)) continue;  // skip page, limit, _count, ...
+*   // … parse as filter predicate
+* }
+* ```
+*/
+function isControlParam(key) {
+	return STANDARD_RESERVED_PARAMS.has(key);
+}
+//#endregion
+export { STANDARD_RESERVED_PARAMS, isControlParam };

package/dist/repository/agg-output.d.mts

@@ -0,0 +1,63 @@
+//#region src/repository/agg-output.d.ts
+/**
+ * Cross-kit AggResult row-shape normalization.
+ *
+ * When an `AggRequest` includes `lookups` and `groupBy` references a
+ * joined-alias path (e.g. `'department.code'`), the row that lands in
+ * `AggResult.rows` carries the joined data as a NESTED object:
+ *
+ *   ```ts
+ *   { status: 'pending', department: { code: 'ENG' }, count: 3 }
+ *   ```
+ *
+ * Same convention `lookupPopulate` uses. Mongokit's `$project` with
+ * dotted-key output naturally nests; sqlitekit gets flat-dotted keys
+ * from Drizzle's SELECT alias map and runs results through
+ * `nestDottedKeys` before returning.
+ *
+ * **Why nested over flat-dotted?**
+ *   - Matches `lookupPopulate` precedent (single convention across
+ *     all read primitives).
+ *   - JSON-clean: `{ department: { code: 'ENG' } }` round-trips
+ *     identically through `JSON.stringify` / `parse`.
+ *   - Cleaner consumer code: `row.department.code` vs
+ *     `row['department.code']`.
+ *   - BSON allows nested but disallows literal `.` in field names —
+ *     the only shape that works in mongo without BSON workarounds.
+ *
+ * **Out of scope**:
+ *   - Multi-level dotted paths (`'a.b.c'`) — kits don't emit these
+ *     today (single-level joins only). The helper handles them
+ *     correctly by recursive descent so future depth is supported.
+ *   - Conflicting flat + nested keys on the same row (e.g. both
+ *     `department` and `department.code`). The flat-dotted side wins;
+ *     a top-level `department` value gets overwritten when a
+ *     `department.<x>` partner key is processed. In practice this
+ *     never happens — kits emit one or the other per groupBy key.
+ */
+/**
+ * Walk a row's top-level keys, splitting any that contain `.` into
+ * nested objects. Keys without `.` pass through unchanged. Mutates a
+ * fresh output object — the input is not modified.
+ *
+ * @example
+ * ```ts
+ * nestDottedKeys({ status: 'pending', 'department.code': 'ENG', count: 3 })
+ * // → { status: 'pending', department: { code: 'ENG' }, count: 3 }
+ * ```
+ *
+ * Multi-level paths (`a.b.c`) recurse:
+ *
+ * ```ts
+ * nestDottedKeys({ 'a.b.c': 1 })
+ * // → { a: { b: { c: 1 } } }
+ * ```
+ */
+declare function nestDottedKeys<T extends Record<string, unknown>>(row: T): Record<string, unknown>;
+/**
+ * Convenience wrapper for an array of rows. Returns a new array of
+ * normalized rows; the input is not modified.
+ */
+declare function nestDottedKeysAll<T extends Record<string, unknown>>(rows: readonly T[]): Record<string, unknown>[];
+//#endregion
+export { nestDottedKeys, nestDottedKeysAll };