@optimystic/db-core 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimystic/db-core",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "type": "module",
   "description": "Core database functionality for Optimystic",
   "main": "dist/src/index.js",

package/src/collection/collection.ts

@@ -8,8 +8,9 @@ import { computeBlockContentDigests } from "../transform/digest.js";
 import { copyTransforms, isTransformsEmpty } from "../transform/helpers.js";
 import { TransactorSource } from "../transactor/transactor-source.js";
 import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
+import { highestStaleAt } from "../network/stale-failure.js";
 import type { CollectionHeaderBlock, CollectionId, ICollection, SyncOptions } from "./index.js";
-import { CollectionHeaderVanishedError, SyncRetryExhaustedError } from "./struct.js";
+import { CollectionHeaderVanishedError, SyncRetryExhaustedError, SyncRevisionStalledError } from "./struct.js";
 import type { ActionContext } from "./action.js";
 import { actionIdAt } from "./action.js";
 import type { ReadDependency } from "../transaction/transaction.js";
@@ -50,6 +51,15 @@ const PendingRetryDelayMs = 100;
 const DefaultMaxAttempts = 10;
 /** Default ceiling on a single exponential-backoff sleep, in ms. */
 const DefaultMaxBackoffMs = 5000;
+/** Default consecutive stalled refreshes — ones that moved this collection's revision NOWHERE
+ * while a responder CONFIRMED a revision at or above the one being requested — before
+ * {@link Collection.sync} gives up. Two, not one, so a single transiently-lagging read is absorbed.
+ *
+ * NOTE: two is a judgement call, not a measurement — nothing here counts how often a legitimate
+ * loser reads a view that moves nowhere for two consecutive rounds. The check only strikes when the
+ * refresh made NO progress at all, so a client merely catching up is already excluded; if a
+ * spurious `SyncRevisionStalledError` ever shows up under real contention anyway, raise this. */
+const DefaultMaxStalledAttempts = 2;
 
 export type CollectionInitOptions<TAction> = {
 	modules: Record<ActionType, ActionHandler<TAction>>;
@@ -918,6 +928,7 @@ export class Collection<TAction> implements ICollection<TAction> {
 		const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
 		const baseBackoffMs = options?.baseBackoffMs ?? PendingRetryDelayMs;
 		const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
+		const maxStalledAttempts = options?.maxStalledAttempts ?? DefaultMaxStalledAttempts;
 		const deadlineMs = options?.deadlineMs;
 		const signal = options?.signal;
 		const startedAt = Date.now();
@@ -927,19 +938,77 @@ export class Collection<TAction> implements ICollection<TAction> {
 		// large multi-batch sync (which iterates many times committing progress) never trips it.
 		let consecutiveFailures = 0;
 		let lastReason: string | undefined;
-		// Last confirmed revision a responder reported holding. Purely diagnostic — it is reported
-		// in the exhaustion error and never consulted to decide whether to keep retrying.
+		// Highest confirmed revision any responder has reported holding, accumulated with the
+		// codebase's single rule for picking among several candidates. Reported on the error, and
+		// the evidence the stall check below reasons from.
 		let lastStaleAt: { blockId: BlockId; rev: number } | undefined;
+		// Whether the failure most recently handled carried its OWN staleAt. A strike needs the
+		// responder to have re-confirmed the number this round, not merely an older observation
+		// left standing in `lastStaleAt`.
+		let lastFailureConfirmedStaleAt = false;
+		// Consecutive refreshes that moved `getNextRev()` nowhere at all while a confirmed revision
+		// stood at or above it.
+		let consecutiveStalls = 0;
+		// The revision the PREVIOUS iteration would have requested, so the stall check can tell a
+		// refresh that moved nowhere from one that is still climbing toward the confirmed number.
+		let previousRequestedRev: number | undefined;
 
 		while (this.hasUnsyncedChanges()) {
 			if (signal?.aborted) {
 				throw makeAbortError(signal);
 			}
-			// Progress-agnostic ceiling: give up if the wall-clock deadline passed.
+			// Progress-agnostic ceiling: give up if the wall-clock deadline passed. Deliberately
+			// ahead of the stall check: the deadline is the documented outer bound, so a sync that
+			// is both past it and stalled reports the deadline.
 			if (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs) {
 				throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason ?? 'deadline exceeded', lastStaleAt);
 			}
 
+			// Can the attempt about to run possibly differ from the one that just failed? Only when
+			// BOTH of these hold is the answer provably no:
+			//
+			//  - The revision it would request is at or below one a responder CONFIRMED is taken. A
+			//    producer sets `staleAt` only after reading that revision as durably held by someone
+			//    else out of its own storage, revisions are one per-collection counter that every
+			//    commit touches, and a confirmed revision never becomes un-taken (invalidation takes
+			//    a NEW slot). So the request is already lost before it is sent.
+			//  - The refresh in between moved the collection nowhere. `advanceContext` never lowers
+			//    the held revision, so "nowhere" is exactly `requestedRev` unchanged since the last
+			//    iteration. A refresh that moved forward WITHOUT clearing the confirmed number is a
+			//    collection still climbing (it read a replica that lags the holder — the same
+			//    partial catch-up `reportShortfall` exists to report), and its next attempt is a
+			//    genuinely different request that may yet win.
+			//
+			// This is NOT a second answer to "is this failure retryable?" — `isConflictFailure`
+			// remains the sole rule for that, untouched. It only ever stops a loop that rule had
+			// already decided to continue.
+			const requestedRev = this.getNextRev();
+			const refreshMoved = previousRequestedRev !== undefined && requestedRev > previousRequestedRev;
+			previousRequestedRev = requestedRev;
+			if (lastStaleAt !== undefined) {
+				if (requestedRev > lastStaleAt.rev || refreshMoved) {
+					// Either the refresh adopted a revision above the confirmed one — ordinary
+					// contention, where the rival's commit is exactly what we just read — or it made
+					// partial forward progress. Both mean the next attempt differs. Not a stall.
+					consecutiveStalls = 0;
+				} else if (lastFailureConfirmedStaleAt) {
+					consecutiveStalls++;
+					if (log.enabled) {
+						log('collection:sync-stalled id=%s tag=%s heldRev=%s requestedRev=%d staleBlock=%s staleRev=%d strike=%d of=%d',
+							this.id, this.instanceTag, this.source.actionContext?.rev ?? 'none', requestedRev,
+							lastStaleAt.blockId, lastStaleAt.rev, consecutiveStalls, maxStalledAttempts);
+					}
+					// Two strikes, not one: a legitimate loser can transiently read a view that has
+					// not yet caught up with the rival's commit, which looks identical for one round.
+					if (consecutiveStalls >= maxStalledAttempts) {
+						throw new SyncRevisionStalledError(this.id, consecutiveFailures, lastStaleAt,
+							requestedRev, this.source.actionContext?.rev, lastReason);
+					}
+				}
+				// Else: the responder told us nothing new this round. No strike, and no reset either
+				// — the budget stays bounded by maxAttempts.
+			}
+
 			// Snapshot the pending actions so that any new actions aren't assumed to be part of this action
 			const pending = [...this.pending];
 
@@ -961,7 +1030,7 @@ export class Collection<TAction> implements ICollection<TAction> {
 			if (!collectionLog) {
 				throw new Error(`Log not found for collection ${this.id}`);
 			}
-			const newRev = (this.source.actionContext?.rev ?? 0) + 1;
+			const newRev = this.getNextRev();
 			const addResult = await collectionLog.addActions(pending, actionId, newRev, () => tracker.transformedBlockIds());
 
 			// Declare what each touched block will contain once committed, computed from this snapshot
@@ -983,7 +1052,11 @@ export class Collection<TAction> implements ICollection<TAction> {
 			if (staleFailure) {
 				consecutiveFailures++;
 				lastReason = staleFailure.reason ?? lastReason;
-				lastStaleAt = staleFailure.staleAt ?? lastStaleAt;
+				// Highest-wins, not last-wins: the next request has to clear EVERY holder, so a later
+				// responder reporting a LOWER number understates the binding constraint. Same rule the
+				// producers and the transactor's aggregation already use.
+				lastStaleAt = highestStaleAt([lastStaleAt, staleFailure.staleAt]);
+				lastFailureConfirmedStaleAt = staleFailure.staleAt !== undefined;
 				// Give up once the consecutive no-progress budget is exhausted, so a transactor that
 				// persistently rejects the sync can no longer hold the collection latch forever.
 				// NOTE: this also bounds the legitimate `pending`-wait case (retrying the same action
@@ -1015,6 +1088,8 @@ export class Collection<TAction> implements ICollection<TAction> {
 				consecutiveFailures = 0;
 				lastReason = undefined;
 				lastStaleAt = undefined;
+				lastFailureConfirmedStaleAt = false;
+				consecutiveStalls = 0;
 				// Clear the pending actions that were part of this action
 				this.pending = this.pending.slice(pending.length);
 				// Reset cache and replay any actions that were added during the action

package/src/collection/struct.ts

@@ -1,98 +1,157 @@
-import type { IBlock, BlockId, Action } from "../index.js";
-import type { IChainHeader } from "../chain/chain-nodes.js";
-import type { RandFn } from "../utility/backoff.js";
-
-export type CollectionId = BlockId;
-
-export type CollectionHeaderBlock = IBlock & Partial<IChainHeader>;
-
-/** Bounds the retry loop inside {@link ICollection.sync} / {@link ICollection.updateAndSync}
- * so a transactor that keeps rejecting the sync can no longer spin the collection latch forever.
- * All fields are optional; unset fields fall back to conservative defaults. */
-export interface SyncOptions {
-	/** Max consecutive stale-failure retries that make no progress before giving up.
-	 * The counter resets to 0 on every successful commit, so a legitimate large multi-batch
-	 * sync (which iterates many times making forward progress) is never falsely tripped.
-	 * Default 10. */
-	maxAttempts?: number;
-	/** Optional wall-clock deadline in ms measured from the start of the sync call. Independent
-	 * of the attempt count — a progress-agnostic ceiling. Unset means no deadline. */
-	deadlineMs?: number;
-	/** Base backoff delay in ms applied before the first retry; subsequent retries grow the delay
-	 * exponentially up to {@link maxBackoffMs}. Default 100. */
-	baseBackoffMs?: number;
-	/** Upper bound on any single backoff sleep, in ms. Default 5000. */
-	maxBackoffMs?: number;
-	/** Optional abort signal. Checked at the top of each loop iteration and raced against the
-	 * backoff sleep, so an aborted sync rejects promptly (with an AbortError) rather than finishing
-	 * the current sleep. */
-	signal?: AbortSignal;
-	/** Advanced/testing hook: source of uniform [0,1) randomness for the backoff jitter. Defaults to
-	 * the package CSPRNG; inject a deterministic sequence to assert exact retry delays. */
-	rand?: RandFn;
-}
-
-/** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when the retry budget
- * (attempt count or deadline) is exhausted while the transactor keeps returning stale failures.
- * Catchable so callers can surface a clear "gave up syncing" condition instead of hanging. */
-export class SyncRetryExhaustedError extends Error {
-	constructor(
-		readonly collectionId: CollectionId,
-		readonly attempts: number,
-		readonly lastReason?: string,
-		/** The last confirmed revision a responder reported holding, if any responder reported one
-		 * (see `StaleFailure.staleAt`). Absent whenever no rejection carried a confirmed number —
-		 * which is normal, not a signal that the failure was something other than a lost race. */
-		readonly staleAt?: { blockId: BlockId; rev: number },
-	) {
-		super(`sync for collection ${collectionId} exhausted ${attempts} retries` +
-			(lastReason ? `: ${lastReason}` : '') +
-			(staleAt ? `, last seen block ${staleAt.blockId} at rev ${staleAt.rev}` : ''));
-		this.name = 'SyncRetryExhaustedError';
-	}
-}
-
-/** Thrown when a collection that already holds a committed revision reads its own header
- * block as authoritatively absent.
- *
- * The two facts contradict each other: this client has proof that something was committed
- * under this id (it holds the revision it committed at, or the one it read off the log tail),
- * and storage has just answered that nothing ever was. Exactly one of them is wrong, so this
- * is a fault rather than an absence — the same reasoning `Collection.attachToLog` applies to a
- * header that probes fine but whose log will not open.
- *
- * Deliberately NOT a `StaleFailure`: {@link ICollection.sync}'s retry loop only absorbs
- * returned stale failures, so throwing this aborts the sync immediately with a named
- * diagnosis instead of letting it spin the full retry budget re-requesting a revision it
- * has silently forgotten.
- *
- * NOTE: durable invalidation restores reverted content to its as-if-absent state, so once the
- * cascade runs end-to-end (docs/right-is-right.md § Durable Invalidation), reverting the commit
- * that CREATED a collection would make its header legitimately absent for a client still holding
- * that revision — a reversal, not a contradiction, which this message would misdiagnose.
- * Aborting is still the right action there; if it ever fires for that reason, distinguish the
- * two by checking the log for an invalidation of the held revision before wording the error. */
-export class CollectionHeaderVanishedError extends Error {
-	constructor(
-		readonly collectionId: CollectionId,
-		/** The committed revision this collection held when the header read came back absent. */
-		readonly heldRev: number,
-	) {
-		super(`collection ${collectionId} holds committed revision ${heldRev}, but its header block `
-			+ `read as absent — storage reported that nothing was ever committed under this id`);
-		this.name = 'CollectionHeaderVanishedError';
-	}
-}
-
-export interface ICollection<TAction> {
-	readonly id: CollectionId;
-	act(...actions: Action<TAction>[]): Promise<void>;
-	update(): Promise<void>;
-	sync(options?: SyncOptions): Promise<void>;
-	updateAndSync(options?: SyncOptions): Promise<void>;
-	selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
-}
-
-export type CreateCollectionAction = Action<void> & {
-	type: "create";
-};
+import type { IBlock, BlockId, Action } from "../index.js";
+import type { IChainHeader } from "../chain/chain-nodes.js";
+import type { RandFn } from "../utility/backoff.js";
+
+export type CollectionId = BlockId;
+
+export type CollectionHeaderBlock = IBlock & Partial<IChainHeader>;
+
+/** Bounds the retry loop inside {@link ICollection.sync} / {@link ICollection.updateAndSync}
+ * so a transactor that keeps rejecting the sync can no longer spin the collection latch forever.
+ * All fields are optional; unset fields fall back to conservative defaults. */
+export interface SyncOptions {
+	/** Max consecutive stale-failure retries that make no progress before giving up.
+	 * The counter resets to 0 on every successful commit, so a legitimate large multi-batch
+	 * sync (which iterates many times making forward progress) is never falsely tripped.
+	 * Default 10. */
+	maxAttempts?: number;
+	/** Optional wall-clock deadline in ms measured from the start of the sync call. Independent
+	 * of the attempt count — a progress-agnostic ceiling. Unset means no deadline. */
+	deadlineMs?: number;
+	/** Base backoff delay in ms applied before the first retry; subsequent retries grow the delay
+	 * exponentially up to {@link maxBackoffMs}. Default 100. */
+	baseBackoffMs?: number;
+	/** Upper bound on any single backoff sleep, in ms. Default 5000. */
+	maxBackoffMs?: number;
+	/** Optional abort signal. Checked at the top of each loop iteration and raced against the
+	 * backoff sleep, so an aborted sync rejects promptly (with an AbortError) rather than finishing
+	 * the current sleep. */
+	signal?: AbortSignal;
+	/** Advanced/testing hook: source of uniform [0,1) randomness for the backoff jitter. Defaults to
+	 * the package CSPRNG; inject a deterministic sequence to assert exact retry delays. */
+	rand?: RandFn;
+	/** Consecutive refreshes that move this collection's revision NOWHERE while a responder has
+	 * CONFIRMED a revision at or above the one the next attempt would request, before sync gives up
+	 * with {@link SyncRevisionStalledError}. Such a retry provably re-sends the identical, already
+	 * lost request, so the wait buys nothing. Two absorbs one transiently-lagging read; set it to
+	 * {@link maxAttempts} or higher to restore the pre-existing behaviour of burning the whole
+	 * budget. Default 2.
+	 *
+	 * Neither shape of progress trips this. Ordinary contention: the rival's commit is what the
+	 * refresh adopts, so the next request lands above the confirmed revision. A collection still
+	 * catching up: the refresh moves the revision forward without yet clearing the confirmed
+	 * number, so the next request differs from the one that just failed. Either resets the counter.
+	 * {@link deadlineMs} is still checked first, so a sync that is both past its deadline and
+	 * stalled reports the deadline (as {@link SyncRetryExhaustedError}), not the stall. */
+	maxStalledAttempts?: number;
+}
+
+/** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when the retry budget
+ * (attempt count or deadline) is exhausted while the transactor keeps returning stale failures.
+ * Catchable so callers can surface a clear "gave up syncing" condition instead of hanging. */
+export class SyncRetryExhaustedError extends Error {
+	constructor(
+		readonly collectionId: CollectionId,
+		readonly attempts: number,
+		readonly lastReason?: string,
+		/** The last confirmed revision a responder reported holding, if any responder reported one
+		 * (see `StaleFailure.staleAt`). Absent whenever no rejection carried a confirmed number —
+		 * which is normal, not a signal that the failure was something other than a lost race. */
+		readonly staleAt?: { blockId: BlockId; rev: number },
+	) {
+		super(`sync for collection ${collectionId} exhausted ${attempts} retries` +
+			(lastReason ? `: ${lastReason}` : '') +
+			(staleAt ? `, last seen block ${staleAt.blockId} at rev ${staleAt.rev}` : ''));
+		this.name = 'SyncRetryExhaustedError';
+	}
+}
+
+/** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when refreshing
+ * repeatedly moved this collection nowhere at all while a responder confirmed a revision at or
+ * above the one being requested — the client's view of the current revision disagrees with the
+ * cluster's, and retrying would re-send the identical taken number.
+ *
+ * The distinction matters because the two failures need different responses. Plain exhaustion
+ * means "I lost a race too many times", and waiting longer or retrying later can succeed. This
+ * one means the next attempt is provably identical to the one that just failed, so the remaining
+ * budget buys nothing — the caller's view of the collection has to be repaired first.
+ *
+ * Sync deliberately does NOT adopt the responder's revision to get past this. `staleAt` is a bare
+ * number, not content: submitting this client's staged transforms at a revision built on a
+ * history it never read would overwrite that history silently. Reconciling a genuine fork is
+ * partition healing's job (docs/transactions.md), not the retry loop's.
+ *
+ * Extends {@link SyncRetryExhaustedError} so existing callers that catch the base class keep
+ * working; catch this subclass to distinguish "my revision view is wrong" from "I lost a race
+ * too many times". */
+export class SyncRevisionStalledError extends SyncRetryExhaustedError {
+	/** Required here, unlike on the base class — it is the evidence the stall is based on. */
+	declare readonly staleAt: { blockId: BlockId; rev: number };
+
+	constructor(
+		collectionId: CollectionId,
+		attempts: number,
+		staleAt: { blockId: BlockId; rev: number },
+		/** The revision the next attempt would have requested. */
+		readonly requestedRev: number,
+		/** The revision this client believes is current. `undefined` for a collection that has
+		 * committed nothing. */
+		readonly heldRev: number | undefined,
+		lastReason?: string,
+	) {
+		super(collectionId, attempts, lastReason, staleAt);
+		// The base class's "exhausted N retries" wording is deliberately NOT reused: it reads as
+		// ordinary contention, which is exactly the misdiagnosis this class exists to prevent.
+		this.message = `sync for collection ${collectionId} stopped after ${attempts} attempts: `
+			+ `this client holds rev ${heldRev ?? 'none'} and would request rev ${requestedRev}, `
+			+ `but block ${staleAt.blockId} is confirmed committed at rev ${staleAt.rev} and `
+			+ `refreshing did not close the gap`
+			+ (lastReason ? `: ${lastReason}` : '');
+		this.name = 'SyncRevisionStalledError';
+	}
+}
+
+/** Thrown when a collection that already holds a committed revision reads its own header
+ * block as authoritatively absent.
+ *
+ * The two facts contradict each other: this client has proof that something was committed
+ * under this id (it holds the revision it committed at, or the one it read off the log tail),
+ * and storage has just answered that nothing ever was. Exactly one of them is wrong, so this
+ * is a fault rather than an absence — the same reasoning `Collection.attachToLog` applies to a
+ * header that probes fine but whose log will not open.
+ *
+ * Deliberately NOT a `StaleFailure`: {@link ICollection.sync}'s retry loop only absorbs
+ * returned stale failures, so throwing this aborts the sync immediately with a named
+ * diagnosis instead of letting it spin the full retry budget re-requesting a revision it
+ * has silently forgotten.
+ *
+ * NOTE: durable invalidation restores reverted content to its as-if-absent state, so once the
+ * cascade runs end-to-end (docs/right-is-right.md § Durable Invalidation), reverting the commit
+ * that CREATED a collection would make its header legitimately absent for a client still holding
+ * that revision — a reversal, not a contradiction, which this message would misdiagnose.
+ * Aborting is still the right action there; if it ever fires for that reason, distinguish the
+ * two by checking the log for an invalidation of the held revision before wording the error. */
+export class CollectionHeaderVanishedError extends Error {
+	constructor(
+		readonly collectionId: CollectionId,
+		/** The committed revision this collection held when the header read came back absent. */
+		readonly heldRev: number,
+	) {
+		super(`collection ${collectionId} holds committed revision ${heldRev}, but its header block `
+			+ `read as absent — storage reported that nothing was ever committed under this id`);
+		this.name = 'CollectionHeaderVanishedError';
+	}
+}
+
+export interface ICollection<TAction> {
+	readonly id: CollectionId;
+	act(...actions: Action<TAction>[]): Promise<void>;
+	update(): Promise<void>;
+	sync(options?: SyncOptions): Promise<void>;
+	updateAndSync(options?: SyncOptions): Promise<void>;
+	selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
+}
+
+export type CreateCollectionAction = Action<void> & {
+	type: "create";
+};

package/src/logger.ts

@@ -1,10 +1,10 @@
-import debug from 'debug'
-
-const BASE_NAMESPACE = 'optimystic:db-core'
-
-export function createLogger(subNamespace: string): debug.Debugger {
-	return debug(`${BASE_NAMESPACE}:${subNamespace}`)
-}
-
-export const verbose = typeof process !== 'undefined'
-	&& (process.env.OPTIMYSTIC_VERBOSE === '1' || process.env.OPTIMYSTIC_VERBOSE === 'true');
+import debug from 'debug'
+
+const BASE_NAMESPACE = 'optimystic:db-core'
+
+export function createLogger(subNamespace: string): debug.Debugger {
+	return debug(`${BASE_NAMESPACE}:${subNamespace}`)
+}
+
+export const verbose = typeof process !== 'undefined'
+	&& (process.env.OPTIMYSTIC_VERBOSE === '1' || process.env.OPTIMYSTIC_VERBOSE === 'true');

package/src/network/stale-failure.ts

@@ -31,7 +31,10 @@ export function isConflictFailure(failure: StaleFailure): boolean {
  * NOTE: comparing revisions across blocks is only meaningful because one pend covers one
  * collection, so every candidate comes from the same revision counter. If a pend is ever allowed
  * to span collections, these numbers come from unrelated counters and selection must become
- * per-collection.
+ * per-collection. `Collection.syncAttempts` now compares the winner against its OWN next revision
+ * to decide whether a retry could differ (`SyncRevisionStalledError`), so a cross-collection
+ * candidate would not merely muddy a diagnostic — it would fail a sync against an unrelated
+ * counter.
  */
 export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]): StaleFailure['staleAt'] {
 	let best: StaleFailure['staleAt'];

package/src/testing/test-transactor.ts

@@ -1,4 +1,5 @@
-import type { ITransactor, GetBlockResults, ActionBlocks, BlockActionStatus, PendResult, CommitResult, PendRequest, BlockId, CommitRequest, BlockGets, IBlock, ActionId, ActionTransforms, Transform, Transforms, ClusterNomineesResult, CollectionId } from "../index.js";
+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 { highestStaleAt, isOwnRevision } from "../network/stale-failure.js";
 import { ensuredMap } from "../utility/ensured.js";
 import { Latches } from "../utility/latches.js";
 import { applyTransform, blockIdsForTransforms, transformForBlockId, emptyTransforms, concatTransform, transformsFromTransform } from "../transform/index.js";
@@ -169,6 +170,10 @@ export class TestTransactor implements ITransactor {
 		const blockIds = blockIdsForTransforms(transforms);
 		const conflictingPendings: { blockId: BlockId, actionId: ActionId }[] = [];
 		const missing: ActionTransforms[] = [];
+		// Confirmed revisions this pend is up against, mirroring StorageRepo.pend: a block whose own
+		// 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'][] = [];
 
 		// Check for conflicts (pending or committed based on rev/insert)
 		for (const blockId of blockIds) {
@@ -188,6 +193,13 @@ export class TestTransactor implements ITransactor {
 				if (rev !== undefined || blockTransform.insert) {
 					const checkRev = rev ?? 0; // Check from revision 0 if it's an insert
 					if (blockState.latestRev >= checkRev) {
+						// 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)) {
+							staleCandidates.push({ blockId, rev: blockState.latestRev });
+						}
 						// Collect conflicting committed actions
 						const missingForBlock = new Map<ActionId, { rev: number, transform: Transform }>();
 						for (let r = checkRev as number; r <= blockState.latestRev; r++) {
@@ -219,10 +231,12 @@ export class TestTransactor implements ITransactor {
 		// `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) {
+			const staleAt = highestStaleAt(staleCandidates);
 			return {
 				success: false,
 				conflict: true,
-				missing
+				missing,
+				...(staleAt ? { staleAt } : {})
 			};
 		}
 
@@ -326,7 +340,16 @@ export class TestTransactor implements ITransactor {
             .find(([, aId]) => aId === actionId)?.[0] ?? rev,
           transforms
         }));
-        return { success: false, missing };
+        // 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 };
+        }));
+        return { success: false, missing, ...(staleAt ? { staleAt } : {}) };
       }
 
       // Verify all blocks have the pending action
@@ -749,6 +772,14 @@ function newBlockState(): BlockState {
 	};
 }
 
+/** This block's latest committed revision in the shape {@link isOwnRevision} compares — the
+ *  harness equivalent of `IBlockStorage.getLatest()`. `undefined` when nothing is recorded at that
+ *  revision, which is how a never-written block reads (`latestRev` starts at 0 with no entry). */
+function latestActionRev(blockState: BlockState): ActionRev | undefined {
+	const actionId = blockState.revisionActions.get(blockState.latestRev);
+	return actionId === undefined ? undefined : { actionId, rev: blockState.latestRev };
+}
+
 /** Returns the materialized block at the highest revision ≤ the given revision, together with
  *  that revision — the caller reports it as {@link GetBlockResult.materialized}. */
 function latestMaterializedAt(blockState: BlockState, maxRev: number): { block: IBlock, rev: number } | undefined {

package/src/transaction/coordinator.ts

@@ -1465,11 +1465,15 @@ export class TransactionCoordinator {
 		// Fan out the per-collection cancels concurrently. Each is best-effort: a cancel
 		// fault is logged and swallowed so it cannot mask the pend/commit failure that
 		// triggered this sweep, and so one failed cancel does not abort the others.
+		// The log line has to be enough to IDENTIFY the stranded pend on its own — action id and
+		// the exact blocks — because `NetworkTransactor.cancel` only throws here once it has
+		// retried and still reached nobody, which means those blocks' pending records are standing
+		// and will refuse every later write to them until something removes them by hand.
 		const cancels = Array.from(pendedBlockIds.entries())
 			.filter(([collectionId]) => !excludeCollections?.has(collectionId))
 			.map(([collectionId, blockIds]) =>
 				this.transactor.cancel({ actionId, blockIds }).catch(err => {
-					log('cancelPhase: best-effort cancel failed collection=%s: %o', collectionId, err);
+					log('cancelPhase: cancel did not discharge — pending records may be stranded actionId=%s collection=%s blocks=%o: %o', actionId, collectionId, blockIds, err);
 				})
 			);
 		await Promise.all(cancels);