@optimystic/db-core 0.28.0 → 0.29.0

package/src/transactor/network-transactor.ts

@@ -14,6 +14,7 @@ import { groupBy } from "../utility/groupby.js";
 import { blockIdToBytes } from "../utility/block-id-to-bytes.js";
 import { isRecordEmpty } from "../utility/is-record-empty.js";
 import { type CoordinatorBatch, makeBatchesByPeer, incompleteBatches, everyBatch, allBatches, mergeBlocks, processBatches, createBatchesForPayload } from "../utility/batch-coordinator.js";
+import { abortableDelay, jitteredBackoffMs } from "../utility/backoff.js";
 import { createLogger, verbose } from "../logger.js";
 
 const log = createLogger('network-transactor');
@@ -280,7 +281,6 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		if (missingIds.length > 0) {
 			log('get:missing blockIds=%o', missingIds);
 			const details = this.formatBatchStatuses(batches,
-				b => (b.request?.isResponse as boolean) ?? false,
 				b => {
 					const status = b.request == null ? 'no-response' : (b.request.isResponse ? 'response' : 'in-flight')
 					const errMsg = b.request?.isError ? ` cause=${errorMessage(b.request.error)}` : ''
@@ -568,7 +568,6 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 
 		if (!everyBatch(batches, b => b.request?.isResponse as boolean && b.request!.response!.success)) {
 			const details = this.formatBatchStatuses(batches,
-				b => (b.request?.isResponse as boolean && (b.request as any).response?.success) ?? false,
 				b => {
 					const status = b.request == null ? 'no-response' : (b.request.isResponse ? 'non-success' : 'in-flight')
 					const errMsg = b.request?.isError ? ` cause=${errorMessage(b.request.error)}` : ''
@@ -584,9 +583,23 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			error = aggregate;
 		}
 
-		if (error) { // If any failures, cancel all pending actions as background microtask
+		if (error) { // If any failures, discharge every pending record this pend left behind
 			log('pend:cancel actionId=%s', blockAction.actionId);
-			void Promise.resolve().then(() => this.cancelBatch(batches, { blockIds, actionId: blockAction.actionId })).catch(e => log('WARN: cancel after pend failure rejected: %o', e));
+			// AWAITED, not fired off as a background microtask. Returning before the cancel lands means
+			// a caller that retries immediately meets its own still-standing pending record and burns a
+			// whole attempt out of its retry budget on it (measured: the attempt after a lost pend reply
+			// was rejected by its own record, and only the one after that landed).
+			// The tradeoff, stated: a losing pend now pays a cancel round-trip before it returns its
+			// StaleFailure, where before it returned at once and cleaned up behind itself. That is the
+			// right trade — the old shape spent one of the CALLER's retries instead of one round-trip.
+			// The catch matters now that `cancelBatch` is checked and throwable: a cancel that could not
+			// discharge must be reported, but must not replace the pend verdict below (the StaleFailure
+			// the caller reads via `isConflictFailure` to decide to rebase, or the original error).
+			try {
+				await this.cancelBatch(batches, { blockIds, actionId: blockAction.actionId });
+			} catch (cancelError) {
+				log('WARN: cancel after pend failure did not discharge: %o', cancelError);
+			}
 			const stale = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
 			if (stale.length > 0) {	// Any active stale failures should preempt reporting connection or other potential transient errors (we have information)
 				log('pend:stale actionId=%s staleCount=%d', blockAction.actionId, stale.length);
@@ -653,23 +666,20 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		};
 	}
 
+	/**
+	 * Discharges every pending record `actionRef` left behind, and THROWS if it could not.
+	 *
+	 * Cancel is the only removal path a client controls (see docs/repository.md, "a pending record's
+	 * lifetime is bounded by its writer"), so a cancel that silently did nothing wedges the block
+	 * against every later writer. `processBatches` never rethrows — it records each batch's outcome
+	 * and swallows the rejection — so a cancel in which every peer's RPC failed used to return
+	 * normally, and each of this method's callers read "returned" as "discharged". It now checks
+	 * completeness and rides out a transient fault, exactly as {@link pend} and {@link commitBlocks}
+	 * already do for their own rounds. See {@link dischargeCancel} for the loop and its bounds.
+	 */
 	async cancel(actionRef: ActionBlocks): Promise<void> {
 		log('cancel actionId=%s blockIds=%d', actionRef.actionId, actionRef.blockIds.length);
-		const batches = await this.batchesForPayload<BlockId[], void>(
-			actionRef.blockIds,
-			actionRef.blockIds,
-			mergeBlocks,
-			[]
-		);
-		const expiration = Date.now() + this.abortOrCancelTimeoutMs;
-		await processBatches(
-			batches,
-			(batch) => this.getRepo(batch.peerId).cancel({ actionId: actionRef.actionId, blockIds: batch.payload }, { expiration, dialTimeoutMs: this.dialTimeoutMs }),
-			batch => batch.payload,
-			mergeBlocks,
-			expiration,
-			async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
-		);
+		await this.dischargeCancel(actionRef);
 	}
 
 	async queryClusterNominees(blockId: BlockId): Promise<ClusterNomineesResult> {
@@ -743,10 +753,12 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				// tickets/fix/refresh-must-always-know-its-own-in-flight-action, and to be fixed there
 				// rather than by tolerating the failure here.
 				//
-				// Transport-shaped failures (throws, no returned refusal) keep the tolerance: the commit
-				// consensus for these blocks exists, so lagging peers converge via reconciliation paths
-				// (e.g. reads with context).
-				try { log('WARN: non-tail commit had errors; proceeding after tail commit: %s', error.message); } catch { /* ignore */ }
+				// Transport-shaped failures (throws, no returned refusal) keep the tolerance for the
+				// RESULT — the tail committed durably, and reporting failure now would disown an
+				// acknowledged write — but NOT for the state the sweep abandoned, which
+				// `cancelAbandonedSweepBlocks` below repairs before this returns.
+				try { log('WARN: non-tail commit had errors; cancelling unconfirmed blocks, proceeding after tail commit: %s', error.message); } catch { /* ignore */ }
+				await this.cancelAbandonedSweepBlocks(request.actionId, remainingBlocks, batches);
 			}
 		}
 
@@ -754,6 +766,62 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		return { success: true };
 	}
 
+	/**
+	 * Cancels every sweep block whose commit batch never confirmed success, so an acknowledged
+	 * commit never walks away from a pending record. Best-effort: a failed cancel is logged, never
+	 * thrown, because the tail is already durable and the caller has nothing left to retry.
+	 *
+	 * **Why cancelling is required.** A thrown sweep does not imply the sweep's commit consensus
+	 * exists anywhere: it also covers a sweep whose cluster transaction reached NOBODY, where no
+	 * consensus record exists, no reconciliation will ever run, and every cohort member still holds
+	 * the pending record its pend wrote. Nothing else removes such a record (its only removers are a
+	 * client cancel, a divergence-shaped commit refusal, and a forward write of the SAME action — see
+	 * docs/repository.md "a pending record's lifetime is bounded by its writer"), and while it stands
+	 * the members reject every later write to the block from any writer.
+	 *
+	 * **Why cancelling is safe** in all three timings:
+	 *  - the sweep's commit DID land on a member (a lost response) ⇒ that member already promoted the
+	 *    record, so the cancel is a no-op there;
+	 *  - it did not land ⇒ the cancel is exactly the repair;
+	 *  - its consensus is still in flight and lands AFTER the cancel ⇒ the member meets a missing
+	 *    pend, which `ClusterMember.applyConsensusOperation` already treats as "behind" divergence and
+	 *    cures by reconciling the block from a cohort peer.
+	 *
+	 * Confirmed blocks are excluded only to skip a pointless consensus round — cancelling one would
+	 * also be a no-op — so an over-broad `confirmed` set costs latency, never correctness.
+	 *
+	 * Residuals: the cancel is retried and checked ({@link dischargeCancel}) but still bounded, so a
+	 * fault outlasting its budget leaves the record wedged until a node-side backstop sweep exists (backlog:
+	 * `debt-unpromotable-pending-records-need-a-sweep`); and this covers only the sweep's abandonment
+	 * — `StorageRepo.commit`'s genuine-fault arm deliberately KEEPS a failed batch's pendings for a
+	 * retry, so it is a second producer of the same durable state whenever that retry never comes.
+	 */
+	private async cancelAbandonedSweepBlocks(actionId: ActionId, sweptBlocks: BlockId[], batches: CoordinatorBatch<BlockId[], CommitResult>[]): Promise<void> {
+		// NOTE: `confirmed` is only ever non-empty when the sweep spans MORE THAN ONE batch, and it
+		// does so only when no single peer covers every swept block — `consolidateCoordinators`'
+		// greedy set cover collapses the pend onto one coordinator otherwise, and commit reuses that
+		// resolution. So on a mesh whose nodes are all responsible for all blocks — every in-process
+		// test mesh today — this filter is structurally unreachable, and
+		// packages/db-p2p/test/torn-commit-cancels-abandoned-blocks.spec.ts cannot cover it. Pinning
+		// a partial sweep needs a mesh whose responsibility sets are disjoint enough to force two
+		// pend batches; a new failure injection alone will not reach it. That fixture is tracked in
+		// backlog `debt-no-mesh-fixture-forces-two-coordinator-batches`, which collects this site and
+		// the two others with the same gap.
+		const confirmed = new Set<BlockId>();
+		for (const b of allBatches(batches, bb => bb.request?.isResponse === true && bb.request!.response!.success)) {
+			for (const bid of b.payload) confirmed.add(bid);
+		}
+		const abandoned = sweptBlocks.filter(bid => !confirmed.has(bid));
+		if (abandoned.length === 0) {
+			return;
+		}
+		try {
+			await this.cancel({ actionId, blockIds: abandoned });
+		} catch (cancelError) {
+			try { log('WARN: cancel of abandoned sweep blocks failed — pending records may wedge until the node-side sweep lands: %o', cancelError); } catch { /* ignore */ }
+		}
+	}
+
 	private async commitBlock(blockId: BlockId, actionId: ActionId, rev: number, tailId?: BlockId, blockDigests?: BlockContentDigests): Promise<CommitResult> {
 		const { batches: tailBatches, error: tailError } = await this.commitBlocks({ blockIds: [blockId], actionId, rev, tailId, blockDigests });
 		if (tailError) {
@@ -826,7 +894,6 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 
 		if (!everyBatch(batches, b => b.request?.isResponse as boolean && b.request!.response!.success)) {
 			const details = this.formatBatchStatuses(batches,
-				b => (b.request?.isResponse as boolean && (b.request as any).response?.success) ?? false,
 				b => {
 					const status = b.request == null ? 'no-response' : (b.request.isResponse ? 'non-success' : 'in-flight')
 					const resp: any = (b.request as any)?.response;
@@ -918,31 +985,150 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		return created.coordinators;
 	}
 
-	/** Cancels a pending transaction by canceling all blocks associated with the transaction, including failed peers */
+	/**
+	 * Cancels a pending transaction by canceling all blocks associated with the transaction,
+	 * including failed peers. Seeds the first round from the peers the failed operation actually
+	 * talked to (a coordinator that answered the pend is the one most likely to be holding the
+	 * record); every later round re-resolves live. Throws on failure to discharge — see
+	 * {@link dischargeCancel}.
+	 *
+	 * The seed uses each batch's `coordinatingBlockIds` — the full set `consolidateCoordinators`
+	 * assigned to that peer — not its anchor `blockId` alone. Anchor-only was silently lossy: when
+	 * consolidation collapsed several blocks onto one coordinator, the non-anchor blocks got no
+	 * cancel at all. `processBatches`' retry batches carry no `coordinatingBlockIds` and fall back to
+	 * their anchor, so a retried multi-block batch can still under-cover the seed round;
+	 * `dischargeCancel`'s per-block outstanding set notices and the next round resolves those live.
+	 * That residual costs a round, never correctness, and is unreachable on a mesh where every node
+	 * covers every block — see backlog `debt-no-mesh-fixture-forces-two-coordinator-batches`.
+	 */
 	private async cancelBatch<TPayload, TResponse>(
 		batches: CoordinatorBatch<TPayload, TResponse>[],
 		actionRef: ActionBlocks,
 	) {
-		const expiration = Date.now() + this.abortOrCancelTimeoutMs;
-		const operationBatches = makeBatchesByPeer(
-			Array.from(allBatches(batches)).map(b => [b.blockId, b.peerId] as const),
+		const operationBatches = makeBatchesByPeer<BlockId[], void>(
+			Array.from(allBatches(batches)).flatMap(b => (b.coordinatingBlockIds ?? [b.blockId]).map(bid => [bid, b.peerId] as const)),
 			actionRef.blockIds,
 			mergeBlocks,
 			[]
 		);
-		await processBatches(
-			operationBatches,
-			(batch) => this.getRepo(batch.peerId).cancel({ actionId: actionRef.actionId, blockIds: batch.payload }, { expiration, dialTimeoutMs: this.dialTimeoutMs }),
-			batch => batch.payload,
-			mergeBlocks,
-			expiration,
-			async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
-		);
+		await this.dischargeCancel(actionRef, operationBatches);
+	}
+
+	/**
+	 * Rounds {@link dischargeCancel} will run before giving up, in addition to the
+	 * `abortOrCancelTimeoutMs` deadline; whichever bound trips first ends the loop.
+	 *
+	 * NOTE: accepted tradeoff — the round cap can end the loop well before the deadline. Six rounds
+	 * means five backoffs, whose pre-jitter values with `baseMs` 50 / `capMs` 500 are 50, 100, 200,
+	 * 400, 500 ms, each drawn from `(0.5·exp, exp]` — so 0.63–1.25 s of waiting, plus each round's
+	 * own RPC time (measured end to end: 1054 ms for the dead-transport arm of
+	 * packages/db-p2p/test/reset-does-not-strand-its-own-pend.spec.ts). That clears a stream reset
+	 * and reconnect, and against a genuinely dead transport it hands the caller a legible failure in
+	 * about a second instead of spending its whole (typically 5 s) abort budget issuing RPCs nobody
+	 * will answer. Raise it if faults longer than that but shorter than the abort budget turn out to
+	 * strand records in practice.
+	 */
+	private static readonly MAX_CANCEL_ROUNDS = 6;
+
+	/**
+	 * Runs cancel rounds until every block of `actionRef` has had a cancel ANSWERED by some peer, or
+	 * the budget runs out — and then throws an aggregate naming the action and the blocks whose
+	 * pending records are still standing.
+	 *
+	 * **Why a completeness check.** `processBatches` deliberately never rethrows, so "it returned"
+	 * says nothing about whether any peer was reached. A block is only discharged once some batch
+	 * carrying it got a response; anything else leaves its pending record standing, and while it
+	 * stands `ClusterMember.validatePendOperations` votes reject on every later pend touching the
+	 * block, from any writer. An application retry loop opens a NEW transaction and so mints a new
+	 * action id, which is none of the three things that remove a record (client cancel,
+	 * divergence-shaped commit refusal, forward write of the SAME action id — docs/repository.md),
+	 * so the write collides with its own predecessor permanently.
+	 *
+	 * **Why a TIME-based retry on top of `processBatches`' own.** That one is a PEER retry: it
+	 * re-homes a failed block onto an alternate coordinator immediately, with no delay. A stream
+	 * reset is time-shaped, not peer-shaped — every peer is equally unreachable for the length of
+	 * the fault — so only a delayed re-attempt clears it. Each round rebuilds its batches from
+	 * scratch, so a re-resolved coordinator is picked up.
+	 *
+	 * **Why retrying is safe.** Cancel is idempotent, and the three-timings argument written out in
+	 * {@link cancelAbandonedSweepBlocks} covers a cancel that races a landing commit. Extra rounds
+	 * cost latency only. Each round narrows to the blocks still outstanding, so a partially
+	 * successful round does not re-issue the cancels that already landed.
+	 *
+	 * NOTE: a fault that outlasts these bounds still strands the record, and nothing node-side
+	 * reclaims it. That residual is the backstop tracked in backlog
+	 * `debt-unpromotable-pending-records-need-a-sweep`.
+	 *
+	 * @param seedBatches Batches to use for round 0 only (see {@link cancelBatch}). Omitted → round
+	 * 0 resolves coordinators live like every later round.
+	 */
+	private async dischargeCancel(
+		actionRef: ActionBlocks,
+		seedBatches?: CoordinatorBatch<BlockId[], void>[]
+	): Promise<void> {
+		let outstanding = Array.from(new Set(actionRef.blockIds));
+		if (outstanding.length === 0) {
+			return;
+		}
+		const deadline = Date.now() + this.abortOrCancelTimeoutMs;
+		let roundBatches: CoordinatorBatch<BlockId[], void>[] = [];
+		let lastError: Error | undefined;
+		for (let round = 0; ; ++round) {
+			roundBatches = [];
+			try {
+				// Batch construction can throw (coordinator lookup); `processBatches` cannot.
+				roundBatches = round === 0 && seedBatches
+					? seedBatches
+					: await this.batchesForPayload<BlockId[], void>(outstanding, outstanding, mergeBlocks, []);
+				await processBatches(
+					roundBatches,
+					(batch) => this.getRepo(batch.peerId).cancel({ actionId: actionRef.actionId, blockIds: batch.payload }, { expiration: deadline, dialTimeoutMs: this.dialTimeoutMs }),
+					batch => batch.payload,
+					mergeBlocks,
+					deadline,
+					async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+				);
+			} catch (e) {
+				lastError = asError(e);
+			}
+
+			const discharged = dischargedBlocks(roundBatches);
+			outstanding = outstanding.filter(bid => !discharged.has(bid));
+			if (outstanding.length === 0) {
+				if (round > 0) {
+					log('cancel:discharged actionId=%s rounds=%d', actionRef.actionId, round + 1);
+				}
+				return;
+			}
+
+			const remainingMs = deadline - Date.now();
+			if (round + 1 >= NetworkTransactor.MAX_CANCEL_ROUNDS || remainingMs <= 0) {
+				break;
+			}
+			log('cancel:retry actionId=%s round=%d outstanding=%d', actionRef.actionId, round, outstanding.length);
+			await abortableDelay(Math.min(jitteredBackoffMs(round, { baseMs: 50, capMs: 500 }), remainingMs));
+		}
+
+		const details = this.formatBatchStatuses(roundBatches,
+			b => {
+				const status = b.request == null ? 'no-response' : (b.request.isResponse ? 'responded' : 'in-flight');
+				const errMsg = b.request?.isError ? ` cause=${errorMessage(b.request.error)}` : '';
+				return `${b.peerId.toString()}[block:${b.blockId}](${status})${errMsg}`;
+			});
+		const rootCause = firstBatchError(roundBatches) ?? lastError;
+		const aggregate = new Error(`Cancel of action ${actionRef.actionId} did not discharge ${outstanding.length} block(s): ${outstanding.join(', ')}`
+			+ (details ? `; peers: ${details}` : '')
+			+ (rootCause ? `; root: ${rootCause.message}` : ''));
+		(aggregate as any).cause = rootCause;
+		(aggregate as AggregateError).errors = rootCause ? [rootCause] : [];
+		throw aggregate;
 	}
 
+	/** Renders the batches worth naming in an aggregate error: the ones that never completed, or —
+	 * when every batch completed and the aggregate is about a non-success RESPONSE rather than a
+	 * transport fault — all of them. */
 	private formatBatchStatuses<TPayload, TResponse>(
 		batches: CoordinatorBatch<TPayload, TResponse>[],
-		_isSuccess: (b: CoordinatorBatch<TPayload, TResponse>) => boolean,
 		formatter: (b: CoordinatorBatch<TPayload, TResponse>) => string
 	): string {
 		const incompletes = Array.from(incompleteBatches(batches))
@@ -955,6 +1141,20 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 }
 
 
+/**
+ * The block ids some batch in the tree got an ANSWER for. A cancel batch that errored, or never
+ * responded, discharged nothing — its blocks' pending records are still standing. Batch payloads
+ * are block-id lists (built with {@link mergeBlocks}), including the retry batches
+ * `processBatches` re-homes, so the union across the whole tree is the discharged set.
+ */
+function dischargedBlocks(batches: CoordinatorBatch<BlockId[], void>[]): Set<BlockId> {
+	const discharged = new Set<BlockId>();
+	for (const b of allBatches(batches, bb => bb.request?.isResponse === true)) {
+		for (const bid of b.payload) discharged.add(bid);
+	}
+	return discharged;
+}
+
 /** The subset of `all` whose ids appear in `batchBlockIds`, wrapped (via {@link blockDigestsField})
  * so it spreads to nothing when the batch declares no digests. Called at SEND time, once per attempt,
  * because `processBatches` re-batches failed blocks onto different coordinators — a subset computed

package/src/transactor/transactor-source.ts

@@ -5,6 +5,9 @@ import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struc
 import type { ReadDependency } from "../transaction/transaction.js";
 import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
 import { blockDigestsField } from "../transform/digest.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('transactor-source');
 
 export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlock> {
 	/** Shared with this collection's CacheSource so cache hits also record dependencies.
@@ -158,13 +161,47 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 				...blockDigestsField(blockDigests)
 			});
 			if (!commitResult.success) {
-				await this.transactor.cancel({ actionId, blockIds: pendResult.blockIds });
+				// A confirmed conflict has to be RETURNED as the StaleFailure, because `Collection.sync`
+				// and the multi-collection pend phase read it via `isConflictFailure` to decide to
+				// rebase — letting the cancel's own failure throw over it would turn a routine,
+				// recoverable race into a hard failure. So the cancel fault is logged, not raised.
+				await this.dischargePend(actionId, pendResult.blockIds);
 				return commitResult;
 			}
 		} catch (e) {
-			await this.transactor.cancel({ actionId, blockIds: pendResult.blockIds });
+			// `e` is the real cause — a transport fault, the thing the caller needs to see. A cancel
+			// that also fails must not silently take its place, but it must not be lost either: the
+			// pend was left undischarged and that is what wedges the block against the caller's own
+			// retry. Attach it to `e` so one report names both.
+			const cancelError = await this.dischargePend(actionId, pendResult.blockIds);
+			if (cancelError !== undefined && e !== null && typeof e === 'object') {
+				// A frozen or sealed error would make this assignment throw, and a throw here would
+				// replace the cause the caller actually needs. The log above already named the cancel.
+				try { (e as { cancelError?: unknown }).cancelError = cancelError; } catch { /* ignore */ }
+			}
 			throw e;
 		}
 	}
+
+	/**
+	 * Discharges the pending records this attempt left behind, on both of `transact`'s abort paths.
+	 *
+	 * `ITransactor.cancel` returns only when the records are gone and throws otherwise
+	 * (`NetworkTransactor.cancel` retries and then verifies that some peer actually answered), so a
+	 * throw here means the block stays wedged against every later writer. That has to be reported —
+	 * but never by displacing the verdict the cancel is cleaning up after, so it comes back as a
+	 * value rather than propagating.
+	 *
+	 * @returns the cancel's own failure, or `undefined` when it discharged.
+	 */
+	private async dischargePend(actionId: ActionId, blockIds: BlockId[]): Promise<unknown> {
+		try {
+			await this.transactor.cancel({ actionId, blockIds });
+			return undefined;
+		} catch (cancelError) {
+			log('WARN: cancel after failed commit did not discharge actionId=%s blocks=%o: %o', actionId, blockIds, cancelError);
+			return cancelError;
+		}
+	}
 }
 

package/src/transactor/transactor.ts

@@ -1,44 +1,49 @@
-import type { GetBlockResults, ActionBlocks, BlockActionStatus, PendResult, CommitResult, PendRequest, CommitRequest, BlockGets, BlockId } from "../index.js";
-import type { PeerId } from "../network/types.js";
-
-export type ClusterNomineesResult = {
-	/** Peer IDs of the cluster members who can participate in consensus */
-	nominees: PeerId[];
-};
-
-export type ITransactor = {
-	/** Get blocks by their IDs and versions or a specific action
-		- Does not update the version of the block, but the action is available for explicit reading, and for committing
-		- If the action targets the correct version, the call succeeds, unless failIfPending and there are any pending actions - the caller may choose to wait for pending actions to clear rather than risk racing with them
-		- If the action targets an older version, the call fails, and the caller must resync using the missing actions
-	 */
-	get(blockGets: BlockGets): Promise<GetBlockResults>;
-
-	/** Get statuses of block actions */
-	getStatus(actionRefs: ActionBlocks[]): Promise<BlockActionStatus[]>;
-
-	/** Post an action for a set of blocks
-		- Does not update the version of the block, but the action is available for explicit reading, and for committing
-		- If the action targets the correct version, the call succeeds, unless pending = 'fail' and there are any pending actions - the caller may choose to wait for pending actions to clear rather than risk racing with them
-		- If the action targets an older version, the call fails, and the caller must resync using the missing actions
-	 */
-	pend(blockAction: PendRequest): Promise<PendResult>;
-
-	/** Cancel a pending action
-		- If the given action ID is pending, it is canceled
-	 */
-	cancel(actionRef: ActionBlocks): Promise<void>;
-
-	/** Commit a pending action
-		- If the action references the current version, the pending action is committed
-		- If the returned fails, the transforms necessary to update all overlapping blocks are returned
-		- If the action mentions other collections, those are assumed conditions - returned conditions only list inherited conditions
-	 */
-	commit(request: CommitRequest): Promise<CommitResult>;
-
-	/** Query cluster nominees for a critical block (used in GATHER phase for multi-collection transactions)
-		- Returns the peer IDs of cluster members who can participate in consensus for the given block
-		- Used to build the supercluster for multi-collection transaction consensus
-	 */
-	queryClusterNominees?(blockId: BlockId): Promise<ClusterNomineesResult>;
-}
+import type { GetBlockResults, ActionBlocks, BlockActionStatus, PendResult, CommitResult, PendRequest, CommitRequest, BlockGets, BlockId } from "../index.js";
+import type { PeerId } from "../network/types.js";
+
+export type ClusterNomineesResult = {
+	/** Peer IDs of the cluster members who can participate in consensus */
+	nominees: PeerId[];
+};
+
+export type ITransactor = {
+	/** Get blocks by their IDs and versions or a specific action
+		- Does not update the version of the block, but the action is available for explicit reading, and for committing
+		- If the action targets the correct version, the call succeeds, unless failIfPending and there are any pending actions - the caller may choose to wait for pending actions to clear rather than risk racing with them
+		- If the action targets an older version, the call fails, and the caller must resync using the missing actions
+	 */
+	get(blockGets: BlockGets): Promise<GetBlockResults>;
+
+	/** Get statuses of block actions */
+	getStatus(actionRefs: ActionBlocks[]): Promise<BlockActionStatus[]>;
+
+	/** Post an action for a set of blocks
+		- Does not update the version of the block, but the action is available for explicit reading, and for committing
+		- If the action targets the correct version, the call succeeds, unless pending = 'fail' and there are any pending actions - the caller may choose to wait for pending actions to clear rather than risk racing with them
+		- If the action targets an older version, the call fails, and the caller must resync using the missing actions
+	 */
+	pend(blockAction: PendRequest): Promise<PendResult>;
+
+	/** Cancel a pending action
+		- If the given action ID is pending, it is canceled
+		- Returning means DISCHARGED: an implementation that could not remove the pending records
+		  must throw rather than return, because nothing else will ever remove them (a record's only
+		  removers are this cancel, a divergence-shaped commit refusal, and a forward write of the
+		  same action id — see docs/repository.md), and while one stands every later write to the
+		  block is refused. A caller that swallows the throw must still say so in its log.
+	 */
+	cancel(actionRef: ActionBlocks): Promise<void>;
+
+	/** Commit a pending action
+		- If the action references the current version, the pending action is committed
+		- If the returned fails, the transforms necessary to update all overlapping blocks are returned
+		- If the action mentions other collections, those are assumed conditions - returned conditions only list inherited conditions
+	 */
+	commit(request: CommitRequest): Promise<CommitResult>;
+
+	/** Query cluster nominees for a critical block (used in GATHER phase for multi-collection transactions)
+		- Returns the peer IDs of cluster members who can participate in consensus for the given block
+		- Used to build the supercluster for multi-collection transaction consensus
+	 */
+	queryClusterNominees?(blockId: BlockId): Promise<ClusterNomineesResult>;
+}