@optimystic/db-core 0.25.1 → 0.27.0

package/src/transaction/coordinator.ts

@@ -2,14 +2,14 @@ import type { ITransactor, BlockId, CollectionId, Transforms, PendRequest, Commi
 import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
 import type { PeerId } from "../network/types.js";
 import { isConflictFailure } from "../network/stale-failure.js";
-import type { Collection } from "../collection/collection.js";
+import type { Collection, CollectionSnapshot } from "../collection/collection.js";
 import type { SyncOptions } from "../collection/index.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 { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
 import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
 import { createLogger } from "../logger.js";
 
@@ -57,13 +57,43 @@ class PendRejectedError extends Error {
  * - Commit transactions by running consensus phases (GATHER, PEND, COMMIT)
  */
 export class TransactionCoordinator {
-	/** Per-stampId tracking: snapshot before first apply + accumulated actions for replay */
+	/** Per-stampId tracking: the pre-staging snapshot of every collection the stamp may have
+	 * staged into, which is everything {@link rollback} needs to rewind it.
+	 *
+	 * INVARIANT: `stampData.size <= 1` — at most ONE open stamp per coordinator, enforced by the
+	 * guards in {@link applyActions} and {@link commit} (which throw
+	 * {@link CoordinatorConcurrentStampError}) and {@link execute} (which returns it as a failure
+	 * result). The registered collections hold exactly one staged state — one tracker transform
+	 * set and one pending action queue each, shared by every open stamp — so two concurrent stamps
+	 * would read each other's uncommitted rows and a commit of either would write the other's
+	 * staged actions into its own durable log entry. A stamp is released by commit (success or
+	 * partial) or by rollback; a CLEAN commit failure keeps its entry so `rollback(stampId)`
+	 * stays a complete recovery, meaning an abandoned failed commit holds the coordinator against
+	 * new stamps until it is rolled back. The guard sees only what opens a stamp, so two
+	 * coordinators sharing collection instances — and writers that stage only via Tree.stage /
+	 * Collection.act, which open none — stay the caller's contract ("own bridge per writer" —
+	 * docs/transactions.md), not this map's.
+	 *
+	 * Each snapshot holds BOTH halves of a collection's staged state — tracker transforms AND
+	 * the pending action queue — as one {@link Collection.snapshotPending} value. Restoring only
+	 * the transforms would leave a rolled-back stamp's actions queued, where the next commit on
+	 * that collection would write them into ITS durable log entry (and a conflicting sync's
+	 * `replayActions` would re-apply them into the tracker as live data). Keeping the pair in one
+	 * value makes half-restored staged state unrepresentable here.
+	 *
+	 * `preSnapshot` is keyed by the {@link Collection} INSTANCE, not by {@link CollectionId}: the
+	 * collection map this coordinator is handed is owned by its caller (the Quereus adapter's
+	 * registry), which may replace the instance stored under an id when a table re-initializes.
+	 * An id-keyed snapshot would then restore the OLD instance's staged state onto the NEW one;
+	 * instance keys make that unrepresentable — the new instance simply gets its own capture at
+	 * the next reconcile, and the stale entry restores a detached object nobody reads.
+	 *
+	 * Capture is LAZY: a collection enters the map at the first {@link applyActions} after it
+	 * appears in `this.collections` (see {@link captureUncaptured}), so a collection registered
+	 * mid-transaction is still captured before anything stages into it. */
 	private stampData = new Map<string, {
-		order: number;
-		preSnapshot: Map<CollectionId, Transforms>;
-		actionBatches: CollectionActions[][];
+		preSnapshot: Map<Collection<any>, CollectionSnapshot<any>>;
 	}>();
-	private nextStampOrder = 0;
 
 	constructor(
 		private readonly transactor: ITransactor,
@@ -84,25 +114,84 @@ export class TransactionCoordinator {
 		actions: CollectionActions[],
 		stampId: string
 	): Promise<void> {
-		// On first call for this stampId, snapshot all collections for potential rollback
-		if (!this.stampData.has(stampId)) {
-			const snapshot = new Map<CollectionId, Transforms>();
-			for (const [id, col] of this.collections) {
-				snapshot.set(id, structuredClone(col.tracker.transforms));
+		let data = this.stampData.get(stampId);
+		if (!data) {
+			// At most one open stamp (see the invariant on stampData). Checked inside this method's
+			// await-free prologue — the check, the entry creation, and the capture below run as one
+			// atomic step, so a second stamp cannot register between a TRACKED stamp's commit guard
+			// and its log append: that stamp's entry stays in the map for the whole commit span, so
+			// this check keeps seeing it. An UNTRACKED commit (the Tree.stage / Collection.act path,
+			// which creates no entry) leaves the map empty and so cannot be interlocked this way —
+			// that is the documented out-of-scope case, not a hole this guard closes.
+			const open = this.openStampOtherThan(stampId);
+			if (open !== undefined) {
+				throw new CoordinatorConcurrentStampError(open, stampId);
 			}
-			this.stampData.set(stampId, {
-				order: this.nextStampOrder++,
-				preSnapshot: snapshot,
-				actionBatches: []
-			});
+			data = { preSnapshot: new Map() };
+			this.stampData.set(stampId, data);
 		}
-		this.stampData.get(stampId)!.actionBatches.push(actions);
+
+		// Runs on EVERY call, and stays await-free through to applyActionsRaw — see the method doc.
+		this.captureUncaptured(data.preSnapshot);
 
 		await this.applyActionsRaw(actions, stampId);
 	}
 
+	/** The id of the open stamp {@link stampData} tracks when it is not `stampId`; undefined when
+	 * no OTHER stamp is open. The single-open-stamp invariant on {@link stampData} is what makes
+	 * "the" (singular) correct here. */
+	private openStampOtherThan(stampId: string): string | undefined {
+		for (const open of this.stampData.keys()) {
+			if (open !== stampId) return open;
+		}
+		return undefined;
+	}
+
 	/**
-	 * Apply actions without tracking (used internally and for replay during rollback).
+	 * Capture the pre-staging state of every registered collection `into` does not already hold.
+	 *
+	 * Called on EVERY {@link applyActions}, not only a stamp's first. `this.collections` is owned
+	 * by the caller (the Quereus adapter's registry) and grows as tables open mid-transaction; a
+	 * collection registered after the stamp's first call would otherwise be visible to commit but
+	 * absent from every snapshot, so {@link rollback} would never visit it and its staged state
+	 * would survive into the next transaction's durable log entry.
+	 *
+	 * `applyActions` is the right capture point because it precedes any staging that call performs
+	 * — and on the Quereus path, where the vtab stages directly into the trees, the awaited
+	 * empty-actions applyActions call exists precisely to be that pre-stage barrier (see
+	 * optimystic-module.ts's "applyActions before any collection.stage" invariant).
+	 *
+	 * The already-captured guard is load-bearing: registration is idempotent (the adapter
+	 * re-registers already-open index trees), and re-capturing a collection this stamp already
+	 * staged into would record a DIRTY state as "before", making rollback preserve the very
+	 * actions it must discard.
+	 *
+	 * Synchronous and await-free BY CONTRACT, for the same reason execute()'s pre-stage snapshot
+	 * loop is: an interleaved stage would land inside a snapshot. Callers must not await between
+	 * this call and the staging it guards.
+	 *
+	 * NOTE: this runs per applyActions call rather than once per transaction. Per-call cost for an
+	 * already-captured collection is one Map.has; snapshotPending (which deep-copies the transforms)
+	 * still runs at most once per collection per stamp. Unmeasured. If the registered-collection
+	 * count ever grows large enough for the scan itself to matter, track a per-stamp "collections
+	 * map size at last capture" rather than dropping the reconcile.
+	 */
+	private captureUncaptured(into: Map<Collection<any>, CollectionSnapshot<any>>): void {
+		for (const col of this.collections.values()) {
+			if (into.has(col)) continue;
+			into.set(col, col.snapshotPending());
+		}
+	}
+
+	/**
+	 * Stage each action against its collection, tagged `transaction: stampId`, without touching
+	 * the {@link stampData} bookkeeping.
+	 *
+	 * That tag is a contract, not an implementation detail: it is the provenance the rollback tests
+	 * read (`expectNoActionsFromStamp` in coordinator-rollback-pending.spec.ts) to tell one stamp's
+	 * queued actions from another's. Only {@link applyActions} calls this; the split exists just to
+	 * keep the single-open-stamp guard and the pre-stage capture readable apart from the staging
+	 * loop.
 	 */
 	private async applyActionsRaw(
 		actions: CollectionActions[],
@@ -143,6 +232,15 @@ export class TransactionCoordinator {
 	 * @param options - Retry knobs; shares the {@link SyncOptions} vocabulary with `Collection.sync`.
 	 */
 	async commit(transaction: Transaction, options?: SyncOptions): Promise<void> {
+		// At most one open stamp (see the invariant on stampData). Checked once, BEFORE the retry
+		// loop — this is a hard failure, never retryable: the open stamp must be committed or
+		// rolled back first. This guard is what catches a caller that staged directly (Tree.stage /
+		// Collection.act, which creates no stampData entry) and commits while a sibling stamp is
+		// tracked — such a commit would sweep the sibling's queued actions into its own log entry.
+		const open = this.openStampOtherThan(transaction.stamp.id);
+		if (open !== undefined) {
+			throw new CoordinatorConcurrentStampError(open, transaction.stamp.id);
+		}
 		const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
 		const baseBackoffMs = options?.baseBackoffMs ?? DefaultBaseBackoffMs;
 		const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
@@ -347,7 +445,7 @@ export class TransactionCoordinator {
 		// failed commit leaves each tracker exactly as it was: a retry re-appends cleanly
 		// (no duplicate log entry) and a directly-staged tree's rollback (which no-ops
 		// when the stamp was never tracked via applyActions) has nothing poisoned to undo.
-		const preCommitSnapshots = new Map<CollectionId, ReturnType<Collection<any>['snapshotPending']>>();
+		const preCommitSnapshots = new Map<CollectionId, CollectionSnapshot<any>>();
 		for (const { collectionId, collection } of collectionData) {
 			preCommitSnapshots.set(collectionId, collection.snapshotPending());
 		}
@@ -471,66 +569,61 @@ export class TransactionCoordinator {
 			collection.clearPendingActions();
 		}
 
-		// Clean up stamp tracking data
+		// Clean up stamp tracking data. The reset+clear above is collection-wide, which is safe
+		// precisely because the coordinator enforces at most ONE open stamp (the invariant on
+		// stampData): no sibling stamp's snapshot exists to go stale against this commit.
 		this.stampData.delete(transaction.stamp.id);
 	}
 
 	/**
 	 * Rollback a transaction (undo only the given stampId's applied actions).
 	 *
-	 * Restores tracker state to the snapshot taken before the stampId's first
-	 * applyActions call, then replays any later stamps' actions to preserve
-	 * other sessions' transforms.
+	 * Restores each collection's staged state — tracker transforms and the pending action
+	 * queue — to the snapshot taken before the stampId's first applyActions call. Because the
+	 * coordinator allows at most ONE open stamp (the invariant on {@link stampData}), there is
+	 * never a sibling stamp whose staged state that restore could clobber, so rewinding is the
+	 * whole of rollback.
+	 *
+	 * Rolling back a stamp with no tracked entry — never opened, or already released by a commit
+	 * or an earlier rollback — is a no-op.
+	 *
+	 * NOTE: this method is complete only while that invariant holds. If the guard is ever relaxed
+	 * to permit concurrent stamps, a plain rewind stops being enough — it would discard a sibling
+	 * stamp's staged state along with this one — and the per-collection-earliest-capture plus
+	 * survivor-replay this method used to carry has to come back. Recover it from commit 26718f8a
+	 * (`ticket(implement): coordinator-drop-multi-stamp-replay-machinery`) rather than re-deriving.
 	 *
 	 * @param stampId - The transaction stamp ID to rollback
 	 */
 	async rollback(stampId: string): Promise<void> {
-		// 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.
+		// NOTE: unlike the commit path, this overwrites BOTH halves of each participant's staged
+		// state — tracker transforms AND the pending action queue — 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. The hazard class is the
+		// same one the transforms-only reset already carried: a concurrent act/sync would already
+		// have raced `tracker.reset`. If rollback ever becomes reachable concurrently with a commit
+		// (a background abort, a second coordinator sharing collection instances), latch the
+		// participants here the way commitOnce does.
 		const data = this.stampData.get(stampId);
 		if (!data) return;
 
 		this.stampData.delete(stampId);
 
-		// Collect all remaining stamps to replay
-		const toReplay = [...this.stampData.entries()]
-			.sort(([, a], [, b]) => a.order - b.order);
-
-		// Find the earliest snapshot among the rolled-back stamp and all remaining stamps.
-		// This is necessary because interleaved execution means a lower-order stamp
-		// may have batches applied after a higher-order stamp's snapshot was taken.
-		let earliestSnapshot = data.preSnapshot;
-		let earliestOrder = data.order;
-		for (const [, d] of toReplay) {
-			if (d.order < earliestOrder) {
-				earliestSnapshot = d.preSnapshot;
-				earliestOrder = d.order;
-			}
-		}
-
-		// Restore to the earliest snapshot
-		for (const [collectionId, transforms] of earliestSnapshot) {
-			const collection = this.collections.get(collectionId);
-			if (collection) {
-				collection.tracker.reset(structuredClone(transforms));
-			}
-		}
-
-		// Replay all remaining stamps' batches in order
-		for (const [replayStampId, replayData] of toReplay) {
-			// Update the snapshot to reflect current (post-replay) state
-			const newSnapshot = new Map<CollectionId, Transforms>();
-			for (const [id, col] of this.collections) {
-				newSnapshot.set(id, structuredClone(col.tracker.transforms));
-			}
-			replayData.preSnapshot = newSnapshot;
-
-			for (const actionBatch of replayData.actionBatches) {
-				await this.applyActionsRaw(actionBatch, replayStampId);
-			}
+		// Restore each captured collection — transforms AND pending queue together, so the
+		// rolled-back stamp's actions leave the queue instead of being written into the next
+		// transaction's durable log entry. `restorePending` deep-copies the transforms itself,
+		// so no structuredClone here. Restoring through the CAPTURED instance (rather than
+		// re-looking-up by id) is what keeps a mid-transaction instance swap under one id from
+		// pushing the old instance's staged state onto the new one.
+		// NOTE: this also discards actions staged OUTSIDE any tracked stamp (the Tree.stage /
+		// deferred-DML path, which calls Collection.act directly and creates no stampData entry)
+		// that landed after that collection's capture — including on a collection registered
+		// mid-transaction, whose capture is simply later than the eagerly-captured ones.
+		// Accepted: the tracker half already discards their transforms, and symmetric is the safer
+		// state — leaving such an action queued while its transforms are gone is exactly the
+		// phantom that a conflicting sync's replayActions would resurrect as live data.
+		for (const [collection, snapshot] of data.preSnapshot) {
+			collection.restorePending(snapshot);
 		}
 	}
 
@@ -621,6 +714,24 @@ export class TransactionCoordinator {
 			return { success: true }; // Nothing to do
 		}
 
+		// At most one open stamp (see the invariant on stampData). execute() reports failures as
+		// results rather than throws (matching its conversion of applyActions' "Collection not
+		// found" throw below), so the refusal is a failure result here where applyActions and
+		// commit throw.
+		//
+		// Deliberately BELOW the empty-actions short-circuit above: a transaction that stages
+		// nothing cannot mix its state with the open stamp's, so a read-only execute is allowed to
+		// run alongside one. Hoisting this to the top of the method would refuse those too — see
+		// the "does not refuse a second stamp that stages nothing" case in
+		// coordinator-single-stamp.spec.ts. The engine has already run by this point, which costs
+		// nothing here: reaching this line means the engine was a pure translator (a
+		// side-effecting engine returns EMPTY actions and short-circuits above, and its own
+		// staging goes through applyActions, which guards).
+		const openStamp = this.openStampOtherThan(transaction.stamp.id);
+		if (openStamp !== undefined) {
+			return { success: false, error: new CoordinatorConcurrentStampError(openStamp, transaction.stamp.id).message };
+		}
+
 		// 1b. Stage the returned actions into the collection trackers.
 		//
 		// Reaching here means the engine RETURNED non-empty actions — i.e. the pure-
@@ -632,11 +743,41 @@ export class TransactionCoordinator {
 		// method merely re-read the already-staged trackers; that side effect is gone, so
 		// the application must happen explicitly here. A side-effecting engine that
 		// applied internally would instead return EMPTY actions and short-circuit at the
-		// guard above.)
+		// empty-actions check above.)
 		//
 		// applyActions() throws if a referenced collection is not registered — the same
 		// "Collection not found" the engine's side-effecting apply used to surface. Convert
 		// it back into a failure result so execute() keeps its return contract.
+
+		// Pre-staging snapshot, one per DISTINCT participating collection, captured here so the
+		// partial-commit branch below can unwind the collections that did NOT land. The unwind
+		// point is "before execute() staged anything", not "before the log append": unlike
+		// commit(), a re-drive of execute() re-runs the engine and re-stages every collection it
+		// names, so leaving this attempt's actions in the pending queue would double-stage them.
+		// That is also exactly the state rollback() would have restored, which is why dropping
+		// the stamp on that branch loses nothing.
+		//
+		// snapshotPending() is synchronous and latch-free — keep it that way: NO await may sit
+		// between this loop and the applyActions() call below, or an interleaved stage would be
+		// captured inside the snapshot. Because the whole loop runs before ANY staging, an engine
+		// naming one collection in two batches yields the state before EITHER batch whichever
+		// batch wins the key — so the dedupe is a COST guard (snapshotPending deep-copies the
+		// transforms and structuredClones the action context), not a correctness one. An
+		// unregistered collection is skipped; applyActions throws on it moments later and the
+		// catch below converts that to a failure result, so the map is never read.
+		//
+		// NOTE: this runs unconditionally, so the overwhelmingly common all-succeed execute() pays
+		// one deep transforms copy + one structuredClone of the action context per participant to
+		// serve a rare branch. Unmeasured, and symmetric with commitOnceLatched, which pays the
+		// same on every commit. If execute() ever shows up hot in a profile, the way out is a
+		// copy-on-first-stage snapshot, not dropping the restore.
+		const preStageSnapshots = new Map<CollectionId, CollectionSnapshot<any>>();
+		for (const { collectionId } of result.actions) {
+			if (preStageSnapshots.has(collectionId)) continue;
+			const collection = this.collections.get(collectionId);
+			if (collection) preStageSnapshots.set(collectionId, collection.snapshotPending());
+		}
+
 		try {
 			await this.applyActions(result.actions, transaction.stamp.id);
 		} catch (error) {
@@ -647,20 +788,49 @@ export class TransactionCoordinator {
 
 		// 2. Build a log entry per collection from the now-staged tracker transforms.
 		//
-		// NOTE: like commit(), this loop appends a log entry into each collection's
-		// tracker and these failure returns do NOT restore that state — so a partially
-		// applied engine transaction leaves appended-but-uncommitted entries in the
-		// trackers. This is deliberately NOT snapshot/restore-wrapped the way commit()
-		// is, because execute()'s asymmetry makes it lower risk: it is not the retryable
-		// session.commit() entry point (a failed execute() is not re-driven through the
-		// same loop), and its actions were tracked via applyActions() so rollback(stampId)
-		// CAN unwind them (unlike commit()'s directly-staged path). If execute() ever
-		// becomes retryable, mirror the commit() snapshot/restore fix here.
+		// NOTE: like commit(), this loop appends a log entry into each collection's tracker.
+		// What happens to that appended-but-uncommitted state on failure depends on whether
+		// anything landed durably:
+		//
+		//  - Failure BEFORE any durable commit (engine failure, log-append failure, or a
+		//    coordination failure with an empty committed set): the failure returns below do NOT
+		//    restore, so the appended entries survive in the trackers and `stampData` is kept.
+		//    That is deliberate — the actions were tracked via applyActions(), so rollback(stampId)
+		//    is a valid AND complete recovery there: its capture predates this staging and covers
+		//    every registered collection, including ones this call never touched. Do not add blind
+		//    restores to these paths.
+		//  - PARTIAL landing (some collections durably committed, others lost): the committed half
+		//    gets the success-path fold, the failed half is restored to the pre-staging snapshot
+		//    captured above, and `stampData` is dropped — because an all-or-nothing rollback() run
+		//    after a partial landing would rewind the collection that DID commit, re-staging
+		//    already-durable actions. Same disposition as commitOnceLatched. See that branch below.
 		const tApply = Date.now();
 		const collectionTransforms = new Map<CollectionId, Transforms>();
 		const criticalBlocks = new Map<CollectionId, BlockId>();
 		const actionResults = new Map<CollectionId, any[]>();
-		const allCollectionIds = result.actions.map(ca => ca.collectionId);
+
+		// Coalesce the engine's batches to ONE per collection. Nothing stops an engine from
+		// emitting two `CollectionActions` entries naming the same collection (with the built-in
+		// ActionsEngine that is just two statements against one table), but everything downstream
+		// of here is written per-PARTICIPANT, not per-batch: the apply loop would append two log
+		// entries stamped with the same revision (the revision only advances at recordCommitted),
+		// the id-keyed maps below would discard the first batch's entry, and both folds would call
+		// recordCommitted twice — the second throwing on the revision it already advanced past,
+		// AFTER the transaction committed durably. One log entry per collection per transaction is
+		// the invariant commitOnceLatched holds by construction (it appends one entry carrying that
+		// collection's whole pending queue), so match it here by grouping instead.
+		//
+		// First-appearance collection order, and each collection's own actions in the order the
+		// engine emitted them. The STAGING above deliberately ran on the original, un-coalesced
+		// list: staging order is what a re-executing validator reproduces, so it stays exactly as
+		// the engine emitted it. Grouping is only for the log-append and fold phase below.
+		const batches = new Map<CollectionId, unknown[]>();
+		for (const { collectionId, actions } of result.actions) {
+			const existing = batches.get(collectionId);
+			if (existing) existing.push(...actions);
+			else batches.set(collectionId, [...actions]);
+		}
+		const allCollectionIds = [...batches.keys()];
 		// Same single-capture rev threading as commitOnce: stamped at the log append below,
 		// named again at pend, commit, and recordCommitted.
 		const pendedRevs = new Map<CollectionId, number>();
@@ -668,21 +838,26 @@ export class TransactionCoordinator {
 		// 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.
+		// itself, so latching earlier would deadlock. The list must be DISTINCT — taking one
+		// instance's latch twice would also deadlock — which the grouping above now guarantees
+		// upstream (`allCollectionIds` is `batches.keys()`) instead of at the acquisition.
+		// Released in the finally: execute has early failure returns.
 		const latchReleases: (() => void)[] = [];
 		try {
-			for (const collectionId of [...new Set(allCollectionIds)].sort()) {
+			// NOTE: deadlock-freedom against a concurrent commitOnce needs BOTH paths to acquire in
+			// the SAME order, not merely each in a sorted one. `CollectionId` is a string, so this
+			// default `.sort()` and commitOnce's explicit `<`/`>` comparator agree today. If either
+			// spelling changes — a custom comparator, a non-string id — change both together.
+			for (const collectionId of [...allCollectionIds].sort()) {
 				const collection = this.collections.get(collectionId);
 				if (collection) {
 					latchReleases.push(await collection.acquireLatch());
 				}
 			}
 
-			for (const collectionActions of result.actions) {
+			for (const [collectionId, actions] of batches) {
 				const applyResult = await this.applyActionsToCollection(
-					collectionActions,
+					{ collectionId, actions },
 					transaction,
 					allCollectionIds
 				);
@@ -691,10 +866,10 @@ export class TransactionCoordinator {
 					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!);
+				collectionTransforms.set(collectionId, applyResult.transforms!);
+				criticalBlocks.set(collectionId, applyResult.logTailBlockId!);
+				actionResults.set(collectionId, applyResult.results!);
+				pendedRevs.set(collectionId, applyResult.rev!);
 			}
 
 			// 3. Compute operations hash for validation (order-independent; see commit()).
@@ -716,19 +891,42 @@ export class TransactionCoordinator {
 			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.
+				// committed, surface that set. The committed subset gets the full success-path
+				// local treatment (the same four steps as commitOnceLatched's partial-commit fold,
+				// in the same order — see the success fold below) so its trackers, read caches and
+				// pending queues aren't left mis-tracking already-durable state; the failed subset
+				// is unwound to its pre-staging snapshot, and the stamp tracking is dropped so no
+				// unsafe all-or-nothing undo handle survives (rollback() would rewind the winner).
+				// Kept await-free for the same reason the success fold is — restorePending is
+				// synchronous and latch-free by contract, so it is safe inside this latched span.
 				const committed = coordResult.committedCollections ?? new Set<CollectionId>();
 				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)!);
+					for (const collectionId of batches.keys()) {
+						const collection = this.collections.get(collectionId);
+						if (!collection) continue;
+						if (committed.has(collectionId)) {
+							const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId)!);
+							collection.applyCommittedToCache(collectionTransforms.get(collectionId)!, rev);
 							collection.tracker.reset();
+							collection.clearPendingActions();
+						} else {
+							// NOTE: blind overwrite of this collection's staged state — anything
+							// staged on it between the pre-stage snapshot above and here is discarded.
+							// No sibling stamp can be that writer (at most one stamp is open), so the
+							// only source is the untracked Tree.stage / Collection.act path, and this
+							// is the same single-call-path assumption rollback() documents. It cannot
+							// be softened by re-applying those actions here: collection.act takes the
+							// same non-reentrant instance latch this span already holds.
+							const snapshot = preStageSnapshots.get(collectionId);
+							if (snapshot) collection.restorePending(snapshot);
 						}
 					}
+					// The undo handle is now unsafe: rollback() is all-or-nothing and would rewind
+					// the collections that DID durably commit. Drop it, matching commitOnceLatched.
+					// Dropping outright (no tombstone) is safe because the coordinator enforces at
+					// most ONE open stamp (the invariant on stampData): no sibling stamp exists,
+					// so nothing else can later look for this entry and be misled by its absence.
+					this.stampData.delete(transaction.stamp.id);
 				}
 				return {
 					success: false,
@@ -738,19 +936,34 @@ export class TransactionCoordinator {
 				};
 			}
 
-			// 5. Update actionContext and reset trackers after successful commit
-			for (const collectionActions of result.actions) {
-				const collection = this.collections.get(collectionActions.collectionId);
+			// 5. Advance actionContext, fold the committed transforms into each collection's read
+			// cache, reset the tracker, and drop the now-committed pending actions — the same four
+			// steps, in the same order, as commitOnceLatched's success fold. Order matters: cache
+			// the committed blocks BEFORE resetting the tracker (the transforms are read live), so a
+			// collection with prior committed state serves the new revision instead of the stale
+			// cached one. Clearing pending keeps a subsequent commit() on this same collection from
+			// re-logging these already-durable actions.
+			// NOTE: this fold loop must stay await-free, for the same reason commitOnce's does —
+			// session-mode publish relies on it being event-loop-atomic across collections.
+			for (const collectionId of batches.keys()) {
+				const collection = this.collections.get(collectionId);
 				if (collection) {
-					collection.recordCommitted(transaction.id, pendedRevs.get(collectionActions.collectionId)!);
+					const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId)!);
+					collection.applyCommittedToCache(collectionTransforms.get(collectionId)!, rev);
 					collection.tracker.reset();
+					collection.clearPendingActions();
 				}
 			}
 
 			// Clean up stamp tracking data
 			this.stampData.delete(transaction.stamp.id);
 
-			// 6. Return results from actions
+			// 6. Return results from actions.
+			// `actions` is the engine's ORIGINAL batch list, un-coalesced — the field is documented
+			// as "the actions produced by executing the transaction", and the caller's own shape is
+			// the honest answer to that. `results` is keyed by collection id, so the two are NOT
+			// positionally aligned when an engine named one collection in more than one batch; join
+			// them on collectionId, never by index.
 			log('execute:done trxId=%s engine=%dms apply=%dms coordinate=%dms total=%dms', trxId, engineMs, applyMs, coordMs, Date.now() - t0);
 			return {
 				success: true,