@optimystic/db-core 0.22.0 → 0.24.1

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

@@ -1,37 +1,37 @@
-import type { BlockType } from "../blocks/index.js";
-import type { ITransactor } from "../transactor/index.js";
-import type { CollectionId, ICollection } from "./struct.js";
-
-export interface CollectionTypeDescriptor {
-	/** The block type used for this collection's header block (e.g. "DIH", "TRE") */
-	blockType: BlockType;
-	/** Human-readable name (e.g. "Diary", "Tree") */
-	name: string;
-	/** 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). */
-	createOrOpen?: (transactor: ITransactor, id: CollectionId) => Promise<ICollection<any>>;
-}
-
-const collectionTypes = new Map<BlockType, CollectionTypeDescriptor>();
-
-/** Register a collection type by its header block type. Throws if already registered. */
-export function registerCollectionType(descriptor: CollectionTypeDescriptor): void {
-	if (collectionTypes.has(descriptor.blockType)) {
-		throw new Error(
-			`Collection type ${descriptor.blockType} (${descriptor.name}) already registered`
-			+ ` (${collectionTypes.get(descriptor.blockType)!.name})`
-		);
-	}
-	collectionTypes.set(descriptor.blockType, descriptor);
-}
-
-/** Look up a collection type descriptor by its header block type. */
-export function getCollectionType(blockType: BlockType): CollectionTypeDescriptor | undefined {
-	return collectionTypes.get(blockType);
-}
-
-/** Returns all registered collection type descriptors. */
-export function getCollectionTypes(): ReadonlyMap<BlockType, CollectionTypeDescriptor> {
-	return collectionTypes;
-}
+import type { BlockType } from "../blocks/index.js";
+import type { ITransactor } from "../transactor/index.js";
+import type { CollectionId, ICollection } from "./struct.js";
+
+export interface CollectionTypeDescriptor {
+	/** The block type used for this collection's header block (e.g. "DIH", "TRE") */
+	blockType: BlockType;
+	/** Human-readable name (e.g. "Diary", "Tree") */
+	name: string;
+	/** 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). */
+	createOrOpen?: (transactor: ITransactor, id: CollectionId) => Promise<ICollection<any>>;
+}
+
+const collectionTypes = new Map<BlockType, CollectionTypeDescriptor>();
+
+/** Register a collection type by its header block type. Throws if already registered. */
+export function registerCollectionType(descriptor: CollectionTypeDescriptor): void {
+	if (collectionTypes.has(descriptor.blockType)) {
+		throw new Error(
+			`Collection type ${descriptor.blockType} (${descriptor.name}) already registered`
+			+ ` (${collectionTypes.get(descriptor.blockType)!.name})`
+		);
+	}
+	collectionTypes.set(descriptor.blockType, descriptor);
+}
+
+/** Look up a collection type descriptor by its header block type. */
+export function getCollectionType(blockType: BlockType): CollectionTypeDescriptor | undefined {
+	return collectionTypes.get(blockType);
+}
+
+/** Returns all registered collection type descriptors. */
+export function getCollectionTypes(): ReadonlyMap<BlockType, CollectionTypeDescriptor> {
+	return collectionTypes;
+}

package/src/collection/collection.ts

@@ -5,7 +5,7 @@ import { Tracker } from "../transform/tracker.js";
 import { CacheSource } from "../transform/cache-source.js";
 import { copyTransforms, isTransformsEmpty } from "../transform/helpers.js";
 import { TransactorSource } from "../transactor/transactor-source.js";
-import { BlockUnavailableError } from "../network/struct.js";
+import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
 import type { CollectionHeaderBlock, CollectionId, ICollection, SyncOptions } from "./index.js";
 import { CollectionHeaderVanishedError, SyncRetryExhaustedError } from "./struct.js";
 import type { ActionContext } from "./action.js";
