@optimystic/db-core 0.21.0 → 0.24.0

package/src/testing/test-transactor.ts

@@ -1,489 +1,638 @@
-import { type ITransactor, type GetBlockResults, type ActionBlocks, type BlockActionStatus, type PendResult, type CommitResult, type PendRequest, type BlockId, type CommitRequest, type BlockGets, type IBlock, type ActionId, type ActionTransforms, type Transform, type Transforms, ensuredMap, Latches, type ClusterNomineesResult } from "../index.js";
-import { applyTransform, blockIdsForTransforms, transformForBlockId, emptyTransforms, concatTransform, transformsFromTransform } from "../transform/index.js";
-
-type RevisionNumber = number;
-
-type BlockState = {
-  /** The current materialized block at each revision */
-  materializedBlocks: Map<RevisionNumber, IBlock>;
-  /** The latest revision number */
-  latestRev: RevisionNumber;
-  /** The action that created each revision */
-  revisionActions: Map<RevisionNumber, ActionId>;
-  /** Currently pending actions */
-  pendingActions: Map<ActionId, Transform>;
-	/** Committed actions */
-	committedActions: Map<ActionId, Transform>;
-}
-
-// Simple in-memory transactor for testing that maintains materialized blocks for every revision
-export class TestTransactor implements ITransactor {
-  private blocks = new Map<BlockId, BlockState>();
-	available = true;
-	private getLocks = new Map<BlockId, Promise<() => void>>(); // Track lock releases
-
-  constructor() {}
-
-  async get(blockGets: BlockGets): Promise<GetBlockResults> {
-		this.checkAvailable();
-    const results: GetBlockResults = {};
-		const uniqueBlockIds = [...new Set(blockGets.blockIds)].sort(); // Ensure consistent lock order if needed, though get is read-only
-		const releases: (() => void)[] = [];
-
-		try {
-			// Acquire locks for all requested blocks to ensure consistent read
-			for (const blockId of uniqueBlockIds) {
-				const lockId = `TestTransactor.commit:${blockId}`; // Use the same lock as commit
-				// Wait for any existing lock promise to resolve before acquiring the next
-				let release = await this.getLocks.get(lockId);
-				if (release) await Promise.resolve(release); // Ensure previous lock released if overlapping calls happen
-
-				const releasePromise = Latches.acquire(lockId);
-				this.getLocks.set(blockId, releasePromise.then(r => () => {
-					r();
-					this.getLocks.delete(blockId); // Clean up map entry after release
-				}));
-				release = await releasePromise;
-				releases.push(release);
-			}
-
-			// --- Start of Critical Section (Read) ---
-			for (const blockId of blockGets.blockIds) {
-				const blockState = this.blocks.get(blockId);
-				if (!blockState) {
-					// Block doesn't exist yet
-					results[blockId] = {
-						block: undefined,
-						state: { latest: undefined, pendings: [] }
-					};
-					continue;
-				}
-
-				// Get the appropriate materialized block based on context
-				let block: IBlock | undefined;
-				// The revision `block` was actually materialized at, reported as
-				// GetBlockResult.materializedRev. Equals `latestRev` on every unpinned path; only a
-				// revision-pinned read of a block committed further since the pin makes them differ,
-				// and there the pinned value is what the reader observed (see the field's doc).
-				let materializedRev: number | undefined;
-				if (blockGets.context?.actionId !== undefined) {
-					// If requesting a specific action, apply pending transform if it exists
-					const pendingTransform = blockState.pendingActions.get(blockGets.context.actionId);
-					if (pendingTransform) {
-						// Read latest committed block as base for pending transform
-						const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
-						block = applyTransformSafe(baseBlock, pendingTransform);
-						// A pending carries no revision of its own — report the committed base it was
-						// applied over. Absent when there was no base (a pending-only insert).
-						if (baseBlock) materializedRev = blockState.latestRev;
-					} else {
-						// Action not pending, maybe committed? Or maybe invalid actionId for context.
-						// For simplicity, return undefined block if specific pending action not found.
-						// A more complex impl might check committedActions history.
-						block = undefined;
-					}
-				} else if (blockGets.context?.committed) {
-					// Check context.committed for matching pending actions — mirrors coordinator
-					// behavior: context.committed proves the action succeeded, so pending blocks
-					// for that action should be served.
-					for (const { actionId: cId } of blockGets.context.committed) {
-						const pendingTransform = blockState.pendingActions.get(cId);
-						if (pendingTransform) {
-							const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
-							block = applyTransformSafe(baseBlock, pendingTransform);
-							if (baseBlock) materializedRev = blockState.latestRev;
-							break;
-						}
-					}
-					// Fall through to standard resolution if no pending match
-					if (block === undefined) {
-						if (blockGets.context.rev !== undefined) {
-							const found = latestMaterializedAt(blockState, blockGets.context.rev);
-							block = structuredClone(found?.block);
-							materializedRev = found?.rev;
-						} else {
-							block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
-							if (block) materializedRev = blockState.latestRev;
-						}
-					}
-				} else if (blockGets.context?.rev !== undefined) {
-					// Return the materialized block at the highest revision ≤ requested
-					const found = latestMaterializedAt(blockState, blockGets.context.rev);
-					block = structuredClone(found?.block);
-					materializedRev = found?.rev;
-				} else {
-					// Otherwise return latest materialized block
-					block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
-					if (block) materializedRev = blockState.latestRev;
-				}
-
-
-				const actionId = blockState.revisionActions.get(blockState.latestRev);
-				results[blockId] = {
-					block,
-					...(materializedRev !== undefined ? { materializedRev } : {}),
-					state: {
-						latest: actionId !== undefined ? {
-							rev: blockState.latestRev,
-							actionId
-						} : undefined,
-						pendings: Array.from(blockState.pendingActions.keys())
-					}
-				};
-			}
-			// --- End of Critical Section (Read) ---
-
-		} finally {
-			// Release locks in reverse order
-			releases.reverse().forEach(release => release());
-		}
-    return results;
-  }
-
-  async getStatus(actionRefs: ActionBlocks[]): Promise<BlockActionStatus[]> {
-    return actionRefs.map(ref => ({
-      ...ref,
-      statuses: ref.blockIds.map(blockId => {
-        const blockState = this.blocks.get(blockId);
-        if (!blockState) return 'aborted';
-        return blockState.pendingActions.has(ref.actionId) ? 'pending'
-					: Array.from(blockState.revisionActions.values()).some(actionId => actionId === ref.actionId) ? 'committed'
-					: 'aborted';
-      })
-    }));
-  }
-
-  async pend(request: PendRequest): Promise<PendResult> {
-		this.checkAvailable();
-		const { actionId, transforms, policy, rev } = request;
-		const blockIds = blockIdsForTransforms(transforms);
-		const conflictingPendings: { blockId: BlockId, actionId: ActionId }[] = [];
-		const missing: ActionTransforms[] = [];
-
-		// Check for conflicts (pending or committed based on rev/insert)
-		for (const blockId of blockIds) {
-			const blockState = this.blocks.get(blockId);
-			const blockTransform = transformForBlockId(transforms, blockId);
-			if (!blockTransform) continue; // Should not happen
-
-			if (blockState) {
-				// Check for existing pending actions
-				if (blockState.pendingActions.size > 0) {
-					blockState.pendingActions.forEach((_, pendingActionId) => {
-						conflictingPendings.push({ blockId, actionId: pendingActionId });
-					});
-				}
-
-				// Check for conflicting committed revisions (if rev specified or it's an insert)
-				if (rev !== undefined || blockTransform.insert) {
-					const checkRev = rev ?? 0; // Check from revision 0 if it's an insert
-					if (blockState.latestRev >= checkRev) {
-						// Collect conflicting committed actions
-						const missingForBlock = new Map<ActionId, { rev: number, transform: Transform }>();
-						for (let r = checkRev as number; r <= blockState.latestRev; r++) {
-							const committedActionId = blockState.revisionActions.get(r);
-							if (committedActionId !== undefined) {
-								const committedTransform = blockState.committedActions.get(committedActionId);
-								if (committedTransform) {
-									missingForBlock.set(committedActionId, { rev: r, transform: committedTransform });
-								}
-							}
-						}
-
-						// Add collected missing transforms for this block to the main missing list
-						for (const [mActionId, data] of missingForBlock.entries()) {
-							let existing = missing.find(m => m.actionId === mActionId);
-							if (!existing) {
-								existing = { actionId: mActionId, rev: data.rev, transforms: emptyTransforms() };
-								missing.push(existing);
-							}
-							existing.rev = Math.max(existing.rev ?? 0, data.rev);
-							existing.transforms = concatTransform(existing.transforms, blockId, data.transform);
-						}
-					}
-				}
-			}
-		}
-
-		// Handle failure due to committed conflicts first.
-		// `conflict: true` on the three optimistic-concurrency returns below mirrors what
-		// StorageRepo.pend now emits, so consumers of this test transactor see the real shape.
-		if (missing.length > 0) {
-			return {
-				success: false,
-				conflict: true,
-				missing
-			};
-		}
-
-		// Handle failure/retry due to pending conflicts
-		if (conflictingPendings.length > 0) {
-			if (policy === 'f') {
-				return { success: false, conflict: true, pending: conflictingPendings };
-			} else if (policy === 'r') {
-				// Simulate fetching pending transforms for 'r' policy
-				const pendingWithTransforms = conflictingPendings
-					.map(({ blockId: pBlockId, actionId: pActionId }) => {
-						const pBlockState = this.blocks.get(pBlockId);
-						const pTransform = pBlockState?.pendingActions.get(pActionId)
-							?? pBlockState?.committedActions.get(pActionId); // Might have been committed since check
-						if (pTransform) {
-							return { blockId: pBlockId, actionId: pActionId, transform: pTransform };
-						}
-						return null; // Handle case where it disappeared (cancelled?)
-					})
-					.filter(p => p !== null) as { blockId: BlockId, actionId: ActionId, transform: Transform }[];
-
-				return {
-					success: false,
-					conflict: true,
-					pending: pendingWithTransforms
-				};
-			}
-			// Policy 'w' allows proceeding despite pending transactions
-		}
-
-		// No fatal conflicts found, proceed to pend
-		for (const blockId of blockIds) {
-			const blockTransform = transformForBlockId(transforms, blockId);
-			if (blockTransform) {
-				const blockState = ensuredMap(this.blocks, blockId, () => newBlockState());
-				blockState.pendingActions.set(actionId, blockTransform);
-			}
-		}
-
-		// Return success, include pending list as per StorageRepo behavior
-		return {
-			success: true,
-			pending: conflictingPendings,
-			blockIds
-		} as PendResult;
-	}
-
-  async cancel(actionRef: ActionBlocks): Promise<void> {
-		this.checkAvailable();
-    for (const blockId of actionRef.blockIds) {
-      const blockState = this.blocks.get(blockId);
-      if (blockState) {
-        blockState.pendingActions.delete(actionRef.actionId);
-      }
-    }
-  }
-
-  async commit(request: CommitRequest): Promise<CommitResult> {
-		this.checkAvailable();
-    const { actionId, rev, blockIds } = request;
-    const uniqueBlockIds = [...new Set(blockIds)].sort();
-    const releases: (() => void)[] = [];
-
-    try {
-      // Simulate acquiring locks sequentially like StorageRepo
-      for (const id of uniqueBlockIds) {
-        const lockId = `TestTransactor.commit:${id}`;
-        const release = await Latches.acquire(lockId);
-        releases.push(release);
-      }
-
-      // --- Start of Critical Section (Simulated) ---
-
-      // Check for stale revisions
-      const staleBlocks = blockIds.filter(blockId => {
-        const blockState = this.blocks.get(blockId);
-        return blockState && blockState.latestRev >= rev;
-      });
-
-      if (staleBlocks.length > 0) {
-        // Collect missing actions for stale blocks
-        const missingByAction = new Map<ActionId, Transforms>();
-        for (const blockId of staleBlocks) {
-          const blockState = this.blocks.get(blockId)!;
-          for (let r = rev; r <= blockState.latestRev; r++) {
-            const committedActionId = blockState.revisionActions.get(r);
-            if (committedActionId) {
-              const transform = blockState.committedActions.get(committedActionId);
-              if (transform) {
-                const existing = missingByAction.get(committedActionId) ?? emptyTransforms();
-                missingByAction.set(committedActionId, concatTransform(existing, blockId, transform));
-              }
-            }
-          }
-        }
-
-        const missing: ActionTransforms[] = Array.from(missingByAction.entries()).map(([actionId, transforms]) => ({
-          actionId,
-          rev: Array.from(this.blocks.values())
-            .flatMap(bs => Array.from(bs.revisionActions.entries()))
-            .find(([, aId]) => aId === actionId)?.[0] ?? rev,
-          transforms
-        }));
-        return { success: false, missing };
-      }
-
-      // Verify all blocks have the pending action
-      for (const blockId of blockIds) {
-        const blockState = this.blocks.get(blockId);
-        if (!blockState || !blockState.pendingActions.has(actionId)) {
-          return {
-            success: false,
-            reason: `Action ${actionId} not found or not pending for block ${blockId}`
-          };
-        }
-      }
-
-      // Commit the action for each block
-      for (const blockId of blockIds) {
-        const blockState = this.blocks.get(blockId)!;
-        const transform = blockState.pendingActions.get(actionId)!;
-
-        // Get base block to apply transform to
-        const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
-
-        let newBlock: IBlock | undefined;
-        if (!baseBlock) {
-          if (!transform.insert) {
-            throw new Error(`Commit Error: Action ${actionId} has no insert for new block ${blockId}`);
-          }
-          newBlock = structuredClone(transform.insert);
-        } else {
-          newBlock = applyTransformSafe(baseBlock, transform);
-          if (!newBlock && !transform.delete) {
-            throw new Error(`Commit Error: Action ${actionId} resulted in undefined block but had no delete flag for block ${blockId}`);
-          }
-        }
-
-        if (newBlock) {
-          blockState.materializedBlocks.set(rev, newBlock);
-        }
-
-        // Update block state
-        blockState.latestRev = rev;
-        blockState.revisionActions.set(rev, actionId);
-        blockState.committedActions.set(actionId, transform);
-        blockState.pendingActions.delete(actionId);
-      }
-
-      // --- End of Critical Section (Simulated) ---
-
-      return { success: true };
-
-    } finally {
-      // Release locks in reverse order
-      releases.reverse().forEach(release => release());
-    }
-  }
-
-  // Helper methods for testing
-  reset() {
-    this.blocks.clear();
-  }
-
-  getPendingActions(): Map<ActionId, ActionTransforms> {
-    const allPending = new Map<ActionId, ActionTransforms>();
-    for (const [blockId, blockState] of this.blocks.entries()) {
-      for (const [actionId, transform] of blockState.pendingActions) {
-        const existing = allPending.get(actionId);
-        if (!existing) {
-          allPending.set(actionId, { actionId, transforms: transformsFromTransform(transform, blockId) });
-        } else {
-          existing.transforms = concatTransform(existing.transforms, blockId, transform);
-        }
-      }
-    }
-    return allPending;
-  }
-
-  getCommittedActions(): Map<ActionId, ActionTransforms> {
-    const allCommitted = new Map<ActionId, ActionTransforms>();
-    for (const [blockId, blockState] of this.blocks.entries()) {
-      for (const [rev, actionId] of blockState.revisionActions) {
-        const transform = blockState.committedActions.get(actionId);
-        if (transform) {
-          const existing = allCommitted.get(actionId);
-          if (!existing) {
-            allCommitted.set(actionId, {
-              actionId,
-              rev,
-              transforms: transformsFromTransform(transform, blockId)
-            });
-          } else {
-            existing.transforms = concatTransform(existing.transforms, blockId, transform);
-          }
-        }
-      }
-    }
-    return allCommitted;
-  }
-
-	setAvailable(available: boolean) {
-		this.available = available;
-	}
-
-	checkAvailable() {
-		if (!this.available) {
-			throw new Error('Transactor is not available');
-		}
-	}
-
-	/** Optional method for querying cluster nominees (used in GATHER phase for multi-collection transactions) */
-	queryClusterNominees?: (blockId: BlockId) => Promise<ClusterNomineesResult>;
-}
-
-/**
- * Wraps a {@link TestTransactor} and forces its commit phase to fail a bounded (or unbounded)
- * number of times before delegating, so tests can exercise the sync retry / backoff / give-up
- * path deterministically. pend/get/getStatus/cancel delegate unchanged, so the pend→commit→cancel
- * round-trip runs exactly as in production.
- */
-export class FlakyCommitTransactor implements ITransactor {
-	/** Number of commit() calls observed so far (across success and forced failure). */
-	commitAttempts = 0;
-
-	/**
-	 * @param inner delegate transactor
-	 * @param failFirstN number of initial commit() calls to fail; Infinity to always fail
-	 * @param reason the StaleFailure.reason returned on a forced failure
-	 */
-	constructor(
-		private readonly inner: TestTransactor,
-		private readonly failFirstN: number,
-		private readonly reason = 'forced stale',
-	) {}
-
-	get(b: BlockGets): Promise<GetBlockResults> { return this.inner.get(b); }
-	getStatus(a: ActionBlocks[]): Promise<BlockActionStatus[]> { return this.inner.getStatus(a); }
-	pend(r: PendRequest): Promise<PendResult> { return this.inner.pend(r); }
-	cancel(a: ActionBlocks): Promise<void> { return this.inner.cancel(a); }
-
-	async commit(request: CommitRequest): Promise<CommitResult> {
-		this.commitAttempts++;
-		if (this.commitAttempts <= this.failFirstN) {
-			return { success: false, reason: this.reason };
-		}
-		return this.inner.commit(request);
-	}
-}
-
-function newBlockState(): BlockState {
-	return {
-		materializedBlocks: new Map(),
-		latestRev: 0,
-		revisionActions: new Map(),
-		pendingActions: new Map(),
-		committedActions: new Map()
-	};
-}
-
-/** Returns the materialized block at the highest revision ≤ the given revision, together with
- *  that revision — the caller reports it as {@link GetBlockResult.materializedRev}. */
-function latestMaterializedAt(blockState: BlockState, maxRev: number): { block: IBlock, rev: number } | undefined {
-	for (let rev = maxRev; rev >= 0; rev--) {
-		const block = blockState.materializedBlocks.get(rev);
-		if (block) return { block, rev };
-	}
-	return undefined;
-}
-
-function applyTransformSafe(block: IBlock | undefined, transform: Transform): IBlock | undefined {
-  if (!block) return undefined;
-  return applyTransform(structuredClone(block), transform);
-}
+import type { ITransactor, GetBlockResults, ActionBlocks, BlockActionStatus, PendResult, CommitResult, PendRequest, BlockId, CommitRequest, BlockGets, IBlock, ActionId, ActionTransforms, Transform, Transforms, ClusterNomineesResult, CollectionId } from "../index.js";
+import { ensuredMap } from "../utility/ensured.js";
+import { Latches } from "../utility/latches.js";
+import { applyTransform, blockIdsForTransforms, transformForBlockId, emptyTransforms, concatTransform, transformsFromTransform } from "../transform/index.js";
+import { Tree } from "../collections/tree/tree.js";
+import type { TreeReplaceAction } from "../collections/tree/struct.js";
+
+type RevisionNumber = number;
+
+type BlockState = {
+  /** The current materialized block at each revision */
+  materializedBlocks: Map<RevisionNumber, IBlock>;
+  /** The latest revision number */
+  latestRev: RevisionNumber;
+  /** The action that created each revision */
+  revisionActions: Map<RevisionNumber, ActionId>;
+  /** Currently pending actions */
+  pendingActions: Map<ActionId, Transform>;
+	/** Committed actions */
+	committedActions: Map<ActionId, Transform>;
+}
+
+// Simple in-memory transactor for testing that maintains materialized blocks for every revision
+export class TestTransactor implements ITransactor {
+  private blocks = new Map<BlockId, BlockState>();
+	available = true;
+	private getLocks = new Map<BlockId, Promise<() => void>>(); // Track lock releases
+
+  constructor() {}
+
+  async get(blockGets: BlockGets): Promise<GetBlockResults> {
+		this.checkAvailable();
+    const results: GetBlockResults = {};
+		const uniqueBlockIds = [...new Set(blockGets.blockIds)].sort(); // Ensure consistent lock order if needed, though get is read-only
+		const releases: (() => void)[] = [];
+
+		try {
+			// Acquire locks for all requested blocks to ensure consistent read
+			for (const blockId of uniqueBlockIds) {
+				const lockId = `TestTransactor.commit:${blockId}`; // Use the same lock as commit
+				// Wait for any existing lock promise to resolve before acquiring the next
+				let release = await this.getLocks.get(lockId);
+				if (release) await Promise.resolve(release); // Ensure previous lock released if overlapping calls happen
+
+				const releasePromise = Latches.acquire(lockId);
+				this.getLocks.set(blockId, releasePromise.then(r => () => {
+					r();
+					this.getLocks.delete(blockId); // Clean up map entry after release
+				}));
+				release = await releasePromise;
+				releases.push(release);
+			}
+
+			// --- Start of Critical Section (Read) ---
+			for (const blockId of blockGets.blockIds) {
+				const blockState = this.blocks.get(blockId);
+				if (!blockState) {
+					// Block doesn't exist yet
+					results[blockId] = {
+						block: undefined,
+						state: { latest: undefined, pendings: [] }
+					};
+					continue;
+				}
+
+				// Get the appropriate materialized block based on context
+				let block: IBlock | undefined;
+				// The revision `block` was actually materialized at, reported as
+				// GetBlockResult.materializedRev. Equals `latestRev` on every unpinned path; only a
+				// revision-pinned read of a block committed further since the pin makes them differ,
+				// and there the pinned value is what the reader observed (see the field's doc).
+				let materializedRev: number | undefined;
+				if (blockGets.context?.actionId !== undefined) {
+					// If requesting a specific action, apply pending transform if it exists
+					const pendingTransform = blockState.pendingActions.get(blockGets.context.actionId);
+					if (pendingTransform) {
+						// Read latest committed block as base for pending transform
+						const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
+						block = applyTransformSafe(baseBlock, pendingTransform);
+						// A pending carries no revision of its own — report the committed base it was
+						// applied over. Absent when there was no base (a pending-only insert).
+						if (baseBlock) materializedRev = blockState.latestRev;
+					} else {
+						// Action not pending, maybe committed? Or maybe invalid actionId for context.
+						// For simplicity, return undefined block if specific pending action not found.
+						// A more complex impl might check committedActions history.
+						block = undefined;
+					}
+				} else if (blockGets.context?.committed) {
+					// Check context.committed for matching pending actions — mirrors coordinator
+					// behavior: context.committed proves the action succeeded, so pending blocks
+					// for that action should be served.
+					for (const { actionId: cId } of blockGets.context.committed) {
+						const pendingTransform = blockState.pendingActions.get(cId);
+						if (pendingTransform) {
+							const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
+							block = applyTransformSafe(baseBlock, pendingTransform);
+							if (baseBlock) materializedRev = blockState.latestRev;
+							break;
+						}
+					}
+					// Fall through to standard resolution if no pending match
+					if (block === undefined) {
+						if (blockGets.context.rev !== undefined) {
+							const found = latestMaterializedAt(blockState, blockGets.context.rev);
+							block = structuredClone(found?.block);
+							materializedRev = found?.rev;
+						} else {
+							block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
+							if (block) materializedRev = blockState.latestRev;
+						}
+					}
+				} else if (blockGets.context?.rev !== undefined) {
+					// Return the materialized block at the highest revision ≤ requested
+					const found = latestMaterializedAt(blockState, blockGets.context.rev);
+					block = structuredClone(found?.block);
+					materializedRev = found?.rev;
+				} else {
+					// Otherwise return latest materialized block
+					block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
+					if (block) materializedRev = blockState.latestRev;
+				}
+
+
+				const actionId = blockState.revisionActions.get(blockState.latestRev);
+				results[blockId] = {
+					block,
+					...(materializedRev !== undefined ? { materializedRev } : {}),
+					state: {
+						latest: actionId !== undefined ? {
+							rev: blockState.latestRev,
+							actionId
+						} : undefined,
+						pendings: Array.from(blockState.pendingActions.keys())
+					}
+				};
+			}
+			// --- End of Critical Section (Read) ---
+
+		} finally {
+			// Release locks in reverse order
+			releases.reverse().forEach(release => release());
+		}
+    return results;
+  }
+
+  async getStatus(actionRefs: ActionBlocks[]): Promise<BlockActionStatus[]> {
+    return actionRefs.map(ref => ({
+      ...ref,
+      statuses: ref.blockIds.map(blockId => {
+        const blockState = this.blocks.get(blockId);
+        if (!blockState) return 'aborted';
+        return blockState.pendingActions.has(ref.actionId) ? 'pending'
+					: Array.from(blockState.revisionActions.values()).some(actionId => actionId === ref.actionId) ? 'committed'
+					: 'aborted';
+      })
+    }));
+  }
+
+  async pend(request: PendRequest): Promise<PendResult> {
+		this.checkAvailable();
+		const { actionId, transforms, policy, rev } = request;
+		const blockIds = blockIdsForTransforms(transforms);
+		const conflictingPendings: { blockId: BlockId, actionId: ActionId }[] = [];
+		const missing: ActionTransforms[] = [];
+
+		// Check for conflicts (pending or committed based on rev/insert)
+		for (const blockId of blockIds) {
+			const blockState = this.blocks.get(blockId);
+			const blockTransform = transformForBlockId(transforms, blockId);
+			if (!blockTransform) continue; // Should not happen
+
+			if (blockState) {
+				// Check for existing pending actions
+				if (blockState.pendingActions.size > 0) {
+					blockState.pendingActions.forEach((_, pendingActionId) => {
+						conflictingPendings.push({ blockId, actionId: pendingActionId });
+					});
+				}
+
+				// Check for conflicting committed revisions (if rev specified or it's an insert)
+				if (rev !== undefined || blockTransform.insert) {
+					const checkRev = rev ?? 0; // Check from revision 0 if it's an insert
+					if (blockState.latestRev >= checkRev) {
+						// Collect conflicting committed actions
+						const missingForBlock = new Map<ActionId, { rev: number, transform: Transform }>();
+						for (let r = checkRev as number; r <= blockState.latestRev; r++) {
+							const committedActionId = blockState.revisionActions.get(r);
+							if (committedActionId !== undefined) {
+								const committedTransform = blockState.committedActions.get(committedActionId);
+								if (committedTransform) {
+									missingForBlock.set(committedActionId, { rev: r, transform: committedTransform });
+								}
+							}
+						}
+
+						// Add collected missing transforms for this block to the main missing list
+						for (const [mActionId, data] of missingForBlock.entries()) {
+							let existing = missing.find(m => m.actionId === mActionId);
+							if (!existing) {
+								existing = { actionId: mActionId, rev: data.rev, transforms: emptyTransforms() };
+								missing.push(existing);
+							}
+							existing.rev = Math.max(existing.rev ?? 0, data.rev);
+							existing.transforms = concatTransform(existing.transforms, blockId, data.transform);
+						}
+					}
+				}
+			}
+		}
+
+		// Handle failure due to committed conflicts first.
+		// `conflict: true` on the three optimistic-concurrency returns below mirrors what
+		// StorageRepo.pend now emits, so consumers of this test transactor see the real shape.
+		if (missing.length > 0) {
+			return {
+				success: false,
+				conflict: true,
+				missing
+			};
+		}
+
+		// Handle failure/retry due to pending conflicts
+		if (conflictingPendings.length > 0) {
+			if (policy === 'f') {
+				return { success: false, conflict: true, pending: conflictingPendings };
+			} else if (policy === 'r') {
+				// Simulate fetching pending transforms for 'r' policy
+				const pendingWithTransforms = conflictingPendings
+					.map(({ blockId: pBlockId, actionId: pActionId }) => {
+						const pBlockState = this.blocks.get(pBlockId);
+						const pTransform = pBlockState?.pendingActions.get(pActionId)
+							?? pBlockState?.committedActions.get(pActionId); // Might have been committed since check
+						if (pTransform) {
+							return { blockId: pBlockId, actionId: pActionId, transform: pTransform };
+						}
+						return null; // Handle case where it disappeared (cancelled?)
+					})
+					.filter(p => p !== null) as { blockId: BlockId, actionId: ActionId, transform: Transform }[];
+
+				return {
+					success: false,
+					conflict: true,
+					pending: pendingWithTransforms
+				};
+			}
+			// Policy 'w' allows proceeding despite pending transactions
+		}
+
+		// No fatal conflicts found, proceed to pend
+		for (const blockId of blockIds) {
+			const blockTransform = transformForBlockId(transforms, blockId);
+			if (blockTransform) {
+				const blockState = ensuredMap(this.blocks, blockId, () => newBlockState());
+				blockState.pendingActions.set(actionId, blockTransform);
+			}
+		}
+
+		// Return success, include pending list as per StorageRepo behavior
+		return {
+			success: true,
+			pending: conflictingPendings,
+			blockIds
+		} as PendResult;
+	}
+
+  async cancel(actionRef: ActionBlocks): Promise<void> {
+		this.checkAvailable();
+    for (const blockId of actionRef.blockIds) {
+      const blockState = this.blocks.get(blockId);
+      if (blockState) {
+        blockState.pendingActions.delete(actionRef.actionId);
+      }
+    }
+  }
+
+  async commit(request: CommitRequest): Promise<CommitResult> {
+		this.checkAvailable();
+    const { actionId, rev, blockIds } = request;
+    const uniqueBlockIds = [...new Set(blockIds)].sort();
+    const releases: (() => void)[] = [];
+
+    try {
+      // Simulate acquiring locks sequentially like StorageRepo
+      for (const id of uniqueBlockIds) {
+        const lockId = `TestTransactor.commit:${id}`;
+        const release = await Latches.acquire(lockId);
+        releases.push(release);
+      }
+
+      // --- Start of Critical Section (Simulated) ---
+
+      // Check for stale revisions
+      const staleBlocks = blockIds.filter(blockId => {
+        const blockState = this.blocks.get(blockId);
+        return blockState && blockState.latestRev >= rev;
+      });
+
+      if (staleBlocks.length > 0) {
+        // Collect missing actions for stale blocks
+        const missingByAction = new Map<ActionId, Transforms>();
+        for (const blockId of staleBlocks) {
+          const blockState = this.blocks.get(blockId)!;
+          for (let r = rev; r <= blockState.latestRev; r++) {
+            const committedActionId = blockState.revisionActions.get(r);
+            if (committedActionId) {
+              const transform = blockState.committedActions.get(committedActionId);
+              if (transform) {
+                const existing = missingByAction.get(committedActionId) ?? emptyTransforms();
+                missingByAction.set(committedActionId, concatTransform(existing, blockId, transform));
+              }
+            }
+          }
+        }
+
+        const missing: ActionTransforms[] = Array.from(missingByAction.entries()).map(([actionId, transforms]) => ({
+          actionId,
+          rev: Array.from(this.blocks.values())
+            .flatMap(bs => Array.from(bs.revisionActions.entries()))
+            .find(([, aId]) => aId === actionId)?.[0] ?? rev,
+          transforms
+        }));
+        return { success: false, missing };
+      }
+
+      // Verify all blocks have the pending action
+      for (const blockId of blockIds) {
+        const blockState = this.blocks.get(blockId);
+        if (!blockState || !blockState.pendingActions.has(actionId)) {
+          return {
+            success: false,
+            reason: `Action ${actionId} not found or not pending for block ${blockId}`
+          };
+        }
+      }
+
+      // Commit the action for each block
+      for (const blockId of blockIds) {
+        const blockState = this.blocks.get(blockId)!;
+        const transform = blockState.pendingActions.get(actionId)!;
+
+        // Get base block to apply transform to
+        const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
+
+        let newBlock: IBlock | undefined;
+        if (!baseBlock) {
+          if (!transform.insert) {
+            throw new Error(`Commit Error: Action ${actionId} has no insert for new block ${blockId}`);
+          }
+          newBlock = structuredClone(transform.insert);
+        } else {
+          newBlock = applyTransformSafe(baseBlock, transform);
+          if (!newBlock && !transform.delete) {
+            throw new Error(`Commit Error: Action ${actionId} resulted in undefined block but had no delete flag for block ${blockId}`);
+          }
+        }
+
+        if (newBlock) {
+          blockState.materializedBlocks.set(rev, newBlock);
+        }
+
+        // Update block state
+        blockState.latestRev = rev;
+        blockState.revisionActions.set(rev, actionId);
+        blockState.committedActions.set(actionId, transform);
+        blockState.pendingActions.delete(actionId);
+      }
+
+      // --- End of Critical Section (Simulated) ---
+
+      return { success: true };
+
+    } finally {
+      // Release locks in reverse order
+      releases.reverse().forEach(release => release());
+    }
+  }
+
+  // Helper methods for testing
+  reset() {
+    this.blocks.clear();
+  }
+
+  getPendingActions(): Map<ActionId, ActionTransforms> {
+    const allPending = new Map<ActionId, ActionTransforms>();
+    for (const [blockId, blockState] of this.blocks.entries()) {
+      for (const [actionId, transform] of blockState.pendingActions) {
+        const existing = allPending.get(actionId);
+        if (!existing) {
+          allPending.set(actionId, { actionId, transforms: transformsFromTransform(transform, blockId) });
+        } else {
+          existing.transforms = concatTransform(existing.transforms, blockId, transform);
+        }
+      }
+    }
+    return allPending;
+  }
+
+  getCommittedActions(): Map<ActionId, ActionTransforms> {
+    const allCommitted = new Map<ActionId, ActionTransforms>();
+    for (const [blockId, blockState] of this.blocks.entries()) {
+      for (const [rev, actionId] of blockState.revisionActions) {
+        const transform = blockState.committedActions.get(actionId);
+        if (transform) {
+          const existing = allCommitted.get(actionId);
+          if (!existing) {
+            allCommitted.set(actionId, {
+              actionId,
+              rev,
+              transforms: transformsFromTransform(transform, blockId)
+            });
+          } else {
+            existing.transforms = concatTransform(existing.transforms, blockId, transform);
+          }
+        }
+      }
+    }
+    return allCommitted;
+  }
+
+	setAvailable(available: boolean) {
+		this.available = available;
+	}
+
+	checkAvailable() {
+		if (!this.available) {
+			throw new Error('Transactor is not available');
+		}
+	}
+
+	/** Optional method for querying cluster nominees (used in GATHER phase for multi-collection transactions) */
+	queryClusterNominees?: (blockId: BlockId) => Promise<ClusterNomineesResult>;
+}
+
+/**
+ * Base for the intercepting wrappers below: forwards every {@link ITransactor} member to `inner`,
+ * so a wrapper overrides only the one call it intercepts and cannot silently drop the rest.
+ *
+ * `queryClusterNominees` is forwarded through a GETTER rather than a method, because the coordinator
+ * treats its ABSENCE as "no supercluster" (see `gatherPhase`). A wrapper that always defined it
+ * would push every wrapped multi-collection test onto the GATHER path even when the inner
+ * transactor never opted in; a wrapper that omits it (as these did before) does the opposite —
+ * a test that sets `inner.queryClusterNominees` and then wraps would skip GATHER and pass
+ * vacuously. The getter reproduces the inner transactor's own answer either way.
+ */
+export abstract class DelegatingTransactor implements ITransactor {
+	protected constructor(protected readonly inner: TestTransactor) {}
+
+	get(b: BlockGets): Promise<GetBlockResults> { return this.inner.get(b); }
+	getStatus(a: ActionBlocks[]): Promise<BlockActionStatus[]> { return this.inner.getStatus(a); }
+	pend(r: PendRequest): Promise<PendResult> { return this.inner.pend(r); }
+	cancel(a: ActionBlocks): Promise<void> { return this.inner.cancel(a); }
+	commit(r: CommitRequest): Promise<CommitResult> { return this.inner.commit(r); }
+
+	get queryClusterNominees(): ((blockId: BlockId) => Promise<ClusterNomineesResult>) | undefined {
+		return this.inner.queryClusterNominees?.bind(this.inner);
+	}
+}
+
+/**
+ * Wraps a {@link TestTransactor} and forces its commit phase to fail a bounded (or unbounded)
+ * number of times before delegating, so tests can exercise the sync retry / backoff / give-up
+ * path deterministically. Everything else delegates unchanged, so the pend→commit→cancel
+ * round-trip runs exactly as in production.
+ */
+export class FlakyCommitTransactor extends DelegatingTransactor {
+	/** Number of commit() calls observed so far (across success and forced failure). */
+	commitAttempts = 0;
+
+	/**
+	 * @param inner delegate transactor
+	 * @param failFirstN number of initial commit() calls to fail; Infinity to always fail
+	 * @param reason the StaleFailure.reason returned on a forced failure
+	 */
+	constructor(
+		inner: TestTransactor,
+		private readonly failFirstN: number,
+		private readonly reason = 'forced stale',
+	) {
+		super(inner);
+	}
+
+	override async commit(request: CommitRequest): Promise<CommitResult> {
+		this.commitAttempts++;
+		if (this.commitAttempts <= this.failFirstN) {
+			return { success: false, reason: this.reason };
+		}
+		return this.inner.commit(request);
+	}
+}
+
+/** A competing writer: a real write driven against the UNWRAPPED transactor, so its own
+ *  pend/commit calls are invisible to {@link CompetingWriterTransactor}'s counters and cannot
+ *  re-trigger the interception. See {@link commitRivalTreeWrite} for the usual implementation. */
+export type RivalWrite = (inner: ITransactor) => Promise<void>;
+
+export type CompetingWriterOptions = {
+	/** Fires on the first pend whose request satisfies this predicate. `callIndex` is 1-based over
+	 *  ALL pend calls seen (not only matching ones). Default: fire on the first pend call. */
+	when?: (request: PendRequest, callIndex: number) => boolean;
+};
+
+/**
+ * Wraps a {@link TestTransactor} and, exactly once, runs a real competing writer to completion
+ * BEFORE delegating the intercepted pend. The rival durably commits (real log entry, real
+ * revision bump), so the delegated pend then fails as a GENUINE optimistic-concurrency loss —
+ * nothing is forced or faked, unlike {@link FlakyCommitTransactor}, which returns a stale failure
+ * without ever advancing a block's revision.
+ *
+ * That distinction is the whole point: only a rival that actually landed can prove the loser
+ * OBSERVED a newer revision, re-applied its work on top of it, and did not lose an update.
+ *
+ * Two deliberate design constraints:
+ *
+ * 1. **The trigger is on PEND, and there is no commit trigger.** The rival is a real
+ *    Collection/Tree, so its write pends with policy `'r'` (see `TransactorSource.transact`), and
+ *    {@link TestTransactor.pend} rejects a pend whose blocks already carry a *pending* action.
+ *    Firing before the loser's pend delegates means the loser has pended nothing yet, so the
+ *    rival pends and commits cleanly and the loser's delegated pend then fails with `missing` — a
+ *    real conflict. Firing at COMMIT time instead would leave the loser already pending on the
+ *    shared log-tail block, so the rival's own pend would collide with it and spin through its
+ *    sync retry budget (~10 attempts, ~21s) while the loser sits awaiting the rival inside its
+ *    own commit: a livelock dressed up as a slow test. Do not add a commit trigger.
+ *
+ * 2. **The rival runs before delegation, never inside {@link TestTransactor}'s critical section.**
+ *    `TestTransactor.get`/`commit` hold per-block latches (`TestTransactor.commit:${blockId}`), and
+ *    those latch keys are process-global — a rival invoked from inside one of them would
+ *    self-deadlock on its own reads. Intercepting here in the wrapper, before
+ *    `await this.inner.pend(...)`, is outside every such section.
+ */
+export class CompetingWriterTransactor extends DelegatingTransactor {
+	/** Pend calls observed (including the intercepted one). */
+	pendCalls = 0;
+	/** Commit calls observed. */
+	commitCalls = 0;
+	/** The 1-based pend call index the rival fired on; undefined if it never fired. */
+	firedAtCall?: number;
+	/** How many times the rival ran. Latched to at most 1 — a second firing would collide with the
+	 *  loser's now-pending blocks and the transaction under test could never win. */
+	rivalRuns = 0;
+
+	constructor(
+		inner: TestTransactor,
+		private readonly rival: RivalWrite,
+		private readonly options?: CompetingWriterOptions,
+	) {
+		super(inner);
+	}
+
+	override async pend(request: PendRequest): Promise<PendResult> {
+		// Increment synchronously, before any await, so call indexes reflect the caller's fan-out
+		// order rather than scheduling order.
+		const callIndex = ++this.pendCalls;
+		const matches = this.options?.when
+			? this.options.when(request, callIndex)
+			: callIndex === 1;
+		if (this.rivalRuns === 0 && matches) {
+			this.rivalRuns++;
+			this.firedAtCall = callIndex;
+			// A throwing rival escapes as a rejected pend, which pendPhase flattens to a bare message
+			// string ("hard failure") with the stack discarded — so name the source in the message, or
+			// a broken rival reads as an unexplained coordinator pend failure.
+			try {
+				await this.rival(this.inner);
+			} catch (e) {
+				throw new Error(`competing writer failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+			}
+		}
+		return this.inner.pend(request);
+	}
+
+	override async commit(request: CommitRequest): Promise<CommitResult> {
+		this.commitCalls++;
+		return this.inner.commit(request);
+	}
+}
+
+/**
+ * Durably commit a conflicting change to a tree collection: opens a SECOND {@link Tree} over the
+ * same transactor + collection id and replaces `entries` through it, producing a real log entry
+ * and a real revision bump — the durable competitor a {@link CompetingWriterTransactor} needs.
+ *
+ * `Tree.replace` is act + `updateAndSync`, i.e. a full commit through the single-collection sync
+ * path, so the rival's write is indistinguishable from any other client's.
+ *
+ * Pass the UNWRAPPED transactor (that is what {@link RivalWrite} receives).
+ *
+ * NOTE: opens the rival tree at the DEFAULT node capacity (64), because fan-out is not persisted
+ * in the collection header (see Tree.createOrOpen's `nodeCapacity` note). Fine while every rival
+ * race is between default-fan-out trees; if a test ever needs to race a small-capacity tree, add a
+ * capacity parameter here and pass the same value both sides, or the two writers will split nodes
+ * at different fan-outs.
+ */
+export async function commitRivalTreeWrite<TKey, TEntry>(
+	inner: ITransactor,
+	collectionId: CollectionId,
+	keyFromEntry: (entry: TEntry) => TKey,
+	entries: TreeReplaceAction<TKey, TEntry>,
+): Promise<void> {
+	const tree = await Tree.createOrOpen<TKey, TEntry>(inner, collectionId, keyFromEntry);
+	await tree.replace(entries);
+}
+
+function newBlockState(): BlockState {
+	return {
+		materializedBlocks: new Map(),
+		latestRev: 0,
+		revisionActions: new Map(),
+		pendingActions: new Map(),
+		committedActions: new Map()
+	};
+}
+
+/** Returns the materialized block at the highest revision ≤ the given revision, together with
+ *  that revision — the caller reports it as {@link GetBlockResult.materializedRev}. */
+function latestMaterializedAt(blockState: BlockState, maxRev: number): { block: IBlock, rev: number } | undefined {
+	for (let rev = maxRev; rev >= 0; rev--) {
+		const block = blockState.materializedBlocks.get(rev);
+		if (block) return { block, rev };
+	}
+	return undefined;
+}
+
+/**
+ * `applyTransform` over cloned inputs, so a returned block never aliases stored state.
+ *
+ * An absent base is NOT a short circuit: an insert needs no base — `applyTransform` adopts it as
+ * the block. Bailing out on `!block` made this double silently drop a pending-only insert read
+ * through the pending overlay, the one shape `StorageRepo.get` serves with content but no
+ * `materializedRev` (see docs/internals.md § the `unavailable`/`materializedRev` bullets). A
+ * pending UPDATE over an absent base still resolves to undefined, matching the real repo.
+ */
+function applyTransformSafe(block: IBlock | undefined, transform: Transform): IBlock | undefined {
+  return applyTransform(
+    block ? structuredClone(block) : undefined,
+    transform.insert ? { ...transform, insert: structuredClone(transform.insert) } : transform
+  );
+}