@optimystic/db-core 0.24.2 → 0.25.0

package/dist/src/transaction/coordinator.js

@@ -2,6 +2,7 @@ import { isConflictFailure } from "../network/stale-failure.js";
 import { isTransactionExpired, clampPriority } from "./transaction.js";
 import { Log } from "../log/log.js";
 import { blockIdsForTransforms } from "../transform/helpers.js";
+import { computeBlockContentDigests, blockDigestsField } from "../transform/digest.js";
 import { collectOperations, hashOperations } from "./operations-hash.js";
 import { CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
 import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
@@ -128,52 +129,67 @@ export class TransactionCoordinator {
         // re-drive a losing transaction before surfacing a terminal error.
         let staleLosses = 0;
         let lastLoss;
-        for (;;) {
-            if (signal?.aborted) {
-                throw makeAbortError(signal);
-            }
-            // Progress-agnostic ceiling: once we've taken at least one loss, give up if the
-            // wall-clock deadline passed (independent of the attempt cap).
-            if (deadlineMs !== undefined && lastLoss && Date.now() - startedAt >= deadlineMs) {
-                throw lastLoss;
-            }
-            // Age the transaction's advisory priority by the number of losses taken so far, so a
-            // repeatedly-losing transaction out-ranks fresh (priority-0) rivals in the cluster's
-            // resolveRace. Fairness-only and capped at MaxPriority; excluded from the tx id / client
-            // signature, so bumping it here does not churn identity. Left untouched on the first
-            // attempt (staleLosses == 0) so the initial pend serializes exactly as before.
-            if (staleLosses > 0) {
-                transaction.priority = clampPriority(staleLosses);
-            }
-            try {
-                await this.commitOnce(transaction);
-                return;
-            }
-            catch (err) {
-                // Only a CLEAN stale loss is retryable. A partial landing, an expired transaction, an
-                // unavailable transactor, etc. all propagate unchanged.
-                if (!(err instanceof CoordinatorStaleLossError)) {
-                    throw err;
+        // Disposers for the in-flight marks {@link commitOnce} sets on each participant it latches.
+        // They must outlive the individual attempt: the inter-attempt refresh below is the ONLY
+        // reader of the mark, and it deliberately runs after the commit span released its latches
+        // (`Latches` is non-reentrant), so a clear tied to the latch would already have run. Hence
+        // the finally spans the WHOLE retry loop — every exit clears: return, stale-loss exhaustion,
+        // a partial landing, a hard error, an abort. Each disposer is id-guarded, so re-marking on a
+        // later attempt is harmless and a stale disposer cannot wipe a newer mark.
+        const inFlightDisposers = [];
+        try {
+            for (;;) {
+                if (signal?.aborted) {
+                    throw makeAbortError(signal);
                 }
-                lastLoss = err;
-                staleLosses++;
-                if (staleLosses >= maxAttempts) {
-                    throw err;
+                // Progress-agnostic ceiling: once we've taken at least one loss, give up if the
+                // wall-clock deadline passed (independent of the attempt cap).
+                if (deadlineMs !== undefined && lastLoss && Date.now() - startedAt >= deadlineMs) {
+                    throw lastLoss;
                 }
-                const delay = jitteredBackoffMs(staleLosses - 1, { baseMs: baseBackoffMs, capMs: maxBackoffMs }, options?.rand);
-                await abortableDelay(delay, signal);
-                // Re-read fresh state before re-attempting so the next commit pends against current
-                // revisions (mirrors how Collection.sync calls updateInternal() before retrying).
-                // NOTE: refreshes EVERY registered collection, not only the participants of this
-                // transaction. Not free: a non-participant's update() throws CollectionHeaderVanishedError
-                // if its header momentarily reads absent while it holds a committed revision, aborting
-                // this retry. The registered set is small today; if that (or retry latency) ever bites,
-                // narrow this to the transaction's participating collections.
-                for (const collection of this.collections.values()) {
-                    await collection.update();
+                // Age the transaction's advisory priority by the number of losses taken so far, so a
+                // repeatedly-losing transaction out-ranks fresh (priority-0) rivals in the cluster's
+                // resolveRace. Fairness-only and capped at MaxPriority; excluded from the tx id / client
+                // signature, so bumping it here does not churn identity. Left untouched on the first
+                // attempt (staleLosses == 0) so the initial pend serializes exactly as before.
+                if (staleLosses > 0) {
+                    transaction.priority = clampPriority(staleLosses);
+                }
+                try {
+                    await this.commitOnce(transaction, inFlightDisposers);
+                    return;
+                }
+                catch (err) {
+                    // Only a CLEAN stale loss is retryable. A partial landing, an expired transaction, an
+                    // unavailable transactor, etc. all propagate unchanged.
+                    if (!(err instanceof CoordinatorStaleLossError)) {
+                        throw err;
+                    }
+                    lastLoss = err;
+                    staleLosses++;
+                    if (staleLosses >= maxAttempts) {
+                        throw err;
+                    }
+                    const delay = jitteredBackoffMs(staleLosses - 1, { baseMs: baseBackoffMs, capMs: maxBackoffMs }, options?.rand);
+                    await abortableDelay(delay, signal);
+                    // Re-read fresh state before re-attempting so the next commit pends against current
+                    // revisions (mirrors how Collection.sync calls updateInternal() before retrying).
+                    // NOTE: refreshes EVERY registered collection, not only the participants of this
+                    // transaction. Not free: a non-participant's update() throws CollectionHeaderVanishedError
+                    // if its header momentarily reads absent while it holds a committed revision, aborting
+                    // this retry. The registered set is small today; if that (or retry latency) ever bites,
+                    // narrow this to the transaction's participating collections.
+                    for (const collection of this.collections.values()) {
+                        await collection.update();
+                    }
                 }
             }
         }
+        finally {
+            for (const dispose of inFlightDisposers) {
+                dispose();
+            }
+        }
     }
     /**
      * Commit a transaction (single attempt): materialise a log entry from each collection's staged
@@ -191,8 +207,14 @@ export class TransactionCoordinator {
      * {@link CoordinatorPartialCommitError} (not retryable).
      *
      * @param transaction - The transaction to commit
+     * @param inFlightDisposers - Collects one disposer per participant marked in flight under this
+     * transaction's id (see {@link Collection.beginInFlightAction}). REQUIRED, so a future caller
+     * cannot silently reintroduce the unmarked refresh this parameter exists to prevent: a caller
+     * that never refreshes between attempts passes a throwaway array and simply ignores it. The
+     * caller owns clearing them, because the mark has to survive past this attempt — see the
+     * array's declaration in {@link commit}.
      */
-    async commitOnce(transaction) {
+    async commitOnce(transaction, inFlightDisposers) {
         if (isTransactionExpired(transaction.stamp)) {
             throw new Error(`Transaction expired at ${transaction.stamp.expiration}`);
         }
@@ -209,6 +231,57 @@ export class TransactionCoordinator {
         if (collectionData.length === 0) {
             return; // Nothing to commit
         }
+        // NOTE: this selection reads each tracker BEFORE the latches below are held, so a stage
+        // that lands between the filter and the acquisition is simply not part of this commit.
+        // Harmless today — a session stages and commits on one call path, so nothing races its
+        // own commit. If a caller ever stages a collection concurrently with committing it,
+        // re-derive the participant set inside the held span instead of filtering out here.
+        // Hold every participating collection's instance latch for the WHOLE commit span —
+        // snapshot, log append, the pend/commit round trips, and the local fold — so a
+        // reader-driven update()/sync() on the same instance cannot interleave: without this, a
+        // refresh could adopt the newly committed revision mid-flight and recordCommitted would
+        // land the action at a revision storage never assigned it. Acquisition is in sorted
+        // collection-id order, mirroring StorageRepo.commit's sorted block-id latch discipline
+        // (db-p2p/src/storage/block-latch.ts), so two concurrent commits over overlapping
+        // participant sets cannot deadlock. `Latches` is non-reentrant, so nothing inside the
+        // held span may call a latched Collection method (act/update/sync/updateAndSync) on a
+        // participant — the retry loop's blanket collection.update() in commit() runs OUTSIDE
+        // this span, after release.
+        // NOTE: the span covers the pend/commit consensus round trips, so every latched method on
+        // a participant instance (act/update/sync) queues for as long as the transactor takes.
+        // Accepted: correctness needs the whole span, and the transactor's own timeouts bound it.
+        // If a stalled peer is ever observed wedging unrelated readers, bound the hold instead —
+        // e.g. acquire with a deadline and fail the commit rather than queueing indefinitely.
+        const latchReleases = [];
+        try {
+            const latchOrder = [...collectionData].sort((a, b) => a.collectionId < b.collectionId ? -1 : a.collectionId > b.collectionId ? 1 : 0);
+            for (const { collection } of latchOrder) {
+                latchReleases.push(await collection.acquireLatch());
+                // Mark THIS attempt's action id on each participant while its latch is held, so the
+                // inter-attempt refresh in commit() recognises a log entry this transaction itself
+                // made durable (a torn commit: header and log tail committed, a later sweep block
+                // reported the conflict) and consumes it instead of replaying it into a second entry
+                // under the same id. `transaction.id` is stable across retries, so re-marking on a
+                // later attempt re-states the same fact. Only participants are marked; a registered
+                // non-participant is left unmarked and its refresh behaves exactly as a reader's.
+                inFlightDisposers.push(collection.beginInFlightAction(transaction.id));
+            }
+            await this.commitOnceLatched(transaction, collectionData);
+        }
+        finally {
+            for (const release of latchReleases.reverse()) {
+                release();
+            }
+        }
+    }
+    /**
+     * The body of {@link commitOnce}, run with every participating collection's instance latch
+     * held by the caller (see the acquisition comment there). Nothing in here may re-acquire a
+     * participant's latch — every Collection member it touches (snapshotPending, getPendingActions,
+     * recordCommitted, applyCommittedToCache, restorePending, clearPendingActions, tracker.reset)
+     * is latch-free by contract.
+     */
+    async commitOnceLatched(transaction, collectionData) {
         // Append each collection's staged actions to its log, then collect the
         // resulting transforms + critical (log-tail) block for consensus.
         //
@@ -224,6 +297,10 @@ export class TransactionCoordinator {
         const allCollectionIds = collectionData.map(({ collectionId }) => collectionId);
         const collectionTransforms = new Map();
         const criticalBlocks = new Map();
+        // The revision each collection's log entry was stamped with. Captured ONCE — at the log
+        // append in applyActionsToCollection, the single legitimate capture point — and threaded
+        // through pend, commit, and the local recordCommitted, so all four name the same number.
+        const pendedRevs = new Map();
         // Snapshot EVERY participating collection's staged state (transforms + pending
         // queue) BEFORE the append loop mutates any tracker. The loop appends log
         // entries sequentially, so a failure on the Nth collection must also undo the
@@ -245,6 +322,7 @@ export class TransactionCoordinator {
                 }
                 collectionTransforms.set(collectionId, applyResult.transforms);
                 criticalBlocks.set(collectionId, applyResult.logTailBlockId);
+                pendedRevs.set(collectionId, applyResult.rev);
             }
             // Compute hash of ALL operations across ALL collections (post-log-append).
             // Validators re-execute the transaction and compare their computed hash.
@@ -252,7 +330,7 @@ export class TransactionCoordinator {
             // this order-independent fingerprint matches what a validator recomputes.
             const operationsHash = await hashOperations(collectOperations(collectionTransforms));
             // Execute consensus phases (GATHER, PEND, COMMIT)
-            coordResult = await this.coordinateTransaction(transaction, operationsHash, collectionTransforms, criticalBlocks);
+            coordResult = await this.coordinateTransaction(transaction, operationsHash, collectionTransforms, criticalBlocks, pendedRevs);
         }
         catch (err) {
             // A throw here means the failure happened BEFORE any collection could
@@ -283,7 +361,7 @@ export class TransactionCoordinator {
                         // collection kept its pending queue, a subsequent commit() would re-append and
                         // re-log its already-durable actions — a duplicate log entry on the winner. The
                         // no-double-apply-on-retry test in transaction.spec.ts locks this.
-                        const rev = collection.recordCommitted(transaction.id);
+                        const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId));
                         collection.applyCommittedToCache(collectionTransforms.get(collectionId), rev);
                         collection.tracker.reset();
                         collection.clearPendingActions();
@@ -322,8 +400,10 @@ export class TransactionCoordinator {
         // with prior committed state (a pre-synced index, or any second commit)
         // serves the new revision instead of the stale cached one. Clearing
         // pending keeps a subsequent commit from re-logging these actions.
+        // NOTE: this fold loop must stay await-free — session-mode publish relies on it being
+        // event-loop-atomic across collections (see OptimysticModule's readCommittedSnapshot audit).
         for (const { collectionId, collection } of collectionData) {
-            const rev = collection.recordCommitted(transaction.id);
+            const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId));
             collection.applyCommittedToCache(collectionTransforms.get(collectionId), rev);
             collection.tracker.reset();
             collection.clearPendingActions();
@@ -341,6 +421,11 @@ export class TransactionCoordinator {
      * @param stampId - The transaction stamp ID to rollback
      */
     async rollback(stampId) {
+        // NOTE: unlike the commit path, this resets and replays into participant trackers WITHOUT
+        // holding their instance latches. Safe today because a session drives abort and commit from
+        // one call path, so a rollback cannot overlap a commit span on the same collections. If
+        // rollback ever becomes reachable concurrently with a commit (a background abort, a second
+        // session sharing collection instances), latch the participants here the way commitOnce does.
         const data = this.stampData.get(stampId);
         if (!data)
             return;
@@ -496,63 +581,87 @@ export class TransactionCoordinator {
         const criticalBlocks = new Map();
         const actionResults = new Map();
         const allCollectionIds = result.actions.map(ca => ca.collectionId);
-        for (const collectionActions of result.actions) {
-            const applyResult = await this.applyActionsToCollection(collectionActions, transaction, allCollectionIds);
-            if (!applyResult.success) {
-                return { success: false, error: applyResult.error };
+        // Same single-capture rev threading as commitOnce: stamped at the log append below,
+        // named again at pend, commit, and recordCommitted.
+        const pendedRevs = new Map();
+        // Hold each participating collection's instance latch for the commit span, same
+        // discipline as commitOnce (sorted acquisition; see the comment there). Acquired only
+        // AFTER applyActions above: collection.act takes the same non-reentrant instance latch
+        // itself, so latching earlier would deadlock. Deduped before acquiring — taking one
+        // instance's latch twice would also deadlock. Released in the finally: execute has
+        // early failure returns.
+        const latchReleases = [];
+        try {
+            for (const collectionId of [...new Set(allCollectionIds)].sort()) {
+                const collection = this.collections.get(collectionId);
+                if (collection) {
+                    latchReleases.push(await collection.acquireLatch());
+                }
             }
-            collectionTransforms.set(collectionActions.collectionId, applyResult.transforms);
-            criticalBlocks.set(collectionActions.collectionId, applyResult.logTailBlockId);
-            actionResults.set(collectionActions.collectionId, applyResult.results);
-        }
-        // 3. Compute operations hash for validation (order-independent; see commit()).
-        const operationsHash = await hashOperations(collectOperations(collectionTransforms));
-        const applyMs = Date.now() - tApply;
-        // 4. Coordinate (GATHER if multi-collection)
-        const tCoord = Date.now();
-        const coordResult = await this.coordinateTransaction(transaction, operationsHash, collectionTransforms, criticalBlocks);
-        const coordMs = Date.now() - tCoord;
-        if (!coordResult.success) {
-            log('execute:done trxId=%s engine=%dms apply=%dms coordinate=%dms success=false total=%dms', trxId, engineMs, applyMs, coordMs, Date.now() - t0);
-            // Stop lying to the caller about a partial commit: if some collections durably
-            // committed, surface that set. execute() is not snapshot/restore-wrapped (see the
-            // note above), but the committed subset must still get the success-path local
-            // treatment (recordCommitted + tracker.reset, as on the success path below) so its
-            // trackers aren't left mis-tracking already-durable state.
-            const committed = coordResult.committedCollections ?? new Set();
-            if (committed.size > 0) {
-                for (const collectionActions of result.actions) {
-                    const collection = this.collections.get(collectionActions.collectionId);
-                    if (collection && committed.has(collectionActions.collectionId)) {
-                        collection.recordCommitted(transaction.id);
-                        collection.tracker.reset();
+            for (const collectionActions of result.actions) {
+                const applyResult = await this.applyActionsToCollection(collectionActions, transaction, allCollectionIds);
+                if (!applyResult.success) {
+                    return { success: false, error: applyResult.error };
+                }
+                collectionTransforms.set(collectionActions.collectionId, applyResult.transforms);
+                criticalBlocks.set(collectionActions.collectionId, applyResult.logTailBlockId);
+                actionResults.set(collectionActions.collectionId, applyResult.results);
+                pendedRevs.set(collectionActions.collectionId, applyResult.rev);
+            }
+            // 3. Compute operations hash for validation (order-independent; see commit()).
+            const operationsHash = await hashOperations(collectOperations(collectionTransforms));
+            const applyMs = Date.now() - tApply;
+            // 4. Coordinate (GATHER if multi-collection)
+            const tCoord = Date.now();
+            const coordResult = await this.coordinateTransaction(transaction, operationsHash, collectionTransforms, criticalBlocks, pendedRevs);
+            const coordMs = Date.now() - tCoord;
+            if (!coordResult.success) {
+                log('execute:done trxId=%s engine=%dms apply=%dms coordinate=%dms success=false total=%dms', trxId, engineMs, applyMs, coordMs, Date.now() - t0);
+                // Stop lying to the caller about a partial commit: if some collections durably
+                // committed, surface that set. execute() is not snapshot/restore-wrapped (see the
+                // note above), but the committed subset must still get the success-path local
+                // treatment (recordCommitted + tracker.reset, as on the success path below) so its
+                // trackers aren't left mis-tracking already-durable state.
+                const committed = coordResult.committedCollections ?? new Set();
+                if (committed.size > 0) {
+                    for (const collectionActions of result.actions) {
+                        const collection = this.collections.get(collectionActions.collectionId);
+                        if (collection && committed.has(collectionActions.collectionId)) {
+                            collection.recordCommitted(transaction.id, pendedRevs.get(collectionActions.collectionId));
+                            collection.tracker.reset();
+                        }
                     }
                 }
+                return {
+                    success: false,
+                    error: coordResult.error,
+                    committedCollections: committed.size > 0 ? [...committed] : undefined,
+                    failedCollections: coordResult.failedCollections ? [...coordResult.failedCollections] : undefined,
+                };
             }
+            // 5. Update actionContext and reset trackers after successful commit
+            for (const collectionActions of result.actions) {
+                const collection = this.collections.get(collectionActions.collectionId);
+                if (collection) {
+                    collection.recordCommitted(transaction.id, pendedRevs.get(collectionActions.collectionId));
+                    collection.tracker.reset();
+                }
+            }
+            // Clean up stamp tracking data
+            this.stampData.delete(transaction.stamp.id);
+            // 6. Return results from actions
+            log('execute:done trxId=%s engine=%dms apply=%dms coordinate=%dms total=%dms', trxId, engineMs, applyMs, coordMs, Date.now() - t0);
             return {
-                success: false,
-                error: coordResult.error,
-                committedCollections: committed.size > 0 ? [...committed] : undefined,
-                failedCollections: coordResult.failedCollections ? [...coordResult.failedCollections] : undefined,
+                success: true,
+                actions: result.actions,
+                results: actionResults
             };
         }
-        // 5. Update actionContext and reset trackers after successful commit
-        for (const collectionActions of result.actions) {
-            const collection = this.collections.get(collectionActions.collectionId);
-            if (collection) {
-                collection.recordCommitted(transaction.id);
-                collection.tracker.reset();
+        finally {
+            for (const release of latchReleases.reverse()) {
+                release();
             }
         }
-        // Clean up stamp tracking data
-        this.stampData.delete(transaction.stamp.id);
-        // 6. Return results from actions
-        log('execute:done trxId=%s engine=%dms apply=%dms coordinate=%dms total=%dms', trxId, engineMs, applyMs, coordMs, Date.now() - t0);
-        return {
-            success: true,
-            actions: result.actions,
-            results: actionResults
-        };
     }
     /**
      * Apply actions to a collection.
@@ -589,12 +698,24 @@ export class TransactionCoordinator {
         // reads are recorded on every collection's entry: a read may target a block in another
         // collection, and the cascade matches read-dependents by (blockId, revision) regardless of
         // which collection's log the dependent landed in.
+        // NOTE: `allCollectionIds` names the participants of THIS attempt, and a retry's participant
+        // set can be SMALLER than the first attempt's. After a torn commit, the participant whose
+        // entry landed durably consumes that entry on the inter-attempt refresh
+        // (Collection.inFlightActionId), empties its pending queue and resets its tracker, so
+        // commitOnce's non-empty-transforms filter drops it from the next attempt. The retry's
+        // entries therefore list only the REMAINING participants, while the torn participant's
+        // already-durable entry lists them all — one transaction id, two different
+        // `allCollectionIds` values across its entries. Nothing today keys off that list for
+        // correctness; a cross-collection invalidation cascade that treats it as "the definitive
+        // participant set of this transaction" must union it across the transaction's entries
+        // rather than trusting any single one.
         const addResult = await log.addActions(collectionActions.actions, actionId, newRev, () => blockIdsForTransforms(transforms), allCollectionIds, transaction.reads);
         // Return the transforms and log tail block ID
         return {
             success: true,
             transforms,
             logTailBlockId: addResult.tailPath.block.header.id,
+            rev: newRev,
             results: [] // TODO: Collect results from action handlers when we support read operations
         };
     }
@@ -605,8 +726,11 @@ export class TransactionCoordinator {
      * @param operationsHash - Hash of all operations for validation
      * @param collectionTransforms - Map of collectionId to its transforms
      * @param criticalBlocks - Map of collectionId to its log tail blockId
+     * @param pendedRevs - Per collection, the revision its log entry was stamped with (from
+     * applyActionsToCollection) — repeated verbatim on the pend and commit requests so storage
+     * and the local record name the same number.
      */
-    async coordinateTransaction(transaction, operationsHash, collectionTransforms, criticalBlocks) {
+    async coordinateTransaction(transaction, operationsHash, collectionTransforms, criticalBlocks, pendedRevs) {
         const trxId = transaction.id;
         const t0 = Date.now();
         // 1. GATHER phase: collect critical cluster nominees (skip if single collection)
@@ -616,7 +740,7 @@ export class TransactionCoordinator {
         const gatherMs = Date.now() - tGather;
         // 2. PEND phase: distribute to all block clusters
         const tPend = Date.now();
-        const pendResult = await this.pendPhase(transaction, operationsHash, collectionTransforms, superclusterNominees);
+        const pendResult = await this.pendPhase(transaction, operationsHash, collectionTransforms, pendedRevs, superclusterNominees);
         const pendMs = Date.now() - tPend;
         if (!pendResult.success) {
             log('trx:phases trxId=%s gather=%dms pend=%dms (failed) total=%dms', trxId, gatherMs, pendMs, Date.now() - t0);
@@ -624,7 +748,7 @@ export class TransactionCoordinator {
         }
         // 3. COMMIT phase: commit to all critical blocks (with retry for forward recovery)
         const tCommit = Date.now();
-        const commitResult = await this.commitPhase(transaction.id, criticalBlockIds, pendResult.pendedBlockIds);
+        const commitResult = await this.commitPhase(transaction.id, criticalBlockIds, pendResult.pendedBlockIds, pendedRevs);
         const commitMs = Date.now() - tCommit;
         if (!commitResult.success) {
             // Targeted cancel: only cancel collections that are still pending (not already committed)
@@ -683,9 +807,12 @@ export class TransactionCoordinator {
      * @param transaction - The full transaction for replay/validation
      * @param operationsHash - Hash of all operations for validation
      * @param collectionTransforms - Map of collectionId to its transforms
+     * @param pendedRevs - Per collection, the revision its log entry was stamped with — the pend
+     * request repeats it verbatim rather than recomputing from the collection (a recompute after
+     * the append could name a different number if the collection refreshed in between).
      * @param superclusterNominees - Nominees for multi-collection consensus (null for single-collection)
      */
-    async pendPhase(transaction, operationsHash, collectionTransforms, superclusterNominees) {
+    async pendPhase(transaction, operationsHash, collectionTransforms, pendedRevs, superclusterNominees) {
         if (collectionTransforms.size === 0) {
             return { success: false, error: 'No transforms to pend' };
         }
@@ -696,7 +823,7 @@ export class TransactionCoordinator {
         // NOTE: unbounded fan-out — one concurrent coordinator round-trip per collection.
         // Transactions touch few collections today; if one ever spans very many, bound this
         // with a concurrency limiter so peak in-flight round-trips stays sane. Same for commitPhase.
-        const outcomes = await Promise.allSettled(Array.from(collectionTransforms.entries()).map(([collectionId, transforms]) => this.pendCollection(transaction, operationsHash, collectionId, transforms, actionId, nominees)));
+        const outcomes = await Promise.allSettled(Array.from(collectionTransforms.entries()).map(([collectionId, transforms]) => this.pendCollection(transaction, operationsHash, collectionId, transforms, pendedRevs.get(collectionId), actionId, nominees)));
         // Partition settled results: every collection that DID pend (keyed with its block
         // ids), plus the first failure reason if any collection failed.
         const pendedBlockIds = new Map();
@@ -737,21 +864,23 @@ export class TransactionCoordinator {
      * pended block ids on success; throws with a per-collection reason on failure so the
      * fan-out in {@link pendPhase} can settle it as a rejection.
      */
-    async pendCollection(transaction, operationsHash, collectionId, transforms, actionId, nominees) {
+    async pendCollection(transaction, operationsHash, collectionId, transforms, 
+    /** The revision the log entry was stamped with (threaded from applyActionsToCollection),
+     * NOT recomputed here: a `getNextRev()` after the append round trips could name a number
+     * a concurrent refresh already moved past. */
+    rev, actionId, nominees) {
         const collection = this.collections.get(collectionId);
         if (!collection) {
             throw new Error(`Collection not found: ${collectionId}`);
         }
-        // Get revision from the collection's source
-        const rev = collection.getNextRev();
-        // Create pend request with transaction and operations hash for validation
+        // Create pend request with the validation payload (transaction + operations hash) —
+        // always BOTH, as one pair: this is the only producer of PendRequest.validation.
         const pendRequest = {
             actionId,
             rev,
             transforms,
             policy: 'r', // Return policy: fail but return pending actions
-            transaction,
-            operationsHash,
+            validation: { transaction, operationsHash },
             superclusterNominees: nominees
         };
         const pendResult = await this.transactor.pend(pendRequest);
@@ -771,10 +900,10 @@ export class TransactionCoordinator {
      * to commit. Failed commits are retried (forward recovery) before giving up.
      * Returns which collections committed vs failed so the caller can do targeted cancel.
      */
-    async commitPhase(actionId, criticalBlockIds, pendedBlockIds) {
+    async commitPhase(actionId, criticalBlockIds, pendedBlockIds, pendedRevs) {
         // Fan out the independent per-collection commit-with-retry concurrently, then
         // aggregate the committed/failed partition from the settled results.
-        const outcomes = await Promise.allSettled(Array.from(pendedBlockIds.entries()).map(([collectionId, blockIds]) => this.commitCollection(actionId, criticalBlockIds, collectionId, blockIds)));
+        const outcomes = await Promise.allSettled(Array.from(pendedBlockIds.entries()).map(([collectionId, blockIds]) => this.commitCollection(actionId, criticalBlockIds, collectionId, blockIds, pendedRevs.get(collectionId))));
         const committedCollections = new Set();
         const failedCollections = new Set();
         const errors = [];
@@ -823,24 +952,33 @@ export class TransactionCoordinator {
      * times (forward recovery). Always resolves — success is carried in the returned
      * `committed` flag — so the fan-out in {@link commitPhase} can aggregate every result.
      */
-    async commitCollection(actionId, criticalBlockIds, collectionId, blockIds) {
+    async commitCollection(actionId, criticalBlockIds, collectionId, blockIds, 
+    /** The revision this collection PENDED at, threaded from the log append — the same bug
+     * family as pendCollection's: recomputing `getNextRev()` here, after the pend round
+     * trips, could stamp the CommitRequest with a different number than the pend named. */
+    rev) {
         const collection = this.collections.get(collectionId);
         if (!collection) {
             return { collectionId, committed: false, error: `Collection not found: ${collectionId}` };
         }
-        // Get revision
-        const rev = collection.getNextRev();
         // Find the critical block (log tail) for this collection
         const logTailBlockId = criticalBlockIds.find(blockId => blockIds.includes(blockId));
         if (!logTailBlockId) {
             return { collectionId, committed: false, error: `Log tail block not found for collection ${collectionId}` };
         }
+        // Declare what each pended block will contain once committed. The collection's tracker still
+        // holds this transaction's staged transforms (it is reset only after commit succeeds) and
+        // layers over the collection's CacheSource, so this is a purely local computation; an id whose
+        // base is not cached is omitted and falls back to corroboration on the member side. Only the
+        // client can declare this — CoordinatorRepo.commit forwards without materializing.
+        const blockDigests = await computeBlockContentDigests(collection.tracker, blockIds);
         // Create commit request
         const commitRequest = {
             actionId,
             blockIds,
             tailId: logTailBlockId,
-            rev
+            rev,
+            ...blockDigestsField(blockDigests)
         };
         // Retry ONLY transient/thrown failures (unreachable peers, timeout) — forward recovery.
         // A returned { success:false } is a permanent stale loss (someone committed a newer rev);
@@ -858,9 +996,14 @@ export class TransactionCoordinator {
                 // mark it retryable at the coordinator level (after a re-read advances the rev).
                 // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict`
                 // like the pend path does. Once the pend succeeded, a returned commit failure means
-                // the revision slot moved, and no commit producer sets `conflict` today. If a commit
-                // producer ever starts distinguishing hard commit rejections (validator policy,
-                // storage fault) from lost races, gate `stale` on isConflictFailure here.
+                // the revision slot moved. One commit producer DOES set `conflict` now —
+                // db-p2p's CoordinatorRepo.commit returns lost commit-consensus races and classified
+                // stale-commit rejections as `{ success:false, conflict:true }` (returning, not
+                // throwing, is what keeps them out of the verbatim retry above) — but every returned
+                // failure still maps to `stale: true` here, and `isConflictFailure` covers that new
+                // shape, so no behavior change is needed. If a commit producer ever starts returning
+                // hard commit rejections (validator policy, storage fault) as results too, gate
+                // `stale` on isConflictFailure here.
                 return {
                     collectionId,
                     committed: false,