@optimystic/db-core 1.0.0-beta.3 → 1.0.0

package/src/testing/test-transactor.ts

@@ -1,5 +1,6 @@
-import type { ITransactor, GetBlockResults, ActionBlocks, BlockActionStatus, PendResult, CommitResult, PendRequest, BlockId, CommitRequest, BlockGets, IBlock, ActionId, ActionRev, ActionTransforms, StaleFailure, Transform, Transforms, ClusterNomineesResult, CollectionId } from "../index.js";
+import type { ITransactor, GetBlockResults, ActionBlocks, ActionLineage, BlockLineage, BlockActionStatus, PendResult, CommitResult, PendRequest, BlockId, CommitRequest, BlockGets, IBlock, ActionId, ActionRev, ActionTransforms, StaleFailure, Transform, Transforms, ClusterNomineesResult, CollectionId } from "../index.js";
 import { highestStaleAt, isOwnRevision } from "../network/stale-failure.js";
+import { localDurability } from "../network/durability.js";
 import { ensuredMap } from "../utility/ensured.js";
 import { Latches } from "../utility/latches.js";
 import { applyTransform, blockIdsForTransforms, transformForBlockId, emptyTransforms, concatTransform, transformsFromTransform } from "../transform/index.js";
@@ -164,6 +165,26 @@ export class TestTransactor implements ITransactor {
     }));
   }
 
