@classytic/mongokit 3.40.0 → 3.41.0

package/dist/testkit/index.d.mts

@@ -1,7 +1,44 @@
-import { r as Repository } from "../Repository-CR8Y9g2E.mjs";
-import { n as CreateRepositoryConfig } from "../create-repository-CAle1MSU.mjs";
+import { r as Repository } from "../Repository-pnLw1rG5.mjs";
+import { n as CreateRepositoryConfig } from "../create-repository-BUx9vfG9.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
+//#region src/testkit/query-plan.d.ts
+interface RecordedCommand {
+  name: string;
+  collection: string | undefined;
+  command: Record<string, unknown>;
+}
+/** Run `fn` and return every command it started on `connection` (in start order). */
+declare function recordCommands<T>(connection: Connection, fn: () => Promise<T>): Promise<{
+  result: T;
+  commands: RecordedCommand[];
+}>;
+interface QueryPlanOptions {
+  connection: Connection;
+  /** Plan stages that fail the gate. Default `['COLLSCAN', 'SORT']` (a scan, an unindexed sort). */
+  forbid?: readonly string[];
+  /** The examined collection must hold at least this many documents. */
+  minDocs: number;
+  /** Every index scan must lead with these keys (directly, or after one equality scope field). */
+  leadingKeys?: readonly string[];
+  /** Only gate commands on these collections (default: every plannable command). */
+  collections?: readonly string[];
+}
+interface PlannedCommand {
+  name: string;
+  collection: string;
+  stages: string[];
+  indexes: string[][];
+}
+/**
+ * Run `run`, explain every read it issued and throw on a forbidden stage, a wrong leading index,
+ * an undersized fixture, or no plannable command at all. Returns what each command used.
+ */
+declare function assertQueryPlan<T>(run: () => Promise<T>, options: QueryPlanOptions): Promise<{
+  result: T;
+  plans: PlannedCommand[];
+}>;
+//#endregion
 //#region src/testkit/index.d.ts
 interface MongoMemoryOptions {
   /**
@@ -132,4 +169,4 @@ interface MongoMemoryBackend {
  */
 declare function mongoMemoryBackend(options?: MongoMemoryOptions): MongoMemoryBackend;
 //#endregion
-export { CreateTestRepositoryOptions, MongoMemoryBackend, MongoMemoryHandle, MongoMemoryOptions, MongoTestContext, TestConnection, TestRepository, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, withMongoMemory };
+export { CreateTestRepositoryOptions, MongoMemoryBackend, MongoMemoryHandle, MongoMemoryOptions, MongoTestContext, type PlannedCommand, type QueryPlanOptions, type RecordedCommand, TestConnection, TestRepository, assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, recordCommands, withMongoMemory };

package/dist/testkit/index.mjs

@@ -1,5 +1,116 @@
-import { t as createRepository } from "../create-repository-BzBUMvd1.mjs";
+import { t as createRepository } from "../create-repository-Bg0H5rte.mjs";
 import { createConnection } from "mongoose";
+//#region src/testkit/query-plan.ts
+const PLANNABLE = /* @__PURE__ */ new Set([
+	"find",
+	"aggregate",
+	"count",
+	"distinct"
+]);
+/** Session/transport fields the server refuses inside an `explain`. */
+const STRIP = /* @__PURE__ */ new Set([
+	"lsid",
+	"txnNumber",
+	"autocommit",
+	"startTransaction",
+	"readConcern",
+	"maxTimeMS"
+]);
+function assertMonitored(connection) {
+	if (connection.getClient().options.monitorCommands !== true) throw new Error("[mongokit/testkit] the connection was not opened with { monitorCommands: true }: no command can be observed");
+}
+/** Run `fn` and return every command it started on `connection` (in start order). */
+async function recordCommands(connection, fn) {
+	assertMonitored(connection);
+	const client = connection.getClient();
+	const commands = [];
+	const listener = (event) => {
+		const target = event.command[event.commandName];
+		commands.push({
+			name: event.commandName,
+			collection: typeof target === "string" ? target : void 0,
+			command: event.command
+		});
+	};
+	client.on("commandStarted", listener);
+	try {
+		return {
+			result: await fn(),
+			commands
+		};
+	} finally {
+		client.off("commandStarted", listener);
+	}
+}
+function collectPlanNodes(node, out) {
+	if (Array.isArray(node)) {
+		for (const n of node) collectPlanNodes(n, out);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node;
+	if (typeof obj.stage === "string") out.push(obj);
+	for (const [key, value] of Object.entries(obj)) {
+		if (key === "rejectedPlans" || key === "allPlansExecution") continue;
+		collectPlanNodes(value, out);
+	}
+}
+function explainable(command) {
+	return Object.fromEntries(Object.entries(command).filter(([k]) => !k.startsWith("$") && !STRIP.has(k)));
+}
+/**
+* Run `run`, explain every read it issued and throw on a forbidden stage, a wrong leading index,
+* an undersized fixture, or no plannable command at all. Returns what each command used.
+*/
+async function assertQueryPlan(run, options) {
+	const forbid = options.forbid ?? ["COLLSCAN", "SORT"];
+	const { result, commands } = await recordCommands(options.connection, run);
+	const db = options.connection.db;
+	if (!db) throw new Error("[mongokit/testkit] connection has no db handle");
+	const plannable = commands.filter((c) => PLANNABLE.has(c.name) && c.collection !== void 0 && (!options.collections || options.collections.includes(c.collection)));
+	if (plannable.length === 0) throw new Error(`[mongokit/testkit] assertQueryPlan saw no plannable command (saw: ${commands.map((c) => c.name).join(", ") || "none"})`);
+	const plans = [];
+	const failures = [];
+	for (const c of plannable) {
+		const collection = c.collection;
+		const size = await db.collection(collection).countDocuments({});
+		if (size < options.minDocs) throw new Error(`[mongokit/testkit] '${collection}' holds ${size} documents, below minDocs ${options.minDocs}: the plan would not be representative`);
+		const explained = await db.command({
+			explain: explainable(c.command),
+			verbosity: "executionStats"
+		});
+		const nodes = [];
+		collectPlanNodes(explained.queryPlanner ?? explained.stages ?? explained, nodes);
+		const stages = nodes.map((n) => n.stage);
+		const indexes = nodes.filter((n) => n.keyPattern && typeof n.keyPattern === "object").map((n) => Object.keys(n.keyPattern));
+		plans.push({
+			name: c.name,
+			collection,
+			stages,
+			indexes
+		});
+		for (const stage of forbid) if (stages.includes(stage)) failures.push(`${c.name} on '${collection}': plan contains ${stage}`);
+		if (options.leadingKeys) {
+			const want = options.leadingKeys;
+			const leads = (key, at) => want.every((k, i) => key[at + i] === k);
+			if (indexes.length === 0) failures.push(`${c.name} on '${collection}': no index used, expected (${want.join(",")})`);
+			for (const key of indexes) if (!leads(key, 0) && !leads(key, 1)) failures.push(`${c.name} on '${collection}': index (${key.join(",")}) does not lead with (${want.join(",")})`);
+		}
+	}
+	if (failures.length > 0) {
+		const error = /* @__PURE__ */ new Error(`[mongokit/testkit] query plan gate failed:\n  ${failures.join("\n  ")}`);
+		Object.assign(error, {
+			code: "mongokit.testkit.query_plan",
+			plans
+		});
+		throw error;
+	}
+	return {
+		result,
+		plans
+	};
+}
+//#endregion
 //#region src/testkit/index.ts
 function idempotentStop(server) {
 	let stopped = false;
@@ -136,4 +247,4 @@ function mongoMemoryBackend(options = {}) {
 	} };
 }
 //#endregion
-export { clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, withMongoMemory };
+export { assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, recordCommands, withMongoMemory };

package/dist/{timestamp.plugin-DF0gJB6p.mjs → timestamp.plugin-DvZlnKEc.mjs}

@@ -1,5 +1,6 @@
-import { i as ALL_OPERATIONS, o as OP_REGISTRY, t as HOOK_PRIORITY } from "./Repository-BMgPSkqZ.mjs";
+import { i as ALL_OPERATIONS, o as OP_REGISTRY, t as HOOK_PRIORITY } from "./Repository-DlhPbXlG.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
+import { n as declareCollectionScope } from "./join-scope-DSAznE8E.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
 import { cachePlugin } from "@classytic/repo-core/cache";
@@ -1067,6 +1068,41 @@ function multiTenantPlugin(options = {}) {
 		name: "multi-tenant",
 		apply(repo) {
 			declareTenantContextKey(repo, contextKey);
+			/** The one tenant decision, shared by the hook and the join rule below. */
+			const decide = (context, op) => {
+				if (context.bypassTenant === true) return { bypass: "option" };
+				if (skipWhen?.(context, op) === true) return { bypass: "callback" };
+				let tenantId = context[contextKey];
+				if (!tenantId && resolveContext) tenantId = resolveContext();
+				return { tenantId };
+			};
+			const castTenant = (tenantId) => fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
+			const missingTenant = (op) => new Error([
+				`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'.`,
+				"",
+				"Three ways to provide it — pick the one that fits the call site:",
+				"",
+				`  1. Per-call:        repo.${op}(..., { ${contextKey}: '<id>' })`,
+				"  2. Ambient (ALS):   `createTenantContext()` + `resolveContext` —",
+				"                       wrap the request in `tenantContext.run({ tenantId }, fn)`,",
+				"                       then every repo call inside the closure inherits the",
+				"                       tenant with no options-bag plumbing. See",
+				"                       `createTenantContext` in @classytic/mongokit.",
+				"  3. Cross-tenant:    `bypassTenant: true` per-call (admin / migration /",
+				"                       support), or `skipWhen: adminBypass({...})` at plugin",
+				"                       construction for an always-on role-based bypass.",
+				"",
+				"Or set `required: false` if this collection is genuinely not tenant-scoped."
+			].join("\n"));
+			if (repo.Model) declareCollectionScope(repo.Model, (context, op) => {
+				const d = decide(context, op);
+				if ("bypass" in d) return void 0;
+				if (!d.tenantId) {
+					if (required) throw missingTenant(op);
+					return;
+				}
+				return { [tenantField]: castTenant(d.tenantId) };
+			}, { tenantField });
 			const allOps = [...ALL_OPERATIONS.map((op) => ({
 				op,
 				policyKey: OP_REGISTRY[op].policyKey
@@ -1075,41 +1111,21 @@ function multiTenantPlugin(options = {}) {
 				if (skipOperations.includes(op)) continue;
 				if (policyKey === "none") continue;
 				repo.on(`before:${op}`, (context) => {
-					const perCallBypass = context.bypassTenant === true;
-					const callbackBypass = !perCallBypass && skipWhen?.(context, op) === true;
-					if (perCallBypass || callbackBypass) {
+					const decision = decide(context, op);
+					if ("bypass" in decision) {
 						repo.emit("after:tenant-bypass", {
 							context,
 							operation: op,
-							reason: perCallBypass ? "option" : "callback"
+							reason: decision.bypass
 						});
 						return;
 					}
-					let tenantId = context[contextKey];
-					if (!tenantId && resolveContext) {
-						tenantId = resolveContext();
-						if (tenantId) context[contextKey] = tenantId;
-					}
+					const tenantId = decision.tenantId;
+					if (tenantId && !context[contextKey]) context[contextKey] = tenantId;
 					if (!tenantId && allowDataInjection && payloadHasTenantField(context, policyKey, tenantField)) return;
-					if (!tenantId && required) throw new Error([
-						`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'.`,
-						"",
-						"Three ways to provide it — pick the one that fits the call site:",
-						"",
-						`  1. Per-call:        repo.${op}(..., { ${contextKey}: '<id>' })`,
-						"  2. Ambient (ALS):   `createTenantContext()` + `resolveContext` —",
-						"                       wrap the request in `tenantContext.run({ tenantId }, fn)`,",
-						"                       then every repo call inside the closure inherits the",
-						"                       tenant with no options-bag plumbing. See",
-						"                       `createTenantContext` in @classytic/mongokit.",
-						"  3. Cross-tenant:    `bypassTenant: true` per-call (admin / migration /",
-						"                       support), or `skipWhen: adminBypass({...})` at plugin",
-						"                       construction for an always-on role-based bypass.",
-						"",
-						"Or set `required: false` if this collection is genuinely not tenant-scoped."
-					].join("\n"));
+					if (!tenantId && required) throw missingTenant(op);
 					if (!tenantId) return;
-					const castId = fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
+					const castId = castTenant(tenantId);
 					const assertTenantValue = (supplied, where) => {
 						if (onMismatch === "overwrite") return;
 						if (supplied === void 0 || supplied === null) return;
@@ -1318,6 +1334,7 @@ function softDeletePlugin(options = {}) {
 	return {
 		name: "softDelete",
 		apply(repo) {
+			if (repo.Model) declareCollectionScope(repo.Model, () => buildDeletedFilter(deletedField, filterMode, false));
 			try {
 				const schemaPaths = repo.Model.schema.paths;
 				if (!schemaPaths[deletedField]) warn(`[softDeletePlugin] Model '${repo.Model.modelName}' has no '${deletedField}' schema path. Soft-delete marks documents by \`$set\`-ing '${deletedField}', but Mongoose strict mode drops updates to undeclared paths — so delete() will SILENTLY no-op (documents are never soft-deleted). Declare it on the schema: { ${deletedField}: { type: Date, default: ${filterMode === "null" ? "null" : "undefined"} } }`);
@@ -1378,7 +1395,8 @@ function softDeletePlugin(options = {}) {
 			const SOFT_DELETE_SPECIAL = /* @__PURE__ */ new Set([
 				"updateMany",
 				"deleteMany",
-				"bulkWrite"
+				"bulkWrite",
+				"bulkUpsert"
 			]);
 			for (const op of ALL_OPERATIONS) {
 				if (SOFT_DELETE_SPECIAL.has(op)) continue;
@@ -1409,7 +1427,7 @@ function softDeletePlugin(options = {}) {
 			* `deleteMode: 'hard'` still bypasses, exactly as the single-doc path does — a purge
 			* is a deliberate physical delete, and it reaches the driver directly anyway.
 			*/
-			repo.on("before:bulkWrite", (context) => {
+			const scopeSubOps = (context) => {
 				if (options.soft === false || context.deleteMode === "hard") return;
 				const ops = context.operations;
 				if (!Array.isArray(ops)) return;
@@ -1440,7 +1458,8 @@ function softDeletePlugin(options = {}) {
 						delete subOp[key];
 					}
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
+			};
+			for (const op of ["bulkWrite", "bulkUpsert"]) repo.on(`before:${op}`, scopeSubOps, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:deleteMany", async (context) => {
 				if (context.deleteMode === "hard") return;
 				if (options.soft !== false) {

package/dist/{to-plain-k7SjNlSS.d.mts → to-plain-CjgEInWV.d.mts}

@@ -1,5 +1,5 @@
-import { v as UserContext } from "./repository-odl03582.mjs";
-import { r as FieldPreset } from "./plugin-options-Zk46lD6F.mjs";
+import { v as UserContext } from "./repository-DNHfjAZX.mjs";
+import { r as FieldPreset } from "./plugin-options-CRhIvSzx.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CacheAdapter } from "@classytic/repo-core/cache";
 import { HttpError } from "@classytic/repo-core/errors";

package/dist/{transaction-B5L9glO0.mjs → transaction-DmiB4k2P.mjs}

@@ -1,3 +1,7 @@
+import { t as createError } from "./error-BuByZwKU.mjs";
+import { d as setTransactionDeadline } from "./query-defaults-BxUcSOoF.mjs";
+import mongoose from "mongoose";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 //#region src/capabilities.ts
 /**
 * Read the provenance of a capability descriptor's `transactions` flag.
@@ -52,7 +56,13 @@ const MONGOKIT_CAPABILITIES = Object.freeze({
 	lean: true,
 	lookupPopulate: true,
 	lookupCoerce: true,
-	streaming: true
+	streaming: true,
+	getByIdsOrdered: true,
+	scopedJoins: true,
+	paginationProperties: true,
+	bulkUpsert: true,
+	readModel: true,
+	mergeKeyset: true
 });
 /**
 * Driver `ServerType`s that positively imply a session-capable, transaction-
@@ -272,6 +282,9 @@ const SESSION_OPTIONS_INDEX = Object.freeze({
 	aggregatePipelinePaginate: 0,
 	lookupPopulate: 0,
 	cursor: 1,
+	iterate: 1,
+	bulkUpsert: 1,
+	keysetCursor: 1,
 	claim: 3,
 	claimVersion: 3,
 	applyTransition: 3,
@@ -381,11 +394,30 @@ function createTxBoundRepo(outer, session) {
 //#endregion
 //#region src/transaction.ts
 /**
+* Cross-repo transaction helper.
+*
+* `Repository#withTransaction` is convenient when every write in a transaction
+* lives on the same repository, but real workflows usually span several:
+*
+*   await withTransaction(connection, async (session) => {
+*     const txn = await revenue.transaction.create(data, { session });
+*     await ledger.entry.create(journal, { session });
+*     await revenue.transaction.verify(txn._id, {}, { session });
+*   });
+*
+* This module-level helper accepts a Mongoose connection (or anything with a
+* compatible `startSession()`), so hosts don't need to arbitrarily pick one
+* repository to hang the transaction off.
+*
+* The Repository instance method delegates to this function — one source of
+* truth for retry semantics, standalone fallback, and session lifecycle.
+*/
+/**
 * 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`.
+* - Starts a session and runs the callback in a transaction with the driver's retry rules
+*   (`TransientTransactionError` → retry the attempt, `UnknownTransactionCommitResult` → retry
+*   the commit), ending the session in `finally`. See {@link runTransaction}.
 * - 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
@@ -406,7 +438,13 @@ function createTxBoundRepo(outer, session) {
 async function withTransaction(connection, callback, options = {}) {
 	const session = await connection.startSession();
 	try {
-		return await session.withTransaction(() => callback(session), options.transactionOptions);
+		assertSessionSurface(session, [...DRIVEN, "endSession"]);
+	} catch (err) {
+		if (typeof session.endSession === "function") await session.endSession();
+		throw err;
+	}
+	try {
+		return await runTransaction(session, callback, options.transactionOptions);
 	} catch (error) {
 		const err = error;
 		if (options.allowFallback && isTransactionUnsupported(err)) {
@@ -418,6 +456,117 @@ async function withTransaction(connection, callback, options = {}) {
 		await session.endSession();
 	}
 }
+const TRANSACTION_ERROR_CODES = { 
+/** The session lacks a method the transaction loop drives (a partial or wrapped fake). */
+SESSION_INCOMPLETE: "mongokit.transaction.session_incomplete" };
+const DRIVEN = [
+	"startTransaction",
+	"commitTransaction",
+	"abortTransaction",
+	"inTransaction"
+];
+/** Refuse, with the missing names, a session that cannot be driven, before calling anything on it. */
+function assertSessionSurface(session, required) {
+	const s = session ?? {};
+	const missing = required.filter((name) => typeof s[name] !== "function");
+	if (missing.length === 0) return;
+	throw createError(500, `[mongokit] the transaction session lacks ${missing.join(", ")}; pass a driver ClientSession`, {
+		code: TRANSACTION_ERROR_CODES.SESSION_INCOMPLETE,
+		meta: { missing }
+	});
+}
+const MAX_TRANSACTION_TIMEOUT_MS = 12e4;
+const BACKOFF_INITIAL_MS = 5;
+const BACKOFF_MAX_MS = 500;
+const MAX_TIME_MS_EXPIRED = 50;
+function hasLabel(err, label) {
+	const e = err;
+	if (typeof e?.hasErrorLabel === "function") return e.hasErrorLabel(label);
+	return Array.isArray(e?.errorLabels) && e.errorLabels.includes(label);
+}
+function isMaxTimeMSExpired(err) {
+	const e = err;
+	return e?.code === MAX_TIME_MS_EXPIRED || e?.writeConcernError?.code === MAX_TIME_MS_EXPIRED;
+}
+function timeoutError(cause, csot) {
+	if (!csot || cause instanceof mongoose.mongo.MongoOperationTimeoutError) return cause;
+	const error = new mongoose.mongo.MongoOperationTimeoutError("Timed out during withTransaction", { cause: cause instanceof Error ? cause : void 0 });
+	if (cause instanceof mongoose.mongo.MongoError) for (const label of cause.errorLabels) error.addErrorLabel(label);
+	return error;
+}
+/**
+* The driver's convenient-transaction algorithm (start → callback → commit, label-based retry,
+* jittered backoff, a deadline), run here so the driver never attaches a session `timeoutContext`:
+* with one, every legacy bulk write (`insertMany`, `bulkWrite`) in the transaction is refused once
+* the client carries `timeoutMS` (driver <= 7.7: the bulk path re-resolves the inherited client
+* `timeoutMS` as a per-op one). Each operation keeps its own per-op CSOT budget instead.
+* Deadline: `transactionOptions.timeoutMS`, else the client's `timeoutMS`, else 120 s (as the driver).
+* Pinned by `tests/integration/csot-transaction-matrix.test.ts`.
+*/
+async function runTransaction(session, callback, transactionOptions = {}) {
+	assertSessionSurface(session, DRIVEN);
+	const { timeoutMS: explicitTimeout, ...startOptions } = transactionOptions;
+	const clientTimeout = session.timeoutMS;
+	const timeoutMS = explicitTimeout ?? clientTimeout;
+	const csot = timeoutMS != null;
+	const deadline = performance.now() + (timeoutMS ?? MAX_TRANSACTION_TIMEOUT_MS);
+	let lastError;
+	if (csot) setTransactionDeadline(session, deadline);
+	try {
+		for (let attempt = 0;; attempt++) {
+			if (attempt > 0) {
+				const backoff = Math.random() * Math.min(BACKOFF_INITIAL_MS * 1.5 ** (attempt - 1), BACKOFF_MAX_MS);
+				if (performance.now() + backoff >= deadline) throw timeoutError(lastError, csot);
+				await setTimeout$1(backoff);
+			}
+			session.startTransaction(startOptions);
+			let result;
+			try {
+				result = await callback(session);
+				if (!session.inTransaction()) return result;
+			} catch (err) {
+				lastError = err;
+				await abortKeepingError(session, err);
+				if (err instanceof mongoose.mongo.MongoError && hasLabel(err, "TransientTransactionError")) {
+					if (performance.now() >= deadline) throw timeoutError(err, csot);
+					continue;
+				}
+				throw err;
+			}
+			for (;;) {
+				const left = deadline - performance.now();
+				if (csot && left <= 0) {
+					const late = new mongoose.mongo.MongoOperationTimeoutError("Transaction budget exhausted before commit; the transaction was aborted, nothing was committed");
+					await abortKeepingError(session, late);
+					throw late;
+				}
+				try {
+					await session.commitTransaction(csot ? { timeoutMS: Math.max(1, Math.floor(left)) } : void 0);
+					return result;
+				} catch (err) {
+					lastError = err;
+					if (hasLabel(err, "UnknownTransactionCommitResult") && !isMaxTimeMSExpired(err)) {
+						if (performance.now() >= deadline) throw timeoutError(err, csot);
+						continue;
+					}
+					if (hasLabel(err, "TransientTransactionError")) break;
+					throw err;
+				}
+			}
+		}
+	} finally {
+		if (csot) setTransactionDeadline(session, void 0);
+	}
+}
+/** Abort if still in progress; an abort failure rides along as `abortError`, never replacing `original`. */
+async function abortKeepingError(session, original) {
+	if (!session.inTransaction()) return;
+	try {
+		await session.abortTransaction();
+	} catch (abortError) {
+		if (original && typeof original === "object") Object.assign(original, { abortError });
+	}
+}
 /**
 * Multi-repo transactional batch — every repo in `repos` becomes a
 * session-bound proxy inside the callback. Eliminates the per-call
@@ -530,4 +679,4 @@ function supportsTransactions(connection) {
 	return resolveTransactionSupport(connection) !== "no";
 }
 //#endregion
-export { createTxBoundRepo as a, classifyHelloReply as c, resolveMongoCapabilities as d, resolveTransactionSupport as f, withTransaction as i, probeMongoCapabilities as l, isTransactionUnsupported as n, MONGOKIT_CAPABILITIES as o, transactionResolutionOf as p, supportsTransactions as r, capabilitiesForSupport as s, batchTransaction as t, resetCapabilityProbeCache as u };
+export { supportsTransactions as a, MONGOKIT_CAPABILITIES as c, probeMongoCapabilities as d, resetCapabilityProbeCache as f, transactionResolutionOf as h, runTransaction as i, capabilitiesForSupport as l, resolveTransactionSupport as m, batchTransaction as n, withTransaction as o, resolveMongoCapabilities as p, isTransactionUnsupported as r, createTxBoundRepo as s, TRANSACTION_ERROR_CODES as t, classifyHelloReply as u };