@classytic/repo-core 0.2.0 → 0.4.0

package/dist/errors/types.d.mts

@@ -1,12 +1,28 @@
 //#region src/errors/types.d.ts
 /**
- * HTTP-shaped error contract used across every driver kit.
+ * HTTP-shaped error contracts used across every driver kit, integrator,
+ * and HTTP-emitting service in the org.
  *
- * An `HttpError` is a plain `Error` with a `status` field and optional
- * structured fields for duplicate-key and validation conflicts. Kits
- * classify their driver-specific errors into this shape at the boundary,
- * so the framework layer (arc) never needs to know whether the error
- * originated from MongoDB `E11000`, Postgres `23505`, or Prisma `P2002`.
+ * **`@classytic/repo-core/errors` is the canonical home for the wire +
+ * throwable error contract.** Two complementary shapes live here:
+ *
+ *   - {@link HttpError} — the *throwable* shape. Plain `Error` with
+ *     `status` and optional structured fields. Kits classify their
+ *     driver-specific errors into this shape at the boundary; framework
+ *     layers (arc) catch and serialize.
+ *   - {@link ErrorContract} — the *wire* shape (RFC 7807 / Stripe-style).
+ *     What gets serialized into JSON responses, queue dead-letter records,
+ *     audit logs, and inter-service error envelopes.
+ *
+ * Throwable classes (arc's `ArcError` family, future `BillingError` etc.)
+ * `implements HttpError` and serialize to `ErrorContract` for the wire.
+ * One contract, one canonical home, every package follows the same shape.
+ *
+ * **Custom-domain escape hatch.** {@link ErrorCode} is a documented union
+ * of canonical codes; `code: string` accepts ANY string so domain packages
+ * can extend (`'order.validation.missing_line'`, `'payment.gateway.timeout'`).
+ * The canonical codes cover cross-cutting concerns; domain extensions
+ * hierarchically narrow.
  */
 /** Structured metadata for duplicate-key (unique-constraint) errors. */
 interface DuplicateKeyMeta {
@@ -24,14 +40,103 @@ interface ValidationErrorMeta {
   validator: string;
   error: string;
 }
-/** HTTP-shaped error — the envelope every repository error resolves to. */
+/**
+ * HTTP-shaped error — the throwable envelope every repository error and
+ * arc handler resolves to.
+ *
+ * Note: `code` and `meta` are optional but every long-lived production
+ * handler should populate them. `code` lets clients switch on
+ * machine-readable identifiers without grepping `message`; `meta` carries
+ * structured diagnostics safe for logs.
+ */
 interface HttpError extends Error {
   /** HTTP status code (400, 404, 409, 500, ...). */
   status: number;
+  /**
+   * Stable machine-readable error code. Use one of {@link ErrorCode} for
+   * cross-cutting cases or extend hierarchically with a domain prefix
+   * (`'order.validation.missing_line'`, `'payment.gateway.timeout'`).
+   * Hosts switch on this in catch blocks instead of regex-matching
+   * `message`.
+   */
+  code?: string;
+  /**
+   * Free-form structured metadata for diagnostics. Pairs with `code` so
+   * hosts can render a clearer message in their own UI without parsing
+   * `message`. Safe for logs (don't include PII).
+   */
+  meta?: Record<string, unknown>;
   /** Structured validation failures when `status` is 400. */
   validationErrors?: ValidationErrorMeta[];
   /** Structured duplicate-key metadata when `status` is 409. */
   duplicate?: DuplicateKeyMeta;
 }
+/**
+ * Standard error contract — a framework-agnostic JSON shape that maps
+ * cleanly to HTTP responses, worker failure logs, and inter-service
+ * errors. Loosely matches RFC 7807 (`application/problem+json`); shape
+ * matches Stripe / Shopify / Slack API conventions.
+ *
+ * Packages throw `HttpError` instances. Hosts (HTTP adapters, workers)
+ * serialize those errors into this shape on the wire via
+ * {@link toErrorContract}. Wire shape is FLAT (top-level `code` /
+ * `message` / `status`), not nested under `{ error: { ... } }` — matches
+ * the existing org-wide envelope convention. Hosts that need a
+ * Stripe-style nested envelope wrap once at the edge.
+ */
+interface ErrorContract {
+  /** Machine-readable, hierarchical code — e.g. `'order.validation.missing_line'`. */
+  code: string;
+  /** Human-readable, safe-for-client message. */
+  message: string;
+  /** Suggested HTTP status code — hosts may override. */
+  status?: number;
+  /**
+   * Field-scoped structured details. Populated for validation failures
+   * (one entry per offending field) or domain errors that map to multiple
+   * sub-codes. Distinct from `HttpError.validationErrors` (which is a
+   * mongokit-shaped throwable field) — the wire form is canonical.
+   */
+  details?: readonly ErrorDetail[];
+  /** Correlation / trace identifier for support lookups. */
+  correlationId?: string;
+  /** Non-PII metadata (safe to log, safe to return to clients). */
+  meta?: Readonly<Record<string, unknown>>;
+}
+/** A single field-scoped error detail. */
+interface ErrorDetail {
+  /** Dot-path pointer to the offending field, e.g. `'lines.0.quantity'`. */
+  path?: string;
+  code: string;
+  message: string;
+  meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Cross-cutting error codes used across the org. Every canonical code is
+ * lowercase + snake_case to match RFC 7807, Stripe, and Shopify
+ * conventions. Domain packages add their own hierarchical codes
+ * (`'order.validation.*'`, `'payment.gateway.*'`); these cover the
+ * universal cases every HTTP-emitting layer needs.
+ *
+ * **Arc compatibility note.** Arc's `ArcError` hierarchy historically
+ * uses UPPER_SNAKE codes (`'NOT_FOUND'`, `'VALIDATION_ERROR'`) for
+ * back-compat with hosts that switch on those values. New code should
+ * prefer the canonical lowercase codes; arc keeps emitting its UPPER_SNAKE
+ * codes on the wire so existing client switches keep working.
+ */
+declare const ERROR_CODES: {
+  readonly VALIDATION: "validation_error";
+  readonly NOT_FOUND: "not_found";
+  readonly CONFLICT: "conflict";
+  readonly UNAUTHORIZED: "unauthorized";
+  readonly FORBIDDEN: "forbidden";
+  readonly RATE_LIMITED: "rate_limited";
+  readonly IDEMPOTENCY_CONFLICT: "idempotency_conflict";
+  readonly PRECONDITION_FAILED: "precondition_failed";
+  readonly INTERNAL: "internal_error";
+  readonly UNAVAILABLE: "service_unavailable";
+  readonly TIMEOUT: "timeout";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
 //#endregion
-export { DuplicateKeyMeta, HttpError, ValidationErrorMeta };
+export { DuplicateKeyMeta, ERROR_CODES, ErrorCode, ErrorContract, ErrorDetail, HttpError, ValidationErrorMeta };

package/dist/errors/types.mjs

@@ -0,0 +1,29 @@
+//#region src/errors/types.ts
+/**
+* Cross-cutting error codes used across the org. Every canonical code is
+* lowercase + snake_case to match RFC 7807, Stripe, and Shopify
+* conventions. Domain packages add their own hierarchical codes
+* (`'order.validation.*'`, `'payment.gateway.*'`); these cover the
+* universal cases every HTTP-emitting layer needs.
+*
+* **Arc compatibility note.** Arc's `ArcError` hierarchy historically
+* uses UPPER_SNAKE codes (`'NOT_FOUND'`, `'VALIDATION_ERROR'`) for
+* back-compat with hosts that switch on those values. New code should
+* prefer the canonical lowercase codes; arc keeps emitting its UPPER_SNAKE
+* codes on the wire so existing client switches keep working.
+*/
+const ERROR_CODES = {
+	VALIDATION: "validation_error",
+	NOT_FOUND: "not_found",
+	CONFLICT: "conflict",
+	UNAUTHORIZED: "unauthorized",
+	FORBIDDEN: "forbidden",
+	RATE_LIMITED: "rate_limited",
+	IDEMPOTENCY_CONFLICT: "idempotency_conflict",
+	PRECONDITION_FAILED: "precondition_failed",
+	INTERNAL: "internal_error",
+	UNAVAILABLE: "service_unavailable",
+	TIMEOUT: "timeout"
+};
+//#endregion
+export { ERROR_CODES };

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

@@ -0,0 +1,35 @@
+import { AnyPaginationResult, BareListResult, PaginatedResult } from "./types.mjs";
+
+//#region src/pagination/canonical.d.ts
+/**
+ * Type guard: is this value a paginated result envelope (vs a bare array
+ * or some other shape)?
+ *
+ * Checks for the `method` discriminant rather than `Array.isArray` so a
+ * paginated result whose `docs` field happens to contain zero items still
+ * routes through the paginated branch.
+ *
+ * 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 `{ 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.
+ */
+declare function isPaginatedResult<TDoc>(input: unknown): input is AnyPaginationResult<TDoc>;
+/**
+ * Normalise a list-shaped value into the canonical wire envelope.
+ *
+ * Overloads keep the return type tight:
+ *   - 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[]): 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

@@ -0,0 +1,26 @@
+//#region src/pagination/canonical.ts
+/**
+* Type guard: is this value a paginated result envelope (vs a bare array
+* or some other shape)?
+*
+* Checks for the `method` discriminant rather than `Array.isArray` so a
+* paginated result whose `docs` field happens to contain zero items still
+* routes through the paginated branch.
+*
+* 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 `{ 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.
+*/
+function isPaginatedResult(input) {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) return false;
+	const method = input.method;
+	return method === "offset" || method === "keyset" || method === "aggregate";
+}
+function toCanonicalList(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,5 +1,6 @@
-import { CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, 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 CursorPayload, type DecodedCursor, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, normalizeSort, shouldWarnDeepPagination, 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/index.mjs

@@ -1,4 +1,5 @@
+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 { calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, normalizeSort, shouldWarnDeepPagination, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };
+export { 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. */
@@ -132,5 +132,59 @@ interface KeysetPaginationResultCore<TDoc> {
  * for the rationale. Defaults to `{}`.
  */
 type KeysetPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = KeysetPaginationResultCore<TDoc> & TExtra;
+/**
+ * Core fields of an aggregate-paginated result. Don't consume this directly —
+ * use `AggregatePaginationResult<TDoc>` or `AggregatePaginationResult<TDoc, TExtra>`.
+ *
+ * Aggregate pagination produces page-shaped envelopes from arbitrary aggregate
+ * pipelines (mongokit's `aggregatePaginate` / `aggregatePipelinePaginate`,
+ * pgkit's CTE-based windowed counts, etc). The shape mirrors offset because
+ * the math is the same — the discriminant exists so consumers can route
+ * "this came from an aggregate, not a plain find" without inspecting the
+ * pipeline.
+ */
+interface AggregatePaginationResultCore<TDoc> {
+  method: 'aggregate';
+  data: TDoc[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+/**
+ * Aggregate-paginated result envelope.
+ *
+ * `TExtra` parallels `OffsetPaginationResult` — kits surface deep-pagination
+ * warnings (`warning?: string`), aggregate-specific stats, etc.
+ */
+type AggregatePaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = AggregatePaginationResultCore<TDoc> & TExtra;
+/**
+ * Union of every pagination *result* shape (server-side, pre-wire).
+ *
+ * What kits return from `getAll` / `aggregatePaginate`. Use this as the
+ * input type to anything that converts repo results into HTTP envelopes —
+ * see {@link toCanonicalList}.
+ */
+type AnyPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra> | AggregatePaginationResult<TDoc, TExtra>;
+/**
+ * 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 BareListResult<TDoc> {
+  data: TDoc[];
+}
+/**
+ * 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 PaginatedResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra> | AggregatePaginationResult<TDoc, TExtra> | BareListResult<TDoc>;
 //#endregion
-export { CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, 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;