@optimystic/db-core 0.14.1 → 0.16.3

package/src/testing/test-transactor.ts

@@ -0,0 +1,468 @@
+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;
+				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);
+					} 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);
+							break;
+						}
+					}
+					// Fall through to standard resolution if no pending match
+					if (block === undefined) {
+						if (blockGets.context.rev !== undefined) {
+							block = structuredClone(latestMaterializedAt(blockState, blockGets.context.rev));
+						} else {
+							block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
+						}
+					}
+				} else if (blockGets.context?.rev !== undefined) {
+					// Return the materialized block at the highest revision ≤ requested
+					block = structuredClone(latestMaterializedAt(blockState, blockGets.context.rev));
+				} else {
+					// Otherwise return latest materialized block
+					block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
+				}
+
+
+				const actionId = blockState.revisionActions.get(blockState.latestRev);
+				results[blockId] = {
+					block,
+					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
+		if (missing.length > 0) {
+			return {
+				success: false,
+				missing
+			};
+		}
+
+		// Handle failure/retry due to pending conflicts
+		if (conflictingPendings.length > 0) {
+			if (policy === 'f') {
+				return { success: false, 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,
+					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 */
+function latestMaterializedAt(blockState: BlockState, maxRev: number): IBlock | undefined {
+	for (let rev = maxRev; rev >= 0; rev--) {
+		const block = blockState.materializedBlocks.get(rev);
+		if (block) return block;
+	}
+	return undefined;
+}
+
+function applyTransformSafe(block: IBlock | undefined, transform: Transform): IBlock | undefined {
+  if (!block) return undefined;
+  return applyTransform(structuredClone(block), transform);
+}

package/src/transaction/actions-engine.ts

@@ -1,5 +1,4 @@
 import type { ITransactionEngine, Transaction, ExecutionResult, CollectionActions } from './transaction.js';
-import type { TransactionCoordinator } from './coordinator.js';
 
 export const ACTIONS_ENGINE_ID = "actions@1.0.0";
 
@@ -9,6 +8,11 @@ export const ACTIONS_ENGINE_ID = "actions@1.0.0";
  * This engine treats each statement as a JSON-encoded CollectionActions object.
  * It's useful for testing the transaction infrastructure without needing SQL.
  *
+ * This is a PURE TRANSLATOR (model (a) of the {@link ITransactionEngine} contract):
+ * execute() parses statements into CollectionActions[] and RETURNS them. It never
+ * touches a coordinator or mutates any collection state — application is the sole
+ * responsibility of the session/coordinator that receives the returned actions.
+ *
  * Each statement format:
  * ```json
  * {
@@ -20,7 +24,7 @@ export const ACTIONS_ENGINE_ID = "actions@1.0.0";
  * ```
  */
 export class ActionsEngine implements ITransactionEngine {
-	constructor(private coordinator: TransactionCoordinator) {}
+	readonly id = ACTIONS_ENGINE_ID;
 
 	async execute(transaction: Transaction): Promise<ExecutionResult> {
 		try {
@@ -46,12 +50,10 @@ export class ActionsEngine implements ITransactionEngine {
 				}
 
 				allActions.push(collectionActions);
-
-				// Apply actions through coordinator (for validation/replay)
-				await this.coordinator.applyActions([collectionActions], transaction.stamp.id);
 			}
 
-			// Return success (actions already applied)
+			// Pure translation: return parsed actions WITHOUT applying them. The caller
+			// (session.execute / coordinator.execute) applies them exactly once.
 			return {
 				success: true,
 				actions: allActions