@optimystic/db-p2p 0.25.1 → 0.27.0

package/src/storage/block-latch.ts

@@ -90,10 +90,11 @@ export type BlockWriteLatches = {
 
 /**
  * Acquire the write latches for a whole set of blocks at once — the only sanctioned way to hold more
- * than one. Two callers need it (`StorageRepo.commit` and `applyInvalidation`), and the property that
- * keeps them from deadlocking against each other is not local to either: it is that EVERY multi-latch
- * holder acquires in the one global order. Owning that here makes it a property of the module that
- * owns the key rather than a rule each call site restates and a third one could get wrong.
+ * than one. Three callers need it (`StorageRepo.pend`, `StorageRepo.commit` and `applyInvalidation`),
+ * and the property that keeps them from deadlocking against each other is not local to any of them:
+ * it is that EVERY multi-latch holder acquires in the one global order. Owning that here makes it a
+ * property of the module that owns the key rather than a rule each call site restates and the next
+ * one could get wrong.
  *
  * Three things this does that a hand-rolled loop keeps getting wrong:
  *  - **Dedups** the ids. `Latches` is a plain FIFO mutex with no re-entrancy, so a repeated id in the

package/src/storage/block-storage.ts

@@ -4,7 +4,7 @@ import type { BlockCommitProof } from "../cluster/commit-proof.js";
 import type { BlockArchive, BlockMetadata, RestoreCallback, RevisionRange } from "./struct.js";
 import type { IRawStorage } from "./i-raw-storage.js";
 import { mergeRanges } from "./helpers.js";
-import { RevisionNotCoveredError, type IBlockStorage } from "./i-block-storage.js";
+import { RevisionNotCoveredError, PendRevisionTakenError, type IBlockStorage } from "./i-block-storage.js";
 import type { BlockWriteLatch } from "./block-latch.js";
 import { createLogger } from "../logger.js";
 
@@ -155,10 +155,18 @@ export class BlockStorage implements IBlockStorage {
 		yield* this.storage.listPendingTransactions(this.blockId);
 	}
 
-	async savePendingTransaction(actionId: ActionId, transform: Transform, latch: BlockWriteLatch): Promise<void> {
+	async savePendingTransaction(actionId: ActionId, transform: Transform, rev: number | undefined, latch: BlockWriteLatch): Promise<void> {
 		this.assertLatch(latch);
-		log('pend blockId=%s actionId=%s', this.blockId, actionId);
+		log('pend blockId=%s actionId=%s rev=%s', this.blockId, actionId, rev);
 		let meta = await this.storage.getMetadata(this.blockId);
+		// Refuse a record that could never be promoted (see IBlockStorage.savePendingTransaction).
+		// The metadata read above is unconditional anyway, so this costs one comparison and no I/O.
+		// `>=` deliberately covers BOTH unpromotable cases at once — our own already-committed
+		// revision (commit partitions it as already-done) and a rival's win (commit refuses it as
+		// stale) — so this is not an `isOwnRevision` check.
+		if (rev !== undefined && meta?.latest !== undefined && meta.latest.rev >= rev) {
+			throw new PendRevisionTakenError(this.blockId, actionId, rev, meta.latest);
+		}
 		if (!meta) {
 			// A freshly-pended block holds NO committed revision, so it can reconstruct
 			// nothing yet: seed empty ranges. The first commit anchors an OPEN-ENDED span at

package/src/storage/cached-raw-storage.ts

@@ -24,11 +24,15 @@ export class RawStorageDriverAdapter implements RawStoreDriver {
 	 * Optional passthroughs wired only when the inner storage provides them, mirroring
 	 * `KvRawStorage`'s constructor: feature-detection above must observe the inner
 	 * storage's true capability. `IRawStorage` has no `close`/`approximateBytesUsed`
-	 * driver names — they map from `listBlockIds`/`getApproximateBytesUsed`.
+	 * driver names — they map from `listBlockIds`/`getApproximateBytesUsed`. `readCached`
+	 * keeps its name across the boundary; carrying it up is what lets a re-kerneled cached
+	 * storage still report itself as cached, and what makes `CachedStoreDriver`'s
+	 * redundant-wrap guard fire for `new CachedRawStorage(alreadyCachedStorage)`.
 	 */
 	listBlockIds?: () => AsyncIterable<BlockId>;
 	approximateBytesUsed?: () => Promise<number>;
 	storeIdentity?: () => StoreIdentity;
+	readCached?: true;
 
 	constructor(private readonly inner: IRawStorage) {
 		if (inner.getStoreIdentity) {
@@ -40,6 +44,9 @@ export class RawStorageDriverAdapter implements RawStoreDriver {
 		if (inner.getApproximateBytesUsed) {
 			this.approximateBytesUsed = () => inner.getApproximateBytesUsed!();
 		}
+		if (inner.readCached) {
+			this.readCached = true;
+		}
 	}
 
 	// --- metadata ---
@@ -176,6 +183,19 @@ export class RawStorageDriverAdapter implements RawStoreDriver {
 export class CachedRawStorage extends KvRawStorage {
 	private readonly cacheDriver: CachedStoreDriver;
 
+	/**
+	 * Always present here: this class is a `KvRawStorage` over a `CachedStoreDriver`, so the
+	 * base constructor's passthrough always sets it. Narrowed from the base's optional
+	 * `readCached?: true` purely for the type.
+	 *
+	 * `declare` — type-only, NO emit. `tsconfig.base.json` targets ES2022 without
+	 * `useDefineForClassFields`, which therefore defaults to true, so a plain field
+	 * declaration here would emit a `defineProperty(this, 'readCached', undefined)` that runs
+	 * AFTER `super()` and clobber what the base constructor just assigned. Same reason
+	 * `FileRawStorage` &c. use `declare getStoreIdentity: …`.
+	 */
+	declare readonly readCached: true;
+
 	constructor(inner: IRawStorage, pool?: SharedCachePool, label?: string) {
 		const cacheDriver = new CachedStoreDriver(new RawStorageDriverAdapter(inner), pool, label);
 		super(cacheDriver);

package/src/storage/cached-store-driver.ts

@@ -200,11 +200,34 @@ export class CachedStoreDriver implements RawStoreDriver, PoolEntryOwner {
 	approximateBytesUsed?: () => Promise<number>;
 	storeIdentity?: () => StoreIdentity;
 
+	/**
+	 * This driver IS the read cache, so the marker is unconditional — unlike the passthroughs
+	 * above, which mirror the inner driver's capabilities. Wrappers above (`KvRawStorage`,
+	 * `RawStorageDriverAdapter`) carry it up, which is how `withReadCache` recognises BOTH
+	 * documented cache constructions without naming a concrete class.
+	 */
+	readonly readCached: true = true;
+
 	constructor(
 		private readonly inner: RawStoreDriver,
 		private readonly pool: SharedCachePool = defaultCachePool(),
 		label?: string,
 	) {
+		// Stacked wrap — the inner driver already has a read cache at or below it, so this one
+		// would only ever read through that one. Caught HERE, and before `registerStore`, because
+		// the pool cannot tell a stacked wrap from a side-by-side pair: it sees only that the
+		// identity is claimed, and would report the (wrong, and much scarier) divergence failure.
+		// Identity-less inner drivers reach the pool's guard not at all, so without this check a
+		// stacked wrap over one of them builds silently — pure overhead, never useful.
+		if (inner.readCached) {
+			throw new Error(
+				`redundant read cache: the inner driver is already read-cached`
+				+ `${inner.storeIdentity ? ` (${JSON.stringify(inner.storeIdentity())})` : ''}, so wrapping `
+				+ `it again (label ${JSON.stringify(label ?? null)}) stacks a second bookkeeping layer that `
+				+ `can only ever read through the first — every miss pays twice and nothing is saved. `
+				+ `Use the inner cached driver as-is.`
+			);
+		}
 		// Registration is the choke point every construction path shares (this constructor, the
 		// `CachedRawStorage` wrapper, `withReadCache`), so naming the backing store here is what
 		// lets the pool refuse a second, permanently divergent view of it. Throws before anything else is

package/src/storage/i-block-storage.ts

@@ -20,6 +20,28 @@ export class RevisionNotCoveredError extends Error {
 	}
 }
 
+/**
+ * Thrown by {@link IBlockStorage.savePendingTransaction} when the block has already committed a
+ * revision at or past the one the pending record names, so the record could never be promoted:
+ * `StorageRepo.commit` partitions such a block as already-done (`latest.rev === rev`, same action)
+ * or refuses it as stale (`latest.rev > rev`, or a rival at the same rev), and neither path runs
+ * the promotion that is the only thing removing a pending record on the success path. The record
+ * would then be reported as a conflicting in-flight action to every later writer of the block —
+ * see **Invariant P** on {@link IBlockStorage.promotePendingTransaction}.
+ *
+ * It is a throw rather than a returned status because a caller reaching it has reintroduced a
+ * check-then-act split that `StorageRepo.pend` closed by classifying and saving under one held
+ * latch; a status is a value a caller can ignore, which is the failure mode being designed out.
+ */
+export class PendRevisionTakenError extends Error {
+	constructor(readonly blockId: BlockId, readonly actionId: ActionId, readonly rev: number, readonly latest: ActionRev) {
+		super(`Block ${blockId}: cannot pend action ${actionId} at revision ${rev}; the block is `
+			+ `already committed at revision ${latest.rev} (action ${latest.actionId}), so the `
+			+ `pending record could never be promoted`);
+		this.name = 'PendRevisionTakenError';
+	}
+}
+
 /**
  * Interface for block-level storage operations.
  *
@@ -70,8 +92,27 @@ export interface IBlockStorage {
     /** Lists all pending action IDs */
     listPendingTransactions(): AsyncIterable<ActionId>;
 
-    /** Saves a pending action (seeding this block's metadata when it has none). */
-    savePendingTransaction(actionId: ActionId, transform: Transform, latch: BlockWriteLatch): Promise<void>;
+    /**
+     * Saves a pending action (seeding this block's metadata when it has none).
+     *
+     * `rev` is the revision the pend is claiming — the `rev` of the `PendRequest` this record
+     * belongs to, or `undefined` for a claim that names no revision (an insert-only pend). When it
+     * names one and the block has already committed at or past it, this REFUSES with
+     * {@link PendRevisionTakenError} and writes nothing.
+     *
+     * The question the refusal asks is **"could this record ever be promoted?"**, not "is this our
+     * own revision?" — which is why it does not use `isOwnRevision`. A single `latest.rev >= rev`
+     * comparison collapses both unpromotable cases: the writer's own already-committed revision
+     * (`===`, which `StorageRepo.commit` partitions as already-done and never promotes) and a
+     * rival's win (`>`, which `commit` refuses as stale). The error carries `latest` so the message
+     * can name which it was. `rev === undefined` names no revision, so no comparison applies.
+     *
+     * The refusal is an assertion, not a control-flow path: `StorageRepo.pend` classifies and saves
+     * under one multi-block write-latch hold, so every block it saves was observed under that same
+     * hold to satisfy `latest === undefined || latest.rev < rev`, and no writer can advance a block
+     * without its latch. A throw here means a caller reintroduced check-then-act.
+     */
+    savePendingTransaction(actionId: ActionId, transform: Transform, rev: number | undefined, latch: BlockWriteLatch): Promise<void>;
 
     /** Deletes a pending action */
     deletePendingTransaction(actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
@@ -104,6 +145,10 @@ export interface IBlockStorage {
      * writes the committed one. A pending record left beside a committed one can never be promoted,
      * and is reported as a phantom conflicting action by `StorageRepo.pend` on every later write to
      * the block.
+     *
+     * The pend side of the invariant is enforced rather than merely required:
+     * {@link savePendingTransaction} refuses ({@link PendRevisionTakenError}) to write a pending
+     * record for a revision the block has already reached.
      */
     promotePendingTransaction(actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
 

package/src/storage/i-raw-storage.ts

@@ -68,6 +68,23 @@ export interface IRawStorage {
 	 */
 	getStoreIdentity?(): StoreIdentity;
 
+	/**
+	 * Optional — present (and only ever `true`) when a write-through read cache
+	 * (`CachedStoreDriver`) sits BELOW this storage, whichever of the two documented
+	 * constructions built it: `new CachedRawStorage(inner)` or
+	 * `new KvRawStorage(new CachedStoreDriver(driver))`. Both contain a `CachedStoreDriver`,
+	 * and both report this marker; `withReadCache` reads it to decide whether to attach a
+	 * cache, so neither shape is misread as uncached.
+	 *
+	 * A property, not a method: there is no behavior to invoke, only a fact to report.
+	 *
+	 * OPTIONAL BY DESIGN, and typed as the literal `true` so "present and false" is
+	 * unrepresentable — truthiness IS the feature detection. Never install a `false` stub: an
+	 * uncached storage must omit the property entirely, exactly as `getStoreIdentity` /
+	 * `listBlockIds` / `getApproximateBytesUsed` are omitted when unsupported.
+	 */
+	readCached?: true;
+
 	/**
 	 * Approximate bytes currently stored by this backend.
 	 *

package/src/storage/kv-raw-storage.ts

@@ -26,11 +26,15 @@ export class KvRawStorage implements IRawStorage {
 	 * (`typeof storage.listBlockIds === 'function'`) sees the driver's true
 	 * capability instead of a stub that silently reports 0 / no seed. The same rule
 	 * governs `getStoreIdentity`: a stub returning `undefined` would make every store
-	 * look identity-less to consumers that dedupe on it.
+	 * look identity-less to consumers that dedupe on it. `readCached` follows the same rule
+	 * for the same reason: it is set only when the driver reports a read cache at or below
+	 * itself, so `withReadCache` sees whether this composition is REALLY already cached
+	 * rather than inferring it from a concrete class name (see {@link IRawStorage.readCached}).
 	 */
 	listBlockIds?: () => AsyncIterable<BlockId>;
 	getApproximateBytesUsed?: () => Promise<number>;
 	getStoreIdentity?: () => StoreIdentity;
+	readCached?: true;
 
 	constructor(private readonly driver: RawStoreDriver) {
 		if (driver.storeIdentity) {
@@ -42,6 +46,9 @@ export class KvRawStorage implements IRawStorage {
 		if (driver.approximateBytesUsed) {
 			this.getApproximateBytesUsed = () => driver.approximateBytesUsed!();
 		}
+		if (driver.readCached) {
+			this.readCached = true;
+		}
 	}
 
 	// --- Metadata ---

package/src/storage/raw-store-driver.ts

@@ -113,10 +113,36 @@ export interface RawStoreDriver {
 	 * - It identifies the STORE, not its contents.
 	 */
 	storeIdentity?(): StoreIdentity;
+
+	/**
+	 * Optional — present (and only ever `true`) when a write-through read cache
+	 * (`CachedStoreDriver`) sits AT or BELOW this driver, so a composition seam can ask
+	 * "is this already read-cached?" of the composition itself instead of guessing from a
+	 * concrete class name. Set unconditionally by `CachedStoreDriver` (it *is* the cache) and
+	 * passed up by every wrapper that fronts a driver, the same way `storeIdentity` is.
+	 *
+	 * A property, not a method: there is no behavior to invoke, only a fact to report.
+	 *
+	 * OPTIONAL BY DESIGN, and typed as the literal `true` so "present and false" is
+	 * unrepresentable — truthiness IS the feature detection. Never install a `false` stub: an
+	 * uncached driver must omit the property entirely, exactly as `storeIdentity` /
+	 * `listBlockIds` / `approximateBytesUsed` are omitted when unsupported.
+	 */
+	readCached?: true;
+
 	/** Optional — enumerate block ids with durable metadata (startup seed). Passed through by the kernel. */
 	listBlockIds?(): AsyncIterable<BlockId>;
 	/** Optional — best cheap byte estimate. Passed through by the kernel. */
 	approximateBytesUsed?(): Promise<number>;
 	/** Optional — release the underlying handle. */
 	close?(): Promise<void>;
+
+	// NOTE: forwarding each optional above is a WRITTEN contract for wrapper drivers, not an
+	// enforced one — a wrapper that forgets one silently reports the composition as less capable
+	// than it is, and for `readCached` that means a seam attaches a redundant second cache. Fine
+	// today: the only two wrapper drivers in the tree are `CachedStoreDriver` and
+	// `RawStorageDriverAdapter`, both forward deliberately (`CachedStoreDriver` withholds `close`
+	// on purpose, and says why at its site), and each has direct tests. If a THIRD wrapper driver
+	// appears, replace the per-wrapper tests with one shared conformance check that asserts
+	// forwarding of each optional, with an explicit per-wrapper exception list.
 }

package/src/storage/shared-cache-pool.ts

@@ -227,6 +227,11 @@ export class SharedCachePool {
 	 * a log line is not a way to notice. A registration with no identity is unaffected: it
 	 * registers exactly as it always did.
 	 *
+	 * This catches the SIDE-BY-SIDE pair only. A cache stacked over an already-cached inner is a
+	 * different (merely redundant) failure and is refused earlier, in `CachedStoreDriver`'s
+	 * constructor, so it never reaches here with the wrong story — see the two `readCached`
+	 * guards in `packages/db-p2p/docs/storage.md`.
+	 *
 	 * The check runs BEFORE any mutation, so a refused registration leaves the pool exactly as it
 	 * was — no store row, no consumed id, no claim.
 	 *
@@ -239,7 +244,7 @@ export class SharedCachePool {
 				`two caches over one backing store never converge: ${JSON.stringify(identity)} is already `
 				+ `cached (label ${JSON.stringify(claimed.label ?? null)}); this registration `
 				+ `(label ${JSON.stringify(label ?? null)}) would be a second, independent view. Share one `
-				+ `CachedRawStorage — withReadCache does this for you — or dispose the first.`
+				+ `read cache — withReadCache does this for you — or dispose the first.`
 			);
 		}
 		const handle = new CacheStoreHandle(`s${++this.storeCounter}`, label, identity);

package/src/storage/storage-repo.ts

@@ -520,6 +520,8 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 			};
 		}
 
+		// Already deduped: `blockIdsForTransforms` builds its result through a Set. So the pass-2 save
+		// loop below cannot write one block twice, and the echoed `blockIds` carries no duplicate.
 		const blockIds = blockIdsForTransforms(request.transforms);
 		log('pend actionId=%s blockIds=%d rev=%s', request.actionId, blockIds.length, request.rev);
 		const pendings: ActionPending[] = [];
@@ -531,124 +533,162 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		// Blocks this action ALREADY committed at exactly the requested revision — the durable half
 		// of a torn action whose retry reuses the same actionId. Sibling of the `alreadyDone`
 		// partition in `commit` below: satisfied, not merely non-stale, so no pending is recorded
-		// for them (see the fan-out at the end of this method).
+		// for them (see pass 2).
 		const satisfied = new Set<BlockId>();
-
-		// 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);
-
-			// Handle any conflicting revisions FIRST: a block this same action already committed at
-			// exactly the requested revision is satisfied, and skips both this check and the
-			// pending-action listing below.
-			if (request.rev !== undefined || transforms.insert) {
-				const latest = await blockStorage.getLatest();
-				// Our own already-durable work, met again by a retry (see {@link isOwnRevision}):
-				// treating it as a stale rival would refuse the writer with its own commit.
-				// NOTE: a rev-less pend (`request.rev === undefined`, an insert-only claim) can
-				// never match, so a torn action retried WITHOUT a revision is still refused by its
-				// own insert. No production caller sends one — `TransactorSource.transact` and the
-				// multi-collection coordinator both require a rev — so this is unreachable today;
-				// if a rev-less write path ever appears, match on `latest.actionId` alone here.
-				if (isOwnRevision(latest, request.rev, request.actionId)) {
-					satisfied.add(blockId);
-					continue;
-				}
-				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 }]);
+		// Blocks observed at or past the requested revision under a DIFFERENT action — a real stale
+		// loss. Counted separately from `missing` because the two are not the same question: `missing`
+		// is the catch-up the loser is handed, and a node whose revision index is sparse over
+		// [request.rev, latest.rev] hands back an empty one while still having lost. Gating the
+		// refusal on the enumeration would then let a block pass classification that pass 2 cannot
+		// write (`savePendingTransaction` refuses it), turning a stale answer into a throw. `commit`
+		// takes the same position — it pushes a `missedCommits` entry "even if transforms is empty,
+		// because we want to reject the older version".
+		let staleCount = 0;
+
+		// Classifying and saving are ONE atomic step per pend: both passes below run inside a single
+		// multi-block write-latch hold, so no commit can land between deciding a block is pendable
+		// and writing its pending record. That is the whole property — a pend never writes a pending
+		// record for a revision already taken. Such a record could never be promoted (`commit`
+		// partitions the block as already-done or refuses it as stale, and promotion is the only
+		// thing that removes a record on the success path), and would then be reported as a
+		// conflicting in-flight action to every later writer of the block. See docs/repository.md,
+		// Invariant P; `BlockStorage.savePendingTransaction` refuses such a write outright.
+		//
+		// TWO passes, not one interleaved loop: with a single loop a block refused partway through
+		// would leave records already written for its predecessors, and retracting those under the
+		// hold could delete a record an EARLIER pend of the same action legitimately left. Classify
+		// everything before writing anything, and no record is ever written that must be taken back.
+		//
+		// Everything inside the hold is local storage I/O. No network I/O and no caller-supplied
+		// code may enter it — `checkPendValidation` above can call the caller's validation hook,
+		// which is precisely why it stays outside. `commit` keeps the same rule. Acquiring through
+		// `acquireBlockWriteLatches` (deduped, sorted) is what keeps the three multi-latch holders —
+		// this, `commit`, and `applyInvalidation` — free of deadlock, and no caller of `pend`
+		// (`ClusterRepo`, `CoordinatorRepo`, `service.ts`) holds a block latch, so the hold cannot
+		// re-enter itself.
+		//
+		// NOTE: a pend now blocks concurrent commits on its blocks for the span of BOTH passes, not
+		// just its writes. Accepted: every call inside is local storage I/O, and `commit` already
+		// holds the same set for a comparable span. If pend latency on contended blocks ever shows
+		// up in a profile, two things inside the hold scale with width and are the ones to look at:
+		// the policy-'r' arm reads one transform per rival, and pass 2 awaits its saves one block at
+		// a time (where the pre-latch code fanned out with `Promise.all`). Sequential is the
+		// deliberate choice — a throw mid-pass then strands records for FEWER blocks, not more — so
+		// batch or fan out only with that tradeoff in hand.
+		const { latches, release } = await acquireBlockWriteLatches(blockIds);
+		try {
+			// --- Pass 1: classify. Every read below runs under the hold. ---
+			for (const blockId of blockIds) {
+				const blockStorage = this.createBlockStorage(blockId);
+				const transforms = transformForBlockId(request.transforms, blockId);
+
+				// Handle any conflicting revisions FIRST: a block this same action already committed at
+				// exactly the requested revision is satisfied, and skips both this check and the
+				// pending-action listing below.
+				if (request.rev !== undefined || transforms.insert) {
+					const latest = await blockStorage.getLatest();
+					// Our own already-durable work, met again by a retry (see {@link isOwnRevision}):
+					// treating it as a stale rival would refuse the writer with its own commit.
+					// NOTE: a rev-less pend (`request.rev === undefined`, an insert-only claim) can
+					// never match, so a torn action retried WITHOUT a revision is still refused by its
+					// own insert. No production caller sends one — `TransactorSource.transact` and the
+					// multi-collection coordinator both require a rev — so this is unreachable today;
+					// if a rev-less write path ever appears, match on `latest.actionId` alone here.
+					if (isOwnRevision(latest, request.rev, request.actionId)) {
+						satisfied.add(blockId);
+						continue;
 					}
-					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}`);
+					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 }]);
+						}
+						staleCount++;
+						const missedRevisions = await asyncIteratorToArray(blockStorage.listRevisions(request.rev ?? 0, latest.rev));
+						for (const actionRev of missedRevisions) {
+							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)
+							});
 						}
-						missing.push({
-							actionId: actionRev.actionId,
-							rev: actionRev.rev,
-							transforms: transformsFromTransform(transform, blockId)
-						});
 					}
 				}
-			}
 
-			// Then handle any pending actions
-			const pending = await asyncIteratorToArray(blockStorage.listPendingTransactions());
-			pendings.push(...pending.map(actionId => ({ blockId, actionId })));
-		}
-
-		if (missing.length) {
-			log('pend:stale actionId=%s missing=%d', request.actionId, missing.length);
-			return {
-				success: false,
-				conflict: true,
-				missing,
-				...(staleAt === undefined ? {} : { staleAt })
-			};
-		}
+				// Then handle any pending actions
+				const pending = await asyncIteratorToArray(blockStorage.listPendingTransactions());
+				pendings.push(...pending.map(actionId => ({ blockId, actionId })));
+			}
 
-		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
+			// Every refusal below returns having written ZERO pending records — that is what pass 1
+			// finishing before pass 2 begins buys.
+			if (staleCount > 0) {
+				log('pend:stale actionId=%s stale=%d missing=%d', request.actionId, staleCount, missing.length);
 				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
-						}
-					}))
+					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,
+								// The fallback stays: a rival enumerated on a block we hold cannot be promoted
+								// out from under us mid-hold, but a partially-overlapping pend can still have
+								// promoted one on a block outside this hold.
+								transform: (await blockStorage.getPendingTransaction(action.actionId))
+									?? (await blockStorage.getTransaction(action.actionId))!
+							}
+						}))
+					};
+				}
+			}
 
-		// 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.
-		//
-		// Each block's pending write runs under THAT block's write latch, one latch per branch and
-		// never nested: savePendingTransaction seeds the block's metadata blob when it has none, and
-		// an unlatched seed racing a concurrent commit/replica on a fresh block erases the `latest`
-		// the other writer just landed. Never more than one block latch is held by a branch, so this
-		// cannot deadlock against commit's sorted multi-latch acquisition.
-		//
-		// `satisfied` blocks are skipped: `commit`'s `alreadyDone` arm skips `internalCommit`, the
-		// only thing that promotes (and thereby removes) a pending record, so a pending saved here
-		// would never clear — a permanent durable reservation that the rival-pending checks (this
-		// method's listPendingTransactions scan, and `ClusterMember.validatePendOperations`) refuse
-		// every future writer against, a worse wedge than the one this carve-out fixes. They still
-		// ride in the returned `blockIds` so `cancel` covers them (deleting an absent pending is a
-		// no-op that writes no metadata).
-		await Promise.all(blockIds.filter(blockId => !satisfied.has(blockId)).map(blockId => {
-			const blockStorage = this.createBlockStorage(blockId);
-			const blockTransform = transformForBlockId(request.transforms, blockId);
-			return withBlockWriteLatch(blockId, latch => blockStorage.savePendingTransaction(request.actionId, blockTransform, latch));
-		}));
+			// --- Pass 2: save. Same hold, so nothing advanced a block since pass 1 observed it. ---
+			//
+			// `satisfied` blocks are skipped: `commit`'s `alreadyDone` arm skips `internalCommit`, the
+			// only thing that promotes (and thereby removes) a pending record, so a pending saved here
+			// would never clear — a permanent durable reservation that the rival-pending checks (this
+			// method's listPendingTransactions scan, and `ClusterMember.validatePendOperations`) refuse
+			// every future writer against. They still ride in the returned `blockIds` so `cancel`
+			// covers them (deleting an absent pending is a no-op that writes no metadata).
+			for (const blockId of blockIds) {
+				if (satisfied.has(blockId)) {
+					continue;
+				}
+				const blockStorage = this.createBlockStorage(blockId);
+				const blockTransform = transformForBlockId(request.transforms, blockId);
+				await blockStorage.savePendingTransaction(request.actionId, blockTransform, request.rev, latches.get(blockId)!);
+			}
 
-		return {
-			success: true,
-			pending: pendings,
-			blockIds
-		} as PendSuccess;
+			return {
+				success: true,
+				pending: pendings,
+				blockIds
+			} as PendSuccess;
+		} finally {
+			// Releases on every path, including the early returns above and the
+			// `Missing action … for block …` throw inside pass 1.
+			release();
+		}
 	}
 
 	async cancel(actionRef: ActionBlocks, _options?: MessageOptions): Promise<void> {