@optimystic/db-core 0.25.1 → 0.26.0

package/dist/src/transaction/coordinator.js

@@ -4,7 +4,7 @@ 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";
 const log = createLogger('trx:coordinator');
@@ -48,9 +48,41 @@ class PendRejectedError extends Error {
 export class TransactionCoordinator {
     transactor;
     collections;
-    /** 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. */
     stampData = new Map();
-    nextStampOrder = 0;
     constructor(transactor, collections) {
         this.transactor = transactor;
         this.collections = collections;
@@ -66,23 +98,81 @@ export class TransactionCoordinator {
      * @param stampId - The transaction stamp ID to tag actions with
      */
     async applyActions(actions, stampId) {
-        // On first call for this stampId, snapshot all collections for potential rollback
-        if (!this.stampData.has(stampId)) {
-            const snapshot = new Map();
-            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. */
+    openStampOtherThan(stampId) {
+        for (const open of this.stampData.keys()) {
+            if (open !== stampId)
+                return open;
+        }
+        return undefined;
+    }
+    /**
+     * 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.
+     */
+    captureUncaptured(into) {
+        for (const col of this.collections.values()) {
+            if (into.has(col))
+                continue;
+            into.set(col, col.snapshotPending());
+        }
+    }
     /**
-     * Apply actions without tracking (used internally and for replay during rollback).
+     * 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.
      */
     async applyActionsRaw(actions, stampId) {
         for (const { collectionId, actions: collectionActions } of actions) {
@@ -118,6 +208,15 @@ export class TransactionCoordinator {
      * @param options - Retry knobs; shares the {@link SyncOptions} vocabulary with `Collection.sync`.
      */
     async commit(transaction, options) {
+        // 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;
@@ -408,60 +507,59 @@ export class TransactionCoordinator {
             collection.tracker.reset();
             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) {
-        // 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();
-            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);
         }
     }
     /**
@@ -541,6 +639,23 @@ export class TransactionCoordinator {
         if (!result.actions || result.actions.length === 0) {
             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-
@@ -552,11 +667,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();
+        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);
         }
@@ -567,46 +712,81 @@ 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();
         const criticalBlocks = new Map();
         const actionResults = new Map();
-        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();
+        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();
         // 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 = [];
         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) {
-                const applyResult = await this.applyActionsToCollection(collectionActions, transaction, allCollectionIds);
+            for (const [collectionId, actions] of batches) {
+                const applyResult = await this.applyActionsToCollection({ collectionId, actions }, 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);
+                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()).
             const operationsHash = await hashOperations(collectOperations(collectionTransforms));
@@ -618,19 +798,45 @@ 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();
                 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,
@@ -639,17 +845,32 @@ export class TransactionCoordinator {
                     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);
+            // 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,