@optimystic/db-core 0.17.0 → 0.18.0

package/src/collection/collection.ts

@@ -1,5 +1,6 @@
 import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId } from "../index.js";
 import { Log, Atomic, Tracker, copyTransforms, CacheSource, isTransformsEmpty, TransactorSource } from "../index.js";
+import { BlockUnavailableError } from "../network/struct.js";
 import type { CollectionHeaderBlock, CollectionId, ICollection, SyncOptions } from "./index.js";
 import { SyncRetryExhaustedError } from "./index.js";
 import type { ReadDependency } from "../transaction/transaction.js";
@@ -9,6 +10,9 @@ import { randomBytes } from '@noble/hashes/utils.js';
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
 import { Latches } from "../utility/latches.js";
 import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('collection');
 
 /** Default base backoff (and historical fixed delay) between sync retries, in ms. */
 const PendingRetryDelayMs = 100;
@@ -57,7 +61,59 @@ export class Collection<TAction> implements ICollection<TAction> {
 		this.latchId = `Collection:${this.id}`;
 	}
 
-	static async createOrOpen<TAction>(transactor: ITransactor, id: CollectionId, init: CollectionInitOptions<TAction>) {
+	/** Open an EXISTING collection.
+	 *
+	 * Resolves to `undefined` when the header block probe comes back empty — an
+	 * authoritatively absent header, meaning nothing has ever been committed under this id.
+	 * A header the storage layer could not RETRIEVE (a revision this node cannot
+	 * reconstruct, an unreachable cohort) is not absent: the probe throws
+	 * {@link BlockUnavailableError} instead of resolving `undefined`, so an unreachable
+	 * collection can never be mistaken for a nonexistent one.
+	 *
+	 * Use this wherever reading — not creating — is what was meant. {@link createOrOpen}
+	 * would instead stage a fresh empty collection, and reads through it would report an
+	 * absent dataset as a legitimately empty one. */
+	static async open<TAction>(transactor: ITransactor, id: CollectionId, init: CollectionInitOptions<TAction>): Promise<Collection<TAction> | undefined> {
+		const { source, sourceCache, tracker, header } = await Collection.probeHeader(transactor, id);
+		if (!header) {
+			// Return before anything is staged: the tracker's transforms stay empty, so a caller
+			// that ignores the undefined cannot later sync a phantom collection into existence.
+			return undefined;
+		}
+		await Collection.attachToLog<TAction>(source, transactor, tracker, id, header);
+		return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict);
+	}
+
+	/** Open an existing collection, or stage a fresh empty one in the local tracker when the
+	 * header is authoritatively absent. Nothing is written to storage until {@link sync}.
+	 *
+	 * Correct only where inventing a collection is genuinely intended — a first write, a
+	 * bootstrap path. The create branch logs `collection:invented`; prefer {@link open} on
+	 * any pure read path. */
+	static async createOrOpen<TAction>(transactor: ITransactor, id: CollectionId, init: CollectionInitOptions<TAction>): Promise<Collection<TAction>> {
+		const { source, sourceCache, tracker, header } = await Collection.probeHeader(transactor, id);
+
+		if (header) {	// Collection already exists
+			await Collection.attachToLog<TAction>(source, transactor, tracker, id, header);
+		} else {	// Collection does not exist
+			log('collection:invented id=%s — no committed header found; staging a fresh empty collection', id);
+			const headerBlock = init.createHeaderBlock(id, tracker);
+			tracker.insert(headerBlock);
+			source.actionContext = undefined;
+			await Log.open<Action<TAction>>(tracker, id);
+		}
+
+		return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict);
+	}
+
+	/** The per-instance read wiring every open path needs, plus the header probe result.
+	 * Shared by {@link open} and {@link createOrOpen} so the two cannot drift. */
+	private static async probeHeader(transactor: ITransactor, id: CollectionId): Promise<{
+		source: TransactorSource<IBlock>,
+		sourceCache: CacheSource<IBlock>,
+		tracker: Tracker<IBlock>,
+		header: CollectionHeaderBlock | undefined,
+	}> {
 		// Start with a context that has an infinite revision number to ensure that we always fetch the latest log information.
 		// One shared read-dependency collector feeds both the source (direct structural reads) and the cache (every
 		// cache hit/miss), so a block read from either layer records a dependency — cache hits included.
@@ -66,22 +122,29 @@ export class Collection<TAction> implements ICollection<TAction> {
 		const sourceCache = new CacheSource(source, undefined, collector);
 		const tracker = new Tracker(sourceCache);
 		const header = await source.tryGet(id) as CollectionHeaderBlock | undefined;
+		return { source, sourceCache, tracker, header };
+	}
 
-		if (header) {	// Collection already exists
-			// Bootstrap ActionContext from the committed tail before walking the chain.
-			// This allows the transactor to serve pending non-tail blocks during Log.open.
-			await Collection.bootstrapContext(source, transactor, header);
+	/** Walk an existing collection's log and point the source at its latest action context.
+	 * A header we just probed successfully but whose log will not open is a fault, not an
+	 * absence — throw rather than let the collection read as empty. (The re-read goes through
+	 * the tracker/cache, so it can disagree with the probe when storage is flaky mid-open.) */
+	private static async attachToLog<TAction>(
+		source: TransactorSource<IBlock>,
+		transactor: ITransactor,
+		tracker: Tracker<IBlock>,
+		id: CollectionId,
+		header: CollectionHeaderBlock,
+	): Promise<void> {
+		// Bootstrap ActionContext from the committed tail before walking the chain.
+		// This allows the transactor to serve pending non-tail blocks during Log.open.
+		await Collection.bootstrapContext(source, transactor, header);
 
-			const log = (await Log.open<Action<TAction>>(tracker, id))!;
-			source.actionContext = await log.getActionContext();
-		} else {	// Collection does not exist
-			const headerBlock = init.createHeaderBlock(id, tracker);
-			tracker.insert(headerBlock);
-			source.actionContext = undefined;
-			await Log.open<Action<TAction>>(tracker, id);
+		const collectionLog = await Log.open<Action<TAction>>(tracker, id);
+		if (!collectionLog) {
+			throw new Error(`Log not found for collection ${id}`);
 		}
-
-		return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict);
+		source.actionContext = await collectionLog.getActionContext();
 	}
 
 	async act(...actions: Action<TAction>[]) {
@@ -129,6 +192,10 @@ export class Collection<TAction> implements ICollection<TAction> {
 
 		// Bootstrap context from committed tail so pending blocks are accessible.
 		// Read through tracker so Chain.open inside Log.open reuses the cached header.
+		// A header the storage layer could not retrieve throws BlockUnavailableError out of
+		// this read (it is not a StaleFailure, so sync's retry loop does not absorb it) —
+		// so an ABSENT header here is authoritative: nothing was ever committed under this
+		// id, and the silent no-op below is correct rather than a masked failure.
 		const header = await tracker.tryGet(this.id) as CollectionHeaderBlock | undefined;
 		if (header) {
 			await Collection.bootstrapContext(source, this.transactor, header);
@@ -136,8 +203,8 @@ export class Collection<TAction> implements ICollection<TAction> {
 
 		// Get the latest entries from the log, starting from where we left off
 		const actionContext = this.source.actionContext;
-		const log = await Log.open<Action<TAction>>(tracker, this.id);
-		const latest = log ? await log.getFrom(actionContext?.rev ?? 0) : undefined;
+		const collectionLog = await Log.open<Action<TAction>>(tracker, this.id);
+		const latest = collectionLog ? await collectionLog.getFrom(actionContext?.rev ?? 0) : undefined;
 
 		// Process the entries and track the blocks they affect
 		let anyConflicts = false;
@@ -166,7 +233,7 @@ export class Collection<TAction> implements ICollection<TAction> {
 		// read — drop the reverted blocks from the read cache and replay pending work against the reverted
 		// base (docs/right-is-right.md §Client notification). De-duped across cascade children by reverted
 		// block; over-inclusive by design (over-invalidation just resubmits — it never wrongly retains).
-		const invalidations = log ? await log.getInvalidationsFrom(actionContext?.rev ?? 0) : [];
+		const invalidations = collectionLog ? await collectionLog.getInvalidationsFrom(actionContext?.rev ?? 0) : [];
 		if (invalidations.length > 0) {
 			const revertedBlockIds = [...new Set(invalidations.flatMap(inv => inv.reverted.map(r => r.blockId)))];
 			this.sourceCache.clear(revertedBlockIds);
@@ -316,12 +383,12 @@ export class Collection<TAction> implements ICollection<TAction> {
 			const tracker = new Tracker(this.sourceCache, snapshot);
 
 			// Add the action to the log (in local tracking space)
-			const log = await Log.open<Action<TAction>>(tracker, this.id);
-			if (!log) {
+			const collectionLog = await Log.open<Action<TAction>>(tracker, this.id);
+			if (!collectionLog) {
 				throw new Error(`Log not found for collection ${this.id}`);
 			}
 			const newRev = (this.source.actionContext?.rev ?? 0) + 1;
-			const addResult = await log.addActions(pending, actionId, newRev, () => tracker.transformedBlockIds());
+			const addResult = await collectionLog.addActions(pending, actionId, newRev, () => tracker.transformedBlockIds());
 
 			// Commit the action to the transactor. Carry the aged retry priority derived from the
 			// consecutive-failure count so a sync that keeps losing concurrent races out-ranks fresh
@@ -381,11 +448,11 @@ export class Collection<TAction> implements ICollection<TAction> {
 	}
 
 	async *selectLog(forward = true): AsyncIterableIterator<Action<TAction>> {
-		const log = await Log.open<Action<TAction>>(this.tracker, this.id);
-		if (!log) {
+		const collectionLog = await Log.open<Action<TAction>>(this.tracker, this.id);
+		if (!collectionLog) {
 			throw new Error(`Log not found for collection ${this.id}`);
 		}
-		for await (const entry of log.select(undefined, forward)) {
+		for await (const entry of collectionLog.select(undefined, forward)) {
 			if (entry.action) {
 				// NOTE: copy-then-reverse to avoid mutating the stored log entry array.
 				// Once tsconfig targets ES2023, `entry.action.actions.toReversed()` is cleaner.
@@ -425,6 +492,13 @@ export class Collection<TAction> implements ICollection<TAction> {
 	 * with context=undefined. Its state.latest contains the ActionRev of the most recent
 	 * committed action — exactly the proof needed for the transactor to serve pending
 	 * non-tail blocks during chain walks.
+	 *
+	 * This read goes to the transactor directly rather than through {@link TransactorSource},
+	 * so it has to honour the `unavailable` flag itself: a tail the repo could not retrieve
+	 * must not degrade into "no context", which would leave the chain walk unable to see
+	 * pending non-tail blocks and the collection reading as if they did not exist. A tail
+	 * with no `state.latest` and NO flag is a real answer (nothing committed yet) and still
+	 * no-ops.
 	 */
 	private static async bootstrapContext(
 		source: TransactorSource<IBlock>,
@@ -434,7 +508,11 @@ export class Collection<TAction> implements ICollection<TAction> {
 		const tailId = header.tailId;
 		if (tailId) {
 			const tailResult = await transactor.get({ blockIds: [tailId] });
-			const tailState = tailResult?.[tailId]?.state;
+			const tailEntry = tailResult?.[tailId];
+			if (tailEntry?.unavailable !== undefined && tailEntry.block == null) {
+				throw new BlockUnavailableError(tailId, tailEntry.unavailable);
+			}
+			const tailState = tailEntry?.state;
 			if (tailState?.latest) {
 				source.actionContext = {
 					committed: [{ actionId: tailState.latest.actionId, rev: tailState.latest.rev }],

package/src/collections/diary/diary.ts

@@ -1,59 +1,67 @@
-import { Collection, registerCollectionType } from "../../index.js";
-import type { ITransactor, Action, BlockId, BlockStore, IBlock, CollectionInitOptions, CollectionId } from "../../index.js";
-import { DiaryHeaderBlockType } from "./struct.js";
-
-export class Diary<TEntry> {
-    private constructor(
-			private readonly collection: Collection<TEntry>
-		) {
-    }
-
-    static async create<TEntry>(network: ITransactor, id: CollectionId): Promise<Diary<TEntry>> {
-        const init: CollectionInitOptions<TEntry> = {
-            modules: {
-							"append": async (_action, _trx) => {
-								// Append-only diary doesn't need to modify any blocks
-								// All entries are stored in the log
-							}
-            },
-            createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => ({
-                header: store.createBlockHeader(DiaryHeaderBlockType, id)
-            })
-        };
-
-        const collection = await Collection.createOrOpen(network, id, init);
-        return new Diary<TEntry>(collection);
-    }
-
-    async append(data: TEntry): Promise<void> {
-        const action: Action<TEntry> = {
-            type: "append",
-            data: data
-        };
-
-        await this.collection.act(action);
-        await this.collection.updateAndSync();
-    }
-
-    /** Fetch the latest state from the network */
-    async update(): Promise<void> {
-        await this.collection.update();
-    }
-
-    async *select(forward = true): AsyncIterableIterator<TEntry> {
-        for await (const entry of this.collection.selectLog(forward)) {
-            yield entry.data;
-        }
-    }
-}
-
-registerCollectionType({
-	blockType: DiaryHeaderBlockType,
-	name: "Diary",
-	open: (transactor, id) => Collection.createOrOpen(transactor, id, {
-		modules: { "append": async () => {} },
-		createHeaderBlock: (hid, store) => ({
-			header: store.createBlockHeader(DiaryHeaderBlockType, hid)
-		})
-	}),
-});
+import { Collection, registerCollectionType } from "../../index.js";
+import type { ITransactor, Action, BlockId, BlockStore, IBlock, CollectionInitOptions, CollectionId } from "../../index.js";
+import { DiaryHeaderBlockType } from "./struct.js";
+
+/** A diary keeps every entry in the log itself, so the header block is the whole structure
+ *  and the "append" handler has no blocks to touch. */
+function diaryInit<TEntry>(): CollectionInitOptions<TEntry> {
+	return {
+		modules: {
+			"append": async (_action, _trx) => {
+				// Append-only diary doesn't need to modify any blocks
+				// All entries are stored in the log
+			}
+		},
+		createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => ({
+			header: store.createBlockHeader(DiaryHeaderBlockType, id)
+		})
+	};
+}
+
+export class Diary<TEntry> {
+    private constructor(
+			private readonly collection: Collection<TEntry>
+		) {
+    }
+
+    /** Open an existing diary, or stage a fresh empty one when nothing has ever been committed
+     *  under this id. Attach-or-create — see {@link Collection.createOrOpen}. */
+    static async createOrOpen<TEntry>(network: ITransactor, id: CollectionId): Promise<Diary<TEntry>> {
+        const collection = await Collection.createOrOpen(network, id, diaryInit<TEntry>());
+        return new Diary<TEntry>(collection);
+    }
+
+    /** Open an EXISTING diary, or resolve to `undefined` when no header block has ever been
+     *  committed under this id. Never brings a diary into existence — see {@link Collection.open}. */
+    static async open<TEntry>(network: ITransactor, id: CollectionId): Promise<Diary<TEntry> | undefined> {
+        const collection = await Collection.open(network, id, diaryInit<TEntry>());
+        return collection ? new Diary<TEntry>(collection) : undefined;
+    }
+
+    async append(data: TEntry): Promise<void> {
+        const action: Action<TEntry> = {
+            type: "append",
+            data: data
+        };
+
+        await this.collection.act(action);
+        await this.collection.updateAndSync();
+    }
+
+    /** Fetch the latest state from the network */
+    async update(): Promise<void> {
+        await this.collection.update();
+    }
+
+    async *select(forward = true): AsyncIterableIterator<TEntry> {
+        for await (const entry of this.collection.selectLog(forward)) {
+            yield entry.data;
+        }
+    }
+}
+
+registerCollectionType({
+	blockType: DiaryHeaderBlockType,
+	name: "Diary",
+	createOrOpen: (transactor, id) => Collection.createOrOpen(transactor, id, diaryInit<unknown>()),
+});

package/src/collections/tree/tree.ts

@@ -20,6 +20,13 @@ export interface TreeReadView<TKey, TEntry> {
 	isValid(path: Path<TKey, TEntry>): boolean;
 }
 
+/** Carries the read {@link BTree} from wherever it gets built (the `createHeaderBlock`
+ * callback on the create path, {@link Tree.attach} on the open path) to the `replace`
+ * handler, which needs the live instance to invalidate outstanding paths. */
+interface BTreeHolder<TKey, TEntry> {
+	btree?: BTree<TKey, TEntry>;
+}
+
 export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 
 	private constructor(
@@ -31,6 +38,24 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 	) {
 	}
 
+	/** Open an EXISTING tree, or resolve to `undefined` when no header block has ever been
+	 * committed under this id. Never brings a tree into existence — nothing is staged into the
+	 * collection's tracker on the absent path, so a caller that ignores the `undefined` cannot
+	 * later sync a phantom tree. Use on pure read paths; see {@link Collection.open}. */
+	static async open<TKey, TEntry>(
+		network: ITransactor,
+		id: CollectionId,
+		keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
+		compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
+		/** See {@link Tree.createOrOpen}'s `nodeCapacity`. */
+		nodeCapacity?: number,
+	): Promise<Tree<TKey, TEntry> | undefined> {
+		const held: BTreeHolder<TKey, TEntry> = {};
+		const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
+		const collection = await Collection.open<TreeReplaceAction<TKey, TEntry>>(network, id, init);
+		return collection ? Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity) : undefined;
+	}
+
 	static async createOrOpen<TKey, TEntry>(
 		network: ITransactor,
 		id: CollectionId,
@@ -49,10 +74,22 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 		 *  the header and read it back on reopen rather than trusting the caller to re-supply it. */
 		nodeCapacity?: number,
 	): Promise<Tree<TKey, TEntry>> {
-		// Tricky bootstrapping here:
-		// We need the root id to initialize the collection header, so we create the btree in the create collection header callback.
-		let btree: BTree<TKey, TEntry> | undefined;
-		const init: CollectionInitOptions<TreeReplaceAction<TKey, TEntry>> = {
+		const held: BTreeHolder<TKey, TEntry> = {};
+		const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
+		const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
+		return Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity);
+	}
+
+	/** The collection wiring both open paths share. `held` carries the read btree between the
+	 * `createHeaderBlock` callback (which must build it to obtain the root id) and {@link attach}. */
+	private static buildInit<TKey, TEntry>(
+		id: CollectionId,
+		keyFromEntry: (entry: TEntry) => TKey,
+		compare: (a: TKey, b: TKey) => number,
+		nodeCapacity: number | undefined,
+		held: BTreeHolder<TKey, TEntry>,
+	): CollectionInitOptions<TreeReplaceAction<TKey, TEntry>> {
+		return {
 			modules: {
 				"replace": async ({ data: actions }, trx) => {
 					// Write through the Atomic store the handler is handed (`trx`), NOT the captured
@@ -78,25 +115,39 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 					// Mutations landed in `trx`, not the read btree, so its version counter never moved.
 					// Bump it to invalidate any Path a caller still holds — preserving the path-invalidation
 					// the previous in-place handler gave for free.
-					btree?.invalidatePaths();
+					held.btree?.invalidatePaths();
 				}
 			},
-			createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => {	// Only called if the collection does not exist
+			createHeaderBlock: (hid: BlockId, store: BlockStore<IBlock>) => {	// Only called if the collection does not exist
+				// Tricky bootstrapping here:
+				// We need the root id to initialize the collection header, so we create the btree here.
 				let rootId: BlockId;
-				btree = BTree.create<TKey, TEntry>(store, (_s, r) => {
+				held.btree = BTree.create<TKey, TEntry>(store, (_s, r) => {
 						rootId = r;
-						return new CollectionTrunk(store, id);
+						return new CollectionTrunk(store, hid);
 					}, keyFromEntry, compare, nodeCapacity);
 				return {
-					header: store.createBlockHeader(TreeHeaderBlockType, id),
+					header: store.createBlockHeader(TreeHeaderBlockType, hid),
 					rootId: rootId!,
 				}
 			}
 		};
+	}
 
-		const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
-		btree = btree ?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare, nodeCapacity);
-		return new Tree<TKey, TEntry>(collection, btree, keyFromEntry, compare);
+	/** Bind an opened collection to its read btree. On the create path `createHeaderBlock` already
+	 * built one (it needed the root id for the header); on the open path it never ran, so build it
+	 * over the collection's existing tracker. Either way the result is written back into `held` so
+	 * the `replace` handler's path-invalidation targets the very btree reads go through. */
+	private static attach<TKey, TEntry>(
+		collection: Collection<TreeReplaceAction<TKey, TEntry>>,
+		held: BTreeHolder<TKey, TEntry>,
+		keyFromEntry: (entry: TEntry) => TKey,
+		compare: (a: TKey, b: TKey) => number,
+		nodeCapacity: number | undefined,
+	): Tree<TKey, TEntry> {
+		held.btree = held.btree
+			?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare, nodeCapacity);
+		return new Tree<TKey, TEntry>(collection, held.btree, keyFromEntry, compare);
 	}
 
 	async replace(data: TreeReplaceAction<TKey, TEntry>): Promise<void> {

package/src/network/index.ts

@@ -2,5 +2,6 @@ export * from "./i-key-network.js";
 export * from "./i-peer-network.js";
 export * from "./i-repo.js";
 export * from "./repo-protocol.js";
+export * from "./stale-failure.js";
 export * from "./struct.js";
 export * from "./types.js";

package/src/network/stale-failure.ts

@@ -0,0 +1,13 @@
+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);
+}

package/src/network/struct.ts

@@ -71,6 +71,14 @@ 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;
 };
 
 export type PendResult = PendSuccess | StaleFailure;
@@ -126,13 +134,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,11 +22,11 @@ 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) {
@@ -929,11 +930,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);
 		}
 
 		return { collectionId, blockIds: pendResult.blockIds };
@@ -1052,6 +1053,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,