@optimystic/db-core 0.17.0 → 0.19.0

package/src/collection/collection-type-registry.ts

@@ -7,9 +7,10 @@ export interface CollectionTypeDescriptor {
 	blockType: BlockType;
 	/** Human-readable name (e.g. "Diary", "Tree") */
 	name: string;
-	/** Optional factory to open a collection with default settings.
+	/** Optional factory to open a collection with default settings, bringing it into existence
+	 *  when nothing has ever been committed under the id (see {@link Collection.createOrOpen}).
 	 *  Not all types support this (e.g. Tree requires keyFromEntry/compare). */
-	open?: (transactor: ITransactor, id: CollectionId) => Promise<ICollection<any>>;
+	createOrOpen?: (transactor: ITransactor, id: CollectionId) => Promise<ICollection<any>>;
 }
 
 const collectionTypes = new Map<BlockType, CollectionTypeDescriptor>();

package/src/collection/collection.ts

@@ -1,7 +1,9 @@
 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 { CollectionHeaderVanishedError, SyncRetryExhaustedError } from "./index.js";
+import type { ActionContext } from "./action.js";
 import type { ReadDependency } from "../transaction/transaction.js";
 import { clampPriority } from "../transaction/transaction.js";
 import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
@@ -9,6 +11,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 +62,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 +123,53 @@ 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}`);
 		}
+		// Monotonic, not an overwrite: getActionContext resolves undefined when the chain has no
+		// tail or the tail block carries zero entries, and that must not erase the revision
+		// bootstrapContext just read off the committed tail.
+		Collection.advanceContext(source, id, await collectionLog.getActionContext());
+	}
 
-		return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict);
+	/** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
+	 *
+	 * The revision a collection last committed at is knowledge it earned; a read that found
+	 * nothing — or found an older view of the log — cannot un-earn it. Silently accepting the
+	 * lower value makes the next sync ask for a revision that is long gone, and every retry
+	 * repeats the same doomed request because each retry re-runs the same losing read.
+	 *
+	 * Equal revisions still adopt `next`: the rev is unchanged but its `committed` list may be
+	 * more complete than what we hold. */
+	private static advanceContext(source: TransactorSource<IBlock>, id: CollectionId, next: ActionContext | undefined): void {
+		const current = source.actionContext;
+		if (next === undefined) {
+			return;	// The read learned nothing — keep what we already know.
+		}
+		if (current !== undefined && next.rev < current.rev) {
+			log('collection:context-not-lowered id=%s held=%d read=%d', id, current.rev, next.rev);
+			return;
+		}
+		source.actionContext = next;
 	}
 
 	async act(...actions: Action<TAction>[]) {
@@ -129,15 +217,32 @@ 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).
 		const header = await tracker.tryGet(this.id) as CollectionHeaderBlock | undefined;
 		if (header) {
 			await Collection.bootstrapContext(source, this.transactor, header);
+		} else if (this.source.actionContext) {
+			// An absent header is only believable for a collection that has never committed.
+			// We hold a committed revision, so the two answers contradict each other — surface it
+			// as a fault instead of no-opping into a forgotten revision and a rev-1 retry spin.
+			// NOTE: this aborts every caller of update(), including TransactionCoordinator's
+			// blanket refresh of ALL registered collections between commit retries — a
+			// non-participant with a momentarily-absent header now fails the whole retry rather
+			// than being skipped. That is the intended loud failure; if it ever shows up as
+			// otherwise-healthy transactions aborting, narrow that refresh to the transaction's
+			// participants (see the note at coordinator.ts's update loop) rather than softening
+			// this throw.
+			throw new CollectionHeaderVanishedError(this.id, this.source.actionContext.rev);
 		}
+		// Falling through means the header is genuinely absent AND we hold no revision: nothing
+		// was ever committed under this id. Log.open reads the same block id, so it too resolves
+		// undefined and everything below no-ops — correct here, rather than a masked failure.
 
 		// 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 +271,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);
@@ -180,8 +285,10 @@ export class Collection<TAction> implements ICollection<TAction> {
 			await this.replayActions();
 		}
 
-		// Update our context to the latest
-		this.source.actionContext = latest?.context;
+		// Update our context to the latest — monotonically. An empty/unopenable log yields no
+		// context at all, and a log read that lags what we already committed yields an older one;
+		// neither is grounds for forgetting the revision we hold.
+		Collection.advanceContext(this.source, this.id, latest?.context);
 	}
 
 	/** Capture the current staged state — tracker transforms plus the pending
@@ -298,6 +405,9 @@ 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.
+		let lastStaleAt: { blockId: BlockId; rev: number } | undefined;
 
 		while (this.pending.length || !isTransformsEmpty(this.tracker.transforms)) {
 			if (signal?.aborted) {
@@ -305,7 +415,7 @@ export class Collection<TAction> implements ICollection<TAction> {
 			}
 			// Progress-agnostic ceiling: give up if the wall-clock deadline passed.
 			if (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs) {
-				throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason ?? 'deadline exceeded');
+				throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason ?? 'deadline exceeded', lastStaleAt);
 			}
 
 			// Snapshot the pending actions so that any new actions aren't assumed to be part of this action
@@ -316,12 +426,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
@@ -331,6 +441,7 @@ export class Collection<TAction> implements ICollection<TAction> {
 			if (staleFailure) {
 				consecutiveFailures++;
 				lastReason = staleFailure.reason ?? lastReason;
+				lastStaleAt = staleFailure.staleAt ?? lastStaleAt;
 				// 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
@@ -338,7 +449,7 @@ export class Collection<TAction> implements ICollection<TAction> {
 				// attempts ≈ 21s of exponential backoff. If a high-contention workload legitimately
 				// needs to wait longer for a pending commit to clear, raise maxAttempts for that caller.
 				if (consecutiveFailures >= maxAttempts) {
-					throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason);
+					throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason, lastStaleAt);
 				}
 				// Back off before every retry (any stale failure — reason/missing/pending), growing
 				// exponentially from the base delay up to the cap, with proportional random jitter so a
@@ -357,6 +468,7 @@ export class Collection<TAction> implements ICollection<TAction> {
 				// Forward progress: reset the no-progress budget.
 				consecutiveFailures = 0;
 				lastReason = undefined;
+				lastStaleAt = undefined;
 				// 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
@@ -381,11 +493,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 +537,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 +553,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/collection/struct.ts

@@ -40,13 +40,50 @@ export class SyncRetryExhaustedError extends Error {
 		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}` : ''));
+			(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>;

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/i-key-network.ts

@@ -1,9 +1,27 @@
 import type { PeerId } from "./types.js";
 import type { ClusterPeers } from "../cluster/structs.js";
 
+/**
+ * What a caller intends to do with the coordinator it is asking for.
+ *
+ * The distinction matters only when a node is isolated and the only candidate left is
+ * itself. A read served from this node's own replica is at worst STALE — and the layers
+ * below already say so (a self-only cohort answers conclusively; an unreachable cohort
+ * comes back flagged unavailable). A write coordinated alone can instead diverge from the
+ * rest of the network, so it is held to the stricter bar.
+ */
+export type CoordinatorIntent = 'read' | 'write';
+
 export type FindCoordinatorOptions = {
 	/** Peers that have already been tried (and failed) */
 	excludedPeers?: PeerId[];
+	/**
+	 * What the caller intends to do with the coordinator. A read may fall back to this
+	 * node's own replica when the network is unreachable; a write may not do so on the
+	 * strength of the same evidence. Defaults to `'write'` (the conservative behavior)
+	 * when unset, so callers that don't set it are unchanged.
+	 */
+	intent?: CoordinatorIntent;
 };
 
 

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";