@classytic/mongokit 3.39.0 → 3.40.1

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

@@ -1,12 +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 compileFilterToMongo, a as count, c as getByQuery, d as deleteById, f as deleteByQuery, g as LookupBuilder, h as distinct, l as getOrCreate, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, v as create, y as createMany } from "./update-c_01A0if.mjs";
+import { 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 { c as resolveCursorSecrets, l as verifySignature, s as attachSignature, t as PaginationEngine } from "./PaginationEngine-DQ7beTCR.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";
@@ -118,257 +121,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.
@@ -431,6 +193,11 @@ const OP_REGISTRY = {
 		mutates: true,
 		hasIdContext: false
 	},
+	bulkUpsert: {
+		policyKey: "operations",
+		mutates: true,
+		hasIdContext: false
+	},
 	getById: {
 		policyKey: "query",
 		mutates: false,
@@ -486,6 +253,11 @@ const OP_REGISTRY = {
 		mutates: false,
 		hasIdContext: false
 	},
+	iterate: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
 	watch: {
 		policyKey: "query",
 		mutates: false,
@@ -528,137 +300,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;
-}
-/**
-* 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…') }
-* ```
-*/
-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 isExpectedIndex(hint) {
+	return typeof hint === "object" && hint !== null && Array.isArray(hint.leadingKeys) && hint.leadingKeys.length > 0;
 }
-//#endregion
-//#region src/actions/aggregate-ir/normalize.ts
+const checked = /* @__PURE__ */ new WeakMap();
 /**
-* 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.
+* 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 validateMeasures$1(measures) {
-	validateMeasures(measures, "mongokit");
+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/dateBucket.ts
@@ -831,11 +498,192 @@ function compileFilterToMongoExpr(input) {
 	*/
 	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: \`where\` must be Filter IR (\`{ op, field, value }\`) or a MongoDB aggregation expression (\`{ \$eq: ['\$field', value] }\`), got ${keys.length === 0 ? "an empty object" : `an object keyed by ${keys.map((k) => `'${k}'`).join(", ")}`}. Query syntax such as \`{ field: { eq: value } }\` works in \`filter\` but not here — evaluated as an expression it is always TRUE, so the filter would silently match every row.`);
+		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) {
 		case "true": return true;
@@ -852,7 +700,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),
@@ -977,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);
@@ -1371,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) : {};
@@ -1392,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) => {
@@ -1406,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.
@@ -1507,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)
@@ -2092,242 +2154,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
@@ -2462,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 {
@@ -2528,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,
@@ -2541,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);
@@ -2785,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;
@@ -2799,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
@@ -2809,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
@@ -2837,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
@@ -2854,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,
@@ -2870,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
@@ -2924,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.
@@ -2953,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
@@ -2991,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
@@ -3038,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 {
@@ -3272,29 +3187,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,
@@ -3343,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
@@ -3425,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
@@ -3436,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.
@@ -3602,7 +3505,8 @@ var Repository = class extends RepositoryBase {
 						casUpdate,
 						{
 							...context,
-							throwOnNotFound: false
+							throwOnNotFound: false,
+							queryOptions: this._opts("findAndModify", context)
 						}
 					));
 					if (!result) {
@@ -3626,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,
@@ -3687,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)
 			});
 		});
 	}
@@ -3862,6 +3773,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("$"));
@@ -3911,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)
 			});
 		});
 	}
@@ -4144,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)
 			});
 		});
 	}
@@ -4206,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", {
@@ -4256,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();
 		});
 	}
 	/**
@@ -4302,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
@@ -4365,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
@@ -4398,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();
 		});
@@ -4429,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));
 	}
@@ -4460,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,
@@ -4471,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)
+			};
 		});
 	}
 	/**
@@ -4518,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) {
@@ -4531,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
@@ -4556,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;
@@ -4567,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 {
@@ -4584,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",
@@ -4606,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,
@@ -4664,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)
 			});
 		});
 	}
@@ -4705,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-DQ7beTCR.mjs").then((n) => n.n);
-					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-DQ7beTCR.mjs").then((n) => n.r);
-					const { getPrimaryField } = await import("./PaginationEngine-DQ7beTCR.mjs").then((n) => n.n);
+					const { 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;
@@ -4733,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();
@@ -4745,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,
@@ -4755,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,
@@ -4945,11 +4949,51 @@ var Repository = class extends RepositoryBase {
 	async _buildContext(operation, options) {
 		throwIfAborted(options.signal);
 		const normalized = this._normalizeFilterSlots(options);
-		const base = 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
@@ -5185,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);
@@ -5196,4 +5246,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 };