@optimystic/db-core 0.17.0 → 0.19.0

package/src/network/stale-failure.ts

@@ -0,0 +1,43 @@
+import type { StaleFailure } from "./struct.js";
+
+/**
+ * The single rule for "is this non-success retryable after a re-read?" Both write paths and the
+ * transactor's aggregation call this — no consumer re-derives it.
+ *
+ * {@link StaleFailure.conflict} is authoritative when present. The `missing`/`pending` fallback
+ * covers producers that have not been taught the field, including a remote peer on an older build
+ * (the repo protocol is plain JSON, so an unset field simply arrives absent).
+ */
+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

@@ -71,6 +71,28 @@ export type StaleFailure = {
 	missing?: ActionTransforms[];
 	/** List of actions that are pending on the blocks touched by this pend */
 	pending?: ActionPending[];
+	/**
+	 * Explicit retryability. True when this failure is an optimistic-concurrency loss — the
+	 * requested revision was taken, or a rival pend holds the blocks — so a re-read, rebase and
+	 * re-pend can win. Set it only when the producer genuinely classified the failure; leave it
+	 * absent otherwise, and consumers fall back to inferring from `missing`/`pending`.
+	 * 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;
@@ -126,13 +148,39 @@ export type BlockGets = {
 	context?: ActionContext;	// Latest if this is omitted
 };
 
+/** Why a repo could not establish whether a block exists. Present ONLY when the repo
+ *  knows its own answer is a guess; an absent field is an authoritative answer. */
+export type BlockUnavailableReason =
+	/** Records for this block exist here but it cannot be reconstructed locally — a
+	 *  revision was received with no base to apply it to, or its history is truncated. */
+	| 'unmaterializable'
+	/** Nothing is held locally and the cohort could not be consulted to confirm it. */
+	| 'peers-unreachable';
+
 export type GetBlockResult = {
 	/** The retrieved block - undefined if the block was deleted	 */
 	block?: IBlock;
 	/** The latest and pending states of the repo that retrieved the block */
 	state: BlockActionState;
+	/** Set when this repo could not determine whether the block exists — its answer is a
+	 *  guess, not an authoritative absent. Every producer that omits it (including
+	 *  TestTransactor) keeps meaning "authoritative". */
+	unavailable?: BlockUnavailableReason;
 };
 
+/**
+ * Thrown by a block read when the responsible repo could not determine whether the
+ * block exists. Distinct from "the block is absent" (undefined) and from a transport
+ * failure — this node's data is genuinely indeterminate and the caller must not treat
+ * it as empty. Not a StaleFailure: `Collection.sync` does not retry it.
+ */
+export class BlockUnavailableError extends Error {
+	constructor(readonly blockId: BlockId, readonly reason: BlockUnavailableReason) {
+		super(`Block ${blockId} is unavailable (${reason}): the repo could not determine whether it exists`);
+		this.name = 'BlockUnavailableError';
+	}
+}
+
 export type GetBlockResults = Record<BlockId, GetBlockResult>;
 
 /**

package/src/testing/test-transactor.ts

@@ -189,10 +189,13 @@ export class TestTransactor implements ITransactor {
 			}
 		}
 
-		// Handle failure due to committed conflicts first
+		// 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
 			};
 		}
@@ -200,7 +203,7 @@ export class TestTransactor implements ITransactor {
 		// Handle failure/retry due to pending conflicts
 		if (conflictingPendings.length > 0) {
 			if (policy === 'f') {
-				return { success: false, pending: conflictingPendings };
+				return { success: false, conflict: true, pending: conflictingPendings };
 			} else if (policy === 'r') {
 				// Simulate fetching pending transforms for 'r' policy
 				const pendingWithTransforms = conflictingPendings
@@ -217,6 +220,7 @@ export class TestTransactor implements ITransactor {
 
 				return {
 					success: false,
+					conflict: true,
 					pending: pendingWithTransforms
 				};
 			}

package/src/transaction/coordinator.ts

@@ -1,6 +1,7 @@
 import type { ITransactor, BlockId, CollectionId, Transforms, PendRequest, CommitRequest, ActionId } from "../index.js";
 import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
 import type { PeerId } from "../network/types.js";
+import { isConflictFailure } from "../network/stale-failure.js";
 import type { Collection } from "../collection/collection.js";
 import type { SyncOptions } from "../collection/index.js";
 import { isTransactionExpired, clampPriority } from "./transaction.js";
@@ -21,15 +22,24 @@ const DefaultBaseBackoffMs = 100;
 const DefaultMaxBackoffMs = 5000;
 
 /**
- * A pend that failed. `conflict` marks the retryable class — an optimistic-concurrency collision (a
- * committed `missing` action newer than our rev, or a `pending` action on a touched block) that a
- * re-read + re-pend can clear. A bare rejection reason (storage full, policy) is NOT a conflict and
- * is not worth re-driving. Thrown by {@link TransactionCoordinator.pendCollection} so the fan-out in
- * pendPhase can settle it and read the flag off the rejection.
+ * A pend that failed. `conflict` marks the retryable class — an optimistic-concurrency collision that
+ * a re-read + re-pend can clear — as decided by `isConflictFailure` over the failure response. A hard
+ * rejection (storage full, policy) is NOT a conflict and is not worth re-driving. Thrown by
+ * {@link TransactionCoordinator.pendCollection} so the fan-out in pendPhase can settle it and read
+ * 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';
 	}
 }
@@ -181,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();
 				}
@@ -929,11 +940,11 @@ export class TransactionCoordinator {
 
 		const pendResult = await this.transactor.pend(pendRequest);
 		if (!pendResult.success) {
-			// A committed `missing` action or a `pending` action on a touched block is an
-			// optimistic-concurrency conflict — retryable after a re-read. A bare `reason` is a hard
-			// rejection (storage/policy) that re-driving won't fix.
-			const conflict = Boolean(pendResult.missing?.length || pendResult.pending?.length);
-			throw new PendRejectedError(collectionId, conflict, pendResult.reason);
+			// Retryability comes from the response itself: a producer that classified the failure sets
+			// `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, pendResult.staleAt);
 		}
 
 		return { collectionId, blockIds: pendResult.blockIds };
@@ -1052,6 +1063,11 @@ export class TransactionCoordinator {
 				}
 				// Permanent stale failure: do not retry here. It IS a clean stale loss, though, so
 				// mark it retryable at the coordinator level (after a re-read advances the rev).
+				// NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict`
+				// like the pend path does. Once the pend succeeded, a returned commit failure means
+				// the revision slot moved, and no commit producer sets `conflict` today. If a commit
+				// producer ever starts distinguishing hard commit rejections (validator policy,
+				// storage fault) from lost races, gate `stale` on isConflictFailure here.
 				return {
 					collectionId,
 					committed: false,

package/src/transactor/network-transactor.ts

@@ -1,6 +1,8 @@
 import { peerIdFromString } from "../network/types.js";
 import type { PeerId } from "../network/types.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 { 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, 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";
@@ -106,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;
@@ -123,35 +130,40 @@ 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;
 		}
 
 		// Second-chance retry: ONLY for a genuine no-response — a batch with no valid
-		// response, or a response missing an entry for a requested block id. An
-		// authoritative "absent" answer (a valid response that carries an entry for
-		// every requested block id, even one whose entry has only `state` and no
-		// materialized `block`) is FINAL and must not retry. A block that genuinely
-		// does not exist yet surfaces as `{ state: {} }` (an entry that is present) —
-		// retrying it doubles the round-trips on the common createOrOpen "does this
-		// block exist?" probe. Cross-member reconciliation for a missing block has
-		// already happened one layer down: CoordinatorRepo.get detects `isMissing` and
-		// consults cluster peers before it responds, so by the time an authoritative
-		// absent reaches here there is nothing left for a transactor-level retry to
-		// discover. See ticket txn-perf-authoritative-notfound.
+		// response, a response missing an entry for a requested block id, or an entry
+		// flagged `unavailable`. An authoritative "absent" answer (a valid response that
+		// carries an entry for every requested block id, even one whose entry has only
+		// `state` and no materialized `block`) is FINAL and must not retry. A block that
+		// genuinely does not exist yet surfaces as `{ state: {} }` (an entry that is
+		// present and unflagged) — retrying it doubles the round-trips on the common
+		// createOrOpen "does this block exist?" probe. Cross-member reconciliation for a
+		// missing block has already happened one layer down: CoordinatorRepo.get detects
+		// `isMissing` and consults cluster peers before it responds — and when that
+		// consult FAILS, the entry now says so via `unavailable` instead of posing as an
+		// authoritative absent. So by the time an unflagged absent reaches here there is
+		// nothing left for a transactor-level retry to discover, while a flagged entry
+		// earns the retry against a different peer that an absent deliberately does not.
+		// See tickets txn-perf-authoritative-notfound and repo-reports-unavailable-vs-absent.
 		const hasValidResponse = (b: CoordinatorBatch<BlockId[], GetBlockResults>) => {
 			return b.request?.isResponse === true && b.request.response != null;
 		};
 
 		// A batch is answered when its response carries an entry for EVERY requested
-		// block id. An entry present with only `state` (no `block`) is an authoritative
-		// "absent", which counts as answered — not a gap.
+		// block id and none of those entries is flagged `unavailable`. An entry present
+		// with only `state` (no `block`) is an authoritative "absent", which counts as
+		// answered — not a gap. An `unavailable` entry is the peer saying its own answer
+		// is a guess, so it does NOT count as answered.
 		const isAuthoritative = (b: CoordinatorBatch<BlockId[], GetBlockResults>) => {
 			if (!hasValidResponse(b)) return false;
 			const resp = b.request!.response! as GetBlockResults;
-			return b.payload.every(bid => resp[bid] !== undefined);
+			return b.payload.every(bid => resp[bid] !== undefined && resp[bid]!.unavailable === undefined);
 		};
 
 		// Retry only genuine no-response / partial-response batches. An authoritative
@@ -172,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];
@@ -182,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' })
 					);
 				}
 			}));
@@ -199,16 +211,24 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// Cache the completed batches that had actual responses (not just coordinator not found)
 		const completedBatches = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && !isRecordEmpty(b.request!.response!)));
 
+		// Three-way ranking per block id: a materialized block beats an authoritative
+		// absent, which beats an `unavailable` guess — one peer that positively knows the
+		// block is absent outranks another that could not find out. Non-object junk ranks
+		// below everything so any real entry replaces it.
+		const rankOf = (r: unknown): number => {
+			if (!r || typeof r !== 'object') return -1;
+			const entry = r as GetBlockResults[BlockId];
+			if (entry.block != null) return 2;
+			return entry.unavailable === undefined ? 1 : 0;
+		};
+
 		// Create a lookup map from successful responses only
 		const resultEntries = new Map<string, any>();
 		for (const batch of completedBatches) {
 			const resp = batch.request!.response! as any;
 			for (const [bid, res] of Object.entries(resp)) {
 				const existing = resultEntries.get(bid);
-				// Prefer responses that include a materialized block
-				const resHasBlock = res && typeof res === 'object' && 'block' in (res as any) && (res as any).block != null;
-				const existingHasBlock = existing && typeof existing === 'object' && 'block' in (existing as any) && (existing as any).block != null;
-				if (!existing || (resHasBlock && !existingHasBlock)) {
+				if (!existing || rankOf(res) > rankOf(existing)) {
 					resultEntries.set(bid, res);
 				}
 			}
@@ -245,6 +265,17 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// Get block states from repos
 		const blockStates = await this.get({ blockIds: allBlockIds });
 
+		// A block whose repo could not determine whether it exists carries no status either:
+		// its empty `state` would read below as `aborted`, turning "I could not find out" into
+		// a definite verdict on someone's action. Fail loudly instead, like every other read of
+		// an unavailable block (see BlockUnavailableError).
+		for (const blockId of allBlockIds) {
+			const entry = blockStates[blockId];
+			if (entry?.unavailable !== undefined && entry.block == null) {
+				throw new BlockUnavailableError(blockId, entry.unavailable);
+			}
+		}
+
 		// Determine status for each action ref
 		const results: BlockActionStatus[] = blockActions.map(ref => ({
 			...ref,
@@ -511,8 +542,33 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			const stale = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
 			if (stale.length > 0) {	// Any active stale failures should preempt reporting connection or other potential transient errors (we have information)
 				log('pend:stale actionId=%s staleCount=%d', blockAction.actionId, stale.length);
+				// Carry the first available reject reason through: `SyncRetryExhaustedError.lastReason`
+				// and the multi-collection writer's failure message both read it, and it is the only
+				// diagnostic that survives an exhausted retry budget.
+				const reason = stale.map(b => (b.request!.response! as StaleFailure).reason).find(r => r !== undefined);
+				// This response is REBUILT from the per-batch ones rather than forwarded, so
+				// retryability has to be carried explicitly or it is lost: a batch whose failure was
+				// a confirmed lost race can arrive with neither `missing` nor `pending` (see
+				// CoordinatorRepo.classifyStaleRejection), and the aggregate would then look like a
+				// hard rejection to `isConflictFailure`. Any conflicting batch makes the aggregate a
+				// conflict — the pend failed as a whole, and a re-read/rebase can clear it.
+				// NOTE: `some`, not `every`, so a pend whose batches mix a lost race with a genuine hard
+				// rejection is reported retryable and burns its (bounded, backed-off) retry budget before
+				// failing. Deliberate: an unclassified reason-only response from an older peer is
+				// indistinguishable from a hard rejection here, and `every` would refuse to retry a real
+				// race whenever one batch came from such a peer. Revisit if every producer sets `conflict`
+				// (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)),
 				};
 			}
@@ -627,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;
 		}
@@ -683,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)
 		);
 	}
 
@@ -705,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);
@@ -713,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 });
 	}
 
 	/**

package/src/transactor/transactor-source.ts

@@ -1,6 +1,7 @@
 import { randomBytes } from '@noble/hashes/utils.js'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, StaleFailure, ActionContext, BlockType, BlockSource, ReadPurpose, Transforms } from "../index.js";
+import { BlockUnavailableError } from "../network/struct.js";
 import type { ReadDependency } from "../transaction/transaction.js";
 import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
 
@@ -42,7 +43,14 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 		// `result[id]` is undefined. Destructuring that would throw a TypeError.
 		const entry = result?.[id];
 		if (entry) {
-			const { block, state } = entry;
+			const { block, state, unavailable } = entry;
+			// An entry flagged `unavailable` with no block is the repo saying "I could not find
+			// out whether this exists" — an answer that must not be read as absent. Throw rather
+			// than return undefined, and record no read dependency (dependencies are recorded
+			// only for blocks that actually exist). A repo that omits the flag stays authoritative.
+			if (!block && unavailable) {
+				throw new BlockUnavailableError(id, unavailable);
+			}
 			// Record a read dependency only for a block that actually exists. A transactor may return a
 			// populated entry with `block: undefined` for a genuinely-missing block (TestTransactor does;
 			// the Network transactor always populates the key); recording there would add a phantom