@classytic/mongokit 3.38.1 → 3.40.0

package/dist/indexes/verify-indexes.d.mts

@@ -14,6 +14,10 @@
  * Missing UNIQUE indexes are reported separately from missing regular ones —
  * the first silently admits duplicate data, the second only costs a scan.
  *
+ * Same keys are not the same index: a live index is compared on the options that decide
+ * correctness (`unique`, `partialFilterExpression`, `sparse`, `collation`, `expireAfterSeconds`).
+ * A same-key index that differs is reported as `incompatible` — its fix is a rebuild, not a create.
+ *
  * DELIBERATELY ONE-DIRECTIONAL: an index present in the database but absent
  * from a schema is NOT drift. Auth libraries and migrations manage indexes
  * outside the ODM, and treating those as removable is exactly what makes a
@@ -44,11 +48,20 @@ interface MissingIndex {
   /** The declared key, JSON-stringified — stable to log and to diff. */
   key: string;
 }
+/** A live index on the declared keys whose correctness options differ from the declaration. */
+interface IncompatibleIndex extends MissingIndex {
+  /** Declared `unique` — a mismatch here can already have admitted duplicates. */
+  unique: boolean;
+  /** One line per differing option: `unique: declared true, live false`. */
+  differences: string[];
+}
 interface IndexVerifyReport {
   modelsChecked: number;
   /** Declared `unique` indexes with nothing behind them. Duplicates can already exist. */
   missingUnique: MissingIndex[];
   missingRegular: MissingIndex[];
+  /** Same keys, different semantics — e.g. declared unique, built non-unique. */
+  incompatible: IncompatibleIndex[];
   /** Models whose indexes could not be read — collection absent, or no permission. */
   unreadable: string[];
 }