@@ -441,6 +441,19 @@ export class Collection<TAction> implements ICollection<TAction> {
 		this.pending = [];
 	}
 
+	/** Whether {@link sync} has anything to push: staged actions, or tracker transforms
+	 * that were never committed (an INVENTED collection's header/root blocks live there
+	 * until its first sync, with no pending action to name them).
+	 *
+	 * This is the exact predicate {@link syncInternal} loops on, so `false` means a sync
+	 * would commit nothing. Exposed so a caller that would otherwise flush
+	 * unconditionally can skip the round trip — note that {@link Tree.sync} routes
+	 * through {@link updateAndSync}, so an unnecessary flush still pays a full,
+	 * cache-bypassing {@link update} before discovering it has nothing to do. */
+	hasUnsyncedChanges(): boolean {
+		return this.pending.length > 0 || !isTransformsEmpty(this.tracker.transforms);
+	}
+
 	/** Fold a just-committed set of transforms into this collection's read cache
 	 * so subsequent reads (and stages) through THIS instance observe the committed
 	 * state, mirroring what {@link sync} does inline after a successful transact.
@@ -505,7 +518,7 @@ export class Collection<TAction> implements ICollection<TAction> {
 		// 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)) {
+		while (this.hasUnsyncedChanges()) {
 			if (signal?.aborted) {
 				throw makeAbortError(signal);
 			}
@@ -640,6 +653,13 @@ export class Collection<TAction> implements ICollection<TAction> {
 	 * 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.
+	 *
+	 * The same goes for `unconfirmedAheadRev`: this unpinned tail read is the ONE seam where a
+	 * lagging collection can learn a newer revision exists — every later data read is pinned to
+	 * the context seeded here. Silently seeding from a tail the repo could not confirm is
+	 * current would freeze the collection at the stale revision with nothing ever reporting a
+	 * problem, so it throws the same way TransactorSource.tryGet does for its unpinned reads
+	 * (see the tradeoff NOTE there).
 	 */
 	private static async bootstrapContext(
 		source: TransactorSource<IBlock>,
@@ -653,6 +673,9 @@ export class Collection<TAction> implements ICollection<TAction> {
 			if (tailEntry?.unavailable !== undefined && tailEntry.block == null) {
 				throw new BlockUnavailableError(tailId, tailEntry.unavailable);
 			}
+			if (tailEntry?.unconfirmedAheadRev !== undefined) {
+				throw new BlockPossiblyStaleError(tailId, tailEntry.unconfirmedAheadRev);
+			}
 			const tailState = tailEntry?.state;
 			if (tailState?.latest) {
 				source.actionContext = {

package/src/collections/diary/diary.ts

@@ -1,68 +1,68 @@
-import { Collection } from "../../collection/collection.js";
-import type { ITransactor, Action, BlockId, BlockStore, IBlock, CollectionInitOptions, CollectionId } from "../../index.js";
-import { registerCollectionType } from "../../collection/collection-type-registry.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>()),
-});
+import { Collection } from "../../collection/collection.js";
+import type { ITransactor, Action, BlockId, BlockStore, IBlock, CollectionInitOptions, CollectionId } from "../../index.js";
+import { registerCollectionType } from "../../collection/collection-type-registry.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/readme.md

@@ -42,6 +42,10 @@ The view guarantees **one consistent answer from first read to last**:
   view-creation time.
 - A block the storage layer cannot reconstruct at the pinned revision surfaces as
   `BlockUnavailableError`, never as a silently absent block.
+- A block served at a revision the repo could not confirm is the newest one *inside the
+  pinned view* (a cohort peer claims a revision at or below the pin that nothing could
+  corroborate) surfaces as `BlockPossiblyStaleError`, never as a snapshot silently missing
+  a committed update. A claim ABOVE the pin is irrelevant to the view and is not raised.
 
 By default a view records **no read dependencies** — it is not part of any transaction's
 conflict set, so an unrelated committed read can never fail a writer's commit validation.