@optimystic/db-core 0.18.0 → 0.19.0

package/src/network/stale-failure.ts

@@ -11,3 +11,33 @@ import type { StaleFailure } from "./struct.js";
 export function isConflictFailure(failure: StaleFailure): boolean {
 	return failure.conflict ?? Boolean(failure.missing?.length || failure.pending?.length);
 }
+
+/**
+ * The single rule for picking one {@link StaleFailure.staleAt} out of several candidates.
+ *
+ * Highest `rev` wins: the losing writer's next request has to clear EVERY holder, so the largest
+ * confirmed revision is the binding constraint and any smaller one understates it. Ties keep the
+ * earlier candidate. Undefined entries (a block or batch with no confirmed number, or a peer that
+ * predates the field) contribute nothing, and an all-undefined input yields undefined so callers
+ * can omit the key rather than emit `staleAt: undefined`.
+ *
+ * Every site that has more than one candidate calls this — the producers scanning several blocks
+ * (`StorageRepo.pend`/`.commit`, `CoordinatorRepo.classifyStaleRejection`) as well as
+ * `NetworkTransactor` rebuilding one response from many per-batch ones. Uniformity is what makes
+ * the transactor's aggregate meaningful: if a producer reported an arbitrary block instead of its
+ * highest, taking the max across producers would still understate the constraint.
+ *
+ * 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.
+ */
+export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]): StaleFailure['staleAt'] {
+	let best: StaleFailure['staleAt'];
+	for (const candidate of candidates) {
+		if (candidate !== undefined && (best === undefined || candidate.rev > best.rev)) {
+			best = candidate;
+		}
+	}
+	return best;
+}

package/src/network/struct.ts

@@ -79,6 +79,20 @@ export type StaleFailure = {
 	 * Read it through `isConflictFailure` rather than testing it directly.
 	 */
 	conflict?: boolean;
+	/**
+	 * The block that already occupies (or is past) the requested revision, and the revision the
+	 * responder holds for it.
+	 *
+	 * CONFIRMED-ONLY: set this only when the producer read the revision out of its own storage.
+	 * A producer that merely suspects staleness — or that learned of it from another peer's
+	 * free-form reject text — must leave it absent. Absent means "no confirmed number", never
+	 * "not stale".
+	 *
+	 * DIAGNOSTIC, NOT A RETRYABILITY SIGNAL: `conflict` (read via `isConflictFailure`) remains the
+	 * single source of truth for "can a re-read and re-pend win?". Never branch retry decisions on
+	 * the presence of this field.
+	 */
+	staleAt?: { blockId: BlockId; rev: number };
 };
 
 export type PendResult = PendSuccess | StaleFailure;

package/src/transaction/coordinator.ts