@@ -66,4 +79,4 @@ declare function verifyIndexes(connection: IndexVerifiableConnection, options?:
 /** One-line summary for a boot log. */
 declare function formatIndexReport(report: IndexVerifyReport): string;
 //#endregion
-export { IndexVerifiableConnection, IndexVerifiableModel, IndexVerifyReport, MissingIndex, VerifyIndexesOptions, formatIndexReport, verifyIndexes };
+export { IncompatibleIndex, IndexVerifiableConnection, IndexVerifiableModel, IndexVerifyReport, MissingIndex, VerifyIndexesOptions, formatIndexReport, verifyIndexes };

package/dist/indexes/verify-indexes.mjs

@@ -22,12 +22,45 @@ function textFields(key) {
 	const fields = Object.entries(key).filter(([, dir]) => dir === "text").map(([field]) => field);
 	return fields.length > 0 ? fields.sort() : null;
 }
+/** Order-free JSON, so `{a:1,b:2}` equals `{b:2,a:1}` — option objects are not order-sensitive. */
+function canonical(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "undefined";
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+}
+/**
+* The options that change what an index GUARANTEES, compared declared → live. Absent means
+* off (`unique`, `sparse`) or none (`partialFilterExpression`, `expireAfterSeconds`). A collation
+* is compared on the DECLARED fields only: the server fills in every default it does not store.
+*/
+function optionDifferences(declared, live) {
+	const diffs = [];
+	const flag = (name) => {
+		const d = declared[name] === true;
+		const l = live[name] === true;
+		if (d !== l) diffs.push(`${name}: declared ${d}, live ${l}`);
+	};
+	flag("unique");
+	flag("sparse");
+	for (const name of ["partialFilterExpression", "expireAfterSeconds"]) {
+		const d = declared[name] === void 0 ? "none" : canonical(declared[name]);
+		const l = live[name] === void 0 ? "none" : canonical(live[name]);
+		if (d !== l) diffs.push(`${name}: declared ${d}, live ${l}`);
+	}
+	const dColl = declared.collation;
+	const lColl = live.collation;
+	if (dColl) {
+		if (Object.keys(dColl).filter((k) => canonical(dColl[k]) !== canonical(lColl?.[k])).length > 0) diffs.push(`collation: declared ${canonical(dColl)}, live ${lColl ? canonical(lColl) : "none"}`);
+	} else if (lColl && lColl.locale !== "simple") diffs.push(`collation: declared none, live ${canonical(lColl)}`);
+	return diffs;
+}
 async function verifyIndexes(connection, options = {}) {
 	const include = options.includeModel ?? (() => true);
 	const report = {
 		modelsChecked: 0,
 		missingUnique: [],
 		missingRegular: [],
+		incompatible: [],
 		unreadable: []
 	};
 	for (const name of connection.modelNames().sort()) {
@@ -39,8 +72,12 @@ async function verifyIndexes(connection, options = {}) {
 		let existingText;
 		try {
 			const live = await model.collection.listIndexes().toArray();
-			existing = new Set(live.map((i) => normalizeKey(i.key)));
-			existingText = new Set(live.filter((i) => i.weights).map((i) => JSON.stringify(Object.keys(i.weights).sort())));
+			existing = /* @__PURE__ */ new Map();
+			existingText = /* @__PURE__ */ new Map();
+			for (const index of live) {
+				const [map, k] = index.weights ? [existingText, JSON.stringify(Object.keys(index.weights).sort())] : [existing, normalizeKey(index.key)];
+				map.set(k, [...map.get(k) ?? [], index]);
+			}
 		} catch {
 			report.unreadable.push(name);
 			continue;
@@ -48,15 +85,24 @@ async function verifyIndexes(connection, options = {}) {
 		report.modelsChecked += 1;
 		for (const [key, indexOptions] of declared) {
 			const asText = textFields(key);
-			if (asText) {
-				if (existingText.has(JSON.stringify(asText))) continue;
-			} else if (existing.has(normalizeKey(key))) continue;
+			const sameKey = asText ? existingText.get(JSON.stringify(asText)) : existing.get(normalizeKey(key));
 			const entry = {
 				model: name,
 				collection: model.collection.name,
 				key: JSON.stringify(key)
 			};
-			if (indexOptions?.unique) report.missingUnique.push(entry);
+			const opts = indexOptions ?? {};
+			if (sameKey && sameKey.length > 0) {
+				const diffsPerCandidate = sameKey.map((live) => optionDifferences(opts, live));
+				if (diffsPerCandidate.some((d) => d.length === 0)) continue;
+				report.incompatible.push({
+					...entry,
+					unique: opts.unique === true,
+					differences: diffsPerCandidate[0] ?? []
+				});
+				continue;
+			}
+			if (opts.unique === true) report.missingUnique.push(entry);
 			else report.missingRegular.push(entry);
 		}
 	}
@@ -67,7 +113,8 @@ function formatIndexReport(report) {
 	const parts = [
 		`${report.modelsChecked} models checked`,
 		`missing unique: ${report.missingUnique.length}`,
-		`missing regular: ${report.missingRegular.length}`
+		`missing regular: ${report.missingRegular.length}`,
+		`incompatible: ${report.incompatible.length}`
 	];
 	if (report.unreadable.length > 0) parts.push(`unreadable: ${report.unreadable.length}`);
 	return `[index-check] ${parts.join(" — ")}`;

package/dist/{method-registry.plugin-DblM7V6j.mjs → method-registry.plugin-C63pGn1d.mjs}

@@ -16,6 +16,58 @@ import { t as createError } from "./error-BuByZwKU.mjs";
 * // bulkWrite is what this plugin contributes.
 * await repo.bulkWrite([...ops]);
 */
+/**
+* Driver options `bulkWrite` forwards, and the only ones it forwards.
+*
+* The signature used to be `{ session?, ordered?, [key: string]: unknown }` and
+* the call forwarded exactly two of them. So `writeConcern: { w: 'majority' }`
+* on a money import was accepted by the type, dropped on the floor, and the
+* write went out under the default concern with nothing raised.
+*/
+const BULK_WRITE_OPTIONS = [
+	"ordered",
+	"session",
+	"writeConcern",
+	"bypassDocumentValidation",
+	"comment",
+	"let",
+	"ignoreUndefined"
+];
+/**
+* Driver options that EXIST but this method does not forward.
+*
+* The options bag is dual-purpose by design: it is spread into
+* `_buildContext`, so it also carries plugin context — `organizationId` for
+* multi-tenant scoping, and whatever else a host's plugins read off it.
+* Refusing every unrecognised key therefore breaks legitimate callers, which
+* is exactly how the first version of this fence failed: it rejected the
+* tenant id and took two passing tests with it.
+*
+* So the line sits where the caller's expectation is. If the DRIVER would
+* understand the option and we would silently not pass it on, refuse — that is
+* the case where someone believes they configured the write. A key the driver
+* does not know either is plugin context, and passes through untouched.
+*/
+const UNSUPPORTED_DRIVER_OPTIONS = /* @__PURE__ */ new Set([
+	"forceServerObjectId",
+	"timeoutMS",
+	"maxTimeMS",
+	"retryWrites",
+	"checkKeys",
+	"serializeFunctions",
+	"enableUtf8Validation",
+	"raw",
+	"explain"
+]);
+/** Narrow the bag to driver options, refusing the ones we would silently drop. */
+function pickBulkWriteOptions(options) {
+	const dropped = Object.keys(options).filter((k) => UNSUPPORTED_DRIVER_OPTIONS.has(k));
+	if (dropped.length > 0) throw createError(400, `bulkWrite: option(s) ${dropped.map((k) => `'${k}'`).join(", ")} are MongoDB driver options this method does not forward. Refused rather than ignored, because silently dropping one changes what the write does. Supported: ${BULK_WRITE_OPTIONS.join(", ")}.`);
+	const out = {};
+	for (const key of BULK_WRITE_OPTIONS) if (options[key] !== void 0) out[key] = options[key];
+	out.ordered = options.ordered ?? true;
+	return out;
+}
 function batchOperationsPlugin() {
 	return {
 		name: "batch-operations",
@@ -36,6 +88,7 @@ function batchOperationsPlugin() {
 			* ]);
 			*/
 			repo.registerMethod("bulkWrite", async function(operations, options = {}) {
+				const driverOptions = pickBulkWriteOptions(options);
 				const context = await this._buildContext("bulkWrite", {
 					operations,
 					...options
@@ -43,10 +96,7 @@ function batchOperationsPlugin() {
 				try {
 					const finalOps = context.operations || operations;
 					if (!finalOps || finalOps.length === 0) throw createError(400, "bulkWrite requires at least one operation");
-					const result = await this.Model.bulkWrite(finalOps, {
-						ordered: options.ordered ?? true,
-						session: options.session
-					});
+					const result = await this.Model.bulkWrite(finalOps, driverOptions);
 					const bulkResult = {
 						ok: result.ok,
 						insertedCount: result.insertedCount,

package/dist/{multi-tenant.plugin-BwSvTirB.d.mts → multi-tenant.plugin-CBgCo9im.d.mts}

@@ -1,5 +1,5 @@
-import { i as ObjectId } from "./core-62oo3N1C.mjs";
-import { l as Plugin, p as RepositoryContext } from "./repository-H_ffGgpE.mjs";
+import { g as ObjectId } from "./pagination-BpIv2bdS.mjs";
+import { l as Plugin, p as RepositoryContext } from "./repository-odl03582.mjs";
 import mongoose, { Connection } from "mongoose";
 import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle as RepositoryCacheHandle$1, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
 import { TenantConfig } from "@classytic/repo-core/tenant";
@@ -307,12 +307,31 @@ interface CustomIdOptions {
  * });
  */
 declare function getNextSequence(counterKey: string, increment?: number, connection?: mongoose.Connection, session?: mongoose.ClientSession): Promise<number>;
+/**
+ * Current value of a counter, or `null` when it has never been created.
+ * `null` and `0` differ: only a missing counter needs seeding.
+ */
+declare function readSequence(counterKey: string, connection?: mongoose.Connection): Promise<number | null>;
+/**
+ * Raise a counter to at least `floor` — never lowers it. Atomic (`$max` +
+ * upsert), so concurrent seeders converge on the highest floor.
+ *
+ * Use before a counter's first increment when ids were already issued under
+ * another key (e.g. moving from a global to a per-tenant sequence); otherwise
+ * the new counter restarts at 1 and re-issues taken ids.
+ *
+ * @returns The counter's value after the raise.
+ */
+declare function ensureSequenceAtLeast(counterKey: string, floor: number, connection?: mongoose.Connection): Promise<number>;
 interface SequentialIdOptions {
   /** Prefix string (e.g., 'INV', 'ORD') */
   prefix: string;
   /** Mongoose model — used to derive the counter key from model name */
   model: mongoose.Model<any>;
-  /** Number of digits to pad to (default: 4 → "0001") */
+  /**
+   * MINIMUM number of digits (default: 4 → "0001"). Never truncates —
+   * sequence 10000 under `padding: 4` renders as `INV-10000`.
+   */
   padding?: number;
   /** Separator between prefix and number (default: '-') */
   separator?: string;
@@ -346,10 +365,54 @@ interface DateSequentialIdOptions {
    * - 'daily'   → BILL-2026-02-20-0001, resets every day
    */
   partition?: 'yearly' | 'monthly' | 'daily';
-  /** Number of digits to pad to (default: 4) */
+  /**
+   * MINIMUM number of digits for the sequence (default: 4). `padStart` never
+   * truncates, so the 10,000th id of a period under `padding: 4` is
+   * `BILL-2026-10000` — it grows a digit rather than wrapping to `0000`.
+   * Lexical sort order therefore only holds while a period stays below
+   * 10^padding; size the padding for your peak period.
+   */
   padding?: number;
   /** Separator (default: '-') */
   separator?: string;
+  /**
+   * Counter scope.
+   * - `'global'` (default) — one counter per model + period, shared by
+   *   every tenant in the database. Ids are unique across the deployment.
+   * - `'tenant'` — one counter per tenant + model + period, keyed by
+   *   `context[tenantKey]`. Every tenant's numbering starts at 1 (Shopify-
+   *   style per-shop order numbers) and the write hot spot on the single
+   *   shared counter document splits per tenant. Ids are unique WITHIN a
+   *   tenant only — index the field compound with the tenant field.
+   *   Fails closed: a create with no tenant in context throws rather than
+   *   falling back to the global key, which would silently merge two
+   *   tenants' sequences.
+   */
+  scope?: 'global' | 'tenant';
+  /**
+   * Context key carrying the tenant id under `scope: 'tenant'` (default:
+   * `'organizationId'` — the same default as `multiTenantPlugin`'s
+   * `contextKey`, so `repo.create(data, { organizationId })` feeds both).
+   */
+  tenantKey?: string;
+  /**
+   * Which clock decides the period boundary.
+   *
+   * - `'local'` (default) — the server's `TZ`. Kept as the default because it
+   *   is what every existing deployment already generated: flipping it would
+   *   retroactively change which period an id near a month boundary belongs
+   *   to, and those ids are invoice and order numbers.
+   * - `'utc'` — **the correct choice for more than one replica.** Two replicas
+   *   with different `TZ` settings derive different counter keys for the same
+   *   logical month and each increments its own, so the same number is issued
+   *   twice inside one tenant-period. UTC is the one boundary every replica
+   *   agrees on. It also matches the ecosystem's other period key,
+   *   `usagePeriod()` in `@classytic/repo-core/usage`.
+   *
+   * Containers usually run UTC anyway, which is exactly why the difference
+   * stays invisible until one host is configured otherwise.
+   */
+  timezone?: 'local' | 'utc';
 }
 /**
  * Generator: Date-partitioned sequential counter.
@@ -371,6 +434,15 @@ interface DateSequentialIdOptions {
  *   }),
  * })
  * ```
+ *
+ * @example Per-tenant numbering in a shared database
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'orderNumber',
+ *   generator: dateSequentialId({ prefix: 'ORD', model: OrderModel, scope: 'tenant' }),
+ * })
+ * // org-a: ORD-2026-02-0001, ORD-2026-02-0002 …   org-b: ORD-2026-02-0001 …
+ * ```
  */
 declare function dateSequentialId(options: DateSequentialIdOptions): IdGenerator;
 interface PrefixedIdOptions {
@@ -582,4 +654,4 @@ declare function adminBypass(options: {
   adminRoles: readonly string[];
 }): (context: RepositoryContext, operation: string) => boolean;
 //#endregion
-export { ensureAuditTrailReady as A, AuditTrailMethods as C, AuditTrailQueryOptions as D, AuditTrailQuery as E, EnsureAuditTrailReadyOptions as O, AuditQueryResult as S, AuditTrailOptions as T, RepositoryCachePluginOptions as _, DateSequentialIdOptions as a, AuditOperation as b, SequentialIdOptions as c, getNextSequence as d, prefixedId as f, RepositoryCacheHandle$1 as g, CacheOptions as h, CustomIdOptions as i, auditTrailPlugin as k, customIdPlugin as l, CacheAdapter$1 as m, adminBypass as n, IdGenerator as o, sequentialId as p, multiTenantPlugin as r, PrefixedIdOptions as s, MultiTenantOptions as t, dateSequentialId as u, cachePlugin as v, AuditTrailMode as w, AuditQueryOptions as x, AuditEntry as y };
+export { EnsureAuditTrailReadyOptions as A, AuditQueryOptions as C, AuditTrailOptions as D, AuditTrailMode as E, ensureAuditTrailReady as M, AuditTrailQuery as O, AuditOperation as S, AuditTrailMethods as T, CacheOptions as _, DateSequentialIdOptions as a, cachePlugin as b, SequentialIdOptions as c, ensureSequenceAtLeast as d, getNextSequence as f, CacheAdapter$1 as g, sequentialId as h, CustomIdOptions as i, auditTrailPlugin as j, AuditTrailQueryOptions as k, customIdPlugin as l, readSequence as m, adminBypass as n, IdGenerator as o, prefixedId as p, multiTenantPlugin as r, PrefixedIdOptions as s, MultiTenantOptions as t, dateSequentialId as u, RepositoryCacheHandle$1 as v, AuditQueryResult as w, AuditEntry as x, RepositoryCachePluginOptions as y };

package/dist/{operations-DZodvjC-.d.mts → operations-CrRIoc8Z.d.mts}

@@ -1,5 +1,4 @@
-import { a as PopulateSpec, i as ObjectId, l as SortSpec, o as ReadPreferenceType, s as SelectSpec } from "./core-62oo3N1C.mjs";
-import { r as CollationOptions } from "./pagination-jSUdrACK.mjs";
+import { _ as PopulateSpec, g as ObjectId, i as CountStrategy, r as CollationOptions, v as ReadPreferenceType, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
 import { DeleteManyResult, DeleteResult, LookupPopulateResult, UpdateManyResult } from "@classytic/repo-core/repository";
 import { PipelineStage, PopulateOptions } from "mongoose";
 import { Filter } from "@classytic/repo-core/filter";
@@ -383,9 +382,21 @@ interface WithTransactionOptions {
 }
 /** Create operation options */
 interface CreateOptions extends SessionOptions {
-  /** Keep insertion order on error (default: false).
-   * When false, all valid documents insert even if some fail (e.g. duplicates).
-   * Set to true to abort remaining inserts on first error. */
+  /**
+   * Keep insertion order on error. **Default `false`, which is the OPPOSITE of
+   * the MongoDB driver's own default** — a deliberate choice for import
+   * throughput, pinned by `tests/integration/createMany-partial-failure.test.ts`.
+   *
+   * The consequence is worth stating plainly, because it is the part that
+   * surprises: with `false`, a REJECTED `createMany` can still have written
+   * documents. Every valid document inserts and only the failures are reported,
+   * so a caller that treats the rejection as "nothing happened" and retries
+   * will double-insert everything that succeeded the first time.
+   *
+   * Retryable imports therefore need a unique index or an idempotency key —
+   * not a try/catch. Pass `ordered: true` when the batch is an all-or-nothing
+   * business operation, and a transaction when it must also be atomic.
+   */
   ordered?: boolean;
 }
 /** Update operation options */
@@ -485,14 +496,18 @@ interface LookupPopulateOptions<TBase = unknown> {
   page?: number;
   /** Cursor token for next page (keyset mode) */
   after?: string;
+  /** Cursor token for the PREVIOUS page (keyset mode). Mutually exclusive with `after`. */
+  before?: string;
   /** Number of documents per page */
   limit?: number;
   /** Fields to select */
   select?: SelectSpec;
   /** Collation for locale-aware string comparison */
   collation?: CollationOptions;
-  /** Count strategy for offset pagination */
-  countStrategy?: 'exact' | 'estimated' | 'none';
+  /** Count strategy for offset pagination. See {@link CountStrategy}. */
+  countStrategy?: CountStrategy;
+  /** Ceiling for `countStrategy: 'capped'` (default 10000). */
+  countLimit?: number;
   /**
    * Transaction session. Typed `unknown` to match repo-core's
    * `RepositorySession` contract — mongokit narrows to `ClientSession`

package/dist/outbox/index.d.mts

@@ -1,4 +1,4 @@
-import { n as Repository } from "../Repository-BdSkQ8vc.mjs";
+import { r as Repository } from "../Repository-CR8Y9g2E.mjs";
 import { Connection, Model } from "mongoose";
 //#region src/outbox/index.d.ts
 /** Delivery states. `dead_letter` is terminal and operator-visible. */

package/dist/outbox/index.mjs

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-Ck5x43wF.mjs";
-import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-DblM7V6j.mjs";
+import { n as Repository } from "../Repository-BMgPSkqZ.mjs";
+import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-C63pGn1d.mjs";
 import { Schema } from "mongoose";
 //#region src/outbox/index.ts
 /**
@@ -172,12 +172,14 @@ function createOutboxModel(connection, options = {}) {
 	*
 	* Mongo rejects `unique` combined with a `sparse: true` + partial filter ("cannot mix"), and
 	* the failure is that the index silently never builds — so duplicate events insert happily
-	* and the outbox's idempotency guarantee is gone with nothing in the logs. Filtering on
-	* `$type: 'string'` indexes only rows that actually carry a key.
+	* and the outbox's idempotency guarantee is gone with nothing in the logs. `$gte: ''` indexes
+	* only rows that carry a string key — the same rows as `$type: 'string'`, but the dedupe
+	* lookup by key can use it (a `$type` filter is never implied by an equality query).
 	*/
 	schema.index({ dedupeKey: 1 }, {
+		name: "dedupeKey_str",
 		unique: true,
-		partialFilterExpression: { dedupeKey: { $type: "string" } }
+		partialFilterExpression: { dedupeKey: { $gte: "" } }
 	});
 	/**
 	* The DEAD-LETTER read. `getDeadLettered` is part of the `OutboxStore` contract and is what

package/dist/pagination/PaginationEngine.d.mts

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-CBS1XGzp.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-D-P19Y9m.mjs";
 export { PaginationEngine };

package/dist/pagination/PaginationEngine.mjs

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-BX9o_-4R.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-Dvl8jcRY.mjs";
 export { PaginationEngine };

package/dist/pagination/utils/limits.d.mts

@@ -1,4 +1,4 @@
-import { c as PaginationConfig } from "../../pagination-jSUdrACK.mjs";
+import { u as PaginationConfig } from "../../pagination-BpIv2bdS.mjs";
 //#region src/pagination/utils/limits.d.ts
 /**
  * Validates and sanitizes limit value

package/dist/pagination/utils/limits.mjs

@@ -1,3 +1,4 @@
+import { t as createError } from "../../error-BuByZwKU.mjs";
 //#region src/pagination/utils/limits.ts
 /**
 * Validates and sanitizes limit value
@@ -27,7 +28,27 @@ function validatePage(page, config) {
 	const parsed = Number(page);
 	if (!Number.isFinite(parsed) || parsed < 1) return 1;
 	const sanitized = Math.floor(parsed);
-	if (sanitized > (config.maxPage || 1e4)) throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage || 1e4}`);
+	const max = config.maxPage || 1e4;
+	if (sanitized > max)
+ /**
+	* 400, not a bare `Error`.
+	*
+	* The page number comes from the querystring, so this is the caller's
+	* mistake — a crawler walking past the end, a fuzzer, a stale deep link.
+	* A bare `Error` carries no status, so every framework above maps it to
+	* `internal_error` 500: the request is refused either way, but one of them
+	* pages an on-call engineer and burns an error budget over `?page=999999`.
+	*
+	* It matters more the lower `maxPage` is set, and a deployment that has
+	* tuned it down for the skip cost is exactly the one getting this traffic.
+	*/
+	throw createError(400, `Page ${sanitized} exceeds maximum ${max}`, {
+		code: "PAGE_OUT_OF_RANGE",
+		meta: {
+			page: sanitized,
+			maxPage: max
+		}
+	});
 	return sanitized;
 }
 /**