@optimystic/db-p2p 0.22.0 → 0.24.1

package/src/storage/storage-repo.ts

@@ -1,1014 +1,1014 @@
-import type {
-	IRepo, MessageOptions, BlockId, CommitRequest, CommitResult, GetBlockResults, PendRequest, PendResult, ActionBlocks,
-	ActionId, BlockGets, ActionPending, PendSuccess, ActionTransform, ActionTransforms,
-	GetBlockResult, IBlock, ActionRev, BlockUnavailableReason,
-	PendValidationHook,
-	CollectionId, IBlockChangeNotifier, CollectionChangeListener, CollectionChangeEvent,
-	StaleFailure
-} from "@optimystic/db-core";
-import {
-	Latches, transformForBlockId, applyTransform, groupBy, concatTransform, emptyTransforms,
-	blockIdsForTransforms, transformsFromTransform, highestStaleAt
-} from "@optimystic/db-core";
-import { asyncIteratorToArray } from "../it-utility.js";
-import type { IBlockStorage } from "./i-block-storage.js";
-import type { IBlockReplicaStore } from "../cluster/block-transfer-service.js";
-import { createLogger } from "../logger.js";
-
-const log = createLogger('storage-repo');
-
-/**
- * Single source of truth for the per-block commit latch key. Held by {@link StorageRepo.commit} and
- * {@link StorageRepo.saveReplicatedBlock}, and — through an injected runner ({@link withBlockCommitLatch})
- * — by the invalidation-apply path. Every out-of-band writer of a block's `meta.latest` must serialize
- * on this key against a concurrent local commit on the same block; keeping all call sites on this helper
- * is what prevents the key from drifting between them.
- */
-export const commitLatchKey = (blockId: BlockId): string => `StorageRepo.commit:${blockId}`;
-
-/**
- * Runs `fn` while holding the per-block commit latch {@link commitLatchKey}. This is the capability the
- * dispute module's `applyInvalidation` is handed (through its context) so its compensating
- * `saveReplica`/`saveDeletion` read-modify-write of `meta.latest` is mutually exclusive with a concurrent
- * {@link StorageRepo.commit} on the same block — otherwise an invalidation advancing `latest` outside
- * that latch is invisible to commit's staleness guard and can be clobbered (a non-monotonic regression).
- *
- * Acquire/release is per call, so a caller holds at most one block latch at any instant and cannot
- * deadlock against commit's sorted, up-front multi-latch acquisition.
- */
-export async function withBlockCommitLatch<T>(blockId: BlockId, fn: () => Promise<T>): Promise<T> {
-	const release = await Latches.acquire(commitLatchKey(blockId));
-	try {
-		return await fn();
-	} finally {
-		release();
-	}
-}
-
-/**
- * Stable, greppable prefix on the failure reason a commit carries when this node cannot materialize
- * the revision it was asked to record. It is a STRING marker rather than only an error class because
- * {@link StorageRepo.commit} reports per-block faults as `StaleFailure.reason` (a plain string that
- * also crosses the wire), so the class identity is lost by the time a caller inspects the result.
- */
-export const MISSING_BASE_REVISION_REASON = 'missing-base-revision';
-
-/**
- * This node was asked to commit revision N of a block it holds no materializable base for, so
- * applying the transform would materialize nothing while `latest` advanced to N — a block that is
- * then unreadable locally, unservable to peers, and that rejects every later write (see
- * {@link StorageRepo.internalCommit}). The commit is refused instead; the caller heals the node
- * out-of-band (`ClusterMember` pulls the committed revision from a cohort peer) and retries.
- */
-export class MissingBaseRevisionError extends Error {
-	constructor(readonly blockId: BlockId, readonly rev: number, detail: string) {
-		super(`${MISSING_BASE_REVISION_REASON}: block ${blockId} cannot materialize rev ${rev} — ${detail}`);
-		this.name = 'MissingBaseRevisionError';
-	}
-}
-
-/**
- * True when a {@link CommitResult} failed because this node holds no materializable base for one of
- * the committed blocks. Distinguishes that recoverable divergence (heal by fetching the block from a
- * cohort peer) from a genuine storage fault, which must still propagate.
- */
-export function isMissingBaseRevisionFailure(result: CommitResult): boolean {
-	return !result.success && (result.reason?.startsWith(MISSING_BASE_REVISION_REASON) ?? false);
-}
-
-export type StorageRepoOptions = {
-	/** Optional hook to validate transactions in PendRequests */
-	validatePend?: PendValidationHook;
-};
-
-export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaStore {
-	private readonly validatePend?: PendValidationHook;
-	/** Per-collection change listeners; empty sets are pruned on unsubscribe. */
-	private readonly changeListeners = new Map<CollectionId, Set<CollectionChangeListener>>();
-	/** Catch-all change listeners — fire for EVERY collection's commit on this node. */
-	private readonly anyChangeListeners = new Set<CollectionChangeListener>();
-
-	constructor(
-		private readonly createBlockStorage: (blockId: BlockId) => IBlockStorage,
-		options?: StorageRepoOptions
-	) {
-		this.validatePend = options?.validatePend;
-	}
-
-	/**
-	 * Subscribe to commits that mutate `collectionId`'s blocks on this node.
-	 * Returns an idempotent unsubscribe. See {@link IBlockChangeNotifier}.
-	 */
-	onCollectionChange(collectionId: CollectionId, listener: CollectionChangeListener): () => void {
-		let set = this.changeListeners.get(collectionId);
-		if (!set) {
-			set = new Set();
-			this.changeListeners.set(collectionId, set);
-		}
-		set.add(listener);
-		let unsubscribed = false;
-		return () => {
-			if (unsubscribed) return;
-			unsubscribed = true;
-			const current = this.changeListeners.get(collectionId);
-			if (current) {
-				current.delete(listener);
-				if (current.size === 0) {
-					this.changeListeners.delete(collectionId);
-				}
-			}
-		};
-	}
-
-	/**
-	 * Subscribe to commits mutating ANY collection on this node — the catch-all feed the
-	 * cohort-topic origination bridge consumes (it cannot enumerate collection ids ahead of time,
-	 * so a per-collection {@link onCollectionChange} subscription cannot see every commit). Fires for
-	 * the same `(pending → committed)` transitions as {@link onCollectionChange}, but across every
-	 * collection. Returns an idempotent unsubscribe; a throwing listener is isolated + logged.
-	 */
-	onAnyCollectionChange(listener: CollectionChangeListener): () => void {
-		this.anyChangeListeners.add(listener);
-		let unsubscribed = false;
-		return () => {
-			if (unsubscribed) return;
-			unsubscribed = true;
-			this.anyChangeListeners.delete(listener);
-		};
-	}
-
-	/**
-	 * Fire one {@link CollectionChangeEvent} per distinct collection that was
-	 * newly committed. Called AFTER the commit critical section (locks released),
-	 * fire-and-forget synchronous; a throwing listener is isolated and logged. Each event reaches
-	 * both that collection's {@link onCollectionChange} subscribers and every
-	 * {@link onAnyCollectionChange} catch-all subscriber.
-	 *
-	 * `tailId` is the `CommitRequest.tailId` on the commit path; `undefined` on read-driven
-	 * promotions (the get/emitPromotions path has no commit request). A single commit is for one
-	 * collection's chain in practice, so all events from one commit share the same `tailId`.
-	 */
-	private emitCollectionChanges(collectionBlocks: Map<CollectionId, BlockId[]>, actionId: ActionId, rev: number, tailId?: BlockId): void {
-		const hasCatchAll = this.anyChangeListeners.size > 0;
-		for (const [collectionId, blockIds] of collectionBlocks) {
-			const listeners = this.changeListeners.get(collectionId);
-			if ((!listeners || listeners.size === 0) && !hasCatchAll) {
-				continue;
-			}
-			const event: CollectionChangeEvent = { collectionId, blockIds, actionId, rev, tailId };
-			if (listeners && listeners.size > 0) {
-				this.fireChangeListeners(listeners, event);
-			}
-			if (hasCatchAll) {
-				this.fireChangeListeners(this.anyChangeListeners, event);
-			}
-		}
-	}
-
-	/** Dispatch `event` to a snapshot of `listeners` (safe under mid-emit (un)subscribe), isolating + logging any throw. */
-	private fireChangeListeners(listeners: Set<CollectionChangeListener>, event: CollectionChangeEvent): void {
-		for (const listener of Array.from(listeners)) {
-			try {
-				listener(event);
-			} catch (err) {
-				log('onCollectionChange listener threw for collection=%s: %o', event.collectionId, err);
-			}
-		}
-	}
-
-	async get({ blockIds, context }: BlockGets, _options?: MessageOptions): Promise<GetBlockResults> {
-		const distinctBlockIds = Array.from(new Set(blockIds));
-		log('get blockIds=%d', distinctBlockIds.length);
-		// Read-driven promotions that land durably here, captured so we can emit a
-		// change event per durable landing after the parallel reads complete (mirrors
-		// commit's "emit after the work" ordering). The array is shared across the
-		// parallel map closures below — safe because each push happens synchronously
-		// between awaits (single-threaded), never concurrently.
-		const promotions: { collectionId: CollectionId, blockId: BlockId, actionId: ActionId, rev: number }[] = [];
-		const results = await Promise.all(distinctBlockIds.map(async (blockId) => {
-			const blockStorage = this.createBlockStorage(blockId);
-			// Set when this node KNOWS its answer for the block is a guess: the promotion
-			// below refused for a missing base, or getBlock() threw (truncated history /
-			// failed restore). An absent-reading block then reports `unavailable` instead of
-			// posing as an authoritative "never existed" — see BlockUnavailableReason.
-			let unavailable: BlockUnavailableReason | undefined;
-
-			// Ensure that all outstanding transactions in the context are committed.
-			// This promotes a landed-elsewhere pending via internalCommit, which mutates
-			// meta.latest — the same read-modify-write commit()/saveReplicatedBlock guard
-			// with the per-block commit latch. It MUST hold that latch too, or a promotion
-			// racing a concurrent commit on the block regresses latest non-monotonically /
-			// cross-writes a revision. Cheap unlatched pre-scan first so the common
-			// contextless read and no-pending read never pay for latch acquisition; the
-			// authoritative decision is re-made inside the latch.
-			if (context) {
-				const preLatest = await blockStorage.getLatest();
-				const preMissing = preLatest
-					? context.committed.filter(c => c.rev > preLatest.rev)
-					: context.committed;
-				if (preMissing.length > 0) {
-					await withBlockCommitLatch(blockId, async () => {
-						// Re-read authoritative state under the latch: a concurrent commit may have
-						// promoted or superseded a pending between the unlatched pre-scan and here.
-						// Recompute which committed entries are still ahead of `latest` (drops the
-						// superseded, rev <= latest.rev) and re-fetch each pending inside the loop
-						// (skips the already-promoted, pending gone). This makes read-driven
-						// promotion idempotent under races, mirroring commit()'s alreadyDone/stale
-						// partitioning.
-						const latest = await blockStorage.getLatest();
-						const missing = latest
-							? context.committed.filter(c => c.rev > latest.rev)
-							: context.committed;
-						// Sort a COPY: when `latest` is undefined, `missing` aliases the caller's
-						// `context.committed` array, and an in-place `.sort()` would reorder the shared
-						// request context under the caller's feet.
-						try {
-							for (const { actionId, rev } of [...missing].sort((a, b) => a.rev - b.rev)) {
-								const pending = await blockStorage.getPendingTransaction(actionId);
-								if (pending) {
-									const collectionId = await this.internalCommit(blockId, actionId, rev, blockStorage);
-									if (collectionId !== undefined) {
-										promotions.push({ collectionId, blockId, actionId, rev });
-									}
-								}
-							}
-						} catch (err) {
-							// This node holds no materializable base for the block, so NO context revision
-							// can be promoted here (each builds on the one before). Leave `latest` where it
-							// is — the invariant internalCommit just enforced — and let the commit-path
-							// healing supply the content; a read must not fail for it. Every other fault
-							// still propagates.
-							if (!(err instanceof MissingBaseRevisionError)) {
-								throw err;
-							}
-							// This node holds records PROVING the block exists (a pending it could not
-							// promote); if the block then reads as absent below, the answer is a guess,
-							// not an authoritative "never existed".
-							unavailable = 'unmaterializable';
-							log('get:promote-skipped-missing-base blockId=%s rev=%d reason=%s', blockId, err.rev, err.message);
-						}
-					});
-				}
-			}
-
-			// NOTE: a Crash-D3 block (durably promoted + revision saved, but the setLatest lost so
-			// meta.latest is stale and the pending record is gone) reads as empty/stale here — a
-			// context-driven get skips promotion (pending gone) and a default getBlock() sees the
-			// stale latest. It is soft-wedged (stale), not hard-wedged: the next commit-retry for
-			// (actionId, rev) self-heals it via storage.recover() in commit(). Not repaired lazily on
-			// the read path because get() holds no commit latch; if stale reads on unwritten blocks
-			// ever become a problem, add a latched lazy recover() here.
-			//
-			// getBlock() THROWS when this node holds a `latest` it cannot materialize (truncated
-			// history: "Failed to find materialized block", or a failed restore). Caught PER BLOCK so
-			// one broken block cannot fail the whole batch's Promise.all and take healthy siblings
-			// down with it. The read still fails for THIS block — TransactorSource throws
-			// BlockUnavailableError on the flagged entry — so nothing is swallowed.
-			let blockRev: Awaited<ReturnType<IBlockStorage['getBlock']>>;
-			try {
-				blockRev = await blockStorage.getBlock(context?.rev);
-			} catch (err) {
-				// NOTE: the entry drops `state.latest`, which this node does know (getLatest() does not
-				// materialize, so it does not throw). Empty state is what makes CoordinatorRepo treat the
-				// block as missing and consult the cohort — exactly the repair this block needs. If a
-				// consumer ever needs the revision behind an unavailable answer (e.g. to ask the cohort
-				// for a specific rev instead of the whole block), carry `latest` here and widen the
-				// coordinator's consult trigger to `isMissing || unavailable` so repair still fires.
-				log('get:unmaterializable blockId=%s error=%s', blockId,
-					err instanceof Error ? err.message : String(err));
-				return [blockId, { state: {}, unavailable: 'unmaterializable' } as GetBlockResult];
-			}
-
-			// Include pending action if requested, applying the pending transform over whatever
-			// committed base getBlock() resolved (possibly none — a pending-only insert has no
-			// committed revision under it and getBlock reports that as an absent base, not a fault).
-			if (context?.actionId !== undefined) {
-				const pendingTransform = await blockStorage.getPendingTransaction(context.actionId);
-				if (!pendingTransform) {
-					if (unavailable !== undefined) {
-						// The promotion refusal above deleted this very pending record
-						// (`refuseMissingBase` drops the pending it cannot promote). This node DID hold
-						// the record and dropped it, so the honest answer is an availability one — not
-						// a caller-contract violation, and never a throw that would fail the whole batch.
-						return [blockId, { state: {}, unavailable } as GetBlockResult];
-					}
-					// Caller-contract violation (the caller asserted a pending this repo never had, or
-					// cancelled) — an error, not an availability question. Deliberately NOT `unavailable`.
-					//
-					// It is NOT the only way to reach here. A context that both PROVES its own action
-					// (`committed` names it) and names it as the pending overlay (`actionId`) is
-					// self-contradictory, and the two halves of that contradiction land differently: if
-					// the read-driven promotion above REFUSED, the arm above answers gracefully; if it
-					// SUCCEEDED, `promotePendingTransaction` moved the record and we throw here — failing
-					// the whole batch for a request the refusal path tolerates. No production code sets
-					// `ActionContext.actionId` at all today, so neither is reachable except from tests or
-					// a peer that crafts the field on the wire. See
-					// tickets/blocked/repo-pending-overlay-has-no-producer.
-					throw new Error(`Pending action ${context.actionId} not found`);
-				}
-				const block = applyTransform(blockRev?.block, pendingTransform);
-				return [blockId, {
-					block,
-					state: {
-						latest: await blockStorage.getLatest(),
-						pendings: [context.actionId]
-					},
-					// The COMMITTED revision underneath the pending overlay. A pending has no revision
-					// of its own, so the honest answer is the base it was applied to. Absent when there
-					// was no base at all — a pending-only insert served over an absent committed base,
-					// where fabricating a revision would claim content this node never committed.
-					...(blockRev ? { materializedRev: blockRev.actionRev.rev } : {}),
-					// A pending applied to a missing base can materialize nothing (applyTransform drops
-					// updates with no block to apply them to) — that absence is a guess, and is flagged.
-					// A materialized block is a real answer regardless of the earlier refusal. TWO ways
-					// an empty result is a guess: the promotion refusal fired (`unavailable` set), or
-					// there was no committed base under the overlay at all (`blockRev === undefined`) —
-					// this node holds a pending record PROVING the block exists and produced nothing.
-					// The second clause's ABSENCE in the other direction is equally load-bearing: a
-					// pending DELETE over a real committed base also lands here with no block, and that
-					// is an authoritative tombstone which must stay unflagged.
-					...(block === undefined && (unavailable !== undefined || blockRev === undefined)
-						? { unavailable: unavailable ?? 'unmaterializable' }
-						: {})
-				} as GetBlockResult];
-			}
-
-			if (!blockRev) {
-				// `unavailable` distinguishes "never existed" (the common insert-probe case, no flag)
-				// from "this node cannot reconstruct it" (the promotion above refused for a missing
-				// base). A tombstoned block also lands here with meta.latest set, but it never enters
-				// the missing-base catch, so it stays an authoritative absent — keyed off the explicit
-				// flag, not off "no block".
-				return [blockId, { state: {}, ...(unavailable !== undefined ? { unavailable } : {}) } as GetBlockResult];
-			}
-
-			const pendings = await asyncIteratorToArray(blockStorage.listPendingTransactions());
-			return [blockId, {
-				block: blockRev.block,
-				// `getBlock(context?.rev)` materialized the content at the highest committed revision
-				// at or below the pin, and reports it as `actionRev` — report THAT alongside the
-				// content. `state.latest` deliberately stays the node's newest revision for the block
-				// (StorageRepo.get's own promotion pre-scan and CoordinatorRepo's read-repair compare
-				// against it), so the two disagree exactly when a pinned read is serving older content.
-				materializedRev: blockRev.actionRev.rev,
-				state: {
-					latest: await blockStorage.getLatest(),
-					pendings
-				}
-			}];
-		}));
-
-		// Emit per durable read-driven landing (Option A — emit eagerly). Done after the
-		// parallel reads complete so emission stays outside the per-block work, matching
-		// commit's ordering. No-op when nothing was promoted.
-		this.emitPromotions(promotions);
-
-		return Object.fromEntries(results);
-	}
-
-	/**
-	 * Emit a {@link CollectionChangeEvent} for each read-driven promotion that landed
-	 * during a {@link get}. A single get() can promote multiple distinct actions, each
-	 * at its own `(actionId, rev)`, so group by `(actionId, rev)` and route each group
-	 * through {@link emitCollectionChanges} once.
-	 */
-	private emitPromotions(promotions: { collectionId: CollectionId, blockId: BlockId, actionId: ActionId, rev: number }[]): void {
-		if (promotions.length === 0) {
-			return;
-		}
-		const groups = new Map<string, { actionId: ActionId, rev: number, collectionBlocks: Map<CollectionId, BlockId[]> }>();
-		for (const { collectionId, blockId, actionId, rev } of promotions) {
-			const key = `${actionId} ${rev}`;
-			let group = groups.get(key);
-			if (!group) {
-				group = { actionId, rev, collectionBlocks: new Map() };
-				groups.set(key, group);
-			}
-			const list = group.collectionBlocks.get(collectionId) ?? [];
-			list.push(blockId);
-			group.collectionBlocks.set(collectionId, list);
-		}
-		for (const { actionId, rev, collectionBlocks } of groups.values()) {
-			this.emitCollectionChanges(collectionBlocks, actionId, rev);
-		}
-	}
-
-	async pend(request: PendRequest, _options?: MessageOptions): Promise<PendResult> {
-		// Validate transaction if present and validation hook is configured
-		if (this.validatePend && request.transaction && request.operationsHash) {
-			const validationResult = await this.validatePend(request.transaction, request.operationsHash);
-			if (!validationResult.valid) {
-				// Hard rejection: the transaction itself is invalid, so no `conflict` flag — a
-				// re-read and re-pend would fail the same way and only burn the retry budget.
-				return {
-					success: false,
-					reason: validationResult.reason ?? 'Transaction validation failed'
-				};
-			}
-		}
-
-		const blockIds = blockIdsForTransforms(request.transforms);
-		log('pend actionId=%s blockIds=%d rev=%s', request.actionId, blockIds.length, request.rev);
-		const pendings: ActionPending[] = [];
-		const missing: ActionTransforms[] = [];
-		// Highest revision this node confirms holding among the blocks that are at or past the
-		// requested one — reported as StaleFailure.staleAt so a losing writer learns the number
-		// instead of parsing prose. Confirmed-local only: we read it from our own storage below.
-		let staleAt: StaleFailure['staleAt'];
-
-		// Potential race condition: A concurrent commit operation could complete
-		// between the conflict checks (latest.rev, listPendingTransactions) and the
-		// savePendingTransaction call below. This pend operation might succeed based on
-		// stale information, but the subsequent commit for this pend would likely
-		// fail correctly later if a conflict arose. Locking here could make the initial
-		// check more accurate but adds overhead. The current approach prioritizes
-		// letting the commit be the final arbiter.
-		for (const blockId of blockIds) {
-			const blockStorage = this.createBlockStorage(blockId);
-			const transforms = transformForBlockId(request.transforms, blockId);
-
-			// First handle any pending actions
-			const pending = await asyncIteratorToArray(blockStorage.listPendingTransactions());
-			pendings.push(...pending.map(actionId => ({ blockId, actionId })));
-
-			// Handle any conflicting revisions
-			if (request.rev !== undefined || transforms.insert) {
-				const latest = await blockStorage.getLatest();
-				if (latest && latest.rev >= (request.rev ?? 0)) {
-					// Only a real revision race yields a meaningful `staleAt`. When `request.rev` is
-					// undefined this same branch fires for an insert collision (the comparison degrades
-					// to `latest.rev >= 0`, true for any existing block), and reporting that block's
-					// revision would be a number that answers a question nobody asked.
-					if (request.rev !== undefined) {
-						staleAt = highestStaleAt([staleAt, { blockId, rev: latest.rev }]);
-					}
-					const transforms = await asyncIteratorToArray(blockStorage.listRevisions(request.rev ?? 0, latest.rev));
-					for (const actionRev of transforms) {
-						const transform = await blockStorage.getTransaction(actionRev.actionId);
-						if (!transform) {
-							throw new Error(`Missing action ${actionRev.actionId} for block ${blockId}`);
-						}
-						missing.push({
-							actionId: actionRev.actionId,
-							rev: actionRev.rev,
-							transforms: transformsFromTransform(transform, blockId)
-						});
-					}
-				}
-			}
-		}
-
-		if (missing.length) {
-			log('pend:stale actionId=%s missing=%d', request.actionId, missing.length);
-			return {
-				success: false,
-				conflict: true,
-				missing,
-				...(staleAt === undefined ? {} : { staleAt })
-			};
-		}
-
-		if (pendings.length > 0) {
-			if (request.policy === 'f') {	// Fail on pending actions
-				return { success: false, conflict: true, pending: pendings };
-			} else if (request.policy === 'r') {	// Return populated pending actions
-				return {
-					success: false,
-					conflict: true,
-					pending: await Promise.all(pendings.map(async action => {
-						const blockStorage = this.createBlockStorage(action.blockId);
-						return {
-							blockId: action.blockId,
-							actionId: action.actionId,
-							transform: (await blockStorage.getPendingTransaction(action.actionId))
-								?? (await blockStorage.getTransaction(action.actionId))!	// Possible that since enumeration, the action has been promoted
-						}
-					}))
-				};
-			}
-		}
-
-
-		// Simultaneously save pending action for each block
-		// Note: that this is not atomic, after we checked for conflicts and pending actions
-		// new pending or committed actions may have been added.  This is okay, because
-		// this check during pend is conservative.
-		await Promise.all(blockIds.map(blockId => {
-			const blockStorage = this.createBlockStorage(blockId);
-			const blockTransform = transformForBlockId(request.transforms, blockId);
-			return blockStorage.savePendingTransaction(request.actionId, blockTransform);
-		}));
-
-		return {
-			success: true,
-			pending: pendings,
-			blockIds
-		} as PendSuccess;
-	}
-
-	async cancel(actionRef: ActionBlocks, _options?: MessageOptions): Promise<void> {
-		log('cancel actionId=%s blockIds=%d', actionRef.actionId, actionRef.blockIds.length);
-		await Promise.all(actionRef.blockIds.map(blockId => {
-			const blockStorage = this.createBlockStorage(blockId);
-			return blockStorage.deletePendingTransaction(actionRef.actionId);
-		}));
-	}
-
-	/**
-	 * Commit a previously-pended action across its blocks, under the per-block commit latches.
-	 *
-	 * **Divergence vs genuine fault.** When the batch cannot be completed, the reason decides what
-	 * happens to the pending records the pend left behind. `ClusterMember.applyConsensusOperation`
-	 * makes the same split one layer up — it *tolerates* a divergence (and reconciles every
-	 * `commit.blockIds` entry from a cohort peer) but *propagates* a genuine fault for retry — so this
-	 * method must agree with it:
-	 *
-	 * - **Divergence** — this node is behind the agreed history, either because it holds no
-	 *   materializable base ({@link MissingBaseRevisionError}) or because it never received the pend
-	 *   (the `Pending action … not found` throw). Reconcile is guaranteed to follow and will advance
-	 *   every block in the batch past `request.rev`, so no pending record here can ever be promoted:
-	 *   {@link dropUnpromotablePendings} deletes them (see {@link refuseMissingBase}, which already
-	 *   accepts this tradeoff for the single refusing block).
-	 * - **Genuine fault** — any other throw out of {@link internalCommit} (a raw-storage error, …).
-	 *   `ClusterMember` propagates it and the commit is retried, and a retry can still replay the
-	 *   pendings, so they are KEPT.
-	 *
-	 * The stale/`missedCommits` early return (this node is AHEAD — it already holds a revision at or
-	 * past `request.rev`, committed under a different action) deliberately keeps pendings too, and its
-	 * cure is the losing client's `cancel`: `CoordinatorRepo.cancel` runs through consensus, so every
-	 * member drops the record, not just the coordinator. Replication cannot be the cure here — this
-	 * node is already ahead, and a later forward write carries a DIFFERENT action id, which is not
-	 * what `BlockStorage.saveForwardRevision` deletes. A client that dies between the stale result and
-	 * its `cancel` therefore still strands the record; that is pre-existing and orthogonal to the
-	 * divergence split above.
-	 */
-	async commit(request: CommitRequest, _options?: MessageOptions): Promise<CommitResult> {
-		log('commit actionId=%s rev=%d blockIds=%d', request.actionId, request.rev, request.blockIds.length);
-		const uniqueBlockIds = Array.from(new Set(request.blockIds)).sort();
-		const releases: (() => void)[] = [];
-		// Collects the blocks newly committed in this call, grouped by collection,
-		// so we can emit change events once locks are released. Blocks that land before
-		// a mid-loop failure stay here and are still emitted (Option A — emit eagerly):
-		// they are durably committed and a retry rolls the remainder forward.
-		const collectionBlocks = new Map<CollectionId, BlockId[]>();
-		// Captured when internalCommit throws mid-loop; we break (rather than return)
-		// so locks release and accumulated landings still emit before we report failure.
-		let failure: { reason: string } | undefined;
-
-		try {
-			// Acquire locks sequentially based on sorted IDs to prevent deadlocks
-			for (const id of uniqueBlockIds) {
-				const lockId = commitLatchKey(id);
-				const release = await Latches.acquire(lockId);
-				releases.push(release);
-			}
-
-			// --- Start of Critical Section ---
-
-			const blockStorages = request.blockIds.map(blockId => ({
-				blockId,
-				storage: this.createBlockStorage(blockId)
-			}));
-
-			// Partition blocks into:
-			//   - alreadyDone: latest.rev === request.rev && latest.actionId === request.actionId
-			//     (idempotent retry — a prior commit of this same action already landed here;
-			//     skip rather than treat as a conflict. Needed to rollforward stranded blocks
-			//     after a mid-batch crash committed some but not all blocks.)
-			//   - missedCommits: latest.rev >= request.rev but not the same actionId → real stale conflict.
-			//   - toCommit: latest.rev < request.rev or no latest yet → run internalCommit.
-			const toCommit: { blockId: BlockId, storage: IBlockStorage }[] = [];
-			const missedCommits: { blockId: BlockId, transforms: ActionTransform[] }[] = [];
-			// Highest revision among the blocks confirmed lost to a newer one — reported as
-			// StaleFailure.staleAt. The idempotent-retry `continue` below is a no-op, not a loss,
-			// so it never seeds this.
-			let staleAt: StaleFailure['staleAt'];
-			for (const entry of blockStorages) {
-				const { blockId, storage } = entry;
-				const latest = await storage.getLatest();
-				if (latest && latest.rev >= request.rev) {
-					if (latest.rev === request.rev && latest.actionId === request.actionId) {
-						// Idempotent no-op for this block — already committed with this exact (actionId, rev).
-						continue;
-					}
-					staleAt = highestStaleAt([staleAt, { blockId, rev: latest.rev }]);
-					const transforms: ActionTransform[] = [];
-					for await (const actionRev of storage.listRevisions(request.rev, latest.rev)) {
-						const transform = await storage.getTransaction(actionRev.actionId);
-						if (!transform) {
-							throw new Error(`Missing action ${actionRev.actionId} for block ${blockId}`);
-						}
-						transforms.push({
-							actionId: actionRev.actionId,
-							rev: actionRev.rev,
-							transform
-						});
-					}
-					missedCommits.push({ blockId, transforms });	// Push, even if transforms is empty, because we want to reject the older version
-					continue;
-				}
-				toCommit.push(entry);
-			}
-
-			if (missedCommits.length) {
-				log('commit:stale actionId=%s missed=%d', request.actionId, missedCommits.length);
-				return { // Return directly, locks will be released in finally
-					success: false,
-					missing: perBlockActionTransformsToPerAction(missedCommits),
-					...(staleAt === undefined ? {} : { staleAt })
-				};
-			}
-
-			// Check for missing pending actions only on blocks that still need to commit.
-			// Already-done blocks will have had their pending promoted, so skipping them here
-			// is what makes the idempotent rollforward work.
-			//
-			// A toCommit block whose pending is absent is one of two states:
-			//   - Crash-D3: the action was durably promoted and its revision saved, but the crash
-			//     lost the setLatest, so meta.latest is still < request.rev and the pending record
-			//     is gone. getTransaction(actionId) returns the promoted transform. Self-heal here
-			//     via storage.recover() (redoes the lost setLatest, advancing latest to the highest
-			//     contiguous promoted rev, >= request.rev). recover() is idempotent + monotonic, so
-			//     calling it under the already-held commit latch is safe. Recovered blocks are then
-			//     excluded from the internalCommit loop below — their pending is gone, so
-			//     internalCommit would throw.
-			//   - Genuine missing pend: the action was never promoted (getTransaction → undefined),
-			//     so the pend is truly missing. Throw exactly as before.
-			// Crash-D2 never reaches this branch: its pending record is still present.
-			const missingPends: { blockId: BlockId, actionId: ActionId }[] = [];
-			const recovered = new Set<BlockId>();
-			for (const { blockId, storage } of toCommit) {
-				const pendingAction = await storage.getPendingTransaction(request.actionId);
-				if (pendingAction) {
-					continue;
-				}
-				const promoted = await storage.getTransaction(request.actionId);
-				if (!promoted) {
-					missingPends.push({ blockId, actionId: request.actionId });
-					continue;
-				}
-				// Crash-D3 signature (pending absent + action durably promoted). Redo the lost setLatest.
-				const result = await storage.recover();
-				if (result.latest !== undefined && result.latest.rev >= request.rev) {
-					recovered.add(blockId);
-				} else {
-					// Torn/partial state: recover() could not advance latest to request.rev (metadata
-					// absent, or a revision entry missing despite the promoted transaction). Fall back
-					// to treating the block as a genuine missing-pend error rather than silently succeeding.
-					missingPends.push({ blockId, actionId: request.actionId });
-				}
-			}
-
-			// NOTE: if a batch ever held BOTH a recovered D3 block and a genuine missing-pend block,
-			// this throw fires after recover() already advanced the D3 block durably, so that block's
-			// change event is skipped (the retry then treats it as alreadyDone and never re-emits;
-			// durable state stays correct, only the emit is lost). Judged unreachable today: a single
-			// crash mid-internalCommit leaves exactly one D3 block, with the rest alreadyDone or
-			// pending-present — a never-pended block cannot coexist with it in one retry. If a path
-			// ever produces that mix, emit recovered blocks' events before throwing here.
-			if (missingPends.length) {
-				// Divergence (this node is behind): `ClusterMember` treats this throw as the canonical
-				// "behind" signal and reconciles EVERY block in the batch, advancing each past
-				// `request.rev`. Nothing can promote the pendings the other blocks still hold, so drop
-				// them here — while the latches are still held — before reporting. The thrown message
-				// must stay byte-identical: `ClusterMember.isMissingPendingActionError` matches on it.
-				await this.dropUnpromotablePendings(toCommit, request.actionId);
-				throw new Error(`Pending action ${request.actionId} not found for block(s): ${missingPends.map(p => p.blockId).join(', ')}`);
-			}
-
-			// The original commit crashed before setLatest, so it also never emitted a change event
-			// for a recovered (Crash-D3) block. Now that recover() has committed it at request.rev,
-			// report its collection so downstream watchers wake — mirroring internalCommit. Resolve
-			// the collectionId from the now-materialized block; a delete materializes to a tombstone
-			// (getBlock → undefined), so fall back to the prior materialized block's header exactly as
-			// internalCommit does — otherwise a recovered delete would silently fail to wake watchers.
-			// Only when neither resolves (a delete-only block with no prior materialization) is the
-			// emit skipped, the same terminal fallback internalCommit uses.
-			for (const { blockId, storage } of toCommit) {
-				if (!recovered.has(blockId)) {
-					continue;
-				}
-				const collectionId = (await storage.getBlock(request.rev))?.block.header.collectionId
-					?? (await storage.getBlock(request.rev - 1))?.block.header.collectionId;
-				if (collectionId !== undefined) {
-					const list = collectionBlocks.get(collectionId) ?? [];
-					list.push(blockId);
-					collectionBlocks.set(collectionId, list);
-				}
-			}
-
-			// Commit the action for each block that still needs it.
-			// This loop will execute atomically for all blocks due to the acquired locks.
-			// Recovered (Crash-D3) blocks are already committed at request.rev and their pending is
-			// gone, so skip them — internalCommit would throw on the missing pending record.
-			//
-			// Set when the mid-loop failure was a divergence rather than a genuine fault — the split
-			// documented on commit() above, which decides the fate of the batch's pending records.
-			let divergentFailure = false;
-			for (const { blockId, storage } of toCommit) {
-				if (recovered.has(blockId)) {
-					continue;
-				}
-				try {
-					// internalCommit will throw if it encounters an issue
-					const collectionId = await this.internalCommit(blockId, request.actionId, request.rev, storage);
-					if (collectionId !== undefined) {
-						const list = collectionBlocks.get(collectionId) ?? [];
-						list.push(blockId);
-						collectionBlocks.set(collectionId, list);
-					}
-				} catch (err) {
-					// Partial-commit recovery: blocks already in collectionBlocks DID land
-					// durably and must still emit; a retry with the same (actionId, rev)
-					// treats them as idempotent no-ops and advances the remainder. Break
-					// instead of returning so locks release and those landings emit below.
-					failure = { reason: err instanceof Error ? err.message : 'Unknown error during commit' };
-					divergentFailure = err instanceof MissingBaseRevisionError;
-					break;
-				}
-			}
-
-			// The break left every not-yet-reached block still holding its pending record. Whether
-			// that record is still usable depends ENTIRELY on why we stopped — see the table on
-			// commit() above. Runs inside the try, so the per-block latches are still held.
-			// NOTE: a non-divergence fault deliberately KEEPS the batch's pendings so a retry can
-			// replay them. If ClusterMember ever stops retrying propagated commit faults, this arm
-			// becomes dead weight and the discriminator can collapse to "always drop".
-			if (divergentFailure) {
-				await this.dropUnpromotablePendings(toCommit, request.actionId);
-			}
-		}
-		finally {
-			// Release locks in reverse order of acquisition
-			releases.reverse().forEach(release => release());
-		}
-
-		// Notify after the critical section, for every block newly committed here —
-		// including those that landed before a mid-loop failure (alreadyDone / stale
-		// partitions never reach `collectionBlocks`).
-		this.emitCollectionChanges(collectionBlocks, request.actionId, request.rev, request.tailId);
-
-		return failure ? { success: false, reason: failure.reason } : { success: true };
-	}
-
-	/**
-	 * Delete `actionId`'s pending record from every given block, tolerating absence.
-	 *
-	 * Called by {@link commit} when it abandons a batch **because this node has diverged from the
-	 * agreed history** — the caller has already made that determination; this helper does not
-	 * re-derive it. Once `ClusterMember` reconciles the batch, every one of these blocks sits at or
-	 * past `request.rev`, so a commit retry partitions them as already-done/stale and never revisits
-	 * their pendings; left in place they are reported as phantom conflicting actions by {@link pend}
-	 * for every later write to the block (under `policy: 'f'`, forever).
-	 *
-	 * No special-casing is needed for blocks that already landed (record promoted), that were
-	 * `recovered` (record already gone), or for the refusing block itself
-	 * ({@link refuseMissingBase} deleted its record): deleting an absent pending record is a no-op on
-	 * every backend.
-	 *
-	 * Per-block failures are logged and swallowed rather than propagated: this cleanup must never
-	 * replace the failure the caller is about to report — the pre-loop throw's message is pattern-
-	 * matched by `ClusterMember.isMissingPendingActionError`, and a swapped error would misroute
-	 * consensus. A leftover record only degrades this node's participation in that one block.
-	 */
-	private async dropUnpromotablePendings(
-		blocks: { blockId: BlockId, storage: IBlockStorage }[],
-		actionId: ActionId
-	): Promise<void> {
-		if (blocks.length === 0) {
-			return;
-		}
-		log('commit:drop-unpromotable-pendings actionId=%s blockIds=%d', actionId, blocks.length);
-		await Promise.all(blocks.map(async ({ blockId, storage }) => {
-			try {
-				await storage.deletePendingTransaction(actionId);
-			} catch (err) {
-				log('commit:drop-unpromotable-pending-failed blockId=%s actionId=%s error=%s', blockId, actionId,
-					err instanceof Error ? err.message : String(err));
-			}
-		}));
-	}
-
-	/**
-	 * Reconciles `metadata.latest` for a single block with the highest contiguous
-	 * fully-promoted revision in durable storage. Use after a crash between
-	 * `promotePendingTransaction` and `setLatest` when retry-commit cannot help
-	 * (the pending record is already gone) but the revision and committed-log entry
-	 * are durable. Idempotent and monotonic.
-	 */
-	async recoverBlock(blockId: BlockId): Promise<void> {
-		log('recoverBlock blockId=%s', blockId);
-		const storage = this.createBlockStorage(blockId);
-		// Hold the per-block commit latch: recover() is a read-modify-write of meta.latest that
-		// blindly writes back the metadata object it read, so its "advance only" guard is TOCTOU —
-		// racing a concurrent commit()/saveReplicatedBlock that advanced latest in between would
-		// clobber it (a non-monotonic regression). Same latching invariant as every other
-		// latest-mutating site. commit() calls storage.recover() directly under its own held latch,
-		// so it never routes through here — no double-acquire / deadlock.
-		await withBlockCommitLatch(blockId, () => storage.recover());
-	}
-
-	/**
-	 * Persist a replica of a block received out-of-band (churn re-replication) into
-	 * local storage. Distinct from the {@link IRepo} commit funnel: the block arrives
-	 * already materialized from a departing owner, not as a pend/commit. See
-	 * {@link IBlockStorage.saveReplica} for the durability/monotonicity contract.
-	 *
-	 * Held under the same `StorageRepo.commit:<id>` latch as {@link commit} so the
-	 * replica's read-modify-write of `latest` is mutually exclusive with a concurrent
-	 * local commit on the same block — otherwise `saveReplica`'s monotonic guard could
-	 * read a stale `latest` and clobber a commit that advanced it in between.
-	 */
-	async saveReplicatedBlock(blockId: BlockId, block: IBlock, source?: ActionRev): Promise<void> {
-		log('saveReplicatedBlock blockId=%s rev=%s', blockId, source?.rev);
-		const storage = this.createBlockStorage(blockId);
-		const release = await Latches.acquire(commitLatchKey(blockId));
-		// Captured under the latch; emitted after release to match commit's ordering.
-		let landed: { collectionId: CollectionId, actionId: ActionId, rev: number } | undefined;
-		try {
-			const priorLatest = await storage.getLatest();
-			const effective = await storage.saveReplica(block, source);
-			// Advanced iff there was no prior revision or the effective rev moved past it. On the
-			// monotonic no-op, saveReplica returns the held latest unchanged → effective.rev === priorLatest.rev.
-			const advanced = priorLatest === undefined || effective.rev > priorLatest.rev;
-			const collectionId = block.header?.collectionId;
-			if (advanced && collectionId !== undefined) {
-				landed = { collectionId, actionId: effective.actionId, rev: effective.rev };
-			}
-		} finally {
-			release();
-		}
-		// Replica-persist has no CommitRequest, hence no tailId — like a read-driven promotion,
-		// this wakes local onCollectionChange watchers but is cert-gated out of cohort-topic
-		// re-origination downstream (change-bridge selfIsCohortMember treats a tail-less event as
-		// never a member).
-		if (landed) {
-			this.emitCollectionChanges(
-				new Map([[landed.collectionId, [blockId]]]),
-				landed.actionId,
-				landed.rev,
-			);
-		}
-	}
-
-	private async internalCommit(blockId: BlockId, actionId: ActionId, rev: number, storage: IBlockStorage): Promise<CollectionId | undefined> {
-		// Note: This method is called under the per-block commit latch — by commit() (within its
-		// locked critical section) and by the read-driven promotion in get() (which now takes the
-		// same latch). So, operations like getPendingTransaction, getLatest, getBlock,
-		// saveMaterializedBlock, saveRevision, promotePendingTransaction, setLatest are protected
-		// against concurrent commits for the *same blockId*.
-
-		const transform = await storage.getPendingTransaction(actionId);
-		// No need to check if !transform here, as the caller (commit) already verified this.
-		// If it's null here, it indicates a logic error or race condition bypassed the lock (unlikely).
-		if (!transform) {
-			throw new Error(`Consistency Error: Pending action ${actionId} disappeared for block ${blockId} within critical section.`);
-		}
-
-		// Get prior materialized block if it exists
-		const latest = await storage.getLatest();
-		const priorBlock = await this.readCommitBase(blockId, actionId, rev, storage, latest);
-
-		// Apply transform and save materialized block
-		// applyTransform handles undefined priorBlock correctly for inserts
-		const newBlock = applyTransform(priorBlock, transform);
-
-		// INVARIANT: `latest` must never advance past a revision this node can materialize.
-		// `applyTransform` silently drops `updates` when there is no block to apply them to, so a
-		// member that missed the block's CREATING revision would otherwise record rev N while storing
-		// nothing to serve it from. `latest === undefined` is precisely the "nothing below to fall
-		// back to" case: materializeBlock's descending walk needs some materialization at or below the
-		// target, and with no prior revision there is none. With a prior `latest` an absent newBlock is
-		// a legitimate tombstone (the walk resolves to an earlier materialization), so it stays allowed.
-		if (!newBlock && latest === undefined) {
-			return await this.refuseMissingBase(blockId, actionId, rev, storage,
-				'no committed revision to apply the transform to');
-		}
-
-		if (newBlock) {
-			await storage.saveMaterializedBlock(actionId, newBlock);
-		}
-
-		// Save revision and promote action *before* updating latest
-		// This ensures that if the process crashes between these steps,
-		// the 'latest' pointer doesn't point to a revision that hasn't been fully recorded.
-		await storage.saveRevision(rev, actionId);
-		await storage.promotePendingTransaction(actionId);
-
-		// Update latest revision *last*
-		await storage.setLatest({ actionId, rev });
-
-		// Prune the now-superseded prior materialization (checkpoint retention). Runs LAST — after the
-		// new rev's materialization + revision + transform + setLatest are all durable — so no crash
-		// point can leave a rev unrecoverable: a crash BEFORE this leaves a redundant (harmless)
-		// materialization the next commit's prune reclaims; a crash AFTER is fully consistent. The prune
-		// only ever deletes a materialization reconstructible from the retained floor + transforms. Runs
-		// under the per-block commit latch already held here, so it serializes against concurrent commits.
-		// NOTE: prune targets ONLY the immediate prior. A crash between setLatest and this call leaves that
-		// one prior materialization un-pruned; since a later commit prunes ITS OWN prior (never the earlier
-		// leaked rev), that copy is NOT auto-reclaimed — a bounded (≤1 block-copy per crash), harmless leak
-		// (state stays consistent + reconstructible). If crash-before-prune leaks ever accumulate materially,
-		// add a bounded look-back (prune non-retained mats in [rev-checkpointInterval, rev)) here, or a
-		// periodic reconciliation sweep — do NOT reintroduce a per-read re-cache.
-		if (latest !== undefined) {
-			await storage.pruneSupersededMaterialization(latest);
-		}
-
-		// Report the affected collection for change-event routing. For a delete the
-		// materialized block is undefined, so fall back to the prior block's header.
-		// Either may be absent only for a malformed/headerless block — return
-		// undefined so the caller skips it rather than emitting a bogus event.
-		return newBlock?.header.collectionId ?? priorBlock?.header.collectionId;
-	}
-
-	/**
-	 * The materialization this commit builds on: the block at `latest`, or `undefined` when the block
-	 * holds no committed revision yet (the normal insert case).
-	 *
-	 * `getBlock` THROWS when this node holds a `latest` it cannot materialize — a block already wedged
-	 * by a pre-fix commit, or by truncated history. That is the same divergence as having no base at
-	 * all, so it is translated into {@link MissingBaseRevisionError} rather than surfacing as an opaque
-	 * storage fault: the healing path can then repair the block instead of the fault resetting the
-	 * cluster stream, and a wedged node recovers on the next write touching the block.
-	 *
-	 * The catch is deliberately UNNARROWED — it also absorbs a transient fault (a raw-storage read
-	 * error, a `restoreCallback` timeout on a block whose `ranges` do not cover its own `latest`).
-	 * BlockStorage reports every one of these as a bare `Error`, so they cannot be told apart here,
-	 * and treating them as divergence is the safe default: this node genuinely cannot materialize the
-	 * base right now, and the cluster's policy is to heal rather than throw out of consensus. The
-	 * price is that a transient fault ALSO drops pending records — this block's (see
-	 * {@link refuseMissingBase}) AND, because {@link commit} keys its cleanup off the same error type,
-	 * every not-yet-reached block in the same batch — so those blocks converge by replication instead
-	 * of by a replay the retry could have done. That is a wider blast radius than the per-block
-	 * refusal alone, and it is why the discriminator must NOT be loosened beyond this error type.
-	 * Narrowing this would require typed faults out of BlockStorage; until then, prefer the tolerant
-	 * reading.
-	 */
-	private async readCommitBase(
-		blockId: BlockId,
-		actionId: ActionId,
-		rev: number,
-		storage: IBlockStorage,
-		latest: ActionRev | undefined
-	): Promise<IBlock | undefined> {
-		if (!latest) {
-			return undefined;
-		}
-		try {
-			return (await storage.getBlock(latest.rev))?.block;
-		} catch (err) {
-			log('commit:unmaterializable-base blockId=%s baseRev=%d error=%s', blockId, latest.rev,
-				err instanceof Error ? err.message : String(err));
-			return await this.refuseMissingBase(blockId, actionId, rev, storage,
-				`local rev ${latest.rev} is not materializable here`);
-		}
-	}
-
-	/**
-	 * Refuse a commit this node cannot materialize. Always throws {@link MissingBaseRevisionError};
-	 * nothing durable has been written at this point, so the block is left exactly as it was minus the
-	 * pending record.
-	 *
-	 * The pending is dropped because it can never be promoted here: promotion needs a base this node
-	 * must obtain out-of-band, and once the healing path lands that revision `latest` is already >= rev,
-	 * so a commit retry partitions the block as already-done/stale and never revisits the pending.
-	 * Leaving it would also report a phantom conflicting action from {@link pend} for every later write.
-	 */
-	private async refuseMissingBase(
-		blockId: BlockId,
-		actionId: ActionId,
-		rev: number,
-		storage: IBlockStorage,
-		detail: string
-	): Promise<never> {
-		await storage.deletePendingTransaction(actionId);
-		log('commit:missing-base blockId=%s rev=%d actionId=%s detail=%s', blockId, rev, actionId, detail);
-		throw new MissingBaseRevisionError(blockId, rev, detail);
-	}
-}
-
-/**
- * Converts list of missing actions per block into a list of missing actions across blocks.
- *
- * NOTE: relies on each (actionId, blockId) pair appearing at most once — one revision per action
- * per block. If a block ever records two revisions under the same actionId, concatTransform now
- * concatenates both revisions' ops into one array rather than dropping the earlier one — still
- * wrong, since ops from distinct revisions are not composable against a single base, but loud
- * rather than silent. Group by (actionId, rev) instead if that case becomes reachable.
- */
-function perBlockActionTransformsToPerAction(missing: { blockId: BlockId; transforms: ActionTransform[]; }[]) {
-	const missingFlat = missing.flatMap(({ blockId, transforms }) =>
-		transforms.map(transform => ({ blockId, transform }))
-	);
-	const missingByActionId = groupBy(missingFlat, ({ transform }) => transform.actionId);
-	return Object.entries(missingByActionId).map(([actionId, items]) =>
-		items.reduce((acc, { blockId, transform }) => {
-			acc.transforms = concatTransform(acc.transforms, blockId, transform.transform);
-			return acc;
-		}, {
-			actionId: actionId as ActionId,
-			rev: items[0]!.transform.rev,	// Assumption: an action commits at one revision, so every block's entry for this actionId agrees. Distinct actionIds may still carry distinct revs.
-			transforms: emptyTransforms()
-		})
-	);
-}
+import type {
+	IRepo, MessageOptions, BlockId, CommitRequest, CommitResult, GetBlockResults, PendRequest, PendResult, ActionBlocks,
+	ActionId, BlockGets, ActionPending, PendSuccess, ActionTransform, ActionTransforms,
+	GetBlockResult, IBlock, ActionRev, BlockUnavailableReason,
+	PendValidationHook,
+	CollectionId, IBlockChangeNotifier, CollectionChangeListener, CollectionChangeEvent,
+	StaleFailure
+} from "@optimystic/db-core";
+import {
+	Latches, transformForBlockId, applyTransform, groupBy, concatTransform, emptyTransforms,
+	blockIdsForTransforms, transformsFromTransform, highestStaleAt
+} from "@optimystic/db-core";
+import { asyncIteratorToArray } from "../it-utility.js";
+import type { IBlockStorage } from "./i-block-storage.js";
+import type { IBlockReplicaStore } from "../cluster/block-transfer-service.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('storage-repo');
+
+/**
+ * Single source of truth for the per-block commit latch key. Held by {@link StorageRepo.commit} and
+ * {@link StorageRepo.saveReplicatedBlock}, and — through an injected runner ({@link withBlockCommitLatch})
+ * — by the invalidation-apply path. Every out-of-band writer of a block's `meta.latest` must serialize
+ * on this key against a concurrent local commit on the same block; keeping all call sites on this helper
+ * is what prevents the key from drifting between them.
+ */
+export const commitLatchKey = (blockId: BlockId): string => `StorageRepo.commit:${blockId}`;
+
+/**
+ * Runs `fn` while holding the per-block commit latch {@link commitLatchKey}. This is the capability the
+ * dispute module's `applyInvalidation` is handed (through its context) so its compensating
+ * `saveReplica`/`saveDeletion` read-modify-write of `meta.latest` is mutually exclusive with a concurrent
+ * {@link StorageRepo.commit} on the same block — otherwise an invalidation advancing `latest` outside
+ * that latch is invisible to commit's staleness guard and can be clobbered (a non-monotonic regression).
+ *
+ * Acquire/release is per call, so a caller holds at most one block latch at any instant and cannot
+ * deadlock against commit's sorted, up-front multi-latch acquisition.
+ */
+export async function withBlockCommitLatch<T>(blockId: BlockId, fn: () => Promise<T>): Promise<T> {
+	const release = await Latches.acquire(commitLatchKey(blockId));
+	try {
+		return await fn();
+	} finally {
+		release();
+	}
+}
+
+/**
+ * Stable, greppable prefix on the failure reason a commit carries when this node cannot materialize
+ * the revision it was asked to record. It is a STRING marker rather than only an error class because
+ * {@link StorageRepo.commit} reports per-block faults as `StaleFailure.reason` (a plain string that
+ * also crosses the wire), so the class identity is lost by the time a caller inspects the result.
+ */
+export const MISSING_BASE_REVISION_REASON = 'missing-base-revision';
+
+/**
+ * This node was asked to commit revision N of a block it holds no materializable base for, so
+ * applying the transform would materialize nothing while `latest` advanced to N — a block that is
+ * then unreadable locally, unservable to peers, and that rejects every later write (see
+ * {@link StorageRepo.internalCommit}). The commit is refused instead; the caller heals the node
+ * out-of-band (`ClusterMember` pulls the committed revision from a cohort peer) and retries.
+ */
+export class MissingBaseRevisionError extends Error {
+	constructor(readonly blockId: BlockId, readonly rev: number, detail: string) {
+		super(`${MISSING_BASE_REVISION_REASON}: block ${blockId} cannot materialize rev ${rev} — ${detail}`);
+		this.name = 'MissingBaseRevisionError';
+	}
+}
+
+/**
+ * True when a {@link CommitResult} failed because this node holds no materializable base for one of
+ * the committed blocks. Distinguishes that recoverable divergence (heal by fetching the block from a
+ * cohort peer) from a genuine storage fault, which must still propagate.
+ */
+export function isMissingBaseRevisionFailure(result: CommitResult): boolean {
+	return !result.success && (result.reason?.startsWith(MISSING_BASE_REVISION_REASON) ?? false);
+}
+
+export type StorageRepoOptions = {
+	/** Optional hook to validate transactions in PendRequests */
+	validatePend?: PendValidationHook;
+};
+
+export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaStore {
+	private readonly validatePend?: PendValidationHook;
+	/** Per-collection change listeners; empty sets are pruned on unsubscribe. */
+	private readonly changeListeners = new Map<CollectionId, Set<CollectionChangeListener>>();
+	/** Catch-all change listeners — fire for EVERY collection's commit on this node. */
+	private readonly anyChangeListeners = new Set<CollectionChangeListener>();
+
+	constructor(
+		private readonly createBlockStorage: (blockId: BlockId) => IBlockStorage,
+		options?: StorageRepoOptions
+	) {
+		this.validatePend = options?.validatePend;
+	}
+
+	/**
+	 * Subscribe to commits that mutate `collectionId`'s blocks on this node.
+	 * Returns an idempotent unsubscribe. See {@link IBlockChangeNotifier}.
+	 */
+	onCollectionChange(collectionId: CollectionId, listener: CollectionChangeListener): () => void {
+		let set = this.changeListeners.get(collectionId);
+		if (!set) {
+			set = new Set();
+			this.changeListeners.set(collectionId, set);
+		}
+		set.add(listener);
+		let unsubscribed = false;
+		return () => {
+			if (unsubscribed) return;
+			unsubscribed = true;
+			const current = this.changeListeners.get(collectionId);
+			if (current) {
+				current.delete(listener);
+				if (current.size === 0) {
+					this.changeListeners.delete(collectionId);
+				}
+			}
+		};
+	}
+
+	/**
+	 * Subscribe to commits mutating ANY collection on this node — the catch-all feed the
+	 * cohort-topic origination bridge consumes (it cannot enumerate collection ids ahead of time,
+	 * so a per-collection {@link onCollectionChange} subscription cannot see every commit). Fires for
+	 * the same `(pending → committed)` transitions as {@link onCollectionChange}, but across every
+	 * collection. Returns an idempotent unsubscribe; a throwing listener is isolated + logged.
+	 */
+	onAnyCollectionChange(listener: CollectionChangeListener): () => void {
+		this.anyChangeListeners.add(listener);
+		let unsubscribed = false;
+		return () => {
+			if (unsubscribed) return;
+			unsubscribed = true;
+			this.anyChangeListeners.delete(listener);
+		};
+	}
+
+	/**
+	 * Fire one {@link CollectionChangeEvent} per distinct collection that was
+	 * newly committed. Called AFTER the commit critical section (locks released),
+	 * fire-and-forget synchronous; a throwing listener is isolated and logged. Each event reaches
+	 * both that collection's {@link onCollectionChange} subscribers and every
+	 * {@link onAnyCollectionChange} catch-all subscriber.
+	 *
+	 * `tailId` is the `CommitRequest.tailId` on the commit path; `undefined` on read-driven
+	 * promotions (the get/emitPromotions path has no commit request). A single commit is for one
+	 * collection's chain in practice, so all events from one commit share the same `tailId`.
+	 */
+	private emitCollectionChanges(collectionBlocks: Map<CollectionId, BlockId[]>, actionId: ActionId, rev: number, tailId?: BlockId): void {
+		const hasCatchAll = this.anyChangeListeners.size > 0;
+		for (const [collectionId, blockIds] of collectionBlocks) {
+			const listeners = this.changeListeners.get(collectionId);
+			if ((!listeners || listeners.size === 0) && !hasCatchAll) {
+				continue;
+			}
+			const event: CollectionChangeEvent = { collectionId, blockIds, actionId, rev, tailId };
+			if (listeners && listeners.size > 0) {
+				this.fireChangeListeners(listeners, event);
+			}
+			if (hasCatchAll) {
+				this.fireChangeListeners(this.anyChangeListeners, event);
+			}
+		}
+	}
+
+	/** Dispatch `event` to a snapshot of `listeners` (safe under mid-emit (un)subscribe), isolating + logging any throw. */
+	private fireChangeListeners(listeners: Set<CollectionChangeListener>, event: CollectionChangeEvent): void {
+		for (const listener of Array.from(listeners)) {
+			try {
+				listener(event);
+			} catch (err) {
+				log('onCollectionChange listener threw for collection=%s: %o', event.collectionId, err);
+			}
+		}
+	}
+
+	async get({ blockIds, context }: BlockGets, _options?: MessageOptions): Promise<GetBlockResults> {
+		const distinctBlockIds = Array.from(new Set(blockIds));
+		log('get blockIds=%d', distinctBlockIds.length);
+		// Read-driven promotions that land durably here, captured so we can emit a
+		// change event per durable landing after the parallel reads complete (mirrors
+		// commit's "emit after the work" ordering). The array is shared across the
+		// parallel map closures below — safe because each push happens synchronously
+		// between awaits (single-threaded), never concurrently.
+		const promotions: { collectionId: CollectionId, blockId: BlockId, actionId: ActionId, rev: number }[] = [];
+		const results = await Promise.all(distinctBlockIds.map(async (blockId) => {
+			const blockStorage = this.createBlockStorage(blockId);
+			// Set when this node KNOWS its answer for the block is a guess: the promotion
+			// below refused for a missing base, or getBlock() threw (truncated history /
+			// failed restore). An absent-reading block then reports `unavailable` instead of
+			// posing as an authoritative "never existed" — see BlockUnavailableReason.
+			let unavailable: BlockUnavailableReason | undefined;
+
+			// Ensure that all outstanding transactions in the context are committed.
+			// This promotes a landed-elsewhere pending via internalCommit, which mutates
+			// meta.latest — the same read-modify-write commit()/saveReplicatedBlock guard
+			// with the per-block commit latch. It MUST hold that latch too, or a promotion
+			// racing a concurrent commit on the block regresses latest non-monotonically /
+			// cross-writes a revision. Cheap unlatched pre-scan first so the common
+			// contextless read and no-pending read never pay for latch acquisition; the
+			// authoritative decision is re-made inside the latch.
+			if (context) {
+				const preLatest = await blockStorage.getLatest();
+				const preMissing = preLatest
+					? context.committed.filter(c => c.rev > preLatest.rev)
+					: context.committed;
+				if (preMissing.length > 0) {
+					await withBlockCommitLatch(blockId, async () => {
+						// Re-read authoritative state under the latch: a concurrent commit may have
+						// promoted or superseded a pending between the unlatched pre-scan and here.
+						// Recompute which committed entries are still ahead of `latest` (drops the
+						// superseded, rev <= latest.rev) and re-fetch each pending inside the loop
+						// (skips the already-promoted, pending gone). This makes read-driven
+						// promotion idempotent under races, mirroring commit()'s alreadyDone/stale
+						// partitioning.
+						const latest = await blockStorage.getLatest();
+						const missing = latest
+							? context.committed.filter(c => c.rev > latest.rev)
+							: context.committed;
+						// Sort a COPY: when `latest` is undefined, `missing` aliases the caller's
+						// `context.committed` array, and an in-place `.sort()` would reorder the shared
+						// request context under the caller's feet.
+						try {
+							for (const { actionId, rev } of [...missing].sort((a, b) => a.rev - b.rev)) {
+								const pending = await blockStorage.getPendingTransaction(actionId);
+								if (pending) {
+									const collectionId = await this.internalCommit(blockId, actionId, rev, blockStorage);
+									if (collectionId !== undefined) {
+										promotions.push({ collectionId, blockId, actionId, rev });
+									}
+								}
+							}
+						} catch (err) {
+							// This node holds no materializable base for the block, so NO context revision
+							// can be promoted here (each builds on the one before). Leave `latest` where it
+							// is — the invariant internalCommit just enforced — and let the commit-path
+							// healing supply the content; a read must not fail for it. Every other fault
+							// still propagates.
+							if (!(err instanceof MissingBaseRevisionError)) {
+								throw err;
+							}
+							// This node holds records PROVING the block exists (a pending it could not
+							// promote); if the block then reads as absent below, the answer is a guess,
+							// not an authoritative "never existed".
+							unavailable = 'unmaterializable';
+							log('get:promote-skipped-missing-base blockId=%s rev=%d reason=%s', blockId, err.rev, err.message);
+						}
+					});
+				}
+			}
+
+			// NOTE: a Crash-D3 block (durably promoted + revision saved, but the setLatest lost so
+			// meta.latest is stale and the pending record is gone) reads as empty/stale here — a
+			// context-driven get skips promotion (pending gone) and a default getBlock() sees the
+			// stale latest. It is soft-wedged (stale), not hard-wedged: the next commit-retry for
+			// (actionId, rev) self-heals it via storage.recover() in commit(). Not repaired lazily on
+			// the read path because get() holds no commit latch; if stale reads on unwritten blocks
+			// ever become a problem, add a latched lazy recover() here.
+			//
+			// getBlock() THROWS when this node holds a `latest` it cannot materialize (truncated
+			// history: "Failed to find materialized block", or a failed restore). Caught PER BLOCK so
+			// one broken block cannot fail the whole batch's Promise.all and take healthy siblings
+			// down with it. The read still fails for THIS block — TransactorSource throws
+			// BlockUnavailableError on the flagged entry — so nothing is swallowed.
+			let blockRev: Awaited<ReturnType<IBlockStorage['getBlock']>>;
+			try {
+				blockRev = await blockStorage.getBlock(context?.rev);
+			} catch (err) {
+				// NOTE: the entry drops `state.latest`, which this node does know (getLatest() does not
+				// materialize, so it does not throw). Empty state is what makes CoordinatorRepo treat the
+				// block as missing and consult the cohort — exactly the repair this block needs. If a
+				// consumer ever needs the revision behind an unavailable answer (e.g. to ask the cohort
+				// for a specific rev instead of the whole block), carry `latest` here and widen the
+				// coordinator's consult trigger to `isMissing || unavailable` so repair still fires.
+				log('get:unmaterializable blockId=%s error=%s', blockId,
+					err instanceof Error ? err.message : String(err));
+				return [blockId, { state: {}, unavailable: 'unmaterializable' } as GetBlockResult];
+			}
+
+			// Include pending action if requested, applying the pending transform over whatever
+			// committed base getBlock() resolved (possibly none — a pending-only insert has no
+			// committed revision under it and getBlock reports that as an absent base, not a fault).
+			if (context?.actionId !== undefined) {
+				const pendingTransform = await blockStorage.getPendingTransaction(context.actionId);
+				if (!pendingTransform) {
+					if (unavailable !== undefined) {
+						// The promotion refusal above deleted this very pending record
+						// (`refuseMissingBase` drops the pending it cannot promote). This node DID hold
+						// the record and dropped it, so the honest answer is an availability one — not
+						// a caller-contract violation, and never a throw that would fail the whole batch.
+						return [blockId, { state: {}, unavailable } as GetBlockResult];
+					}
+					// Caller-contract violation (the caller asserted a pending this repo never had, or
+					// cancelled) — an error, not an availability question. Deliberately NOT `unavailable`.
+					//
+					// It is NOT the only way to reach here. A context that both PROVES its own action
+					// (`committed` names it) and names it as the pending overlay (`actionId`) is
+					// self-contradictory, and the two halves of that contradiction land differently: if
+					// the read-driven promotion above REFUSED, the arm above answers gracefully; if it
+					// SUCCEEDED, `promotePendingTransaction` moved the record and we throw here — failing
+					// the whole batch for a request the refusal path tolerates. No production code sets
+					// `ActionContext.actionId` at all today, so neither is reachable except from tests or
+					// a peer that crafts the field on the wire. See
+					// tickets/blocked/repo-pending-overlay-has-no-producer.
+					throw new Error(`Pending action ${context.actionId} not found`);
+				}
+				const block = applyTransform(blockRev?.block, pendingTransform);
+				return [blockId, {
+					block,
+					state: {
+						latest: await blockStorage.getLatest(),
+						pendings: [context.actionId]
+					},
+					// The COMMITTED revision underneath the pending overlay. A pending has no revision
+					// of its own, so the honest answer is the base it was applied to. Absent when there
+					// was no base at all — a pending-only insert served over an absent committed base,
+					// where fabricating a revision would claim content this node never committed.
+					...(blockRev ? { materializedRev: blockRev.actionRev.rev } : {}),
+					// A pending applied to a missing base can materialize nothing (applyTransform drops
+					// updates with no block to apply them to) — that absence is a guess, and is flagged.
+					// A materialized block is a real answer regardless of the earlier refusal. TWO ways
+					// an empty result is a guess: the promotion refusal fired (`unavailable` set), or
+					// there was no committed base under the overlay at all (`blockRev === undefined`) —
+					// this node holds a pending record PROVING the block exists and produced nothing.
+					// The second clause's ABSENCE in the other direction is equally load-bearing: a
+					// pending DELETE over a real committed base also lands here with no block, and that
+					// is an authoritative tombstone which must stay unflagged.
+					...(block === undefined && (unavailable !== undefined || blockRev === undefined)
+						? { unavailable: unavailable ?? 'unmaterializable' }
+						: {})
+				} as GetBlockResult];
+			}
+
+			if (!blockRev) {
+				// `unavailable` distinguishes "never existed" (the common insert-probe case, no flag)
+				// from "this node cannot reconstruct it" (the promotion above refused for a missing
+				// base). A tombstoned block also lands here with meta.latest set, but it never enters
+				// the missing-base catch, so it stays an authoritative absent — keyed off the explicit
+				// flag, not off "no block".
+				return [blockId, { state: {}, ...(unavailable !== undefined ? { unavailable } : {}) } as GetBlockResult];
+			}
+
+			const pendings = await asyncIteratorToArray(blockStorage.listPendingTransactions());
+			return [blockId, {
+				block: blockRev.block,
+				// `getBlock(context?.rev)` materialized the content at the highest committed revision
+				// at or below the pin, and reports it as `actionRev` — report THAT alongside the
+				// content. `state.latest` deliberately stays the node's newest revision for the block
+				// (StorageRepo.get's own promotion pre-scan and CoordinatorRepo's read-repair compare
+				// against it), so the two disagree exactly when a pinned read is serving older content.
+				materializedRev: blockRev.actionRev.rev,
+				state: {
+					latest: await blockStorage.getLatest(),
+					pendings
+				}
+			}];
+		}));
+
+		// Emit per durable read-driven landing (Option A — emit eagerly). Done after the
+		// parallel reads complete so emission stays outside the per-block work, matching
+		// commit's ordering. No-op when nothing was promoted.
+		this.emitPromotions(promotions);
+
+		return Object.fromEntries(results);
+	}
+
+	/**
+	 * Emit a {@link CollectionChangeEvent} for each read-driven promotion that landed
+	 * during a {@link get}. A single get() can promote multiple distinct actions, each
+	 * at its own `(actionId, rev)`, so group by `(actionId, rev)` and route each group
+	 * through {@link emitCollectionChanges} once.
+	 */
+	private emitPromotions(promotions: { collectionId: CollectionId, blockId: BlockId, actionId: ActionId, rev: number }[]): void {
+		if (promotions.length === 0) {
+			return;
+		}
+		const groups = new Map<string, { actionId: ActionId, rev: number, collectionBlocks: Map<CollectionId, BlockId[]> }>();
+		for (const { collectionId, blockId, actionId, rev } of promotions) {
+			const key = `${actionId} ${rev}`;
+			let group = groups.get(key);
+			if (!group) {
+				group = { actionId, rev, collectionBlocks: new Map() };
+				groups.set(key, group);
+			}
+			const list = group.collectionBlocks.get(collectionId) ?? [];
+			list.push(blockId);
+			group.collectionBlocks.set(collectionId, list);
+		}
+		for (const { actionId, rev, collectionBlocks } of groups.values()) {
+			this.emitCollectionChanges(collectionBlocks, actionId, rev);
+		}
+	}
+
+	async pend(request: PendRequest, _options?: MessageOptions): Promise<PendResult> {
+		// Validate transaction if present and validation hook is configured
+		if (this.validatePend && request.transaction && request.operationsHash) {
+			const validationResult = await this.validatePend(request.transaction, request.operationsHash);
+			if (!validationResult.valid) {
+				// Hard rejection: the transaction itself is invalid, so no `conflict` flag — a
+				// re-read and re-pend would fail the same way and only burn the retry budget.
+				return {
+					success: false,
+					reason: validationResult.reason ?? 'Transaction validation failed'
+				};
+			}
+		}
+
+		const blockIds = blockIdsForTransforms(request.transforms);
+		log('pend actionId=%s blockIds=%d rev=%s', request.actionId, blockIds.length, request.rev);
+		const pendings: ActionPending[] = [];
+		const missing: ActionTransforms[] = [];
+		// Highest revision this node confirms holding among the blocks that are at or past the
+		// requested one — reported as StaleFailure.staleAt so a losing writer learns the number
+		// instead of parsing prose. Confirmed-local only: we read it from our own storage below.
+		let staleAt: StaleFailure['staleAt'];
+
+		// Potential race condition: A concurrent commit operation could complete
+		// between the conflict checks (latest.rev, listPendingTransactions) and the
+		// savePendingTransaction call below. This pend operation might succeed based on
+		// stale information, but the subsequent commit for this pend would likely
+		// fail correctly later if a conflict arose. Locking here could make the initial
+		// check more accurate but adds overhead. The current approach prioritizes
+		// letting the commit be the final arbiter.
+		for (const blockId of blockIds) {
+			const blockStorage = this.createBlockStorage(blockId);
+			const transforms = transformForBlockId(request.transforms, blockId);
+
+			// First handle any pending actions
+			const pending = await asyncIteratorToArray(blockStorage.listPendingTransactions());
+			pendings.push(...pending.map(actionId => ({ blockId, actionId })));
+
+			// Handle any conflicting revisions
+			if (request.rev !== undefined || transforms.insert) {
+				const latest = await blockStorage.getLatest();
+				if (latest && latest.rev >= (request.rev ?? 0)) {
+					// Only a real revision race yields a meaningful `staleAt`. When `request.rev` is
+					// undefined this same branch fires for an insert collision (the comparison degrades
+					// to `latest.rev >= 0`, true for any existing block), and reporting that block's
+					// revision would be a number that answers a question nobody asked.
+					if (request.rev !== undefined) {
+						staleAt = highestStaleAt([staleAt, { blockId, rev: latest.rev }]);
+					}
+					const transforms = await asyncIteratorToArray(blockStorage.listRevisions(request.rev ?? 0, latest.rev));
+					for (const actionRev of transforms) {
+						const transform = await blockStorage.getTransaction(actionRev.actionId);
+						if (!transform) {
+							throw new Error(`Missing action ${actionRev.actionId} for block ${blockId}`);
+						}
+						missing.push({
+							actionId: actionRev.actionId,
+							rev: actionRev.rev,
+							transforms: transformsFromTransform(transform, blockId)
+						});
+					}
+				}
+			}
+		}
+
+		if (missing.length) {
+			log('pend:stale actionId=%s missing=%d', request.actionId, missing.length);
+			return {
+				success: false,
+				conflict: true,
+				missing,
+				...(staleAt === undefined ? {} : { staleAt })
+			};
+		}
+
+		if (pendings.length > 0) {
+			if (request.policy === 'f') {	// Fail on pending actions
+				return { success: false, conflict: true, pending: pendings };
+			} else if (request.policy === 'r') {	// Return populated pending actions
+				return {
+					success: false,
+					conflict: true,
+					pending: await Promise.all(pendings.map(async action => {
+						const blockStorage = this.createBlockStorage(action.blockId);
+						return {
+							blockId: action.blockId,
+							actionId: action.actionId,
+							transform: (await blockStorage.getPendingTransaction(action.actionId))
+								?? (await blockStorage.getTransaction(action.actionId))!	// Possible that since enumeration, the action has been promoted
+						}
+					}))
+				};
+			}
+		}
+
+
+		// Simultaneously save pending action for each block
+		// Note: that this is not atomic, after we checked for conflicts and pending actions
+		// new pending or committed actions may have been added.  This is okay, because
+		// this check during pend is conservative.
+		await Promise.all(blockIds.map(blockId => {
+			const blockStorage = this.createBlockStorage(blockId);
+			const blockTransform = transformForBlockId(request.transforms, blockId);
+			return blockStorage.savePendingTransaction(request.actionId, blockTransform);
+		}));
+
+		return {
+			success: true,
+			pending: pendings,
+			blockIds
+		} as PendSuccess;
+	}
+
+	async cancel(actionRef: ActionBlocks, _options?: MessageOptions): Promise<void> {
+		log('cancel actionId=%s blockIds=%d', actionRef.actionId, actionRef.blockIds.length);
+		await Promise.all(actionRef.blockIds.map(blockId => {
+			const blockStorage = this.createBlockStorage(blockId);
+			return blockStorage.deletePendingTransaction(actionRef.actionId);
+		}));
+	}
+
+	/**
+	 * Commit a previously-pended action across its blocks, under the per-block commit latches.
+	 *
+	 * **Divergence vs genuine fault.** When the batch cannot be completed, the reason decides what
+	 * happens to the pending records the pend left behind. `ClusterMember.applyConsensusOperation`
+	 * makes the same split one layer up — it *tolerates* a divergence (and reconciles every
+	 * `commit.blockIds` entry from a cohort peer) but *propagates* a genuine fault for retry — so this
+	 * method must agree with it:
+	 *
+	 * - **Divergence** — this node is behind the agreed history, either because it holds no
+	 *   materializable base ({@link MissingBaseRevisionError}) or because it never received the pend
+	 *   (the `Pending action … not found` throw). Reconcile is guaranteed to follow and will advance
+	 *   every block in the batch past `request.rev`, so no pending record here can ever be promoted:
+	 *   {@link dropUnpromotablePendings} deletes them (see {@link refuseMissingBase}, which already
+	 *   accepts this tradeoff for the single refusing block).
+	 * - **Genuine fault** — any other throw out of {@link internalCommit} (a raw-storage error, …).
+	 *   `ClusterMember` propagates it and the commit is retried, and a retry can still replay the
+	 *   pendings, so they are KEPT.
+	 *
+	 * The stale/`missedCommits` early return (this node is AHEAD — it already holds a revision at or
+	 * past `request.rev`, committed under a different action) deliberately keeps pendings too, and its
+	 * cure is the losing client's `cancel`: `CoordinatorRepo.cancel` runs through consensus, so every
+	 * member drops the record, not just the coordinator. Replication cannot be the cure here — this
+	 * node is already ahead, and a later forward write carries a DIFFERENT action id, which is not
+	 * what `BlockStorage.saveForwardRevision` deletes. A client that dies between the stale result and
+	 * its `cancel` therefore still strands the record; that is pre-existing and orthogonal to the
+	 * divergence split above.
+	 */
+	async commit(request: CommitRequest, _options?: MessageOptions): Promise<CommitResult> {
+		log('commit actionId=%s rev=%d blockIds=%d', request.actionId, request.rev, request.blockIds.length);
+		const uniqueBlockIds = Array.from(new Set(request.blockIds)).sort();
+		const releases: (() => void)[] = [];
+		// Collects the blocks newly committed in this call, grouped by collection,
+		// so we can emit change events once locks are released. Blocks that land before
+		// a mid-loop failure stay here and are still emitted (Option A — emit eagerly):
+		// they are durably committed and a retry rolls the remainder forward.
+		const collectionBlocks = new Map<CollectionId, BlockId[]>();
+		// Captured when internalCommit throws mid-loop; we break (rather than return)
+		// so locks release and accumulated landings still emit before we report failure.
+		let failure: { reason: string } | undefined;
+
+		try {
+			// Acquire locks sequentially based on sorted IDs to prevent deadlocks
+			for (const id of uniqueBlockIds) {
+				const lockId = commitLatchKey(id);
+				const release = await Latches.acquire(lockId);
+				releases.push(release);
+			}
+
+			// --- Start of Critical Section ---
+
+			const blockStorages = request.blockIds.map(blockId => ({
+				blockId,
+				storage: this.createBlockStorage(blockId)
+			}));
+
+			// Partition blocks into:
+			//   - alreadyDone: latest.rev === request.rev && latest.actionId === request.actionId
+			//     (idempotent retry — a prior commit of this same action already landed here;
+			//     skip rather than treat as a conflict. Needed to rollforward stranded blocks
+			//     after a mid-batch crash committed some but not all blocks.)
+			//   - missedCommits: latest.rev >= request.rev but not the same actionId → real stale conflict.
+			//   - toCommit: latest.rev < request.rev or no latest yet → run internalCommit.
+			const toCommit: { blockId: BlockId, storage: IBlockStorage }[] = [];
+			const missedCommits: { blockId: BlockId, transforms: ActionTransform[] }[] = [];
+			// Highest revision among the blocks confirmed lost to a newer one — reported as
+			// StaleFailure.staleAt. The idempotent-retry `continue` below is a no-op, not a loss,
+			// so it never seeds this.
+			let staleAt: StaleFailure['staleAt'];
+			for (const entry of blockStorages) {
+				const { blockId, storage } = entry;
+				const latest = await storage.getLatest();
+				if (latest && latest.rev >= request.rev) {
+					if (latest.rev === request.rev && latest.actionId === request.actionId) {
+						// Idempotent no-op for this block — already committed with this exact (actionId, rev).
+						continue;
+					}
+					staleAt = highestStaleAt([staleAt, { blockId, rev: latest.rev }]);
+					const transforms: ActionTransform[] = [];
+					for await (const actionRev of storage.listRevisions(request.rev, latest.rev)) {
+						const transform = await storage.getTransaction(actionRev.actionId);
+						if (!transform) {
+							throw new Error(`Missing action ${actionRev.actionId} for block ${blockId}`);
+						}
+						transforms.push({
+							actionId: actionRev.actionId,
+							rev: actionRev.rev,
+							transform
+						});
+					}
+					missedCommits.push({ blockId, transforms });	// Push, even if transforms is empty, because we want to reject the older version
+					continue;
+				}
+				toCommit.push(entry);
+			}
+
+			if (missedCommits.length) {
+				log('commit:stale actionId=%s missed=%d', request.actionId, missedCommits.length);
+				return { // Return directly, locks will be released in finally
+					success: false,
+					missing: perBlockActionTransformsToPerAction(missedCommits),
+					...(staleAt === undefined ? {} : { staleAt })
+				};
+			}
+
+			// Check for missing pending actions only on blocks that still need to commit.
+			// Already-done blocks will have had their pending promoted, so skipping them here
+			// is what makes the idempotent rollforward work.
+			//
+			// A toCommit block whose pending is absent is one of two states:
+			//   - Crash-D3: the action was durably promoted and its revision saved, but the crash
+			//     lost the setLatest, so meta.latest is still < request.rev and the pending record
+			//     is gone. getTransaction(actionId) returns the promoted transform. Self-heal here
+			//     via storage.recover() (redoes the lost setLatest, advancing latest to the highest
+			//     contiguous promoted rev, >= request.rev). recover() is idempotent + monotonic, so
+			//     calling it under the already-held commit latch is safe. Recovered blocks are then
+			//     excluded from the internalCommit loop below — their pending is gone, so
+			//     internalCommit would throw.
+			//   - Genuine missing pend: the action was never promoted (getTransaction → undefined),
+			//     so the pend is truly missing. Throw exactly as before.
+			// Crash-D2 never reaches this branch: its pending record is still present.
+			const missingPends: { blockId: BlockId, actionId: ActionId }[] = [];
+			const recovered = new Set<BlockId>();
+			for (const { blockId, storage } of toCommit) {
+				const pendingAction = await storage.getPendingTransaction(request.actionId);
+				if (pendingAction) {
+					continue;
+				}
+				const promoted = await storage.getTransaction(request.actionId);
+				if (!promoted) {
+					missingPends.push({ blockId, actionId: request.actionId });
+					continue;
+				}
+				// Crash-D3 signature (pending absent + action durably promoted). Redo the lost setLatest.
+				const result = await storage.recover();
+				if (result.latest !== undefined && result.latest.rev >= request.rev) {
+					recovered.add(blockId);
+				} else {
+					// Torn/partial state: recover() could not advance latest to request.rev (metadata
+					// absent, or a revision entry missing despite the promoted transaction). Fall back
+					// to treating the block as a genuine missing-pend error rather than silently succeeding.
+					missingPends.push({ blockId, actionId: request.actionId });
+				}
+			}
+
+			// NOTE: if a batch ever held BOTH a recovered D3 block and a genuine missing-pend block,
+			// this throw fires after recover() already advanced the D3 block durably, so that block's
+			// change event is skipped (the retry then treats it as alreadyDone and never re-emits;
+			// durable state stays correct, only the emit is lost). Judged unreachable today: a single
+			// crash mid-internalCommit leaves exactly one D3 block, with the rest alreadyDone or
+			// pending-present — a never-pended block cannot coexist with it in one retry. If a path
+			// ever produces that mix, emit recovered blocks' events before throwing here.
+			if (missingPends.length) {
+				// Divergence (this node is behind): `ClusterMember` treats this throw as the canonical
+				// "behind" signal and reconciles EVERY block in the batch, advancing each past
+				// `request.rev`. Nothing can promote the pendings the other blocks still hold, so drop
+				// them here — while the latches are still held — before reporting. The thrown message
+				// must stay byte-identical: `ClusterMember.isMissingPendingActionError` matches on it.
+				await this.dropUnpromotablePendings(toCommit, request.actionId);
+				throw new Error(`Pending action ${request.actionId} not found for block(s): ${missingPends.map(p => p.blockId).join(', ')}`);
+			}
+
+			// The original commit crashed before setLatest, so it also never emitted a change event
+			// for a recovered (Crash-D3) block. Now that recover() has committed it at request.rev,
+			// report its collection so downstream watchers wake — mirroring internalCommit. Resolve
+			// the collectionId from the now-materialized block; a delete materializes to a tombstone
+			// (getBlock → undefined), so fall back to the prior materialized block's header exactly as
+			// internalCommit does — otherwise a recovered delete would silently fail to wake watchers.
+			// Only when neither resolves (a delete-only block with no prior materialization) is the
+			// emit skipped, the same terminal fallback internalCommit uses.
+			for (const { blockId, storage } of toCommit) {
+				if (!recovered.has(blockId)) {
+					continue;
+				}
+				const collectionId = (await storage.getBlock(request.rev))?.block.header.collectionId
+					?? (await storage.getBlock(request.rev - 1))?.block.header.collectionId;
+				if (collectionId !== undefined) {
+					const list = collectionBlocks.get(collectionId) ?? [];
+					list.push(blockId);
+					collectionBlocks.set(collectionId, list);
+				}
+			}
+
+			// Commit the action for each block that still needs it.
+			// This loop will execute atomically for all blocks due to the acquired locks.
+			// Recovered (Crash-D3) blocks are already committed at request.rev and their pending is
+			// gone, so skip them — internalCommit would throw on the missing pending record.
+			//
+			// Set when the mid-loop failure was a divergence rather than a genuine fault — the split
+			// documented on commit() above, which decides the fate of the batch's pending records.
+			let divergentFailure = false;
+			for (const { blockId, storage } of toCommit) {
+				if (recovered.has(blockId)) {
+					continue;
+				}
+				try {
+					// internalCommit will throw if it encounters an issue
+					const collectionId = await this.internalCommit(blockId, request.actionId, request.rev, storage);
+					if (collectionId !== undefined) {
+						const list = collectionBlocks.get(collectionId) ?? [];
+						list.push(blockId);
+						collectionBlocks.set(collectionId, list);
+					}
+				} catch (err) {
+					// Partial-commit recovery: blocks already in collectionBlocks DID land
+					// durably and must still emit; a retry with the same (actionId, rev)
+					// treats them as idempotent no-ops and advances the remainder. Break
+					// instead of returning so locks release and those landings emit below.
+					failure = { reason: err instanceof Error ? err.message : 'Unknown error during commit' };
+					divergentFailure = err instanceof MissingBaseRevisionError;
+					break;
+				}
+			}
+
+			// The break left every not-yet-reached block still holding its pending record. Whether
+			// that record is still usable depends ENTIRELY on why we stopped — see the table on
+			// commit() above. Runs inside the try, so the per-block latches are still held.
+			// NOTE: a non-divergence fault deliberately KEEPS the batch's pendings so a retry can
+			// replay them. If ClusterMember ever stops retrying propagated commit faults, this arm
+			// becomes dead weight and the discriminator can collapse to "always drop".
+			if (divergentFailure) {
+				await this.dropUnpromotablePendings(toCommit, request.actionId);
+			}
+		}
+		finally {
+			// Release locks in reverse order of acquisition
+			releases.reverse().forEach(release => release());
+		}
+
+		// Notify after the critical section, for every block newly committed here —
+		// including those that landed before a mid-loop failure (alreadyDone / stale
+		// partitions never reach `collectionBlocks`).
+		this.emitCollectionChanges(collectionBlocks, request.actionId, request.rev, request.tailId);
+
+		return failure ? { success: false, reason: failure.reason } : { success: true };
+	}
+
+	/**
+	 * Delete `actionId`'s pending record from every given block, tolerating absence.
+	 *
+	 * Called by {@link commit} when it abandons a batch **because this node has diverged from the
+	 * agreed history** — the caller has already made that determination; this helper does not
+	 * re-derive it. Once `ClusterMember` reconciles the batch, every one of these blocks sits at or
+	 * past `request.rev`, so a commit retry partitions them as already-done/stale and never revisits
+	 * their pendings; left in place they are reported as phantom conflicting actions by {@link pend}
+	 * for every later write to the block (under `policy: 'f'`, forever).
+	 *
+	 * No special-casing is needed for blocks that already landed (record promoted), that were
+	 * `recovered` (record already gone), or for the refusing block itself
+	 * ({@link refuseMissingBase} deleted its record): deleting an absent pending record is a no-op on
+	 * every backend.
+	 *
+	 * Per-block failures are logged and swallowed rather than propagated: this cleanup must never
+	 * replace the failure the caller is about to report — the pre-loop throw's message is pattern-
+	 * matched by `ClusterMember.isMissingPendingActionError`, and a swapped error would misroute
+	 * consensus. A leftover record only degrades this node's participation in that one block.
+	 */
+	private async dropUnpromotablePendings(
+		blocks: { blockId: BlockId, storage: IBlockStorage }[],
+		actionId: ActionId
+	): Promise<void> {
+		if (blocks.length === 0) {
+			return;
+		}
+		log('commit:drop-unpromotable-pendings actionId=%s blockIds=%d', actionId, blocks.length);
+		await Promise.all(blocks.map(async ({ blockId, storage }) => {
+			try {
+				await storage.deletePendingTransaction(actionId);
+			} catch (err) {
+				log('commit:drop-unpromotable-pending-failed blockId=%s actionId=%s error=%s', blockId, actionId,
+					err instanceof Error ? err.message : String(err));
+			}
+		}));
+	}
+
+	/**
+	 * Reconciles `metadata.latest` for a single block with the highest contiguous
+	 * fully-promoted revision in durable storage. Use after a crash between
+	 * `promotePendingTransaction` and `setLatest` when retry-commit cannot help
+	 * (the pending record is already gone) but the revision and committed-log entry
+	 * are durable. Idempotent and monotonic.
+	 */
+	async recoverBlock(blockId: BlockId): Promise<void> {
+		log('recoverBlock blockId=%s', blockId);
+		const storage = this.createBlockStorage(blockId);
+		// Hold the per-block commit latch: recover() is a read-modify-write of meta.latest that
+		// blindly writes back the metadata object it read, so its "advance only" guard is TOCTOU —
+		// racing a concurrent commit()/saveReplicatedBlock that advanced latest in between would
+		// clobber it (a non-monotonic regression). Same latching invariant as every other
+		// latest-mutating site. commit() calls storage.recover() directly under its own held latch,
+		// so it never routes through here — no double-acquire / deadlock.
+		await withBlockCommitLatch(blockId, () => storage.recover());
+	}
+
+	/**
+	 * Persist a replica of a block received out-of-band (churn re-replication) into
+	 * local storage. Distinct from the {@link IRepo} commit funnel: the block arrives
+	 * already materialized from a departing owner, not as a pend/commit. See
+	 * {@link IBlockStorage.saveReplica} for the durability/monotonicity contract.
+	 *
+	 * Held under the same `StorageRepo.commit:<id>` latch as {@link commit} so the
+	 * replica's read-modify-write of `latest` is mutually exclusive with a concurrent
+	 * local commit on the same block — otherwise `saveReplica`'s monotonic guard could
+	 * read a stale `latest` and clobber a commit that advanced it in between.
+	 */
+	async saveReplicatedBlock(blockId: BlockId, block: IBlock, source?: ActionRev): Promise<void> {
+		log('saveReplicatedBlock blockId=%s rev=%s', blockId, source?.rev);
+		const storage = this.createBlockStorage(blockId);
+		const release = await Latches.acquire(commitLatchKey(blockId));
+		// Captured under the latch; emitted after release to match commit's ordering.
+		let landed: { collectionId: CollectionId, actionId: ActionId, rev: number } | undefined;
+		try {
+			const priorLatest = await storage.getLatest();
+			const effective = await storage.saveReplica(block, source);
+			// Advanced iff there was no prior revision or the effective rev moved past it. On the
+			// monotonic no-op, saveReplica returns the held latest unchanged → effective.rev === priorLatest.rev.
+			const advanced = priorLatest === undefined || effective.rev > priorLatest.rev;
+			const collectionId = block.header?.collectionId;
+			if (advanced && collectionId !== undefined) {
+				landed = { collectionId, actionId: effective.actionId, rev: effective.rev };
+			}
+		} finally {
+			release();
+		}
+		// Replica-persist has no CommitRequest, hence no tailId — like a read-driven promotion,
+		// this wakes local onCollectionChange watchers but is cert-gated out of cohort-topic
+		// re-origination downstream (change-bridge selfIsCohortMember treats a tail-less event as
+		// never a member).
+		if (landed) {
+			this.emitCollectionChanges(
+				new Map([[landed.collectionId, [blockId]]]),
+				landed.actionId,
+				landed.rev,
+			);
+		}
+	}
+
+	private async internalCommit(blockId: BlockId, actionId: ActionId, rev: number, storage: IBlockStorage): Promise<CollectionId | undefined> {
+		// Note: This method is called under the per-block commit latch — by commit() (within its
+		// locked critical section) and by the read-driven promotion in get() (which now takes the
+		// same latch). So, operations like getPendingTransaction, getLatest, getBlock,
+		// saveMaterializedBlock, saveRevision, promotePendingTransaction, setLatest are protected
+		// against concurrent commits for the *same blockId*.
+
+		const transform = await storage.getPendingTransaction(actionId);
+		// No need to check if !transform here, as the caller (commit) already verified this.
+		// If it's null here, it indicates a logic error or race condition bypassed the lock (unlikely).
+		if (!transform) {
+			throw new Error(`Consistency Error: Pending action ${actionId} disappeared for block ${blockId} within critical section.`);
+		}
+
+		// Get prior materialized block if it exists
+		const latest = await storage.getLatest();
+		const priorBlock = await this.readCommitBase(blockId, actionId, rev, storage, latest);
+
+		// Apply transform and save materialized block
+		// applyTransform handles undefined priorBlock correctly for inserts
+		const newBlock = applyTransform(priorBlock, transform);
+
+		// INVARIANT: `latest` must never advance past a revision this node can materialize.
+		// `applyTransform` silently drops `updates` when there is no block to apply them to, so a
+		// member that missed the block's CREATING revision would otherwise record rev N while storing
+		// nothing to serve it from. `latest === undefined` is precisely the "nothing below to fall
+		// back to" case: materializeBlock's descending walk needs some materialization at or below the
+		// target, and with no prior revision there is none. With a prior `latest` an absent newBlock is
+		// a legitimate tombstone (the walk resolves to an earlier materialization), so it stays allowed.
+		if (!newBlock && latest === undefined) {
+			return await this.refuseMissingBase(blockId, actionId, rev, storage,
+				'no committed revision to apply the transform to');
+		}
+
+		if (newBlock) {
+			await storage.saveMaterializedBlock(actionId, newBlock);
+		}
+
+		// Save revision and promote action *before* updating latest
+		// This ensures that if the process crashes between these steps,
+		// the 'latest' pointer doesn't point to a revision that hasn't been fully recorded.
+		await storage.saveRevision(rev, actionId);
+		await storage.promotePendingTransaction(actionId);
+
+		// Update latest revision *last*
+		await storage.setLatest({ actionId, rev });
+
+		// Prune the now-superseded prior materialization (checkpoint retention). Runs LAST — after the
+		// new rev's materialization + revision + transform + setLatest are all durable — so no crash
+		// point can leave a rev unrecoverable: a crash BEFORE this leaves a redundant (harmless)
+		// materialization the next commit's prune reclaims; a crash AFTER is fully consistent. The prune
+		// only ever deletes a materialization reconstructible from the retained floor + transforms. Runs
+		// under the per-block commit latch already held here, so it serializes against concurrent commits.
+		// NOTE: prune targets ONLY the immediate prior. A crash between setLatest and this call leaves that
+		// one prior materialization un-pruned; since a later commit prunes ITS OWN prior (never the earlier
+		// leaked rev), that copy is NOT auto-reclaimed — a bounded (≤1 block-copy per crash), harmless leak
+		// (state stays consistent + reconstructible). If crash-before-prune leaks ever accumulate materially,
+		// add a bounded look-back (prune non-retained mats in [rev-checkpointInterval, rev)) here, or a
+		// periodic reconciliation sweep — do NOT reintroduce a per-read re-cache.
+		if (latest !== undefined) {
+			await storage.pruneSupersededMaterialization(latest);
+		}
+
+		// Report the affected collection for change-event routing. For a delete the
+		// materialized block is undefined, so fall back to the prior block's header.
+		// Either may be absent only for a malformed/headerless block — return
+		// undefined so the caller skips it rather than emitting a bogus event.
+		return newBlock?.header.collectionId ?? priorBlock?.header.collectionId;
+	}
+
+	/**
+	 * The materialization this commit builds on: the block at `latest`, or `undefined` when the block
+	 * holds no committed revision yet (the normal insert case).
+	 *
+	 * `getBlock` THROWS when this node holds a `latest` it cannot materialize — a block already wedged
+	 * by a pre-fix commit, or by truncated history. That is the same divergence as having no base at
+	 * all, so it is translated into {@link MissingBaseRevisionError} rather than surfacing as an opaque
+	 * storage fault: the healing path can then repair the block instead of the fault resetting the
+	 * cluster stream, and a wedged node recovers on the next write touching the block.
+	 *
+	 * The catch is deliberately UNNARROWED — it also absorbs a transient fault (a raw-storage read
+	 * error, a `restoreCallback` timeout on a block whose `ranges` do not cover its own `latest`).
+	 * BlockStorage reports every one of these as a bare `Error`, so they cannot be told apart here,
+	 * and treating them as divergence is the safe default: this node genuinely cannot materialize the
+	 * base right now, and the cluster's policy is to heal rather than throw out of consensus. The
+	 * price is that a transient fault ALSO drops pending records — this block's (see
+	 * {@link refuseMissingBase}) AND, because {@link commit} keys its cleanup off the same error type,
+	 * every not-yet-reached block in the same batch — so those blocks converge by replication instead
+	 * of by a replay the retry could have done. That is a wider blast radius than the per-block
+	 * refusal alone, and it is why the discriminator must NOT be loosened beyond this error type.
+	 * Narrowing this would require typed faults out of BlockStorage; until then, prefer the tolerant
+	 * reading.
+	 */
+	private async readCommitBase(
+		blockId: BlockId,
+		actionId: ActionId,
+		rev: number,
+		storage: IBlockStorage,
+		latest: ActionRev | undefined
+	): Promise<IBlock | undefined> {
+		if (!latest) {
+			return undefined;
+		}
+		try {
+			return (await storage.getBlock(latest.rev))?.block;
+		} catch (err) {
+			log('commit:unmaterializable-base blockId=%s baseRev=%d error=%s', blockId, latest.rev,
+				err instanceof Error ? err.message : String(err));
+			return await this.refuseMissingBase(blockId, actionId, rev, storage,
+				`local rev ${latest.rev} is not materializable here`);
+		}
+	}
+
+	/**
+	 * Refuse a commit this node cannot materialize. Always throws {@link MissingBaseRevisionError};
+	 * nothing durable has been written at this point, so the block is left exactly as it was minus the
+	 * pending record.
+	 *
+	 * The pending is dropped because it can never be promoted here: promotion needs a base this node
+	 * must obtain out-of-band, and once the healing path lands that revision `latest` is already >= rev,
+	 * so a commit retry partitions the block as already-done/stale and never revisits the pending.
+	 * Leaving it would also report a phantom conflicting action from {@link pend} for every later write.
+	 */
+	private async refuseMissingBase(
+		blockId: BlockId,
+		actionId: ActionId,
+		rev: number,
+		storage: IBlockStorage,
+		detail: string
+	): Promise<never> {
+		await storage.deletePendingTransaction(actionId);
+		log('commit:missing-base blockId=%s rev=%d actionId=%s detail=%s', blockId, rev, actionId, detail);
+		throw new MissingBaseRevisionError(blockId, rev, detail);
+	}
+}
+
+/**
+ * Converts list of missing actions per block into a list of missing actions across blocks.
+ *
+ * NOTE: relies on each (actionId, blockId) pair appearing at most once — one revision per action
+ * per block. If a block ever records two revisions under the same actionId, concatTransform now
+ * concatenates both revisions' ops into one array rather than dropping the earlier one — still
+ * wrong, since ops from distinct revisions are not composable against a single base, but loud
+ * rather than silent. Group by (actionId, rev) instead if that case becomes reachable.
+ */
+function perBlockActionTransformsToPerAction(missing: { blockId: BlockId; transforms: ActionTransform[]; }[]) {
+	const missingFlat = missing.flatMap(({ blockId, transforms }) =>
+		transforms.map(transform => ({ blockId, transform }))
+	);
+	const missingByActionId = groupBy(missingFlat, ({ transform }) => transform.actionId);
+	return Object.entries(missingByActionId).map(([actionId, items]) =>
+		items.reduce((acc, { blockId, transform }) => {
+			acc.transforms = concatTransform(acc.transforms, blockId, transform.transform);
+			return acc;
+		}, {
+			actionId: actionId as ActionId,
+			rev: items[0]!.transform.rev,	// Assumption: an action commits at one revision, so every block's entry for this actionId agrees. Distinct actionIds may still carry distinct revs.
+			transforms: emptyTransforms()
+		})
+	);
+}