@@ -29,8 +29,17 @@ const DefaultMaxBackoffMs = 5000;
  * the flag off the rejection.
  */
 class PendRejectedError extends Error {
-	constructor(collectionId: CollectionId, readonly conflict: boolean, reason?: string) {
-		super(`Pend failed for collection ${collectionId}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`);
+	constructor(
+		collectionId: CollectionId,
+		readonly conflict: boolean,
+		reason?: string,
+		/** Confirmed revision the responder holds, from `StaleFailure.staleAt`. Folded into the
+		 * message because pendPhase collapses this error to its `.message` string, which is the only
+		 * form that reaches an embedder through the transaction result's `error` field. */
+		staleAt?: { blockId: BlockId; rev: number },
+	) {
+		super(`Pend failed for collection ${collectionId}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
+			+ (staleAt ? ` (block ${staleAt.blockId} at rev ${staleAt.rev})` : ''));
 		this.name = 'PendRejectedError';
 	}
 }
@@ -182,9 +191,10 @@ export class TransactionCoordinator {
 				// Re-read fresh state before re-attempting so the next commit pends against current
 				// revisions (mirrors how Collection.sync calls updateInternal() before retrying).
 				// NOTE: refreshes EVERY registered collection, not only the participants of this
-				// transaction. Harmless (a non-participant's update() just fetches latest) and the
-				// registered set is small today; if a coordinator ever holds many collections and this
-				// shows up as retry latency, narrow it to the transaction's participating collections.
+				// transaction. Not free: a non-participant's update() throws CollectionHeaderVanishedError
+				// if its header momentarily reads absent while it holds a committed revision, aborting
+				// this retry. The registered set is small today; if that (or retry latency) ever bites,
+				// narrow this to the transaction's participating collections.
 				for (const collection of this.collections.values()) {
 					await collection.update();
 				}
@@ -934,7 +944,7 @@ export class TransactionCoordinator {
 			// `conflict`, and only where no producer set it do we fall back to inferring from
 			// `missing`/`pending`. Either way a conflict is an optimistic-concurrency loss, clearable
 			// by a re-read; anything else is a hard rejection (storage/policy) that re-driving won't fix.
-			throw new PendRejectedError(collectionId, isConflictFailure(pendResult), pendResult.reason);
+			throw new PendRejectedError(collectionId, isConflictFailure(pendResult), pendResult.reason, pendResult.staleAt);
 		}
 
 		return { collectionId, blockIds: pendResult.blockIds };

package/src/transactor/network-transactor.ts

@@ -1,8 +1,8 @@
 import { peerIdFromString } from "../network/types.js";
 import type { PeerId } from "../network/types.js";
-import { isConflictFailure } from "../network/stale-failure.js";
+import { highestStaleAt, isConflictFailure } from "../network/stale-failure.js";
 import { BlockUnavailableError } from "../network/struct.js";
-import type { ActionTransforms, ActionBlocks, BlockActionStatus, ITransactor, PendSuccess, StaleFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock } from "../index.js";
+import type { ActionTransforms, ActionBlocks, BlockActionStatus, ITransactor, PendSuccess, StaleFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock, CoordinatorIntent } from "../index.js";
 import type { IBlockChangeNotifier, CollectionChangeListener } from "./change-notifier.js";
 import { transformForBlockId, groupBy, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms, Log, Tracker, CacheSource, TransactorSource } from "../index.js";
 import { blockIdToBytes } from "../utility/block-id-to-bytes.js";
@@ -108,11 +108,16 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		const t0 = Date.now();
 		log('get blockIds=%d', distinctBlockIds.length);
 
+		// `intent: 'read'` throughout this method: a read that can find no reachable
+		// coordinator may still be answered from the local replica (degraded but reported),
+		// where a write on the same evidence may not. See CoordinatorIntent.
 		const batches = await this.batchesForPayload<BlockId[], GetBlockResults>(
 			distinctBlockIds,
 			distinctBlockIds,
 			(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(bid => bid === blockId)],
-			[]
+			[],
+			undefined,
+			'read'
 		);
 
 		const expiration = Date.now() + this.timeoutMs;
@@ -125,7 +130,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				batch => batch.payload,
 				(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(bid => bid === blockId)],
 				expiration,
-				async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+				async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent: 'read' })
 			);
 		} catch (e) {
 			error = e as Error;
@@ -179,7 +184,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 					b.payload,
 					(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)],
 					Array.from(excluded),
-					async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+					async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent: 'read' })
 				);
 				if (retries.length > 0) {
 					b.subsumedBy = [...(b.subsumedBy ?? []), ...retries];
@@ -189,7 +194,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 						batch => batch.payload,
 						(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)],
 						expiration,
-						async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+						async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent: 'read' })
 					);
 				}
 			}));
@@ -555,10 +560,15 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				// (then `every` is both safe and tighter), or if mixed-outcome pends show up as wasted
 				// retry latency in practice.
 				const conflict = stale.some(b => isConflictFailure(b.request!.response! as StaleFailure));
+				// Deliberately NOT first-wins like `reason` above — `highestStaleAt` takes the largest
+				// confirmed revision, which is the binding constraint on the client's next request.
+				// Its doc comment carries the rule and the one-pend-one-collection assumption it rests on.
+				const staleAt = highestStaleAt(stale.map(b => (b.request!.response! as StaleFailure).staleAt));
 				return {
 					success: false,
 					conflict,
 					...(reason === undefined ? {} : { reason }),
+					...(staleAt === undefined ? {} : { staleAt }),
 					missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing).filter((x): x is ActionTransforms => x !== undefined)),
 				};
 			}
@@ -673,10 +683,17 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			const stale = Array.from(allBatches(tailBatches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
 			if (stale.length > 0) {
 				// NOTE: a reason-only StaleFailure (success:false, no `missing`) lands here too and
-				// returns { missing: [], success:false } — the `reason` string is dropped rather than
-				// surfaced via `throw tailError`. Fine today (failure still propagates); if reason-only
-				// commit rejections ever need their diagnostic reason, gate this branch on non-empty missing.
-				return { missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing).filter((x): x is ActionTransforms => x !== undefined)), success: false as const };
+				// returns { missing: [], success:false } — the `reason` PROSE is still dropped rather
+				// than surfaced via `throw tailError`. `staleAt` is carried, so the one machine-readable
+				// fact in that prose (which block is at which revision) now survives; only the free-form
+				// wording is lost. If the wording itself is ever needed, gate this branch on non-empty
+				// missing rather than reinstating it unconditionally.
+				const staleAt = highestStaleAt(stale.map(b => (b.request!.response! as StaleFailure).staleAt));
+				return {
+					missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing).filter((x): x is ActionTransforms => x !== undefined)),
+					...(staleAt === undefined ? {} : { staleAt }),
+					success: false as const
+				};
 			}
 			throw tailError;
 		}
@@ -729,14 +746,16 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		getBlockPayload: (payload: TPayload, blockId: BlockId, mergeWithPayload: TPayload | undefined) => TPayload,
 		excludedPeers: PeerId[],
 		/** When set, prefer a coordinator this transaction already resolved at pend (see {@link resolveCoordinator}). */
-		actionId?: ActionId
+		actionId?: ActionId,
+		/** What the batches will be used for. Defaults to `'write'` — see {@link CoordinatorIntent}. */
+		intent: CoordinatorIntent = 'write'
 	): Promise<CoordinatorBatch<TPayload, TResponse>[]> {
 		return createBatchesForPayload<TPayload, TResponse>(
 			blockIds,
 			payload,
 			getBlockPayload,
 			excludedPeers,
-			async (blockId, options) => this.resolveCoordinator(blockId, options, actionId)
+			async (blockId, options) => this.resolveCoordinator(blockId, options, actionId, intent)
 		);
 	}
 
@@ -751,7 +770,8 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	private async resolveCoordinator(
 		blockId: BlockId,
 		options: { excludedPeers: PeerId[] },
-		actionId: ActionId | undefined
+		actionId: ActionId | undefined,
+		intent: CoordinatorIntent = 'write'
 	): Promise<PeerId> {
 		if (actionId !== undefined) {
 			const cached = this.txnCoordinatorCache.get(actionId)?.coordinators.get(blockId);
@@ -759,7 +779,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				return cached;
 			}
 		}
-		return this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options);
+		return this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent });
 	}
 
 	/**