@classytic/mongokit 3.39.0 → 3.40.0

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

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