@classytic/mongokit 3.40.0 → 3.40.1

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

@@ -1,13 +1,15 @@
 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 { _ 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 { a as narrowToIds, i as keysetFilter, o as selectKeysetChunk, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-BmAwsqNk.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-WgeAUJ_I.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.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 { i as applyToQuery, n as applyCursorTimeoutMode, r as applyToAggregate, u as resolveQueryOptions } from "./query-defaults-BxUcSOoF.mjs";
+import { a as createTxBoundRepo, d as resolveMongoCapabilities, i as withTransaction } from "./transaction-BrRYtH_b.mjs";
+import { _ as resolveCursorSecrets, d as withGroupTiebreak, f as withIdTiebreak, g as attachSignature, i as validateKeysetSort, l as assertOffsetWithinCap, n as getPrimaryField, o as encodeCursor, s as resolveCursorFilter, t as PaginationEngine, u as cursorScope, v as verifySignature } from "./PaginationEngine-CfT2Cxkj.mjs";
 import { calculateTotalPages } from "./pagination/utils/limits.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
-import { RepositoryBase, createDistributionGuard, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry } from "@classytic/repo-core/repository";
+import { a as scopeJoins, r as markGoverned } from "./join-scope-DSAznE8E.mjs";
+import { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, RepositoryBase, bulkUpsertOptionsError, createDistributionGuard, runChunkedArchive, runChunkedPurge, summarizeBulkUpsert, 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";
@@ -191,6 +193,11 @@ const OP_REGISTRY = {
 		mutates: true,
 		hasIdContext: false
 	},
+	bulkUpsert: {
+		policyKey: "operations",
+		mutates: true,
+		hasIdContext: false
+	},
 	getById: {
 		policyKey: "query",
 		mutates: false,
@@ -246,6 +253,11 @@ const OP_REGISTRY = {
 		mutates: false,
 		hasIdContext: false
 	},
+	iterate: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
 	watch: {
 		policyKey: "query",
 		mutates: false,
@@ -316,20 +328,6 @@ function assertExpectedIndex(model, leadingKeys) {
 	checked.set(model, (done ?? /* @__PURE__ */ new Set()).add(id));
 }
 //#endregion
-//#region src/actions/aggregate-ir/normalize.ts
-/**
-* AggRequest → input normalization (mongokit binding).
-*
-* Re-exports the kit-neutral helpers from `@classytic/repo-core/aggregate`
-* with the mongokit error-prefix pre-bound, so call sites stay free of
-* boilerplate. The actual logic lives in repo-core — when the rules
-* for what a valid AggRequest looks like change, update the IR
-* contract there.
-*/
-function validateMeasures$1(measures) {
-	validateMeasures(measures, "mongokit");
-}
-//#endregion
 //#region src/actions/aggregate-ir/dateBucket.ts
 /**
 * Compile a `AggDateBucket` to the mongo expression that produces the
@@ -845,6 +843,20 @@ function compileMeasure(measure) {
 	}
 }
 //#endregion
+//#region src/actions/aggregate-ir/normalize.ts
+/**
+* AggRequest → input normalization (mongokit binding).
+*
+* Re-exports the kit-neutral helpers from `@classytic/repo-core/aggregate`
+* with the mongokit error-prefix pre-bound, so call sites stay free of
+* boilerplate. The actual logic lives in repo-core — when the rules
+* for what a valid AggRequest looks like change, update the IR
+* contract there.
+*/
+function validateMeasures$1(measures) {
+	validateMeasures(measures, "mongokit");
+}
+//#endregion
 //#region src/actions/aggregate-ir/pipeline.ts
 function buildAggPipeline(req, schema) {
 	validateMeasures$1(req.measures);
@@ -1239,19 +1251,34 @@ function irReferencesAlias(filter, aliasSet) {
 	return false;
 }
 //#endregion
+//#region src/actions/aggregate-ir/execute.ts
+/** Build the aggregate for `stages` with every execution option applied, unexecuted. */
+function prepareAgg(Model, stages, req, options = {}) {
+	const aggregation = Model.aggregate(options.finalize ? options.finalize(stages) : stages);
+	if (options.session) aggregation.session(options.session);
+	applyToAggregate(aggregation, options.queryOptions ?? {});
+	applyExecutionHints(aggregation, options.queryOptions && req.executionHints ? {
+		...req.executionHints,
+		maxTimeMs: void 0
+	} : req.executionHints);
+	return aggregation;
+}
+async function runAgg(Model, stages, req, options = {}) {
+	return await prepareAgg(Model, stages, req, options).exec();
+}
+async function executeAgg(Model, req, options = {}) {
+	const { pipeline } = buildAggPipeline(req, Model.schema);
+	return runAgg(Model, pipeline, req, options);
+}
+//#endregion
 //#region src/actions/aggregate-ir/count.ts
 async function countAggGroups(Model, req, options = {}) {
-	const session = options.session;
 	const groupCols = normalizeGroupBy(req.groupBy);
 	const hasDottedGroupBy = groupCols.some((f) => f.includes("."));
 	const hasDateBuckets = !!req.dateBuckets && Object.keys(req.dateBuckets).length > 0;
 	if (req.having !== void 0 || req.lookups !== void 0 && req.lookups.length > 0 || hasDottedGroupBy || hasDateBuckets) {
 		const { pipeline, prePaginationIndex } = buildAggPipeline(req, Model.schema);
-		const finalPipeline = [...pipeline.slice(0, prePaginationIndex), { $count: "n" }];
-		const aggregation = Model.aggregate(finalPipeline);
-		if (session) aggregation.session(session);
-		applyExecutionHints(aggregation, req.executionHints);
-		const [row] = await aggregation.exec();
+		const [row] = await runAgg(Model, [...pipeline.slice(0, prePaginationIndex), { $count: "n" }], req, options);
 		return row?.n ?? 0;
 	}
 	const match = req.filter ? compileFilterToMongo(castFilterToSchema(req.filter, Model.schema), Model.schema) : {};
@@ -1260,10 +1287,7 @@ async function countAggGroups(Model, req, options = {}) {
 		if (Object.keys(match).length > 0) pipeline.push({ $match: match });
 		pipeline.push({ $limit: 1 });
 		pipeline.push({ $count: "n" });
-		const aggregation = Model.aggregate(pipeline);
-		if (session) aggregation.session(session);
-		applyExecutionHints(aggregation, req.executionHints);
-		const [row] = await aggregation.exec();
+		const [row] = await runAgg(Model, pipeline, req, options);
 		return row?.n ?? 0;
 	}
 	const groupId = groupCols.reduce((acc, field) => {
@@ -1274,22 +1298,10 @@ async function countAggGroups(Model, req, options = {}) {
 	if (Object.keys(match).length > 0) pipeline.push({ $match: match });
 	pipeline.push({ $group: { _id: groupId } });
 	pipeline.push({ $count: "n" });
-	const aggregation = Model.aggregate(pipeline);
-	if (session) aggregation.session(session);
-	const [row] = await aggregation.exec();
+	const [row] = await runAgg(Model, pipeline, req, options);
 	return row?.n ?? 0;
 }
 //#endregion
-//#region src/actions/aggregate-ir/execute.ts
-async function executeAgg(Model, req, options = {}) {
-	const session = options.session;
-	const { pipeline } = buildAggPipeline(req, Model.schema);
-	const aggregation = Model.aggregate(pipeline);
-	if (session) aggregation.session(session);
-	applyExecutionHints(aggregation, req.executionHints);
-	return await aggregation.exec();
-}
-//#endregion
 //#region src/actions/aggregate-ir/keyset.ts
 /**
 * Keyset (cursor) pagination helpers — mongokit binding.
@@ -1375,6 +1387,188 @@ function createMongoArchivePort(repo, filter, session) {
 	};
 }
 //#endregion
+//#region src/actions/bulk-upsert.ts
+/**
+* `bulkUpsert` execution: keyed `updateOne` + `upsert` sub-ops in ONE `client.bulkWrite` with
+* `verboseResults`, the only form that reports matched / modified / upserted PER OP (server 8.0,
+* driver ClientBulkWrite). Mongoose's unordered `Connection.bulkWrite` returns without rethrowing a
+* driver error (lib/connection.js, the `[res, error]` branch), so it is not used. Each row is cast
+* with `Model.castObject` (a bad value fails that row as `validation`) and schema timestamps are
+* stamped here, since the driver path runs no mongoose middleware.
+*/
+/** Split rows into sendable sub-ops and rows refused before sending (`invalid_row`). */
+function planUpserts(rows, key, routing) {
+	const planned = [];
+	const refused = [];
+	rows.forEach((row, index) => {
+		const keyVals = Object.fromEntries(key.map((k) => [k, row[k]]));
+		const missingKey = key.some((k) => row[k] === void 0 || row[k] === null);
+		const badInc = routing.inc.some((f) => row[f] !== void 0 && typeof row[f] !== "number");
+		if (missingKey || badInc) {
+			refused.push({
+				index,
+				key: keyVals,
+				outcome: "failed",
+				code: BULK_UPSERT_FAILURE_CODES.INVALID_ROW
+			});
+			return;
+		}
+		const $set = {};
+		const $inc = {};
+		const $setOnInsert = {};
+		for (const [field, value] of Object.entries(row)) {
+			if (key.includes(field) || value === void 0) continue;
+			if (routing.inc.includes(field)) $inc[field] = value;
+			else if (routing.setOnInsert.includes(field)) $setOnInsert[field] = value;
+			else if (!routing.set || routing.set.includes(field)) $set[field] = value;
+		}
+		const update = {};
+		if (Object.keys($set).length > 0) update.$set = $set;
+		if (Object.keys($inc).length > 0) update.$inc = $inc;
+		if (Object.keys($setOnInsert).length > 0) update.$setOnInsert = $setOnInsert;
+		if (Object.keys(update).length === 0) update.$set = {};
+		planned.push({
+			index,
+			key: keyVals,
+			filter: { ...keyVals },
+			update
+		});
+	});
+	return {
+		planned,
+		refused
+	};
+}
+/** Field sets a unique index covers; `_id` always. */
+function uniqueIndexes(model) {
+	const out = [["_id"]];
+	for (const [fields, options] of model.schema.indexes()) if (options.unique === true) out.push(Object.keys(fields));
+	return out;
+}
+/** Is some unique index entirely pinned by the filter's equality fields (so it matches <= 1 row)? */
+function keyIsUnique(model, filterFields) {
+	return uniqueIndexes(model).some((fields) => fields.every((f) => filterFields.includes(f)));
+}
+function timestampFields(model) {
+	const ts = model.schema.get("timestamps");
+	if (!ts) return {};
+	if (ts === true) return {
+		createdAt: "createdAt",
+		updatedAt: "updatedAt"
+	};
+	const name = (v, d) => v === false ? void 0 : typeof v === "string" ? v : d;
+	return {
+		createdAt: name(ts.createdAt, "createdAt"),
+		updatedAt: name(ts.updatedAt, "updatedAt")
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** `Model.castObject`, narrowed to the plain object it returns for a plain object input. */
+function castRecord(model, fields) {
+	const casted = model.castObject(fields);
+	if (!isRecord(casted)) throw new TypeError("[mongokit] castObject returned a non-object");
+	return casted;
+}
+/** A server before 8.0 has no `bulkWrite` command (CommandNotFound, 59): a closed refusal. */
+function throwIfUnsupported(err) {
+	if (err instanceof mongoose.mongo.MongoServerError && err.code === 59) throw createError(501, "[mongokit] bulkUpsert needs MongoDB 8.0 (client bulkWrite with per-op results)", { code: BULK_UPSERT_ERROR_CODES.UNSUPPORTED });
+}
+function failureCode(code) {
+	if (code === 11e3 || code === 11001) return BULK_UPSERT_FAILURE_CODES.DUPLICATE;
+	if (code === 121) return BULK_UPSERT_FAILURE_CODES.VALIDATION;
+	return BULK_UPSERT_FAILURE_CODES.WRITE_ERROR;
+}
+/** Cast, stamp, send in one command, and map every sub-op to its exact outcome. */
+async function executeUpserts(model, ops, options) {
+	const results = [];
+	const sendable = [];
+	const namespace = `${model.db.name}.${model.collection.collectionName}`;
+	const ts = timestampFields(model);
+	const now = /* @__PURE__ */ new Date();
+	for (const op of ops) try {
+		const update = {};
+		for (const [operator, fields] of Object.entries(op.update)) update[operator] = Object.keys(fields).length > 0 ? castRecord(model, fields) : {};
+		if (ts.updatedAt) update.$set = {
+			...update.$set,
+			[ts.updatedAt]: now
+		};
+		if (ts.createdAt) update.$setOnInsert = {
+			...update.$setOnInsert,
+			[ts.createdAt]: now
+		};
+		sendable.push({
+			...op,
+			filter: castRecord(model, op.filter),
+			update
+		});
+	} catch (err) {
+		if (!(err instanceof mongoose.Error.ValidationError) && !(err instanceof mongoose.Error.CastError)) throw err;
+		results.push({
+			index: op.index,
+			key: op.key,
+			outcome: "failed",
+			code: BULK_UPSERT_FAILURE_CODES.VALIDATION
+		});
+	}
+	if (sendable.length === 0) return results;
+	const models = sendable.map((op) => ({
+		name: "updateOne",
+		namespace,
+		filter: op.filter,
+		update: op.update,
+		upsert: true
+	}));
+	let res;
+	let writeErrors = /* @__PURE__ */ new Map();
+	try {
+		res = await model.db.getClient().bulkWrite(models, {
+			ordered: options.ordered,
+			verboseResults: true,
+			...options.session ? { session: options.session } : {},
+			...options.writeConcern ? { writeConcern: options.writeConcern } : {},
+			...options.timeoutMS !== void 0 ? { timeoutMS: options.timeoutMS } : {}
+		});
+	} catch (err) {
+		throwIfUnsupported(err);
+		if (!(err instanceof mongoose.mongo.MongoClientBulkWriteError) || err.writeConcernErrors.length > 0) throw err;
+		res = err.partialResult;
+		writeErrors = err.writeErrors;
+	}
+	const updates = res?.updateResults ?? /* @__PURE__ */ new Map();
+	sendable.forEach((op, i) => {
+		const failed = writeErrors.get(i);
+		if (failed) {
+			results.push({
+				index: op.index,
+				key: op.key,
+				outcome: "failed",
+				code: failureCode(failed.code)
+			});
+			return;
+		}
+		const r = updates.get(i);
+		if (!r) {
+			if (!options.ordered) throw new Error(`[mongokit] bulkUpsert: the server reported no outcome for row ${op.index}`);
+			results.push({
+				index: op.index,
+				key: op.key,
+				outcome: "failed",
+				code: BULK_UPSERT_FAILURE_CODES.NOT_ATTEMPTED
+			});
+			return;
+		}
+		const outcome = r.upsertedId !== void 0 && r.upsertedId !== null ? "inserted" : r.modifiedCount > 0 ? "updated" : "unchanged";
+		results.push({
+			index: op.index,
+			key: op.key,
+			outcome
+		});
+	});
+	return results;
+}
+//#endregion
 //#region src/query/AggregationBuilder.ts
 /**
 * Normalize SortSpec to MongoDB's strict format (1 | -1)
@@ -2094,7 +2288,7 @@ const HOOK_PRIORITY$1 = HOOK_PRIORITY;
 */
 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.`);
+	warn(`[mongokit] countStrategy 'capped' is not supported by ${where} — counting exactly. Group counts are exact here: a bounded group count would need its own estimate flag. Use getAll()/aggregatePaginate() where a bounded count matters.`);
 	return "exact";
 }
 var Repository = class extends RepositoryBase {
@@ -2160,6 +2354,8 @@ var Repository = class extends RepositoryBase {
 	* {@link ID_ADDRESSED_OPERATIONS}.
 	*/
 	_guardIdAddressed = false;
+	/** This repository's own `queryDefaults` / `aggregateDefaults` (deployment ones fill the gaps). */
+	_queryDefaults;
 	constructor(Model, plugins = [], paginationConfig = {}, options = {}) {
 		super({
 			name: Model.modelName,
@@ -2173,6 +2369,11 @@ var Repository = class extends RepositoryBase {
 			warn(m);
 		});
 		this.Model = Model;
+		markGoverned(Model);
+		this._queryDefaults = {
+			query: options.queryDefaults,
+			aggregate: options.aggregateDefaults
+		};
 		this._capabilitiesOverride = options.capabilities;
 		this.model = Model.modelName;
 		this._pagination = new PaginationEngine(Model, paginationConfig);
@@ -2417,6 +2618,31 @@ var Repository = class extends RepositoryBase {
 	* `_buildContext` inputs), so every op routed through `_runOp` — and the
 	* inline-try methods that call this directly — honors them uniformly.
 	*/
+	/** One command's time bound and concerns: per call, then this repository, then the deployment. */
+	_opts(kind, perCall) {
+		return resolveQueryOptions(kind, perCall, this._queryDefaults);
+	}
+	/** How an IR request runs: per-call hints, then this repository's and the deployment's defaults. */
+	_aggRun(req, context) {
+		return {
+			session: context.session,
+			queryOptions: this._opts("aggregate", {
+				...context,
+				maxTimeMS: req.executionHints?.maxTimeMs ?? context.maxTimeMS,
+				allowDiskUse: req.executionHints?.allowDiskUse ?? context.allowDiskUse
+			}),
+			finalize: (stages) => this._scopeJoins(stages, context)
+		};
+	}
+	/** Scope every join in `pipeline` under its owning collection's policy (see `join-scope.ts`). */
+	_scopeJoins(pipeline, context) {
+		return scopeJoins(pipeline, {
+			connection: this.Model.db,
+			context,
+			operation: context.operation,
+			unscopedJoins: context.unscopedJoins
+		});
+	}
 	_withResilience(context, fn) {
 		const signal = context.signal;
 		const retryPolicy = context.retryPolicy;
@@ -2431,7 +2657,10 @@ var Repository = class extends RepositoryBase {
 			data,
 			...options
 		});
-		return this._runOp("create", context, () => create(this.Model, context.data || data, options));
+		return this._runOp("create", context, () => create(this.Model, context.data || data, {
+			...options,
+			queryOptions: this._opts("write", context)
+		}));
 	}
 	/**
 	* Create multiple documents
@@ -2441,7 +2670,10 @@ var Repository = class extends RepositoryBase {
 			dataArray,
 			...options
 		});
-		return this._runOp("createMany", context, () => createMany(this.Model, context.dataArray || dataArray, options));
+		return this._runOp("createMany", context, () => createMany(this.Model, context.dataArray || dataArray, {
+			...options,
+			queryOptions: this._opts("write", context)
+		}));
 	}
 	/**
 	* Get document by ID
@@ -2469,7 +2701,10 @@ var Repository = class extends RepositoryBase {
 					const result = await this._withResilience(context, () => getByQuery(this.Model, {
 						[effectiveIdField]: id,
 						...context.query || {}
-					}, context));
+					}, {
+						...context,
+						queryOptions: this._opts("read", context)
+					}));
 					await this._emitHook("after:getById", {
 						context,
 						result
@@ -2486,7 +2721,10 @@ var Repository = class extends RepositoryBase {
 					});
 					return null;
 				}
-				const result = await this._withResilience(context, () => getById(this.Model, id, context));
+				const result = await this._withResilience(context, () => getById(this.Model, id, {
+					...context,
+					queryOptions: this._opts("read", context)
+				}));
 				if (!result && wantsThrow) throw createError(404, "Document not found");
 				await this._emitHook("after:getById", {
 					context,
@@ -2502,39 +2740,21 @@ var Repository = class extends RepositoryBase {
 			}
 		});
 	}
-	/**
-	* Batch point-read — the `$in` counterpart to {@link getById}. Fetches every
-	* doc whose id (the repo's `idField`, default `_id`) is in `ids` in ONE query,
-	* routed through `findAll` so tenant + soft-delete scoping and hooks apply
-	* exactly as a single read would. Returns a Map keyed by the stringified id;
-	* ids are de-duplicated and ids with no matching doc are simply absent (no
-	* throw — mirrors `getById(..., { throwOnNotFound: false })`). Structurally
-	* INVALID ids (wrong ObjectId shape, non-numeric for a Number id field, ...)
-	* are dropped the same way — an id that cannot exist in the collection is
-	* unambiguously a miss, and one malformed id must never poison the rest of
-	* the batch. Lean by default (findAll semantics) — pass `{ lean: false }`
-	* for hydrated docs.
-	*
-	* The N+1 killer for hosts that resolve many ids in one tick (order-line
-	* snapshotting, availability matrices, dashboard row enrichment):
-	*
-	* @example
-	* const byId = await repo.getByIds(offerIds, ctx);
-	* const doc = byId.get(offerId); // O(1); undefined if not found
-	*
-	* Sizing: there is no library-imposed cap — the bounds are MongoDB's (the
-	* `$in` array must fit the 16 MB query document; `$in` on an indexed field
-	* is n point-lookups). Keep batches ≤ ~10k ids per call and chunk beyond
-	* that. Don't exclude the id field via `select` — result keys derive from
-	* it.
-	*/
 	async getByIds(ids, options = {}) {
+		const { chunkSize = DEFAULT_ID_CHUNK, concurrency = 4, preserveOrder, ...readOptions } = options;
+		if (!Number.isInteger(concurrency) || concurrency < 1) throw new TypeError(`getByIds: concurrency must be a positive integer, got ${String(concurrency)}`);
 		const field = options.idField ?? this.idField;
 		const idType = getSchemaIdType(this.Model.schema, field);
 		const unique = [...new Set(ids.map((id) => String(id)))].filter((id) => isValidIdForType(id, idType));
-		if (unique.length === 0) return /* @__PURE__ */ new Map();
-		const docs = await this.findAll({ [field]: { $in: unique } }, options);
-		return new Map(docs.map((d) => [String(d[field]), d]));
+		const byId = /* @__PURE__ */ new Map();
+		const chunks = [...idChunks(unique, chunkSize)];
+		const load = async (chunk) => {
+			const docs = await this.findAll({ [field]: { $in: chunk } }, readOptions);
+			for (const d of docs) byId.set(String(d[field]), d);
+		};
+		if (readOptions.session) for (const chunk of chunks) await load(chunk);
+		else for (let i = 0; i < chunks.length; i += concurrency) await Promise.all(chunks.slice(i, i + concurrency).map(load));
+		return preserveOrder ? ids.map((id) => byId.get(String(id))) : byId;
 	}
 	/**
 	* Get single document by query
@@ -2556,7 +2776,10 @@ var Repository = class extends RepositoryBase {
 			return cachedResult;
 		}
 		const finalQuery = context.query || query;
-		return this._runOp("getByQuery", context, () => getByQuery(this.Model, finalQuery, context));
+		return this._runOp("getByQuery", context, () => getByQuery(this.Model, finalQuery, {
+			...context,
+			queryOptions: this._opts("read", context)
+		}));
 	}
 	/**
 	* Get single document by arbitrary filter.
@@ -2585,7 +2808,10 @@ var Repository = class extends RepositoryBase {
 			}
 			const finalQuery = context.query || query;
 			try {
-				const result = await this._withResilience(context, () => getByQuery(this.Model, finalQuery, context));
+				const result = await this._withResilience(context, () => getByQuery(this.Model, finalQuery, {
+					...context,
+					queryOptions: this._opts("read", context)
+				}));
 				await this._emitHook("after:getOne", {
 					context,
 					result
@@ -2623,13 +2849,68 @@ var Repository = class extends RepositoryBase {
 			if (options.populate || context.populate) query.populate(this._parsePopulate(context.populate || options.populate));
 			if (context.lean ?? options.lean ?? true) query.lean();
 			if (options.session) query.session(options.session);
-			if (options.readPreference) query.read(options.readPreference);
+			applyToQuery(query, this._opts("read", context));
 			const limitSpec = context.limit ?? options.limit;
 			if (typeof limitSpec === "number" && limitSpec > 0) query.limit(limitSpec);
 			return await query.exec();
 		});
 	}
 	/**
+	* The keyset cursor `getAll({ sort, filters, mode: 'keyset' })` would mint for `row`, under the
+	* same policy scope, so a page resumes AFTER it. For composing keyset walks (repo-core
+	* `mergeKeysetPages` via `keysetSource`), where the last CONSUMED row is not a page's last row.
+	*/
+	async keysetCursor(row, options) {
+		if (typeof row !== "object" || row === null || !("_id" in row)) throw createError(400, "keysetCursor: the row must be a document carrying _id");
+		const { sort, filters = {}, collation, ...rest } = options;
+		const scoped = (await this._buildContext("getAll", {
+			filters,
+			sort,
+			...rest
+		})).filters ?? filters;
+		const cfg = this._pagination.config;
+		const normalized = validateKeysetSort(this._parseSort(sort), cfg.strictKeysetSortFields);
+		return encodeCursor(Object.fromEntries(Object.entries(row)), getPrimaryField(normalized), normalized, cfg.cursorVersion, cursorScope(this.Model.collection.collectionName, scoped, collation), cfg.cursorSecret);
+	}
+	/**
+	* Resumable keyset batches over `_id`: each batch is ONE bounded `find` (no long-lived server
+	* cursor, so no cursor timeout and no CSOT lifetime budget), memory is one batch, and every
+	* batch carries a `checkpoint`. Pass a checkpoint back as `after` to resume: rows written
+	* behind it are not revisited, rows ahead of it are reached. A checkpoint is bound to the
+	* collection, the post-policy filter (tenant included) and is refused elsewhere.
+	*/
+	async *iterate(filter = {}, options = {}) {
+		const { after, batchSize = 500, select, ...rest } = options;
+		if (!Number.isInteger(batchSize) || batchSize < 1) throw createError(400, `iterate: batchSize must be a positive integer, got ${String(batchSize)}`);
+		const context = await this._buildContext("iterate", {
+			query: filter,
+			...rest
+		});
+		const scoped = context.query ?? filter;
+		const sort = { _id: 1 };
+		const scope = cursorScope(this.Model.collection.collectionName, scoped, void 0);
+		const cfg = this._pagination.config;
+		let position = after ? resolveCursorFilter(after, sort, cfg.cursorVersion, scoped, cfg.minCursorVersion, sort, scope, cfg.cursorSecret) : scoped;
+		const opts = this._opts("read", context);
+		for (;;) {
+			const query = this.Model.find(position).sort(sort).limit(batchSize).lean();
+			if (select) query.select(select);
+			if (context.session) query.session(context.session);
+			applyToQuery(query, opts);
+			const docs = await this._withResilience(context, () => query.exec());
+			if (docs.length === 0) return;
+			const last = docs[docs.length - 1];
+			if (last._id === void 0) throw createError(400, "iterate: the checkpoint needs _id; do not exclude it with select");
+			const checkpoint = encodeCursor(last, "_id", sort, cfg.cursorVersion, scope, cfg.cursorSecret);
+			yield {
+				docs,
+				checkpoint
+			};
+			if (docs.length < batchSize) return;
+			position = resolveCursorFilter(checkpoint, sort, cfg.cursorVersion, scoped, cfg.minCursorVersion, sort, scope, cfg.cursorSecret);
+		}
+	}
+	/**
 	* Streaming reads — async iterator over data, suitable for migrations,
 	* backfills, schema audits, and any once-a-quarter "touch every row"
 	* job. Goes through the standard `before:cursor` hook pipeline so
@@ -2670,7 +2951,9 @@ var Repository = class extends RepositoryBase {
 		if (options.batchSize) query.batchSize(options.batchSize);
 		if (context.lean ?? options.lean ?? true) query.lean();
 		if (options.session) query.session(options.session);
-		if (options.readPreference) query.read(options.readPreference);
+		const cursorOpts = this._opts("read", context);
+		applyToQuery(query, cursorOpts);
+		applyCursorTimeoutMode(query, cursorOpts, this.Model.db);
 		const stream = query.cursor();
 		let yieldedCount = 0;
 		try {
@@ -2952,7 +3235,12 @@ var Repository = class extends RepositoryBase {
 			lean: context.lean ?? options.lean ?? true,
 			session: options.session,
 			hint: context.hint ?? params.hint,
-			maxTimeMS: context.maxTimeMS ?? params.maxTimeMS,
+			queryOptions: this._opts("read", {
+				...context,
+				maxTimeMS: context.maxTimeMS ?? params.maxTimeMS,
+				readPreference: context.readPreference ?? options.readPreference ?? params.readPreference,
+				session: options.session
+			}),
 			countLimit: context.countLimit ?? params.countLimit,
 			readPreference: context.readPreference ?? options.readPreference ?? params.readPreference,
 			collation: context.collation ?? params.collation
@@ -3034,7 +3322,10 @@ var Repository = class extends RepositoryBase {
 			query,
 			...options
 		});
-		return this._runOp("count", context, () => count(this.Model, context.query || query, options));
+		return this._runOp("count", context, () => count(this.Model, context.query || query, {
+			session: options.session,
+			queryOptions: this._opts("read", context)
+		}));
 	}
 	/**
 	* Check if document exists
@@ -3045,7 +3336,10 @@ var Repository = class extends RepositoryBase {
 			query,
 			...options
 		});
-		return this._runOp("exists", context, () => exists(this.Model, context.query || query, options));
+		return this._runOp("exists", context, () => exists(this.Model, context.query || query, {
+			session: options.session,
+			queryOptions: this._opts("read", context)
+		}));
 	}
 	/**
 	* Update a document by id and return the post-update doc.
@@ -3211,7 +3505,8 @@ var Repository = class extends RepositoryBase {
 						casUpdate,
 						{
 							...context,
-							throwOnNotFound: false
+							throwOnNotFound: false,
+							queryOptions: this._opts("findAndModify", context)
 						}
 					));
 					if (!result) {
@@ -3235,8 +3530,14 @@ var Repository = class extends RepositoryBase {
 				} else if (effectiveIdField !== "_id") result = await this._withResilience(context, () => updateByQuery(this.Model, {
 					[effectiveIdField]: id,
 					...context.query || {}
-				}, context.data || data, context));
-				else result = await this._withResilience(context, () => update(this.Model, id, context.data || data, context));
+				}, context.data || data, {
+					...context,
+					queryOptions: this._opts("findAndModify", context)
+				}));
+				else result = await this._withResilience(context, () => update(this.Model, id, context.data || data, {
+					...context,
+					queryOptions: this._opts("findAndModify", context)
+				}));
 				if (!result && wantsThrow) throw createError(404, "Document not found");
 				await this._emitHook("after:update", {
 					context,
@@ -3296,7 +3597,8 @@ var Repository = class extends RepositoryBase {
 				sort: options.sort,
 				returnDocument: options.returnDocument ?? "after",
 				upsert: options.upsert ?? false,
-				session: options.session
+				session: options.session,
+				queryOptions: this._opts("findAndModify", context)
 			});
 		});
 	}
@@ -3525,7 +3827,8 @@ var Repository = class extends RepositoryBase {
 			return await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
 				returnDocument: "after",
 				upsert: options.upsert ?? false,
-				session: options.session
+				session: options.session,
+				queryOptions: this._opts("findAndModify", context)
 			});
 		});
 	}
@@ -3758,7 +4061,8 @@ var Repository = class extends RepositoryBase {
 			return await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
 				returnDocument: "after",
 				upsert: false,
-				session: options.session
+				session: options.session,
+				queryOptions: this._opts("findAndModify", context)
 			});
 		});
 	}
@@ -3820,9 +4124,13 @@ var Repository = class extends RepositoryBase {
 					[effectiveIdField]: id,
 					...context.query || {}
 				} : void 0;
-				const result = await this._withResilience(context, () => deleteQuery ? deleteByQuery(this.Model, deleteQuery, { session: options.session }) : deleteById(this.Model, id, {
+				const result = await this._withResilience(context, () => deleteQuery ? deleteByQuery(this.Model, deleteQuery, {
 					session: options.session,
-					query: context.query
+					queryOptions: this._opts("findAndModify", context)
+				}) : deleteById(this.Model, id, {
+					session: options.session,
+					query: context.query,
+					queryOptions: this._opts("findAndModify", context)
 				}));
 				if (!result && wantsThrow) throw createError(404, "Document not found");
 				await this._emitHook("after:delete", {
@@ -3870,11 +4178,13 @@ var Repository = class extends RepositoryBase {
 			if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "updateMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass updates.");
 			if (Array.isArray(normalizedData) && options.updatePipeline !== true) throw createError(400, "Update pipelines (array updates) are disabled by default; pass `{ updatePipeline: true }` to explicitly allow pipeline-style updates.");
 			const finalData = context.data || normalizedData;
-			return await this.Model.updateMany(finalQuery, finalData, {
+			const updateQuery = this.Model.updateMany(finalQuery, finalData, {
 				runValidators: true,
 				session: options.session,
 				...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-			}).exec();
+			});
+			applyToQuery(updateQuery, this._opts("write", context));
+			return await updateQuery.exec();
 		});
 	}
 	/**
@@ -3916,7 +4226,11 @@ var Repository = class extends RepositoryBase {
 				}
 				const finalQuery = context.query || filter;
 				if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "deleteMany requires a non-empty query filter after policy hooks.");
-				const result = await this._withResilience(context, () => this.Model.deleteMany(finalQuery, { session: options.session }).exec());
+				const result = await this._withResilience(context, () => (() => {
+					const q = this.Model.deleteMany(finalQuery, { session: options.session });
+					applyToQuery(q, this._opts("write", context));
+					return q.exec();
+				})());
 				await this._emitHook("after:deleteMany", {
 					context,
 					result
@@ -3979,6 +4293,70 @@ var Repository = class extends RepositoryBase {
 		return runChunkedArchive(options, sink, port);
 	}
 	/**
+	* Many keyed upserts in ONE command with an exact per-row outcome (repo-core `bulkUpsert` IR).
+	* Sub-ops pass through the `before:bulkUpsert` policy hooks (tenant, soft-delete) like bulkWrite
+	* sub-ops. Refused unless a unique index is pinned by the key plus the policy scope. Needs
+	* MongoDB 8.0 (client bulkWrite with verbose results).
+	*/
+	async bulkUpsert(rows, options) {
+		const invalid = bulkUpsertOptionsError(options);
+		if (invalid) throw createError(400, `[mongokit] bulkUpsert: ${invalid}`, { code: BULK_UPSERT_ERROR_CODES.INVALID_OPTIONS });
+		const { key, set, inc = [], setOnInsert = [], ordered = false, ...rest } = options;
+		const { planned, refused } = planUpserts(rows, key, {
+			set,
+			inc,
+			setOnInsert
+		});
+		const operations = planned.map((p) => ({ updateOne: {
+			filter: p.filter,
+			update: p.update,
+			upsert: true
+		} }));
+		const context = await this._buildContext("bulkUpsert", {
+			...rest,
+			operations
+		});
+		const scoped = context.operations ?? operations;
+		const filterFields = Object.keys(scoped[0]?.updateOne.filter ?? Object.fromEntries(key.map((k) => [k, 1])));
+		if (!keyIsUnique(this.Model, filterFields)) throw createError(400, `[mongokit] bulkUpsert on '${this.model}': no unique index is pinned by (${filterFields.join(", ")}), so one key could match several rows`, {
+			code: BULK_UPSERT_ERROR_CODES.KEY_NOT_UNIQUE,
+			meta: {
+				key,
+				filterFields
+			}
+		});
+		planned.forEach((p, i) => {
+			const filter = scoped[i]?.updateOne.filter ?? p.filter;
+			for (const field of Object.keys(filter)) {
+				if (key.includes(field)) continue;
+				for (const fields of Object.values(p.update)) {
+					if (!(field in fields)) continue;
+					if (String(fields[field]) !== String(filter[field])) throw createError(400, `[mongokit] bulkUpsert: '${field}' in row ${p.index} does not match the resolved tenant scope`, {
+						code: BULK_UPSERT_ERROR_CODES.INVALID_OPTIONS,
+						meta: {
+							field,
+							index: p.index
+						}
+					});
+					delete fields[field];
+				}
+			}
+		});
+		return this._runOp("bulkUpsert", context, async () => {
+			const writeOpts = this._opts("write", context);
+			const sent = await executeUpserts(this.Model, planned.map((p, i) => ({
+				...p,
+				filter: scoped[i]?.updateOne.filter ?? p.filter
+			})), {
+				ordered,
+				session: context.session,
+				writeConcern: writeOpts.writeConcern,
+				timeoutMS: writeOpts.maxTimeMS
+			});
+			return summarizeBulkUpsert([...refused, ...sent].sort((a, b) => a.index - b.index));
+		});
+	}
+	/**
 	* Kit-native aggregation pipeline — takes a MongoDB stage array and
 	* returns the raw pipeline output. Use this for `$lookup`, `$unwind`,
 	* `$facet`, `$graphLookup`, and any other mongo-specific power
@@ -4012,15 +4390,10 @@ var Repository = class extends RepositoryBase {
 		const maxStages = options.maxPipelineStages;
 		if (maxStages && pipeline.length > maxStages) throw createError(400, `Aggregation pipeline exceeds maximum allowed stages (${pipeline.length} > ${maxStages})`);
 		return this._runOp("aggregatePipeline", context, async () => {
-			const finalPipeline = [...pipeline];
-			if (context.query && Object.keys(context.query).length > 0) finalPipeline.unshift({ $match: context.query });
-			const aggregation = this.Model.aggregate(finalPipeline);
+			const scoped = context.query && Object.keys(context.query).length > 0 ? [{ $match: context.query }, ...pipeline] : pipeline;
+			const aggregation = this.Model.aggregate(this._scopeJoins(scoped, context));
 			if (options.session) aggregation.session(options.session);
-			if (options.allowDiskUse) aggregation.allowDiskUse(true);
-			if (options.readPreference) aggregation.read(options.readPreference);
-			if (options.maxTimeMS) aggregation.option({ maxTimeMS: options.maxTimeMS });
-			if (options.comment) aggregation.option({ comment: options.comment });
-			if (options.readConcern) aggregation.option({ readConcern: options.readConcern });
+			applyToAggregate(aggregation, this._opts("aggregate", context));
 			if (options.collation) aggregation.collation(options.collation);
 			return await aggregation.exec();
 		});
@@ -4043,7 +4416,8 @@ var Repository = class extends RepositoryBase {
 		if (context.filters && Object.keys(context.filters).length > 0) finalPipeline.unshift({ $match: context.filters });
 		const aggOptions = {
 			...context,
-			pipeline: finalPipeline
+			pipeline: this._scopeJoins(finalPipeline, context),
+			queryOptions: this._opts("aggregate", context)
 		};
 		return this._runOp("aggregatePipelinePaginate", context, () => this._pagination.aggregatePaginate(aggOptions));
 	}
@@ -4074,7 +4448,7 @@ var Repository = class extends RepositoryBase {
 			aggRequest: req,
 			...options
 		});
-		const cached = this._cachedValue(context);
+		const cached = options.explain ? void 0 : this._cachedValue(context);
 		if (cached !== void 0) {
 			await this._emitHook("after:aggregate", {
 				context,
@@ -4085,7 +4459,14 @@ var Repository = class extends RepositoryBase {
 		}
 		return this._runOp("aggregate", context, async () => {
 			const finalReq = this._injectPolicyScopeIntoAgg(req, context);
-			return { rows: await executeAgg(this.Model, finalReq, { session: context.session }) };
+			const run = this._aggRun(finalReq, context);
+			const rows = await executeAgg(this.Model, finalReq, run);
+			if (!options.explain) return { rows };
+			const { pipeline } = buildAggPipeline(finalReq, this.Model.schema);
+			return {
+				rows,
+				plan: await prepareAgg(this.Model, pipeline, finalReq, run).explain(options.explain)
+			};
 		});
 	}
 	/**
@@ -4132,7 +4513,7 @@ var Repository = class extends RepositoryBase {
 			...options
 		});
 		const limit = Math.max(1, Math.min(req.limit ?? 20, 1e3));
-		const session = context.session;
+		context.session;
 		const useKeyset = isKeysetMode(req);
 		const cachedEnvelope = this._cachedValue(context);
 		if (cachedEnvelope !== void 0) {
@@ -4145,8 +4526,12 @@ var Repository = class extends RepositoryBase {
 		}
 		return this._composeMiddleware("aggregatePaginate", context, async () => {
 			try {
-				const finalReq = this._injectPolicyScopeIntoAgg(req, context);
-				const result = await this._executeAggregatePaginate(finalReq, useKeyset, limit, session);
+				const scopedReq = this._injectPolicyScopeIntoAgg(req, context);
+				const finalReq = scopedReq.sort ? {
+					...scopedReq,
+					sort: withGroupTiebreak(scopedReq.sort, normalizeGroupBy(scopedReq.groupBy))
+				} : scopedReq;
+				const result = await this._executeAggregatePaginate(finalReq, useKeyset, limit, this._aggRun(finalReq, context));
 				await this._emitHook("after:aggregatePaginate", {
 					context,
 					result
@@ -4170,7 +4555,7 @@ var Repository = class extends RepositoryBase {
 	* built by the outer wrapper matches the request the executor
 	* sees — no cross-tenant cache poisoning.
 	*/
-	async _executeAggregatePaginate(finalReq, useKeyset, limit, session) {
+	async _executeAggregatePaginate(finalReq, useKeyset, limit, run) {
 		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, this._pagination.config.cursorSecret) : void 0;
@@ -4181,10 +4566,7 @@ var Repository = class extends RepositoryBase {
 			if (keysetMatch) tailStages.push(keysetMatch);
 			tailStages.push({ $sort: finalReq.sort });
 			tailStages.push({ $limit: limit + 1 });
-			const aggregation = this.Model.aggregate([...headStages, ...tailStages]);
-			if (session) aggregation.session(session);
-			applyExecutionHints(aggregation, finalReq.executionHints);
-			const peeked = await aggregation.exec();
+			const peeked = await runAgg(this.Model, [...headStages, ...tailStages], finalReq, run);
 			const hasMore = peeked.length > limit;
 			const data = hasMore ? peeked.slice(0, limit) : peeked;
 			return {
@@ -4198,12 +4580,13 @@ var Repository = class extends RepositoryBase {
 		const page = Math.max(1, finalReq.page ?? 1);
 		const countStrategy = downgradeCappedCount(finalReq.countStrategy ?? this._pagination.config.defaultCountStrategy, "aggregatePaginateIr");
 		const offset = (page - 1) * limit;
+		assertOffsetWithinCap(offset, this._pagination.config.maxOffset);
 		if (countStrategy === "none") {
 			const peek = await executeAgg(this.Model, {
 				...finalReq,
 				limit: limit + 1,
 				offset
-			}, session ? { session } : {});
+			}, run);
 			const hasNext = peek.length > limit;
 			return {
 				method: "offset",
@@ -4220,7 +4603,7 @@ var Repository = class extends RepositoryBase {
 			...finalReq,
 			limit,
 			offset
-		}, session ? { session } : {}), countAggGroups(this.Model, finalReq, session ? { session } : {})]);
+		}, run), countAggGroups(this.Model, finalReq, run)]);
 		return {
 			method: "offset",
 			data,
@@ -4278,10 +4661,9 @@ var Repository = class extends RepositoryBase {
 		});
 		return this._runOp("distinct", context, () => {
 			const finalQuery = context.query || query;
-			const readPreference = context.readPreference ?? options.readPreference;
 			return distinct(this.Model, field, finalQuery, {
 				session: options.session,
-				readPreference
+				queryOptions: this._opts("read", context)
 			});
 		});
 	}
@@ -4319,24 +4701,24 @@ var Repository = class extends RepositoryBase {
 				const filters = context.filters ?? options.filters;
 				const sort = context.sort ?? options.sort;
 				const limit = context.limit ?? options.limit ?? this._pagination.config.defaultLimit ?? 20;
-				const readPref = context.readPreference ?? options.readPreference;
 				const session = context.session ?? options.session;
 				const collation = context.collation ?? options.collation;
 				const after = context.after ?? options.after;
 				const pageFromContext = context.page ?? options.page;
 				const isKeyset = !!after || !pageFromContext && !!sort;
-				const countStrategy = downgradeCappedCount(context.countStrategy ?? options.countStrategy ?? this._pagination.config.defaultCountStrategy, "lookupPopulate");
+				const countStrategy = context.countStrategy ?? options.countStrategy ?? this._pagination.config.defaultCountStrategy;
 				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-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 { validateKeysetSort } = await import("./PaginationEngine-CfT2Cxkj.mjs").then((n) => n.r);
+					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-CfT2Cxkj.mjs").then((n) => n.a);
+					const { getPrimaryField } = await import("./PaginationEngine-CfT2Cxkj.mjs").then((n) => n.r);
 					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, normalizedSort, this._pagination.config.cursorSecret) : { ...filters || {} };
+					const scope = cursorScope(this.Model.collection.collectionName, filters || {}, collation);
+					const matchFilters = after ? resolveCursorFilter(after, normalizedSort, cursorVersion, { ...filters || {} }, minCursorVersion, normalizedSort, scope, 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;
@@ -4347,9 +4729,9 @@ var Repository = class extends RepositoryBase {
 					pipeline.push({ $sort: normalizedSort });
 					pipeline.push({ $limit: limit + 1 });
 					appendLookupStages$2(pipeline);
-					const aggregation = this.Model.aggregate(pipeline).session(session || null);
+					const aggregation = this.Model.aggregate(this._scopeJoins(pipeline, context)).session(session || null);
 					if (collation) aggregation.collation(collation);
-					if (readPref) aggregation.read(readPref);
+					applyToAggregate(aggregation, this._opts("aggregate", context));
 					const data = await aggregation;
 					const hasMore = data.length > limit;
 					if (hasMore) data.pop();
@@ -4359,7 +4741,7 @@ var Repository = class extends RepositoryBase {
 						data,
 						limit,
 						hasMore,
-						next: hasMore && data.length > 0 ? encodeCursor(data[data.length - 1], primaryField, normalizedSort, cursorVersion, this._pagination.config.cursorSecret) : null
+						next: hasMore && data.length > 0 ? encodeCursor(data[data.length - 1], primaryField, normalizedSort, cursorVersion, scope, this._pagination.config.cursorSecret) : null
 					};
 					await this._emitHook("after:lookupPopulate", {
 						context,
@@ -4369,61 +4751,69 @@ var Repository = class extends RepositoryBase {
 				}
 				const page = pageFromContext ?? 1;
 				const skip = (page - 1) * limit;
-				if (skip > 1e4) warn(`[mongokit] Large offset (${skip}) in lookupPopulate. Consider using keyset pagination: getAll({ sort, after, limit, lookups })`);
-				const dataPipeline = [];
-				if (filters && Object.keys(filters).length > 0) dataPipeline.push({ $match: filters });
-				if (sort) dataPipeline.push({ $sort: this._parseSort(sort) });
-				if (countStrategy === "none") {
-					dataPipeline.push({ $skip: skip }, { $limit: limit + 1 });
-					appendLookupStages$2(dataPipeline);
-					const aggregation = this.Model.aggregate(dataPipeline).session(session || null);
+				assertOffsetWithinCap(skip, this._pagination.config.maxOffset);
+				const match = filters && Object.keys(filters).length > 0 ? [{ $match: filters }] : [];
+				const dataPipeline = [...match];
+				if (sort) dataPipeline.push({ $sort: withIdTiebreak(this._parseSort(sort)) });
+				dataPipeline.push({ $skip: skip }, { $limit: limit + 1 });
+				appendLookupStages$2(dataPipeline);
+				const run = async (stages) => {
+					const aggregation = this.Model.aggregate(this._scopeJoins(stages, context)).session(session || null);
 					if (collation) aggregation.collation(collation);
-					if (readPref) aggregation.read(readPref);
-					const data = await aggregation;
-					const hasNext = data.length > limit;
-					if (hasNext) data.pop();
-					const result = {
-						method: "offset",
-						data,
-						page,
-						limit,
+					applyToAggregate(aggregation, this._opts("aggregate", context));
+					return aggregation.exec();
+				};
+				const ceiling = context.countLimit ?? options.countLimit ?? this._pagination.config.defaultCountLimit;
+				const bounded = countStrategy === "capped" || countStrategy === "cached";
+				const countOnce = async () => {
+					return (await run([
+						...match,
+						...bounded ? [{ $limit: ceiling }] : [],
+						{ $count: "total" }
+					]))[0]?.total ?? 0;
+				};
+				const runCount = async () => {
+					if (countStrategy === "none") return {
 						total: 0,
-						pages: 0,
-						hasNext,
-						hasPrev: page > 1
+						totalIsEstimate: true,
+						countedAt: null
+					};
+					if (countStrategy === "cached" && !session) {
+						const key = cursorScope(this.Model.collection.collectionName, [
+							filters ?? {},
+							ceiling,
+							"lookupPopulate"
+						], collation);
+						return {
+							...await this._pagination._countMemo().get({
+								key,
+								run: countOnce
+							}),
+							totalIsEstimate: true
+						};
+					}
+					const total = await countOnce();
+					return {
+						total,
+						totalIsEstimate: bounded && total >= ceiling,
+						countedAt: /* @__PURE__ */ new Date()
 					};
-					await this._emitHook("after:lookupPopulate", {
-						context,
-						result
-					});
-					return result;
-				}
-				dataPipeline.push({ $skip: skip }, { $limit: limit });
-				appendLookupStages$2(dataPipeline);
-				const countPipeline = [];
-				if (filters && Object.keys(filters).length > 0) countPipeline.push({ $match: filters });
-				countPipeline.push({ $count: "total" });
-				const pipeline = [{ $facet: {
-					metadata: countPipeline,
-					data: dataPipeline
-				} }];
-				const aggregation = this.Model.aggregate(pipeline).session(session || null);
-				if (collation) aggregation.collation(collation);
-				if (readPref) aggregation.read(readPref);
-				const facetResult = (await aggregation)[0] || {
-					metadata: [],
-					data: []
 				};
-				const total = facetResult.metadata[0]?.total || 0;
+				const [rows, counted] = session ? [await run(dataPipeline), await runCount()] : await Promise.all([run(dataPipeline), runCount()]);
+				const data = rows;
+				const hasNext = data.length > limit;
+				if (hasNext) data.pop();
 				const result = {
 					method: "offset",
-					data: facetResult.data || [],
+					data,
 					page,
 					limit,
-					total,
-					pages: calculateTotalPages(total, limit),
-					hasNext: page * limit < total,
-					hasPrev: page > 1
+					total: counted.total,
+					pages: countStrategy === "none" ? 0 : calculateTotalPages(counted.total, limit),
+					hasNext,
+					hasPrev: page > 1,
+					totalIsEstimate: counted.totalIsEstimate,
+					countedAt: counted.countedAt
 				};
 				await this._emitHook("after:lookupPopulate", {
 					context,
@@ -4839,8 +5229,14 @@ var Repository = class extends RepositoryBase {
 		if (Array.isArray(labels) && (labels.includes("TransientTransactionError") || labels.includes("UnknownTransactionCommitResult")) || typeof hasLabel === "function" && (hasLabel.call(error, "TransientTransactionError") || hasLabel.call(error, "UnknownTransactionCommitResult"))) return error;
 		if (error instanceof mongoose.mongo.MongoOperationTimeoutError) return error;
 		if (error instanceof mongoose.Error.ValidationError) {
-			const messages = Object.values(error.errors).map((err) => err.message);
-			return createError(400, `Validation Error: ${messages.join(", ")}`);
+			const errs = Object.values(error.errors);
+			const http = createError(400, `Validation Error: ${errs.map((e) => e.message).join(", ")}`);
+			http.validationErrors = errs.map((e) => ({
+				validator: e.kind ?? "mongoose",
+				error: e.message,
+				...e.path ? { path: e.path } : {}
+			}));
+			return http;
 		}
 		if (error instanceof mongoose.Error.CastError) return createError(400, `Invalid ${error.path}: ${error.value}`);
 		const duplicateErr = parseDuplicateKeyError(error);