@classytic/mongokit 3.38.1 → 3.40.0

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

@@ -1,12 +1,13 @@
 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 SHORTHAND_OPS, a as count, b as create, 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 compileFilterToMongo, x as createMany, y as castFilterToSchema } from "./update-DG0fCwRJ.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 { a as createTxBoundRepo, d as resolveMongoCapabilities, i as withTransaction } from "./transaction-B5L9glO0.mjs";
+import { c as resolveCursorSecrets, l as verifySignature, s as attachSignature, t as PaginationEngine } from "./PaginationEngine-Dvl8jcRY.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";
@@ -118,257 +119,16 @@ async function purgeAnonymizeFunctional(repo, selectFilter, fields, limit, sessi
 		ordered: false,
 		session: session ?? void 0
 	});
+	await repo.emitAsync("after:anonymize", {
+		context: { ...session ? { session } : {} },
+		result: { ids: docs.map((doc) => doc._id) }
+	});
 	return {
 		processed: docs.length,
 		lastId: docs[docs.length - 1]?._id ?? null
 	};
 }
 //#endregion
-//#region src/capabilities.ts
-/**
-* Read the provenance of a capability descriptor's `transactions` flag.
-* A descriptor without the field is a static declaration (`'declared'`) —
-* which is exactly right for sqlitekit / prismakit / any kit whose answer
-* genuinely does not depend on a live deployment.
-*/
-function transactionResolutionOf(caps) {
-	const value = caps.transactionsResolution;
-	return value === "observed" || value === "unknown" ? value : "declared";
-}
-/**
-* What MongoDB supports through mongokit's surface, DECLARED (not observed).
-*
-* Deployment-dependent flags (`transactions`, `changeStreams` — both need a
-* replica set or mongos) are `true` here because they describe the product,
-* not the server you happen to be pointed at. `nestedTransactions` is NOT one
-* of them: it is `false` unconditionally, because the refusal comes from
-* mongokit's own tx-bound proxy rather than from the deployment. **Do not read this constant to decide whether a live connection can run
-* a transaction** — that is {@link resolveMongoCapabilities}, which is what
-* `Repository#capabilities` returns. This one is for the cross-kit conformance
-* harness (which overrides environment-specific limits where it is
-* constructed) and as the base every observed descriptor is derived from.
-*/
-const MONGOKIT_CAPABILITIES = Object.freeze({
-	transactionsResolution: "declared",
-	transactions: true,
-	nestedTransactions: false,
-	transactionRetry: "managed",
-	upsert: true,
-	duplicateKeyError: true,
-	optimisticConcurrency: true,
-	distinct: true,
-	aggregate: true,
-	aggregateOps: Object.freeze({
-		percentile: true,
-		stddev: true,
-		topN: true,
-		dateBucketTimezone: true,
-		customDateBuckets: true,
-		dateBucketSubMinute: true,
-		cache: true
-	}),
-	getOrCreate: true,
-	countAndExists: true,
-	purgeByField: true,
-	purgeByFilter: true,
-	archiveByFilter: true,
-	arrayOperators: true,
-	regexFilter: true,
-	changeStreams: true,
-	lean: true,
-	lookupPopulate: true,
-	lookupCoerce: true,
-	streaming: true
-});
-/**
-* Driver `ServerType`s that positively imply a session-capable, transaction-
-* capable deployment. Verified against mongodb driver 7.x: a single-node
-* replica set reports `RSPrimary` (topology `ReplicaSetWithPrimary`, or
-* `Single` when reached with `directConnection`), a standalone `mongod`
-* reports `Standalone`, and a mongos reports `Mongos`.
-*
-* **This is why the check reads SERVER type, not just topology type.** The
-* pre-existing heuristic (`topology.description.type !== 'Single'`) has a
-* false NEGATIVE: a directly-connected single-node replica set is `Single`
-* yet runs transactions fine.
-*/
-const TRANSACTION_CAPABLE_SERVER_TYPES = /* @__PURE__ */ new Set([
-	"RSPrimary",
-	"RSSecondary",
-	"RSArbiter",
-	"RSOther",
-	"RSGhost",
-	"Mongos",
-	"LoadBalancer"
-]);
-/** Topology types that positively imply transactions regardless of server detail. */
-const TRANSACTION_CAPABLE_TOPOLOGY_TYPES = /* @__PURE__ */ new Set([
-	"ReplicaSetWithPrimary",
-	"ReplicaSetNoPrimary",
-	"Sharded",
-	"LoadBalanced"
-]);
-function clientOf(connection) {
-	const probe = connection;
-	if (!probe || typeof probe !== "object") return void 0;
-	try {
-		return probe.getClient?.() ?? probe.client ?? (probe.topology !== void 0 ? probe : void 0);
-	} catch {
-		return;
-	}
-}
-function serverTypes(description) {
-	const servers = description.servers;
-	if (!servers) return [];
-	return (typeof servers.values === "function" ? [...servers.values()] : Object.values(servers)).map((s) => s?.type).filter((t) => typeof t === "string");
-}
-/**
-* Read whether a connection's LIVE deployment supports multi-document
-* transactions, synchronously, from the driver's SDAM topology description.
-*
-* Free (a few property reads against an object the driver keeps current), so
-* it is deliberately NOT memoized — a connection that opens after the repo was
-* constructed upgrades its own answer with no invalidation step. What IS
-* memoized is the async {@link probeMongoCapabilities} result, which this
-* function consults first so an exotic deployment that answered `hello` but
-* exposes no topology still reports definitively.
-*
-* @returns `'yes'` / `'no'` when the topology is conclusive, `'unknown'`
-*   otherwise — never optimistic. See the module docblock on rule 3.
-*/
-function resolveTransactionSupport(connection) {
-	const cached = readProbeCache(connection);
-	if (cached) return cached;
-	const description = clientOf(connection)?.topology?.description;
-	if (!description) return "unknown";
-	const types = serverTypes(description);
-	if (types.some((t) => TRANSACTION_CAPABLE_SERVER_TYPES.has(t))) return "yes";
-	if (types.length > 0 && types.every((t) => t === "Standalone")) return "no";
-	const topologyType = description.type;
-	if (topologyType && TRANSACTION_CAPABLE_TOPOLOGY_TYPES.has(topologyType)) return "yes";
-	return "unknown";
-}
-function deriveCapabilities(support) {
-	const available = support === "yes";
-	return Object.freeze({
-		...MONGOKIT_CAPABILITIES,
-		transactionsResolution: support === "unknown" ? "unknown" : "observed",
-		transactions: available,
-		nestedTransactions: false,
-		changeStreams: available
-	});
-}
-/** Three possible answers ⇒ three frozen singletons; the getter allocates nothing. */
-const DERIVED = Object.freeze({
-	yes: deriveCapabilities("yes"),
-	no: deriveCapabilities("no"),
-	unknown: deriveCapabilities("unknown")
-});
-/**
-* The capability descriptor for a LIVE connection — what
-* `Repository#capabilities` returns.
-*
-* Every deployment-dependent flag reflects the observed topology; everything
-* else comes from {@link MONGOKIT_CAPABILITIES}. Cheap enough to call per
-* access (topology read + one frozen-object lookup).
-*/
-function resolveMongoCapabilities(connection) {
-	return DERIVED[resolveTransactionSupport(connection)];
-}
-/** The three derived descriptors, for tests and for gates that want to compare identity. */
-function capabilitiesForSupport(support) {
-	return DERIVED[support];
-}
-/** Definitive results only. Keyed on the connection object; never holds `'unknown'`. */
-const PROBE_RESULTS = /* @__PURE__ */ new WeakMap();
-/** In-flight de-duplication so N repos on one connection issue ONE `hello`. */
-const PROBE_INFLIGHT = /* @__PURE__ */ new WeakMap();
-function readProbeCache(connection) {
-	if (!connection || typeof connection !== "object") return void 0;
-	return PROBE_RESULTS.get(connection);
-}
-/** Test seam — drop memoized probe answers (a reused connection object across suites). */
-function resetCapabilityProbeCache(connection) {
-	if (connection && typeof connection === "object") {
-		PROBE_RESULTS.delete(connection);
-		PROBE_INFLIGHT.delete(connection);
-	}
-}
-function withTimeout(promise, ms, onTimeout) {
-	return new Promise((resolve) => {
-		const timer = setTimeout(() => resolve(onTimeout), ms);
-		timer.unref?.();
-		promise.then((value) => {
-			clearTimeout(timer);
-			resolve(value);
-		}, () => {
-			clearTimeout(timer);
-			resolve(onTimeout);
-		});
-	});
-}
-/**
-* Classify a `hello` (or legacy `isMaster`) reply.
-*
-* - `msg: 'isdbgrid'` ⇒ mongos ⇒ transactions (Mongo 4.2+ sharded).
-* - `setName` ⇒ a replica-set member ⇒ transactions.
-* - a reply that IS a hello (`isWritablePrimary` / `ismaster` present) with
-*   neither marker ⇒ standalone ⇒ **no**. Verified: a memory-server standalone
-*   returns `{ isWritablePrimary: true }` and nothing else.
-* - anything unrecognised ⇒ `'unknown'`. A reply we cannot parse is not a yes.
-*/
-function classifyHelloReply(reply) {
-	if (!reply || typeof reply !== "object") return "unknown";
-	const { msg, setName } = reply;
-	if (msg === "isdbgrid") return "yes";
-	if (typeof setName === "string" && setName.length > 0) return "yes";
-	return "isWritablePrimary" in reply || "ismaster" in reply ? "no" : "unknown";
-}
-async function runProbe(connection, timeoutMs) {
-	if (connection.readyState === 2 && typeof connection.asPromise === "function") await withTimeout(connection.asPromise().then(() => void 0, () => void 0), timeoutMs, void 0);
-	const fromTopology = resolveTransactionSupport(connection);
-	if (fromTopology !== "unknown") return fromTopology;
-	const admin = connection.db?.admin?.();
-	if (!admin) return "unknown";
-	return classifyHelloReply(await withTimeout(admin.command({ hello: 1 }).catch(async () => admin.command({ isMaster: 1 }).catch(() => void 0)), timeoutMs, void 0));
-}
-/**
-* Resolve a connection's real capabilities, waiting for (and if necessary
-* asking) the deployment. Memoized per connection: N repositories and N
-* kernels on one connection issue at most ONE `hello`.
-*
-* Hosts do not have to call this — `Repository#capabilities` reads the live
-* topology synchronously, which is already conclusive once
-* `await mongoose.connect()` has returned (the Kernel Construction Standard's
-* Describe → **Bind** ordering guarantees that). It exists for the cases the
-* sync read cannot cover: binding while a connection is still opening, or a
-* deployment whose driver surfaces no topology description. Calling it makes
-* the SUBSEQUENT synchronous reads definitive, so nothing else needs rewiring:
-*
-* ```ts
-* await probeMongoCapabilities(connection);   // once, before bind
-* const engine = defineWallet().bind(connection);  // gate now sees the truth
-* ```
-*
-* Only definitive answers are cached — an `'unknown'` may be re-probed later
-* (the deployment may simply not have been up yet).
-*/
-async function probeMongoCapabilities(connection, options = {}) {
-	if (!connection || typeof connection !== "object") return DERIVED.unknown;
-	const key = connection;
-	const cached = PROBE_RESULTS.get(key);
-	if (cached) return DERIVED[cached];
-	const inflight = PROBE_INFLIGHT.get(key);
-	if (inflight) return DERIVED[await inflight];
-	const run = runProbe(connection, options.timeoutMs ?? 2e3).catch(() => "unknown").then((support) => {
-		if (support !== "unknown") PROBE_RESULTS.set(key, support);
-		PROBE_INFLIGHT.delete(key);
-		return support;
-	});
-	PROBE_INFLIGHT.set(key, run);
-	return DERIVED[await run];
-}
-//#endregion
 //#region src/operations.ts
 /**
 * The registry. Order intentionally groups by category for readability.
@@ -528,123 +288,32 @@ function applyExecutionHints(aggregation, hints) {
 	if (!hints) return;
 	if (hints.allowDiskUse) aggregation.allowDiskUse(true);
 	if (typeof hints.maxTimeMs === "number" && hints.maxTimeMs > 0) aggregation.option({ maxTimeMS: hints.maxTimeMs });
-	if (hints.indexHint !== void 0) aggregation.option({ hint: hints.indexHint });
-}
-//#endregion
-//#region src/filter/cast-schema.ts
-/** Operators whose operand is a single scalar to cast. */
-const SCALAR_OPS = /* @__PURE__ */ new Set([
-	"$eq",
-	"$ne",
-	"$gt",
-	"$gte",
-	"$lt",
-	"$lte"
-]);
-/** Operators whose operand is an array of scalars to cast element-wise. */
-const ARRAY_OPS = /* @__PURE__ */ new Set(["$in", "$nin"]);
-/** Logical operators whose operand is an ARRAY of sub-filters. */
-const LOGICAL_ARRAY_OPS = /* @__PURE__ */ new Set([
-	"$and",
-	"$or",
-	"$nor"
-]);
-/** Logical operators whose operand is a SINGLE nested sub-filter. */
-const LOGICAL_OBJECT_OPS = /* @__PURE__ */ new Set(["$not"]);
-function isPlainObject(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
-}
-/**
-* Cast one value through a schema path. Returns the original value when the
-* path is unknown, the value is nullish, or the cast throws — never raises.
-*/
-function castValue(schema, field, value) {
-	if (value === null || value === void 0) return value;
-	if (typeof value === "object" && !(value instanceof Date)) return value;
-	let schemaType;
-	try {
-		schemaType = schema.path(field);
-	} catch {
-		return value;
-	}
-	if (!schemaType || typeof schemaType.cast !== "function") return value;
-	try {
-		return schemaType.cast(value);
-	} catch {
-		return value;
+	if (hints.indexHint === void 0) return;
+	if (isExpectedIndex(hints.indexHint)) {
+		assertExpectedIndex(aggregation.model(), hints.indexHint.leadingKeys);
+		return;
 	}
+	aggregation.option({ hint: hints.indexHint });
 }
-/**
-* Cast the operand(s) of a field-level operator object, leaving operators we
-* don't understand (`$regex`, `$exists`, `$size`, `$elemMatch`, …) alone.
-*/
-function castOperatorObject(schema, field, ops) {
-	let changed = false;
-	const out = {};
-	for (const [op, operand] of Object.entries(ops)) if (SCALAR_OPS.has(op)) {
-		const next = castValue(schema, field, operand);
-		out[op] = next;
-		if (next !== operand) changed = true;
-	} else if (ARRAY_OPS.has(op) && Array.isArray(operand)) {
-		const arr = operand.map((entry) => castValue(schema, field, entry));
-		out[op] = arr;
-		if (arr.some((v, i) => v !== operand[i])) changed = true;
-	} else out[op] = operand;
-	return changed ? out : ops;
+function isExpectedIndex(hint) {
+	return typeof hint === "object" && hint !== null && Array.isArray(hint.leadingKeys) && hint.leadingKeys.length > 0;
 }
+const checked = /* @__PURE__ */ new WeakMap();
 /**
-* Cast a record-shape Mongo filter against a Mongoose schema so it is safe to
-* hand to a `$match` stage. Recurses `$and` / `$or` / `$nor` / `$not`, since a
-* policy/tenant scope conjoined with a caller filter nests one level down.
-*
-* Filter IR nodes and non-objects pass through untouched — IR values are built
-* in code (already correctly typed) and carry no schema paths to resolve.
-*
-* @example
-* ```ts
-* // organizationId is an ObjectId column; arc supplies the scope id as a string
-* castFilterToSchema({ organizationId: '6a6a…' }, Order.schema)
-* // → { organizationId: ObjectId('6a6a…') }
-* ```
+* Throw unless the model DECLARES an index whose key starts with `leadingKeys`, directly or after
+* one leading scope field (a tenant / branch column the query pins by equality). Forcing such a
+* description as a `hint` was wrong twice over: Mongo requires an index with EXACTLY that key, so a
+* longer one failed `BadValue`; and a hint overrides the planner. The planner picks; this only
+* guarantees the declared expectation holds. Checked once per model and key set.
 */
-function castFilterToSchema(filter, schema) {
-	if (!isPlainObject(filter)) return filter;
-	if (typeof filter.op === "string") return filter;
-	let changed = false;
-	const out = {};
-	for (const [key, value] of Object.entries(filter)) {
-		if (LOGICAL_ARRAY_OPS.has(key) && Array.isArray(value)) {
-			const arr = value.map((entry) => castFilterToSchema(entry, schema));
-			out[key] = arr;
-			if (arr.some((v, i) => v !== value[i])) changed = true;
-			continue;
-		}
-		if (LOGICAL_OBJECT_OPS.has(key) && isPlainObject(value)) {
-			const nested = castFilterToSchema(value, schema);
-			out[key] = nested;
-			if (nested !== value) changed = true;
-			continue;
-		}
-		if (key.startsWith("$")) {
-			out[key] = value;
-			continue;
-		}
-		if (isPlainObject(value)) {
-			const keys = Object.keys(value);
-			if (keys.length > 0 && keys.every((k) => k.startsWith("$"))) {
-				const nextOps = castOperatorObject(schema, key, value);
-				out[key] = nextOps;
-				if (nextOps !== value) changed = true;
-				continue;
-			}
-			out[key] = value;
-			continue;
-		}
-		const next = castValue(schema, key, value);
-		out[key] = next;
-		if (next !== value) changed = true;
-	}
-	return changed ? out : filter;
+function assertExpectedIndex(model, leadingKeys) {
+	const id = leadingKeys.join(",");
+	const done = checked.get(model);
+	if (done?.has(id)) return;
+	const keys = model.schema.indexes().map(([fields]) => Object.keys(fields));
+	const startsWith = (key, at) => leadingKeys.every((k, i) => key[at + i] === k);
+	if (!keys.some((key) => startsWith(key, 0) || startsWith(key, 1))) throw new Error(`[mongokit] ${model.modelName}: an aggregation expects an index leading with (${id}), but none is declared — declared: ${keys.map((k) => `(${k.join(",")})`).join(" ") || "none"}. Declare one, or drop the hint.`);
+	checked.set(model, (done ?? /* @__PURE__ */ new Set()).add(id));
 }
 //#endregion
 //#region src/actions/aggregate-ir/normalize.ts
@@ -806,8 +475,216 @@ 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);
+		/**
+		* Normalization is attempted FIRST, before the "all `$` keys means it is
+		* already an expression" fallback — because `{ $and: [...] }` satisfies
+		* both readings. As a query it is a conjunction of query objects; as an
+		* expression `$and` is a real operator whose operands would be those same
+		* objects, evaluated as TRUTHY. Taking the expression reading first made
+		* every `$and`/`$or` filter match all rows.
+		*
+		* Trying the query reading first disambiguates correctly: a genuine
+		* expression (`{ $eq: ['$a', 1] }`, or `$and` over expressions) fails to
+		* normalize — its operands are not field/operator objects — and falls
+		* through unchanged.
+		*/
+		const normalized = queryToFilterIr(input);
+		if (normalized) return compile(normalized);
+		if (keys.length > 0 && keys.every((k) => k.startsWith("$"))) return input;
+		throw createError(400, `mongokit/filter: could not express this \`where\` as an aggregation condition. Accepted: query syntax (\`{ field: { gte: 1 } }\`, the same language \`filter\` and \`lookup.where\` take), Filter IR (\`{ op, field, value }\`), or a MongoDB expression (\`{ \$eq: ['\$field', value] }\`). Got ${keys.length === 0 ? "an empty object" : `an object keyed by ${keys.map((k) => `'${k}'`).join(", ")}`}. \`mod\` and \`$where\` have no expression form and are refused by name. Refused rather than passed through: evaluated as an expression a plain object is always TRUE, so the filter would silently match every row.`);
+	}
+	return input;
+}
+/**
+* Operators a query object may use, mapped to their Filter IR op.
+*
+* Exactly the set `compileFilterToMongo`'s `expandShorthands` accepts, minus
+* the ones the IR cannot express — so this is COMPLETE over its input, not a
+* best-effort subset. Anything outside it reaches the refusal below rather
+* than being quietly dropped.
+*
+* `mod` is the one shorthand with no IR node. It is refused by name, because
+* "translated everything except the operator you used" is the failure this
+* whole function exists to stop.
+*/
+/**
+* Query operators this translates, and the Filter IR node each becomes.
+*
+* Exactly the set `compileFilterToMongo`'s `expandShorthands` accepts, minus
+* the ones the IR cannot express — so the translation is COMPLETE over its
+* input rather than a best-effort subset. Anything outside reaches the refusal
+* below instead of being quietly dropped.
+*
+* Each node is BUILT, not spread from a common shape: the IR is not uniform —
+* `in`/`nin` carry `values`, `exists` carries `exists`, `regex` carries
+* `pattern`/`flags`. Emitting `value` for all of them compiled without
+* complaint and then matched nothing, which the parity suite caught and a
+* hand-written expectation would not have.
+*/
+const QUERY_OPS = {
+	eq: (field, value) => ({
+		op: "eq",
+		field,
+		value
+	}),
+	ne: (field, value) => ({
+		op: "ne",
+		field,
+		value
+	}),
+	gt: (field, value) => ({
+		op: "gt",
+		field,
+		value
+	}),
+	gte: (field, value) => ({
+		op: "gte",
+		field,
+		value
+	}),
+	lt: (field, value) => ({
+		op: "lt",
+		field,
+		value
+	}),
+	lte: (field, value) => ({
+		op: "lte",
+		field,
+		value
+	}),
+	in: (field, operand) => ({
+		op: "in",
+		field,
+		values: toArray(operand)
+	}),
+	nin: (field, operand) => ({
+		op: "nin",
+		field,
+		values: toArray(operand)
+	}),
+	exists: (field, operand) => ({
+		op: "exists",
+		field,
+		exists: operand !== false
+	}),
+	regex: (field, operand) => buildRegex(field, operand)
+};
+for (const name of Object.keys(QUERY_OPS)) QUERY_OPS[`$${name}`] = QUERY_OPS[name];
+function toArray(operand) {
+	return Array.isArray(operand) ? [...operand] : [operand];
+}
+/** `regex` accepts a string, `{ $regex, $options }`, or a real RegExp. */
+function buildRegex(field, operand) {
+	if (operand instanceof RegExp) return operand.flags ? {
+		op: "regex",
+		field,
+		pattern: operand.source,
+		flags: operand.flags
+	} : {
+		op: "regex",
+		field,
+		pattern: operand.source
+	};
+	if (operand !== null && typeof operand === "object") {
+		const o = operand;
+		const flags = typeof o.$options === "string" ? o.$options : void 0;
+		return flags ? {
+			op: "regex",
+			field,
+			pattern: String(o.$regex ?? ""),
+			flags
+		} : {
+			op: "regex",
+			field,
+			pattern: String(o.$regex ?? "")
+		};
+	}
+	return {
+		op: "regex",
+		field,
+		pattern: String(operand)
+	};
+}
+const LOGICAL = {
+	$and: "and",
+	$or: "or"
+};
+/** `{ field: { gte: 1, lte: 9 } }` and `{ a: 1, b: 2 }` are both conjunctions. */
+function allOf(children) {
+	if (children.length === 0) return { op: "true" };
+	if (children.length === 1) return children[0];
+	return {
+		op: "and",
+		children
+	};
+}
+/**
+* Translate a plain query object into Filter IR, or return `null` when it uses
+* anything outside {@link QUERY_OPS}.
+*
+* `null` rather than a throw so the caller owns the error message — it has the
+* context (which surface, what was passed) that makes the refusal actionable.
+*/
+function queryToFilterIr(query) {
+	const children = [];
+	for (const [key, value] of Object.entries(query)) {
+		const logical = LOGICAL[key];
+		if (logical) {
+			if (!Array.isArray(value)) return null;
+			const subs = [];
+			for (const entry of value) {
+				if (entry === null || typeof entry !== "object") return null;
+				const sub = queryToFilterIr(entry);
+				if (!sub) return null;
+				subs.push(sub);
+			}
+			children.push({
+				op: logical,
+				children: subs
+			});
+			continue;
+		}
+		if (key.startsWith("$")) return null;
+		if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+			const ops = Object.keys(value);
+			if (ops.length > 0 && ops.some((o) => o.startsWith("$") || SHORTHAND_OPS.has(o))) {
+				if (!ops.every((o) => o in QUERY_OPS)) return null;
+				for (const [op, operand] of Object.entries(value)) children.push(QUERY_OPS[op](key, operand));
+				continue;
+			}
+		}
+		children.push({
+			op: "eq",
+			field: key,
+			value
+		});
+	}
+	return allOf(children);
 }
 function compile(filter) {
 	switch (filter.op) {
@@ -825,7 +702,25 @@ function compile(filter) {
 		case "nin":
 			if (filter.values.length === 0) return true;
 			return { $not: [{ $in: [`$${filter.field}`, [...filter.values]] }] };
-		case "exists": return filter.exists ? { $ne: [`$${filter.field}`, null] } : { $eq: [`$${filter.field}`, null] };
+		case "exists": {
+			/**
+			* SQL parity: `exists: false` matches NULL and MISSING alike (`IS
+			* NULL`); `exists: true` matches neither (`IS NOT NULL`).
+			*
+			* This was `$ne: [field, null]` / `$eq: [field, null]`, on the stated
+			* grounds that "mongo treats [null and missing] the same way for missing
+			* fields". It does not: a missing path in an expression is MISSING, not
+			* null, and `$ne: ['$absent', null]` is TRUE. So `exists: true` matched
+			* every document including the ones without the field, and
+			* `exists: false` matched none — the predicate inverted on exactly the
+			* documents it was asked about.
+			*
+			* `$type` is the only operator that distinguishes the three states, and
+			* it names both of the ones SQL folds together.
+			*/
+			const nullish = { $in: [{ $type: `$${filter.field}` }, ["missing", "null"]] };
+			return filter.exists ? { $not: [nullish] } : nullish;
+		}
 		case "like": return { $regexMatch: {
 			input: `$${filter.field}`,
 			regex: likeToRegexPattern(filter.pattern),
@@ -983,20 +878,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 +966,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 +1305,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
@@ -1949,242 +1960,6 @@ function appendLookupStages(pipeline, lookups, projection, keysetSort) {
 	if (finalProjection) pipeline.push({ $project: finalProjection });
 }
 //#endregion
-//#region src/tx-bound.ts
-/**
-* Map of session-aware method name → positional index of the `{ session }`
-* options bag. Keep this list in sync with the method signatures in
-* `Repository.ts` and the plugin method definitions. Unknown plugin
-* methods pass through unwrapped (callers use the standalone helper).
-*/
-const SESSION_OPTIONS_INDEX = Object.freeze({
-	create: 1,
-	update: 2,
-	delete: 1,
-	getById: 1,
-	getAll: 1,
-	createMany: 1,
-	findAll: 1,
-	getOrCreate: 2,
-	count: 1,
-	exists: 1,
-	getByQuery: 1,
-	getOne: 1,
-	findOneAndUpdate: 2,
-	distinct: 2,
-	aggregate: 1,
-	aggregatePaginate: 0,
-	lookupPopulate: 0,
-	upsert: 2,
-	increment: 3,
-	decrement: 3,
-	multiplyField: 3,
-	setMin: 3,
-	setMax: 3,
-	pushToArray: 3,
-	pullFromArray: 3,
-	addToSet: 3,
-	setField: 3,
-	unsetField: 2,
-	renameField: 3,
-	atomicUpdate: 2,
-	updateMany: 2,
-	deleteMany: 1,
-	bulkWrite: 1,
-	restore: 1,
-	getDeleted: 1,
-	addSubdocument: 3,
-	getSubdocument: 3,
-	updateSubdocument: 4,
-	deleteSubdocument: 3,
-	groupBy: 1,
-	sum: 2,
-	average: 2,
-	min: 2,
-	max: 2
-});
-/**
-* Build a session-threaded proxy over `outer`. The returned object has the
-* same method signatures, but every CRUD call auto-injects the supplied
-* session into the options bag. Non-CRUD properties (Model, modelName,
-* hook API, utility helpers) pass through.
-*/
-function createTxBoundRepo(outer, session) {
-	return new Proxy(outer, { get(target, prop, receiver) {
-		if (prop === "withTransaction") return () => {
-			throw new Error("[mongokit] Nested withTransaction is not supported on a tx-bound repository. Reuse the outer `txRepo` directly, or collapse the nesting.");
-		};
-		const value = Reflect.get(target, prop, receiver);
-		if (typeof value !== "function") return value;
-		if (prop === "Model") return value;
-		if (typeof prop === "symbol") return value.bind(target);
-		if (prop.startsWith("_")) return value.bind(target);
-		const optionsIndex = SESSION_OPTIONS_INDEX[prop];
-		if (optionsIndex === void 0) return value.bind(target);
-		return function txBoundMethod(...args) {
-			while (args.length <= optionsIndex) args.push(void 0);
-			const current = args[optionsIndex];
-			if (current === void 0) args[optionsIndex] = { session };
-			else if (typeof current === "object" && current !== null && !Array.isArray(current)) args[optionsIndex] = {
-				...current,
-				session
-			};
-			else return value.apply(target, args);
-			return value.apply(target, args);
-		};
-	} });
-}
-//#endregion
-//#region src/transaction.ts
-/**
-* Run a callback inside a MongoDB transaction on the given connection.
-*
-* - Starts a session, runs `session.withTransaction(callback)` (which auto-retries
-*   on `TransientTransactionError` and `UnknownTransactionCommitResult`), and
-*   always ends the session in `finally`.
-* - When `allowFallback` is true and the deployment doesn't support transactions
-*   (e.g. standalone MongoDB in dev), the callback runs once without a
-*   transaction on the same session. `onFallback` is invoked with the original
-*   error so hosts can log the degradation.
-*
-* @example
-* ```ts
-* import mongoose from 'mongoose';
-* import { withTransaction } from '@classytic/mongokit';
-*
-* await withTransaction(mongoose.connection, async (session) => {
-*   const order  = await orderRepo.create(data, { session });
-*   await inventoryRepo.decrement(order.items, { session });
-*   return order;
-* });
-* ```
-*/
-async function withTransaction(connection, callback, options = {}) {
-	const session = await connection.startSession();
-	try {
-		return await session.withTransaction(() => callback(session), options.transactionOptions);
-	} catch (error) {
-		const err = error;
-		if (options.allowFallback && isTransactionUnsupported(err)) {
-			options.onFallback?.(err);
-			return await callback(session);
-		}
-		throw err;
-	} finally {
-		await session.endSession();
-	}
-}
-/**
-* Multi-repo transactional batch — every repo in `repos` becomes a
-* session-bound proxy inside the callback. Eliminates the per-call
-* `{ session }` threading that was repeated across ~20 call sites
-* (be-prod outbox writes, order placement, transfer source/dest pairs,
-* payrun saga steps).
-*
-* Same retry + fallback semantics as `withTransaction`: the
-* `transactionOptions` / `allowFallback` / `onFallback` knobs apply.
-*
-* Each property of the input `repos` map is rebound via the
-* `createTxBoundRepo` proxy — every CRUD method on the bound repo
-* auto-injects `session` into its options bag, including
-* `claim` / `claimVersion` / `findOneAndUpdate` and plugin-contributed
-* methods. Non-CRUD properties (Model, modelName, hook engine,
-* idField) pass through to the underlying repo. Nested
-* `boundRepo.withTransaction(...)` throws — reuse the outer bound
-* repos.
-*
-* @example Order placement across three repos in one transaction
-* ```ts
-* import { batchTransaction } from '@classytic/mongokit';
-*
-* const order = await batchTransaction(
-*   mongoose.connection,
-*   { orders: orderRepo, events: eventRepo, inventory: inventoryRepo },
-*   async ({ orders, events, inventory }) => {
-*     const created = await orders.create(orderData);          // session auto-injected
-*     await events.create({ type: 'order.placed', orderId: created._id });
-*     await inventory.claim(skuId, { from: 'available', to: 'reserved' });
-*     return created;
-*   },
-* );
-* ```
-*
-* @example With fallback for standalone-mongo dev environments
-* ```ts
-* await batchTransaction(
-*   mongoose.connection,
-*   { orders, events },
-*   async ({ orders, events }) => { ... },
-*   { allowFallback: true, onFallback: (err) => log.warn(err) },
-* );
-* ```
-*
-* @param connection - Mongoose connection (or anything with
-*   `startSession()`). Single source of session truth — every bound
-*   repo shares this session.
-* @param repos - Map of repo instances to rebind. Keys become the
-*   property names on the callback's argument.
-* @param callback - Receives the bound repo map. Return value flows
-*   through to the outer `Promise`.
-*/
-async function batchTransaction(connection, repos, callback, options = {}) {
-	return withTransaction(connection, async (session) => {
-		const bound = {};
-		for (const key of Object.keys(repos)) {
-			const repo = repos[key];
-			bound[key] = createTxBoundRepo(repo, session);
-		}
-		return callback(bound);
-	}, options);
-}
-/**
-* Detect whether an error indicates the MongoDB deployment does not support
-* multi-document transactions (standalone server, older topology, etc.).
-*
-* Checks MongoDB error codes first — 263 (standalone) and 20 (unsupported
-* topology) — with a message-matching fallback for edge cases surfaced by
-* driver versions that throw before the proper code lands.
-*
-* **Driver-version drift:** modern mongoose / mongodb-driver versions hit
-* the standalone case via the retryable-writes precondition rather than
-* the transaction precondition (`retryWrites=true` is on by default,
-* standalone Mongo rejects it before the transaction is even attempted).
-* So we accept that message as equivalent — the underlying topology
-* problem is the same, and the fallback semantics are correct either way.
-*/
-function isTransactionUnsupported(error) {
-	const code = error.code;
-	if (code === 263 || code === 20) return true;
-	const message = (error.message || "").toLowerCase();
-	return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("transaction is not supported") || message.includes("does not support retryable writes");
-}
-/**
-* PROACTIVELY report whether a connection's deployment supports multi-document
-* transactions — the read-side companion to {@link isTransactionUnsupported}
-* (which classifies a FAILED attempt). Lets a caller skip a doomed transaction
-* attempt on standalone dev Mongo rather than starting one just to catch the
-* error.
-*
-* Delegates to {@link resolveTransactionSupport} so mongokit has exactly ONE
-* topology reader. That also fixes a false NEGATIVE this function used to
-* have: it tested `description.type !== 'Single'`, but a single-node replica
-* set reached with `directConnection` is `Single` with a server type of
-* `RSPrimary` and runs transactions fine. The shared reader looks at the
-* SERVER descriptions first.
-*
-* **`unknown` is optimistic HERE and pessimistic in `capabilities.ts` — the
-* difference is deliberate.** This answers "should I bother ATTEMPTING a
-* transaction?", where guessing yes costs one caught error (`allowFallback`
-* still recovers). The capability descriptor answers "may this deployment be
-* trusted with money?", where guessing yes is the bug class this repo keeps
-* hitting (AGENTS.md FAIL LOUD rule 3). Do not "unify" them.
-*
-* Accepts a Mongoose `Connection` (or anything exposing `getClient()`/`client`
-* with a driver `topology`), so it stays decoupled from mongoose types.
-*/
-function supportsTransactions(connection) {
-	return resolveTransactionSupport(connection) !== "no";
-}
-//#endregion
 //#region src/Repository.ts
 /**
 * Validates that an update patch is homogeneous — either all top-level
@@ -2232,6 +2007,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 +2079,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 +2148,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 +2181,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 +2716,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 +2738,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 +2753,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 +2816,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 +2868,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) {
@@ -2977,29 +2904,6 @@ var Repository = class extends RepositoryBase {
 			await closeStream();
 		}
 	}
-	/**
-	* Unified pagination - auto-detects offset vs keyset based on params
-	*
-	* Auto-detection logic:
-	* - If params has 'cursor' or 'after' → uses keyset pagination (stream)
-	* - If params has 'pagination' or 'page' → uses offset pagination (paginate)
-	* - Else → defaults to offset pagination with page=1
-	*
-	* @example
-	* // Offset pagination (page-based)
-	* await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
-	* await repo.getAll({ pagination: { page: 2, limit: 20 } });
-	*
-	* // Keyset pagination (cursor-based)
-	* await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
-	* await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
-	*
-	* // Simple query (defaults to page 1)
-	* await repo.getAll({ filters: { status: 'active' } });
-	*
-	* // Skip cache for fresh data
-	* await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
-	*/
 	async getAll(params = {}, options = {}) {
 		const normalizedParams = {
 			...params,
@@ -3034,8 +2938,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 +2953,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 +2970,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 +2979,8 @@ var Repository = class extends RepositoryBase {
 			if (useKeyset) result = await this._pagination.stream({
 				...paginationOptions,
 				sort: paginationOptions.sort,
-				after
+				after,
+				before
 			});
 			else {
 				let countFilters;
@@ -3563,6 +3471,11 @@ var Repository = class extends RepositoryBase {
 			[effectiveIdField]: id,
 			[stateField]: fromSpec
 		};
+		const seeded = options.target;
+		if (seeded !== void 0) {
+			if (String(seeded[effectiveIdField]) !== String(id)) throw new Error(`[claim] options.target is ${effectiveIdField}=${String(seeded[effectiveIdField])}, not the claimed ${String(id)}`);
+			for (const key of [this.versionField, "updatedAt"]) if (seeded[key] !== void 0 && !(key in filter)) filter[key] = seeded[key];
+		}
 		assertNoMixedPatchShape("claim", patch);
 		const patchKeys = Object.keys(patch);
 		const operatorPatchKeys = patchKeys.filter((k) => k.startsWith("$"));
@@ -4260,7 +4173,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 +4192,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 +4325,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-Dvl8jcRY.mjs").then((n) => n.n);
+					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-Dvl8jcRY.mjs").then((n) => n.r);
+					const { getPrimaryField } = await import("./PaginationEngine-Dvl8jcRY.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 +4359,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 +4559,82 @@ 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._sharedReadSeams(operation, normalized)
+		});
+		this._guardDistribution(operation, base);
+		return base;
+	}
+	/**
+	* `memo` and (for an id-addressed op) `loadTarget` — attached before the before-hooks
+	* run so every hook of one operation shares one read. A caller that has just read the
+	* document in the same session passes it as `target`, and nothing is read at all.
+	*/
+	_sharedReadSeams(operation, options) {
+		const store = /* @__PURE__ */ new Map();
+		const memo = (key, load) => {
+			let pending = store.get(key);
+			if (!pending) {
+				pending = Promise.resolve().then(load);
+				store.set(key, pending);
+				pending.catch(() => store.delete(key));
+			}
+			return pending;
+		};
+		const id = options.id;
+		if (!OP_REGISTRY[operation]?.hasIdContext || id === void 0) return { memo };
+		const seeded = options.target;
+		const idField = options.idField ?? this.idField;
+		const session = options.session;
+		const supplied = options.query ?? {};
+		const Model = this.Model;
+		function loadTarget() {
+			if (!this || typeof this !== "object") throw new Error("context.loadTarget() must be called as a method (ctx.loadTarget()) — it reads the operation tenant scope");
+			const query = this.query ?? {};
+			const policyScope = Object.fromEntries(Object.entries(query).filter(([k]) => !(k in supplied)));
+			return memo("mongokit:target", async () => seeded !== void 0 ? seeded : await Model.findOne({
+				...policyScope,
+				[idField]: id
+			}, null, { session }).lean());
+		}
+		return {
+			memo,
+			loadTarget
+		};
+	}
+	/**
+	* 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 +4671,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 +4811,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;
@@ -4833,4 +4850,4 @@ var Repository = class extends RepositoryBase {
 	}
 };
 //#endregion
-export { resetCapabilityProbeCache as _, supportsTransactions as a, transactionResolutionOf as b, ALL_OPERATIONS as c, READ_OPERATIONS as d, operationsByPolicyKey as f, probeMongoCapabilities as g, classifyHelloReply as h, isTransactionUnsupported as i, MUTATING_OPERATIONS as l, capabilitiesForSupport as m, Repository as n, withTransaction as o, MONGOKIT_CAPABILITIES as p, batchTransaction as r, AggregationBuilder as s, HOOK_PRIORITY$1 as t, OP_REGISTRY as u, resolveMongoCapabilities as v, createMongoPurgePort as x, resolveTransactionSupport as y };
+export { MUTATING_OPERATIONS as a, operationsByPolicyKey as c, ALL_OPERATIONS as i, createMongoPurgePort as l, Repository as n, OP_REGISTRY as o, AggregationBuilder as r, READ_OPERATIONS as s, HOOK_PRIORITY$1 as t };