+	/** One store, no replicas: every revision was applied here onto the one before it, so the
+	 *  revision index answers for lineage outright — mirroring `BlockStorage.lineageOf`, including
+	 *  the one way a later revision does NOT build on its predecessor (an insert replaces the block
+	 *  wholesale). The "cohort" is this store alone, which is what the durability says. */
+	async getLineage(ref: ActionBlocks & { rev: number }): Promise<ActionLineage> {
+		this.checkAvailable();
+		const blocks = ref.blockIds.map((blockId): BlockLineage => {
+			const blockState = this.blocks.get(blockId);
+			if (!blockState || blockState.latestRev < ref.rev) return 'behind';
+			if (blockState.revisionActions.get(ref.rev) !== ref.actionId) return 'excludes';
+			const replacedSince = Array.from(blockState.revisionActions.entries()).some(([rev, actionId]) =>
+				rev > ref.rev && blockState.committedActions.get(actionId)?.insert !== undefined);
+			return replacedSince ? 'unknown' : 'contains';
+		});
+		return {
+			blocks,
+			...(blocks.length > 0 && blocks.every(lineage => lineage === 'contains') ? { durability: localDurability() } : {})
+		};
+	}
+
   async pend(request: PendRequest): Promise<PendResult> {
 		this.checkAvailable();
 		const { actionId, transforms, policy, rev } = request;
@@ -174,6 +195,12 @@ export class TestTransactor implements ITransactor {
 		// storage is already at or past the requested revision, held by someone other than this same
 		// action. Reported as `staleAt` so a caller reading the shared harness sees the real shape.
 		const staleCandidates: StaleFailure['staleAt'][] = [];
+		// Blocks this SAME action already committed at exactly the requested revision — the durable
+		// half of a torn action, met again by its own retry. Mirrors StorageRepo.pend's `satisfied`
+		// set: such a block is neither a committed conflict nor a pending one, and no pending record
+		// is written for it (commit's own-revision arm below never promotes one, so it would never
+		// clear). It still rides in the returned `blockIds`, as in the real repo, so `cancel` covers it.
+		const satisfied = new Set<BlockId>();
 
 		// Check for conflicts (pending or committed based on rev/insert)
 		for (const blockId of blockIds) {
@@ -181,6 +208,11 @@ export class TestTransactor implements ITransactor {
 			const blockTransform = transformForBlockId(transforms, blockId);
 			if (!blockTransform) continue; // Should not happen
 
+			if (blockState && isOwnRevision(latestActionRev(blockState), rev, actionId)) {
+				satisfied.add(blockId);
+				continue;
+			}
+
 			if (blockState) {
 				// Check for existing pending actions
 				if (blockState.pendingActions.size > 0) {
@@ -196,8 +228,9 @@ export class TestTransactor implements ITransactor {
 						// Mirrors StorageRepo.pend exactly: only a real revision race yields a
 						// meaningful `staleAt`. A rev-less pend reaches here as an insert collision
 						// (`checkRev` degraded to 0), where the block's revision answers a question
-						// nobody asked; and our own durable half of a torn action is not a rival's win.
-						if (rev !== undefined && !isOwnRevision(latestActionRev(blockState), rev, actionId)) {
+						// nobody asked. (Our own durable half of a torn action never reaches here —
+						// it was set aside as `satisfied` above.)
+						if (rev !== undefined) {
 							staleCandidates.push({ blockId, rev: blockState.latestRev });
 						}
 						// Collect conflicting committed actions
@@ -269,6 +302,7 @@ export class TestTransactor implements ITransactor {
 
 		// No fatal conflicts found, proceed to pend
 		for (const blockId of blockIds) {
+			if (satisfied.has(blockId)) continue;
 			const blockTransform = transformForBlockId(transforms, blockId);
 			if (blockTransform) {
 				const blockState = ensuredMap(this.blocks, blockId, () => newBlockState());
@@ -276,11 +310,13 @@ export class TestTransactor implements ITransactor {
 			}
 		}
 
-		// Return success, include pending list as per StorageRepo behavior
+		// Return success, include pending list as per StorageRepo behavior. The in-memory double is one
+		// node with no cohort, so its honest class is `local` — exactly what a bare StorageRepo answers.
 		return {
 			success: true,
 			pending: conflictingPendings,
-			blockIds
+			blockIds,
+			durability: localDurability()
 		} as PendResult;
 	}
 
@@ -310,10 +346,19 @@ export class TestTransactor implements ITransactor {
 
       // --- Start of Critical Section (Simulated) ---
 
+      // Blocks this same action already committed at exactly this revision: an idempotent no-op,
+      // mirroring StorageRepo.commit's `alreadyDone` partition. They are neither stale nor in need
+      // of a pending record (pend wrote none for them — see `satisfied` there), which is what lets
+      // a torn action's retry roll its remaining blocks forward.
+      const alreadyDone = new Set(blockIds.filter(blockId => {
+        const blockState = this.blocks.get(blockId);
+        return blockState !== undefined && isOwnRevision(latestActionRev(blockState), rev, actionId);
+      }));
+
       // Check for stale revisions
       const staleBlocks = blockIds.filter(blockId => {
         const blockState = this.blocks.get(blockId);
-        return blockState && blockState.latestRev >= rev;
+        return blockState && blockState.latestRev >= rev && !alreadyDone.has(blockId);
       });
 
       if (staleBlocks.length > 0) {
@@ -341,19 +386,17 @@ export class TestTransactor implements ITransactor {
           transforms
         }));
         // Same rule as StorageRepo.commit's missedCommits branch: report the highest confirmed
-        // revision a stale block is already at, skipping one held by this very action (the
-        // durable half of a torn action, which its own retry must not be refused by).
-        const staleAt = highestStaleAt(staleBlocks.map(blockId => {
-          const blockState = this.blocks.get(blockId)!;
-          return isOwnRevision(latestActionRev(blockState), rev, actionId)
-            ? undefined
-            : { blockId, rev: blockState.latestRev };
-        }));
+        // revision a stale block is already at. A block held by this very action never reaches
+        // here — it was partitioned out as `alreadyDone` above.
+        const staleAt = highestStaleAt(staleBlocks.map(blockId =>
+          ({ blockId, rev: this.blocks.get(blockId)!.latestRev })));
         return { success: false, missing, ...(staleAt ? { staleAt } : {}) };
       }
 
-      // Verify all blocks have the pending action
-      for (const blockId of blockIds) {
+      const toCommit = blockIds.filter(blockId => !alreadyDone.has(blockId));
+
+      // Verify all blocks that still need committing have the pending action
+      for (const blockId of toCommit) {
         const blockState = this.blocks.get(blockId);
         if (!blockState || !blockState.pendingActions.has(actionId)) {
           return {
@@ -364,7 +407,7 @@ export class TestTransactor implements ITransactor {
       }
 
       // Commit the action for each block
-      for (const blockId of blockIds) {
+      for (const blockId of toCommit) {
         const blockState = this.blocks.get(blockId)!;
         const transform = blockState.pendingActions.get(actionId)!;
 
@@ -397,7 +440,7 @@ export class TestTransactor implements ITransactor {
 
       // --- End of Critical Section (Simulated) ---
 
-      return { success: true };
+      return { success: true, durability: localDurability() };
 
     } finally {
       // Release locks in reverse order
@@ -480,6 +523,7 @@ export abstract class DelegatingTransactor implements ITransactor {
 	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); }
+	getLineage(ref: ActionBlocks & { rev: number }): Promise<ActionLineage> { return this.inner.getLineage(ref); }
 
 	get queryClusterNominees(): ((blockId: BlockId) => Promise<ClusterNomineesResult>) | undefined {
 		return this.inner.queryClusterNominees?.bind(this.inner);
@@ -519,16 +563,29 @@ export class FlakyCommitTransactor extends DelegatingTransactor {
 }
 
 /**
- * Commits durably on the inner {@link TestTransactor}, then reports a stale failure anyway —
- * the exact observable shape of `NetworkTransactor.commit`'s TORN ACTION: the collection's log
- * tail is committed BEFORE the sweep of the remaining blocks, so a later sweep block coming back
- * as a confirmed conflict returns a stale failure over an action whose log entry is already
- * durable.
+ * Commits the WHOLE action durably on the inner {@link TestTransactor}, then reports a stale
+ * failure anyway — a write that fully landed but whose writer was told it failed.
+ *
+ * This is NOT the shape `NetworkTransactor.commit` produces when it refuses a write whose log tail
+ * landed: there the tail is committed BEFORE the sweep of the remaining blocks, so the blocks after
+ * the tail did NOT land. That shape is {@link TailLandsButReportsStale}, and it is the one that
+ * matters in production. This double makes "my own log entry is visible" and "my action is fully
+ * durable" the same thing, so on its own it cannot tell a writer that finishes its half-landed
+ * action from one that merely assumes it is finished. Keep it for the case it does model — every
+ * block already holds the action's revision, so the writer's completion pass has nothing left to
+ * land and must not duplicate or move the entry.
  *
  * Safe against the inner transactor's bookkeeping because `TransactorSource.transact` cancels
  * the pend on the reported failure and {@link TestTransactor.cancel} only deletes PENDING records
  * — the real commit already promoted them, so the cancel is a no-op.
  *
+ * `afterLanding`, when given, runs a competing writer ONCE, after the first masked commit has
+ * landed and before its failure is reported: the rival reads the landed write and commits the next
+ * revision ON TOP of it, so by the time the writer looks again every block it wrote has moved past
+ * its revision while still containing it. Safe to await from inside `commit` here (unlike
+ * {@link TailLandsButReportsStale}'s rival, which has to wait for the cancel): the whole action
+ * landed, so it left no pending record for the rival's pend to collide with.
+ *
  * Used by both write paths' own-entry regression suites (collection-own-action-replay.spec.ts and
  * coordinator-own-action-replay.spec.ts); it lives here so the two cannot drift apart.
  */
@@ -537,10 +594,12 @@ export class CommitLandsButReportsStale extends DelegatingTransactor {
 	private injections: number;
 	/** Commits that actually landed on the inner transactor (masked or not). */
 	landedCommits = 0;
+	private rivalDue: boolean;
 
-	constructor(inner: TestTransactor, injections = 1) {
+	constructor(inner: TestTransactor, injections = 1, private readonly afterLanding?: RivalWrite) {
 		super(inner);
 		this.injections = injections;
+		this.rivalDue = afterLanding !== undefined;
 	}
 
 	override async commit(request: CommitRequest): Promise<CommitResult> {
@@ -548,6 +607,10 @@ export class CommitLandsButReportsStale extends DelegatingTransactor {
 		if (result.success) {
 			this.landedCommits++;
 			if (this.injections-- > 0) {
+				if (this.rivalDue) {
+					this.rivalDue = false;
+					await this.afterLanding!(this.inner);
+				}
 				return { success: false, conflict: true, reason: 'stale commit: injected torn-action conflict' };
 			}
 		}
@@ -555,6 +618,64 @@ export class CommitLandsButReportsStale extends DelegatingTransactor {
 	}
 }
 
+/**
+ * Lands ONLY the action's log tail on the inner {@link TestTransactor}, then reports a retryable
+ * failure — the shape `NetworkTransactor.commit` actually produces for a half-landed write. It
+ * commits the tail first and sweeps the remaining blocks only if the tail answered success, and a
+ * failed tail answer does not mean the tail is absent: the coordinator's durability gate answers
+ * `commit-not-durable` whenever fewer than a majority of the cohort hold the revision, even though
+ * some members stored it. So the writer is told "failed" over a log entry that is durable, while
+ * none of the entry's other blocks were ever committed — and the writer's own cancel then drops
+ * their pending records.
+ *
+ * A commit carrying nothing but the tail is delegated untouched (there is nothing to abandon), and
+ * does not consume an injection.
+ *
+ * `afterCancel`, when given, runs a competing writer ONCE, right after the writer's cancel of the
+ * torn attempt has been delegated. It is on `cancel` and not inside `commit` for the reason
+ * {@link CompetingWriterTransactor} documents: until that cancel lands, the torn action's data
+ * blocks still carry its pending records, a rival pending with policy `'r'` collides with them, and
+ * awaiting that rival from inside the writer's own commit is a livelock.
+ */
+export class TailLandsButReportsStale extends DelegatingTransactor {
+	/** Remaining number of commits to tear. */
+	private injections: number;
+	/** Commits torn so far: the tail landed, every other block of the action was abandoned. */
+	tears = 0;
+	/** Commits delegated whole that succeeded on the inner transactor. */
+	landedCommits = 0;
+	private rivalDue = false;
+
+	constructor(inner: TestTransactor, injections = 1, private readonly afterCancel?: RivalWrite) {
+		super(inner);
+		this.injections = injections;
+	}
+
+	override async commit(request: CommitRequest): Promise<CommitResult> {
+		if (this.injections > 0 && request.blockIds.some(blockId => blockId !== request.tailId)) {
+			const tail = await this.inner.commit({ ...request, blockIds: [request.tailId] });
+			// A tail that itself lost is an ordinary loss — nothing is torn, so report it verbatim
+			// and keep the injection for a commit that can actually tear.
+			if (!tail.success) return tail;
+			this.injections--;
+			this.tears++;
+			this.rivalDue = this.afterCancel !== undefined;
+			return { success: false, conflict: true, reason: 'commit-not-durable: injected tail-only landing' };
+		}
+		const result = await this.inner.commit(request);
+		if (result.success) this.landedCommits++;
+		return result;
+	}
+
+	override async cancel(actionRef: ActionBlocks): Promise<void> {
+		await this.inner.cancel(actionRef);
+		if (this.rivalDue) {
+			this.rivalDue = false;
+			await this.afterCancel!(this.inner);
+		}
+	}
+}
+
 /** 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. */
@@ -793,6 +914,13 @@ function latestMaterializedAt(blockState: BlockState, maxRev: number): { block:
 /**
  * `applyTransform` over cloned inputs, so a returned block never aliases stored state.
  *
+ * The `insert` clone here is not redundant with `transformForBlockId`'s: callers pass `Transform`
+ * values pulled straight out of `blockState.pendingActions` (a `Map<ActionId, Transform>` written
+ * once by `pend()`), which can be `get()`'d more than once and read again at commit time before
+ * being superseded. `applyTransform` mutates `transform.insert` in place when `updates` ride
+ * along, so cloning immediately before each call is what keeps that stored entry pristine across
+ * repeated reads.
+ *
  * 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