@classytic/mongokit 3.38.1 → 3.39.0

package/dist/{Repository-Ck5x43wF.mjs → Repository-D7fDpyFx.mjs}

@@ -1,12 +1,12 @@
 import { i as isValidIdForType, t as getSchemaIdType } from "./id-resolution-BqDrk0S2.mjs";
 import { a as narrowToIds, i as keysetFilter, o as selectKeysetChunk } from "./id-chunks-BmAwsqNk.mjs";
-import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-jSXp3nu3.mjs";
+import { _ as compileFilterToMongo, a as count, c as getByQuery, d as deleteById, f as deleteByQuery, g as LookupBuilder, h as distinct, l as getOrCreate, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, v as create, y as createMany } from "./update-c_01A0if.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-BX9o_-4R.mjs";
+import { c as resolveCursorSecrets, l as verifySignature, s as attachSignature, t as PaginationEngine } from "./PaginationEngine-DQ7beTCR.mjs";
 import { calculateTotalPages } from "./pagination/utils/limits.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
-import { RepositoryBase, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry } from "@classytic/repo-core/repository";
+import { RepositoryBase, createDistributionGuard, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
 import { isFilter } from "@classytic/repo-core/filter";
 import { VersionConflictError, conservativeMongoIsTransientConflict } from "@classytic/repo-core/errors";
@@ -806,8 +806,35 @@ function formatForUnit(unit) {
 */
 function compileFilterToMongoExpr(input) {
 	if (input === void 0 || input === null) return true;
-	if (!isFilter(input)) return input;
-	return compile(input);
+	if (isFilter(input)) return compile(input);
+	if (typeof input === "boolean") return input;
+	/**
+	* Anything else must be an aggregation EXPRESSION, and an aggregation
+	* expression's operator keys are `$`-prefixed (`$eq`, `$and`, `$gt`).
+	*
+	* This used to `return input` for everything that was not Filter IR,
+	* described as "already an expression — pass through unchanged". A plain
+	* query object is not an expression: `{ status: { eq: 'paid' } }` reaches
+	* `$cond` as a non-empty object, which MongoDB evaluates as TRUTHY. So a
+	* measure's `where` written in query syntax silently matched every row and
+	* the filtered aggregate came back equal to the unfiltered one, with nothing
+	* raised.
+	*
+	* That syntax is not imaginary — it is exactly what `AggRequest.filter`
+	* accepts, because `compileFilterToMongo` runs `expandShorthands` over it.
+	* Two filter surfaces on one request object, one of which honoured the
+	* syntax and the other quietly ignored it.
+	*
+	* Refused rather than translated: a partial query-to-expression translator
+	* would get the common operators right and fail the same silent way on the
+	* rest, which is the failure being fixed.
+	*/
+	if (typeof input === "object") {
+		const keys = Object.keys(input);
+		if (keys.length > 0 && keys.every((k) => k.startsWith("$"))) return input;
+		throw createError(400, `mongokit/filter: \`where\` must be Filter IR (\`{ op, field, value }\`) or a MongoDB aggregation expression (\`{ \$eq: ['\$field', value] }\`), got ${keys.length === 0 ? "an empty object" : `an object keyed by ${keys.map((k) => `'${k}'`).join(", ")}`}. Query syntax such as \`{ field: { eq: value } }\` works in \`filter\` but not here — evaluated as an expression it is always TRUE, so the filter would silently match every row.`);
+	}
+	return input;
 }
 function compile(filter) {
 	switch (filter.op) {
@@ -983,20 +1010,26 @@ function buildAggPipeline(req, schema) {
 		for (const alias of bucketAliases) addFields[bucketInternalKey(alias)] = compileDateBucket(req.dateBuckets[alias]);
 		stages.push({ $addFields: addFields });
 	}
-	const groupStage = { _id: groupCols.length === 0 && bucketAliases.length === 0 ? null : (() => {
+	const groupId = groupCols.length === 0 && bucketAliases.length === 0 ? null : (() => {
 		const id = {};
 		for (const field of groupCols) id[safeIdKey(field)] = `$${field}`;
 		for (const alias of bucketAliases) id[alias] = `$${bucketInternalKey(alias)}`;
 		return id;
-	})() };
+	})();
+	const groupStage = { _id: groupId };
 	const distinctSetAliases = [];
 	const percentileAliases = [];
-	for (const [alias, measure] of Object.entries(req.measures)) {
-		groupStage[alias] = compileMeasure(measure).groupExpr;
-		if (measure.op === "countDistinct") distinctSetAliases.push(alias);
-		else if (measure.op === "percentile") percentileAliases.push(alias);
+	const groupedDistinct = req.countDistinctStrategy === "grouped";
+	const distinctAliases = Object.entries(req.measures).filter(([, m]) => m.op === "countDistinct").map(([alias]) => alias);
+	if (groupedDistinct && distinctAliases.length > 0) appendGroupedDistinctStages(stages, req, groupId, distinctAliases);
+	else {
+		for (const [alias, measure] of Object.entries(req.measures)) {
+			groupStage[alias] = compileMeasure(measure).groupExpr;
+			if (measure.op === "countDistinct") distinctSetAliases.push(alias);
+			else if (measure.op === "percentile") percentileAliases.push(alias);
+		}
+		stages.push({ $group: groupStage });
 	}
-	stages.push({ $group: groupStage });
 	if (distinctSetAliases.length > 0) {
 		const addFields = {};
 		for (const alias of distinctSetAliases) addFields[alias] = { $size: { $ifNull: [`$${alias}`, []] } };
@@ -1065,12 +1098,108 @@ function validateTopN(topN, groupCols, bucketAliases, measures) {
 *   - `'dense_rank'`  → `$denseRank`        (no gaps)
 *   - `'row_number'`  → `$documentNumber`   (each row unique)
 */
+/**
+* Accumulators that survive being computed over a FINER partition and then
+* combined — the whole constraint on the grouped strategy.
+*
+* Pre-grouping by the distinct field splits every group into one sub-group per
+* distinct value, so each remaining measure must answer the same over the split
+* as it did whole. Summing is associative over a partition, and so are min and
+* max, so those four are exact.
+*
+* `avg` is not (the mean of means is not the mean); `percentile` and `stddev`
+* are not; and a SECOND `countDistinct` would need the partition to carry both
+* fields, which multiplies the rows and breaks the first count. Those are
+* REFUSED rather than approximated — a distinct count that is quietly wrong is
+* the exact failure this strategy exists to avoid.
+*/
+const REAGGREGATABLE = {
+	count: "$sum",
+	sum: "$sum",
+	min: "$min",
+	max: "$max"
+};
+/** Internal `_id` slot holding one distinct value during the pre-group. */
+const distinctIdKey = (alias) => `__dv_${alias}`;
+/**
+* Compile `countDistinct` as pre-group + count instead of accumulate + size.
+*
+* `$addToSet` holds every distinct value of a group in that group's accumulator,
+* so memory grows with cardinality and MongoDB caps it at 100MB. Grouping by the
+* value instead turns each distinct value into a ROW, and rows spill. Nothing
+* accumulates, so cardinality stops being a memory question.
+*
+* The two semantics that had to be matched exactly, both measured against
+* `$addToSet` rather than assumed:
+*
+*   - a MISSING field is not a distinct value, but an explicit `null` IS. A
+*     naive `$group` disagrees on both, and on a group whose field is always
+*     missing it answers 1 where `$addToSet` answers 0. The `$type` check is
+*     what separates them: a missing field leaves the `_id` slot absent, an
+*     explicit null leaves it `null`.
+*   - `where` excludes a row from the COUNT without excluding it from the other
+*     measures. `compileMeasure` already emits `$$REMOVE` for a non-matching
+*     row, which lands it in the same "missing" slot — so the same `$type`
+*     check covers the filtered case with no extra branch.
+*/
+function appendGroupedDistinctStages(stages, req, groupId, distinctAliases) {
+	if (distinctAliases.length > 1) throw createError(400, `mongokit/aggregate: countDistinctStrategy 'grouped' supports one countDistinct per request, got ${distinctAliases.length} (${distinctAliases.join(", ")}). Two distinct fields would have to share one partition, which multiplies the rows and makes both counts wrong. Issue them as separate requests, or use the default 'accumulator'.`);
+	const distinctAlias = distinctAliases[0];
+	const blocked = Object.entries(req.measures).filter(([alias, m]) => alias !== distinctAlias && !REAGGREGATABLE[m.op]);
+	if (blocked.length > 0) throw createError(400, `mongokit/aggregate: countDistinctStrategy 'grouped' cannot combine with ${blocked.map(([a, m]) => `'${a}' (${m.op})`).join(", ")}. Pre-grouping by the distinct field splits each group, and only count/sum/min/max survive being recombined — an ${blocked[0][1].op} over the split would be silently wrong. Compute it in a separate request, or use the default 'accumulator' strategy.`);
+	const dvKey = distinctIdKey(distinctAlias);
+	const preId = { ...groupId ?? {} };
+	preId[dvKey] = compileMeasure(req.measures[distinctAlias]).groupExpr;
+	preId[dvKey] = preId[dvKey].$addToSet;
+	const preGroup = { _id: preId };
+	for (const [alias, measure] of Object.entries(req.measures)) {
+		if (alias === distinctAlias) continue;
+		preGroup[alias] = compileMeasure(measure).groupExpr;
+	}
+	stages.push({ $group: preGroup });
+	const regroup = { _id: groupId === null ? null : Object.fromEntries(Object.keys(groupId).map((k) => [k, `$_id.${k}`])) };
+	regroup[distinctAlias] = { $sum: { $cond: [
+		{ $eq: [{ $type: `$_id.${dvKey}` }, "missing"] },
+		0,
+		1
+	] } };
+	for (const [alias, measure] of Object.entries(req.measures)) {
+		if (alias === distinctAlias) continue;
+		regroup[alias] = { [REAGGREGATABLE[measure.op]]: `$${alias}` };
+	}
+	stages.push({ $group: regroup });
+}
 function appendTopNStages(stages, topN) {
 	const partitionList = Array.isArray(topN.partitionBy) ? topN.partitionBy : [topN.partitionBy];
-	const partitionExpr = partitionList.length === 1 ? `$${partitionList[0]}` : { $concat: partitionList.flatMap((field, i) => {
-		const ref = { $toString: { $ifNull: [`$${field}`, "__NULL__"] } };
-		return i === 0 ? [ref] : ["
", ref];
-	}) };
+	/**
+	* A compound partition is a TUPLE, and a tuple's identity cannot be a string.
+	*
+	* This built the key by `$toString`-ing each value and joining with U+0001,
+	* mapping null to the literal `'__NULL__'`. Both halves lose information, and
+	* the loss merges partitions that are not the same — a value CONTAINING the
+	* separator, or a document genuinely holding the string `'__NULL__'`, lands
+	* on another partition's key. Two unrelated partitions then rank as one, so
+	* `topN` returns rows that are not the top N of anything. Measured: four rows
+	* across two partitions came back ranked 1, 2, 3, 4.
+	*
+	* A DOCUMENT expression compares by value, field by field, with no
+	* serialization in between, so distinct tuples stay distinct whatever they
+	* contain. An array would read more naturally and is not available: Mongo
+	* refuses it outright with "An expression used to partition cannot evaluate
+	* to value of type array".
+	*
+	* Keys are positional (`k0`, `k1`, ...) rather than the field names, because
+	* a partition field may be a dotted path and a dot is not legal in an
+	* expression document's key. They are internal to this stage and never
+	* surface in output.
+	*
+	* `$ifNull` to null keeps arity fixed, so a missing field and an explicit
+	* null partition together the way SQL's `PARTITION BY` groups NULLs, while a
+	* real `'__NULL__'` string stays separate from both.
+	*
+	* Single-key partitions keep the bare path: same semantics, cleaner plan.
+	*/
+	const partitionExpr = partitionList.length === 1 ? `$${partitionList[0]}` : Object.fromEntries(partitionList.map((field, i) => [`k${i}`, { $ifNull: [`$${field}`, null] }]));
 	const tiesOp = topN.ties === "dense_rank" ? "$denseRank" : topN.ties === "row_number" ? "$documentNumber" : "$rank";
 	const RANK_FIELD = "__topNRank";
 	stages.push({ $setWindowFields: {
@@ -1308,8 +1437,22 @@ async function executeAgg(Model, req, options = {}) {
 * keyset predicate runs AFTER the post-group `$project` stage, which
 * is when the output column names exist.
 */
-function decodeAggCursor$1(cursor) {
-	return decodeAggCursor(cursor, "mongokit");
+/**
+* The aggregate cursor is signed by the SAME key as the find-based one.
+*
+* Two cursor codecs are exposed on the wire, and a deployment that signed only
+* the one on `getAll` would still hand out a tamperable position on every
+* aggregate keyset endpoint. A guarantee with an unsigned second door is not a
+* guarantee — it is a guarantee-shaped thing that reviewers stop checking.
+*
+* The signature wraps repo-core's kit-neutral codec rather than living inside
+* it: repo-core's codec is browser-safe by contract and `node:crypto` is not.
+*/
+function encodeAggCursor$1(row, sort, secret) {
+	return attachSignature(encodeAggCursor(row, sort), resolveCursorSecrets(secret));
+}
+function decodeAggCursor$1(cursor, secret) {
+	return decodeAggCursor(verifySignature(cursor, resolveCursorSecrets(secret)), "mongokit");
 }
 /**
 * Build a `$match` stage that selects rows AFTER the cursor row given
@@ -2232,6 +2375,41 @@ function assertCasOwnsVersionField(opName, patch, versionField) {
 		throw createError(400, `[${opName}] payload's ${op} targets '${versionField}', but the optimistic-concurrency CAS owns that field — it increments it as part of the same write. ` + (op === "$inc" ? `Only \`$inc: { ${versionField}: 1 }\` is accepted (it matches what the CAS does); any other increment would be silently overridden. ` : `A conflicting ${op} would either fail the update with a Mongo path conflict or be silently overridden. `) + `Remove it; the expected version belongs in \`options.ifVersion\`.`);
 	}
 }
+/** Filter-bearing ops — those a policy plugin can inject a scope into. */
+function carriesAFilter(op) {
+	const policyKey = OP_REGISTRY[op].policyKey;
+	return policyKey === "query" || policyKey === "filters";
+}
+/**
+* Shapes the guard can never say anything useful about, whatever the key:
+* `watch` (a change stream is cluster-wide however it is filtered) and
+* `getOrCreate` (its filter is the unique key by construction, and a unique
+* index on a sharded collection must already contain the shard key).
+*/
+const DISTRIBUTION_EXEMPT_SHAPES = /* @__PURE__ */ new Set(["watch", "getOrCreate"]);
+/**
+* Verbs the distribution guard inspects — every op whose filter the CALLER
+* assembles and can therefore omit the shard key.
+*
+* DERIVED from `OP_REGISTRY`, not hardcoded: a future query-shaped op is
+* covered by its one registry entry, which is the same rule the strict-query
+* diagnostic below follows and the redundancy the registry exists to remove.
+*/
+const DISTRIBUTION_GUARDED_OPERATIONS = new Set(ALL_OPERATIONS.filter((op) => carriesAFilter(op) && !OP_REGISTRY[op].hasIdContext && !DISTRIBUTION_EXEMPT_SHAPES.has(op)));
+/**
+* Id-addressed verbs (`getById`, `update`, `delete`, `claim*`, `restore`) —
+* guarded ONLY when the distribution key is not the id field.
+*
+* The reasoning they were first excluded under — "the `_id` match is routed,
+* not scattered" — holds only when `_id` IS the shard key. Sharded on anything
+* else (`organizationId`, the tenant-prefixed design this guard mostly exists
+* for), a by-id update is a broadcast to every shard; MongoDB before 7.0
+* rejected `updateOne`/`deleteOne` without the shard key outright. These verbs
+* all take a filter slot too, which is where tenant scope lands — so a scoped
+* write satisfies the guard and only a `bypassTenant` one is flagged, exactly
+* the call that deserves the scrutiny.
+*/
+const ID_ADDRESSED_OPERATIONS = new Set(ALL_OPERATIONS.filter((op) => carriesAFilter(op) && OP_REGISTRY[op].hasIdContext && !DISTRIBUTION_EXEMPT_SHAPES.has(op)));
 /** Mongo `operationType` → portable `ChangeEvent.operation`. */
 const CHANGE_OPERATION_MAP = {
 	insert: "create",
@@ -2269,6 +2447,24 @@ function changeEventTimestamp(change) {
 * OBSERVABILITY=300, DEFAULT=500) and the two refs are reference-equal.
 */
 const HOOK_PRIORITY$1 = HOOK_PRIORITY;
+/**
+* `capped` needs an envelope that can say "this total is a FLOOR".
+*
+* `paginate()` and `aggregatePaginate()` carry `totalIsLowerBound` through
+* mongokit's `TExtra` slot. `lookupPopulate` and the aggregate-IR offset path
+* return repo-core's CORE envelope, which has no such slot — so a bounded count
+* there would be indistinguishable from a real one, and a caller would render a
+* ceiling as a total. That is the failure the strategy exists to prevent.
+*
+* So they count exactly, and SAY they did. A deployment-wide `capped` policy
+* keeps working (an exact count is slower, never wrong); the log line is what
+* makes the one path that ignored the policy findable instead of mysterious.
+*/
+function downgradeCappedCount(strategy, where) {
+	if (strategy !== "capped") return strategy;
+	warn(`[mongokit] countStrategy 'capped' is not supported by ${where} — counting exactly. Its result envelope cannot carry \`totalIsLowerBound\`, and an unflagged ceiling reads as a total. Use getAll()/aggregatePaginate() where a bounded count matters.`);
+	return "exact";
+}
 var Repository = class extends RepositoryBase {
 	/**
 	* Runtime capability descriptor required by `StandardRepo<TDoc>`
@@ -2320,6 +2516,18 @@ var Repository = class extends RepositoryBase {
 	* the `Middleware<TDoc>` type for the protocol.
 	*/
 	_middlewares = [];
+	/**
+	* Shard-key guard built once from `options.distribution`; `undefined`
+	* when not configured so the per-op check is a single falsy test.
+	*/
+	_checkDistribution;
+	/**
+	* Whether id-addressed verbs are guarded too — true unless the
+	* distribution key IS the id field, where an `_id` match is genuinely
+	* routed and guarding would flag every by-id call. See
+	* {@link ID_ADDRESSED_OPERATIONS}.
+	*/
+	_guardIdAddressed = false;
 	constructor(Model, plugins = [], paginationConfig = {}, options = {}) {
 		super({
 			name: Model.modelName,
@@ -2341,6 +2549,10 @@ var Repository = class extends RepositoryBase {
 		this.searchMode = options.searchMode ?? "text";
 		this.searchFields = options.searchFields;
 		this._wireStrictQueryStripDiagnostic(options.warnOnStrictQueryStrip === true);
+		this._checkDistribution = options.distribution ? createDistributionGuard(options.distribution, options.distribution.onMiss ?? ((info) => {
+			warn(`[mongokit] Repository "${this.model}": ${info.operation} filter omits the distribution key "${info.key}" — this fans out across every shard. Include the key, list the op in distribution.exemptOperations, or set onMissingKey: 'off'.`);
+		})) : void 0;
+		this._guardIdAddressed = options.distribution !== void 0 && options.distribution.key !== this.idField;
 		if (this.searchMode === "regex" && (!this.searchFields || this.searchFields.length === 0)) warn(`[mongokit] Repository "${this.model}" configured with searchMode: 'regex' but no searchFields provided. getAll({ search }) will throw until searchFields is set.`);
 		for (const plugin of plugins) this.use(plugin);
 		if (options.requirePlugins && options.requirePlugins.length > 0) {
@@ -2872,8 +3084,12 @@ var Repository = class extends RepositoryBase {
 	*     repo without a filter to observe deletes.
 	*   - `options.signal` ends the iterator (closes the stream). A
 	*     pre-aborted signal rejects at the op boundary like every other op.
-	*   - `options.resumeAfter` forwards a previously captured Mongo
-	*     resume token for at-least-once consumption across restarts.
+	*   - Every yielded event carries `resumeToken` (the change document's
+	*     `_id`). Persist the last one you finished processing and pass it
+	*     back as `options.resumeAfter` — or `options.startAfter` to also
+	*     step past an invalidate event — for at-least-once consumption
+	*     across restarts. Setting both is rejected up front (Mongo forbids
+	*     the combination; the driver error is far less legible).
 	*
 	* Context keys for policy plugins (`organizationId`, `bypassTenant`,
 	* `includeDeleted`, ...) ride the options bag at runtime — same as every
@@ -2890,6 +3106,7 @@ var Repository = class extends RepositoryBase {
 	* ```
 	*/
 	async *watch(filter, options = {}) {
+		if (options.resumeAfter !== void 0 && options.startAfter !== void 0) throw createError(400, "watch() accepts either `resumeAfter` or `startAfter`, not both — they are alternative resume positions for the same stream.");
 		const context = await this._buildContext("watch", {
 			query: filter ?? {},
 			...options
@@ -2904,9 +3121,60 @@ var Repository = class extends RepositoryBase {
 		if (Object.keys(compiled).length > 0) pipeline.push({ $match: prefixMatchPaths(compiled, "fullDocument") });
 		const stream = this.Model.watch(pipeline, {
 			fullDocument: "updateLookup",
-			...options.resumeAfter !== void 0 ? { resumeAfter: options.resumeAfter } : {}
+			...options.resumeAfter !== void 0 ? { resumeAfter: options.resumeAfter } : {},
+			...options.startAfter !== void 0 ? { startAfter: options.startAfter } : {}
 		});
+		/**
+		* A change feed has NO backpressure — the server pushes, and this bridge
+		* buffers whatever the consumer has not reached yet. Unbounded, a consumer
+		* merely slower than the write rate becomes unbounded memory growth whose
+		* symptom (an OOM) appears nowhere near its cause.
+		*
+		* `head` rather than `queue.shift()`: shift is O(n) on a real array, so a
+		* backlog made draining quadratic exactly when the process was already
+		* struggling. The array is compacted once the read head passes halfway, so
+		* the retained slots stay bounded by the live depth rather than by
+		* everything ever enqueued.
+		*/
+		/**
+		* An unusable bound must not read as "no bound".
+		*
+		* `maxBuffered > 0` is the guard below, and a negative, a fraction,
+		* `Infinity` and `NaN` all slip past it into UNBOUNDED buffering — the
+		* failure this option exists to prevent, silently, in a deployment that
+		* believed it had configured a ceiling. Same shape as the `countLimit`
+		* ceiling, and refused the same way.
+		*
+		* `0` stays legal because it is the documented, explicit escape hatch;
+		* every other non-positive-integer is a mistake.
+		*/
+		const maxBuffered = options.maxBufferedEvents ?? 1024;
+		if (maxBuffered !== 0 && !(Number.isInteger(maxBuffered) && maxBuffered > 0)) throw createError(400, `watch(): maxBufferedEvents must be a positive integer, or 0 to disable the bound — got ${String(maxBuffered)}. A negative, fractional, infinite or NaN value would silently buffer without limit, which is the failure the option exists to prevent.`);
 		const queue = [];
+		let head = 0;
+		let overflowed = false;
+		/**
+		* Delivered is not processed.
+		*
+		* `lastDelivered` is set before the `yield`; `lastAcknowledged` only when
+		* execution RESUMES after it, which happens when the consumer comes back
+		* for the next value — the one observable proof it finished with the
+		* previous one.
+		*
+		* The distinction is the whole difference between at-least-once and
+		* silent loss. Resuming after a merely DELIVERED token skips an event the
+		* consumer may have been halfway through when the stream ended: it was
+		* handed over, never processed, and never seen again. Resuming after the
+		* ACKNOWLEDGED one redelivers at most the in-flight event, which an
+		* idempotent consumer is already built to absorb.
+		*
+		* The asymmetry is the point: redelivering costs a duplicate, skipping
+		* costs a lost write. For money, inventory and outbox consumers those are
+		* not comparable.
+		*/
+		let lastDeliveredToken;
+		let lastAcknowledgedToken;
+		const depth = () => queue.length - head;
 		let streamError = null;
 		let ended = false;
 		let notify = null;
@@ -2916,6 +3184,26 @@ var Repository = class extends RepositoryBase {
 			resolve?.();
 		};
 		const onChange = (change) => {
+			if (overflowed) return;
+			if (maxBuffered > 0 && depth() >= maxBuffered) {
+				overflowed = true;
+				streamError = createError(503, `watch(): consumer fell more than ${maxBuffered} events behind and the buffer is full. Events are never dropped, so the stream ends here — resume with \`startAfter\` from this error's \`resumeToken\`, which is the last event the consumer ACKNOWLEDGED (not the last delivered: resuming past an event still being processed would lose it). Raise \`maxBufferedEvents\` for burst tolerance, or move consumption off the iterator onto a durable queue.`);
+				/**
+				* `resumeToken` is the ACKNOWLEDGED token, never the delivered one:
+				* restarting after an event the consumer had not finished would drop
+				* it. `deliveredToken` rides along for diagnostics only — a supervisor
+				* that resumes from it reintroduces the loss this separation prevents.
+				*
+				* Both may be `undefined` when overflow arrives before the consumer
+				* completed anything; the caller then restarts from whatever position
+				* it opened the stream with, not from here.
+				*/
+				const overflowError = streamError;
+				overflowError.resumeToken = lastAcknowledgedToken;
+				overflowError.deliveredToken = lastDeliveredToken;
+				wake();
+				return;
+			}
 			queue.push(change);
 			wake();
 		};
@@ -2948,16 +3236,23 @@ var Repository = class extends RepositoryBase {
 			}
 			while (true) {
 				if (signal?.aborted) return;
-				const change = queue.shift();
+				const change = head < queue.length ? queue[head++] : void 0;
+				if (head > 32 && head * 2 >= queue.length) {
+					queue.splice(0, head);
+					head = 0;
+				}
 				if (change) {
 					const operation = CHANGE_OPERATION_MAP[change.operationType];
 					if (!operation) continue;
+					lastDeliveredToken = change._id;
 					yield {
 						operation,
 						id: change.documentKey?._id,
 						...change.fullDocument !== void 0 ? { doc: change.fullDocument } : {},
-						timestamp: changeEventTimestamp(change)
+						timestamp: changeEventTimestamp(change),
+						...change._id !== void 0 ? { resumeToken: change._id } : {}
 					};
+					lastAcknowledgedToken = change._id;
 					continue;
 				}
 				if (streamError) {
@@ -3034,8 +3329,9 @@ var Repository = class extends RepositoryBase {
 		const limit = context.limit ?? params.limit ?? params.pagination?.limit ?? this._pagination.config.defaultLimit;
 		const page = context.page ?? params.pagination?.page ?? params.page;
 		const after = context.after ?? params.cursor ?? params.after;
+		const before = context.before ?? params.before;
 		const mode = context.mode ?? params.mode;
-		const useKeyset = this._detectPaginationMode(mode, page, after, sort, context, params);
+		const useKeyset = this._detectPaginationMode(mode, page, after ?? before, sort, context, params);
 		const query = this._buildSearchQuery(filters, search);
 		const populateSpec = options.populateOptions || params.populateOptions || context.populate || options.populate;
 		const paginationOptions = {
@@ -3048,6 +3344,7 @@ var Repository = class extends RepositoryBase {
 			session: options.session,
 			hint: context.hint ?? params.hint,
 			maxTimeMS: context.maxTimeMS ?? params.maxTimeMS,
+			countLimit: context.countLimit ?? params.countLimit,
 			readPreference: context.readPreference ?? options.readPreference ?? params.readPreference,
 			collation: context.collation ?? params.collation
 		};
@@ -3064,7 +3361,8 @@ var Repository = class extends RepositoryBase {
 				session: options.session,
 				readPreference: paginationOptions.readPreference,
 				collation: paginationOptions.collation,
-				countStrategy: context.countStrategy ?? params.countStrategy
+				countStrategy: context.countStrategy ?? params.countStrategy,
+				countLimit: context.countLimit ?? params.countLimit
 			});
 		});
 		return this._runOp("getAll", context, async () => {
@@ -3072,7 +3370,8 @@ var Repository = class extends RepositoryBase {
 			if (useKeyset) result = await this._pagination.stream({
 				...paginationOptions,
 				sort: paginationOptions.sort,
-				after
+				after,
+				before
 			});
 			else {
 				let countFilters;
@@ -4260,7 +4559,7 @@ var Repository = class extends RepositoryBase {
 	async _executeAggregatePaginate(finalReq, useKeyset, limit, session) {
 		if (useKeyset) {
 			if (!finalReq.sort || Object.keys(finalReq.sort).length === 0) throw new Error("mongokit/aggregatePaginate: keyset pagination requires `sort` — the cursor anchors on the sort-key tuple");
-			const cursor = finalReq.after ? decodeAggCursor$1(finalReq.after) : void 0;
+			const cursor = finalReq.after ? decodeAggCursor$1(finalReq.after, this._pagination.config.cursorSecret) : void 0;
 			const keysetMatch = cursor ? buildKeysetPredicate(finalReq.sort, cursor) : void 0;
 			const { pipeline, prePaginationIndex } = buildAggPipeline(finalReq, this.Model.schema);
 			const headStages = pipeline.slice(0, prePaginationIndex);
@@ -4279,11 +4578,11 @@ var Repository = class extends RepositoryBase {
 				data,
 				limit,
 				hasMore,
-				next: hasMore && data.length > 0 ? encodeAggCursor(data[data.length - 1], finalReq.sort) : null
+				next: hasMore && data.length > 0 ? encodeAggCursor$1(data[data.length - 1], finalReq.sort, this._pagination.config.cursorSecret) : null
 			};
 		}
 		const page = Math.max(1, finalReq.page ?? 1);
-		const countStrategy = finalReq.countStrategy ?? "exact";
+		const countStrategy = downgradeCappedCount(finalReq.countStrategy ?? this._pagination.config.defaultCountStrategy, "aggregatePaginateIr");
 		const offset = (page - 1) * limit;
 		if (countStrategy === "none") {
 			const peek = await executeAgg(this.Model, {
@@ -4412,18 +4711,18 @@ var Repository = class extends RepositoryBase {
 				const after = context.after ?? options.after;
 				const pageFromContext = context.page ?? options.page;
 				const isKeyset = !!after || !pageFromContext && !!sort;
-				const countStrategy = context.countStrategy ?? options.countStrategy ?? "exact";
+				const countStrategy = downgradeCappedCount(context.countStrategy ?? options.countStrategy ?? this._pagination.config.defaultCountStrategy, "lookupPopulate");
 				const projection = buildLookupProjection(context.select ?? options.select, lookups);
 				const appendLookupStages$2 = (pipeline) => appendLookupStages(pipeline, lookups, projection, isKeyset && sort ? this._parseSort(sort) : void 0);
 				if (isKeyset && sort) {
 					const parsedSort = this._parseSort(sort);
-					const { validateKeysetSort } = await import("./PaginationEngine-BX9o_-4R.mjs").then((n) => n.n);
-					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-BX9o_-4R.mjs").then((n) => n.r);
-					const { getPrimaryField } = await import("./PaginationEngine-BX9o_-4R.mjs").then((n) => n.n);
+					const { validateKeysetSort } = await import("./PaginationEngine-DQ7beTCR.mjs").then((n) => n.n);
+					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-DQ7beTCR.mjs").then((n) => n.r);
+					const { getPrimaryField } = await import("./PaginationEngine-DQ7beTCR.mjs").then((n) => n.n);
 					const normalizedSort = validateKeysetSort(parsedSort, this._pagination.config.strictKeysetSortFields);
 					const cursorVersion = this._pagination.config.cursorVersion ?? 1;
 					const minCursorVersion = this._pagination.config.minCursorVersion ?? 1;
-					const matchFilters = after ? resolveCursorFilter(after, normalizedSort, cursorVersion, { ...filters || {} }, minCursorVersion) : { ...filters || {} };
+					const matchFilters = after ? resolveCursorFilter(after, normalizedSort, cursorVersion, { ...filters || {} }, minCursorVersion, normalizedSort, this._pagination.config.cursorSecret) : { ...filters || {} };
 					if (projection) {
 						if (Object.values(projection).some((v) => v === 1)) {
 							for (const sortField of Object.keys(normalizedSort)) if (!(sortField in projection)) projection[sortField] = 1;
@@ -4446,7 +4745,7 @@ var Repository = class extends RepositoryBase {
 						data,
 						limit,
 						hasMore,
-						next: hasMore && data.length > 0 ? encodeCursor(data[data.length - 1], primaryField, normalizedSort, cursorVersion) : null
+						next: hasMore && data.length > 0 ? encodeCursor(data[data.length - 1], primaryField, normalizedSort, cursorVersion, this._pagination.config.cursorSecret) : null
 					};
 					await this._emitHook("after:lookupPopulate", {
 						context,
@@ -4646,7 +4945,42 @@ var Repository = class extends RepositoryBase {
 	async _buildContext(operation, options) {
 		throwIfAborted(options.signal);
 		const normalized = this._normalizeFilterSlots(options);
-		return await super._buildContext(operation, normalized);
+		const base = await super._buildContext(operation, normalized);
+		this._guardDistribution(operation, base);
+		return base;
+	}
+	/**
+	* Feed the resolved filter of a guarded verb to the distribution guard.
+	* The slot follows `OP_REGISTRY[op].policyKey` (`query` vs `filters`);
+	* the portable aggregate verbs ALSO carry the caller's filter on
+	* `aggRequest.filter` (merged into the pipeline later by
+	* `_injectPolicyScopeIntoAgg`), and the kit-native pipeline verbs may
+	* carry it as leading `$match` stages — both are folded in so a key the
+	* caller did supply is never reported missing.
+	*/
+	_guardDistribution(operation, context) {
+		if (!this._checkDistribution) return;
+		if (!(DISTRIBUTION_GUARDED_OPERATIONS.has(operation) || this._guardIdAddressed && ID_ADDRESSED_OPERATIONS.has(operation))) return;
+		const policyKey = OP_REGISTRY[operation]?.policyKey;
+		const parts = [];
+		const push = (candidate) => {
+			if (!candidate || typeof candidate !== "object") return;
+			const compiled = compileFilterToMongo(candidate);
+			if (Object.keys(compiled).length > 0) parts.push(compiled);
+		};
+		push(policyKey === "filters" ? context.filters : context.query);
+		push(context.aggRequest?.filter);
+		const pipeline = context.pipeline;
+		if (Array.isArray(pipeline)) for (const stage of pipeline) {
+			if (!stage || typeof stage !== "object") break;
+			if ("$geoNear" in stage) {
+				push(stage.$geoNear?.query);
+				continue;
+			}
+			if (!("$match" in stage)) break;
+			push(stage.$match);
+		}
+		this._checkDistribution(operation, parts.length === 0 ? void 0 : parts.length === 1 ? parts[0] : { $and: parts });
 	}
 	/**
 	* Walk the well-known filter-carrying keys (`query`, `filters`,
@@ -4683,10 +5017,17 @@ var Repository = class extends RepositoryBase {
 	}
 	/**
 	* Detect whether to use keyset (cursor) or offset (page) pagination.
+	* Precedence: explicit `mode` → `page` (offset) → `after` (keyset) →
+	* `PaginationConfig.defaultMode` → the sort heuristic (a non-default
+	* sort with no page means the caller wants a cursor).
 	*/
 	_detectPaginationMode(mode, page, after, sort, context, params) {
 		if (mode) return mode === "keyset";
-		return !page && !!(after || sort !== "-createdAt" && (context.sort ?? params.sort));
+		if (page) return false;
+		if (after) return true;
+		const defaultMode = this._pagination.config.defaultMode;
+		if (defaultMode) return defaultMode === "keyset";
+		return sort !== "-createdAt" && !!(context.sort ?? params.sort);
 	}
 	/**
 	* Build the MongoDB query filter with search merged in. Handles text
@@ -4816,7 +5157,29 @@ var Repository = class extends RepositoryBase {
 	* `errorLabels` exactly as we received it. The caller still sees a
 	* thrown error — only the wrapping layer is skipped.
 	*/
+	/**
+	* Translate a driver error into the repository's error contract, WITHOUT
+	* losing structured diagnostics an action attached to it.
+	*
+	* The translation replaces the object — an E11000 becomes a 409 — so any
+	* property a caller was meant to read went with it. `createMany` attaches a
+	* `partial` report naming which documents landed, and it arrived nowhere:
+	* the report existed, the test for it failed, and the only evidence was the
+	* absence.
+	*
+	* Carried explicitly rather than by copying every own-property, because the
+	* wrap is deliberate: the point is to hide driver internals, and a blanket
+	* copy would put them back.
+	*/
 	_handleError(error) {
+		const translated = this._translateError(error);
+		if (translated !== error) {
+			const partial = error.partial;
+			if (partial !== void 0) translated.partial = partial;
+		}
+		return translated;
+	}
+	_translateError(error) {
 		const labels = error.errorLabels;
 		const hasLabel = error.hasErrorLabel;
 		if (Array.isArray(labels) && (labels.includes("TransientTransactionError") || labels.includes("UnknownTransactionCommitResult")) || typeof hasLabel === "function" && (hasLabel.call(error, "TransientTransactionError") || hasLabel.call(error, "UnknownTransactionCommitResult"))) return error;