@optimystic/db-core 0.20.0 → 0.21.0

package/src/collections/tree/readme.md

@@ -17,3 +17,35 @@ tree.replace([
 ]);
 ```
 Replaces the value at key 5 with { a: 1, b: 'Value' }, and deletes the value at key 10.
+
+## Committed read views (`readView`)
+
+`tree.readView(snapshot)` builds a read-only view of the tree as captured by an earlier
+`tree.snapshot()` — typically the pre-transaction state recorded before any DML was staged.
+It is how a `committed.<Table>` reference (e.g. inside a deferred CHECK) reads committed
+rows while the live tree still holds the transaction's in-flight changes.
+
+The view guarantees **one consistent answer from first read to last**:
+
+- It never sees mutations staged into the live tree after the snapshot was taken.
+- It is pinned to the **snapshot's** committed boundary — the revision the collection held
+  when `snapshot()` was called (`CollectionSnapshot.context`), not the revision at
+  view-creation time. So a view built AFTER the same tree flushed a further commit still
+  describes the snapshot's boundary (the multi-tree commit-sweep case: tree N already
+  flushed, tree N+1 not — views of both describe the one pre-sweep boundary). Commits
+  that fold into the live tree's cache — or clear it (a live read's `update()` after
+  another writer commits) — while the view is being walked do not change what the view
+  returns. This holds even for blocks the view has to fetch from storage mid-scan (the
+  view carries its own frozen action context, which the transactor honours on `get`, and
+  cache entries newer than the pin are excluded from the view's warm seed). A hand-built
+  snapshot with no recorded boundary falls back to the collection's context at
+  view-creation time.
+- A block the storage layer cannot reconstruct at the pinned revision surfaces as
+  `BlockUnavailableError`, never as a silently absent block.
+
+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.
+Pass `{ recordReads: true }` to opt back in.
+
+Each view privately holds up to the block-cache LRU budget (128 blocks, cloned at creation)
+plus whatever it faults in; views are intended to be per-scan and dropped when the scan ends.

package/src/collections/tree/tree.ts

@@ -1,293 +1,312 @@
-import { Collection, type CollectionInitOptions, type CollectionId, type CollectionSnapshot } from "../../collection/index.js";
-import type { ITransactor, BlockId, BlockStore, IBlock } from "../../index.js";
-import { BTree, type Path, type KeyRange } from "../../btree/index.js";
-import { CollectionTrunk } from "./collection-trunk.js";
-import { TreeHeaderBlockType, type TreeReplaceAction } from "./struct.js";
-
-/**
- * Read-only surface of a tree: every navigation/lookup method a reader needs, with
- * none of the mutation (stage/sync) or network-refresh (update) entry points. Both
- * the live {@link Tree} and the committed view returned by {@link Tree.readView}
- * structurally satisfy this, so a consumer can read through either uniformly.
- */
-export interface TreeReadView<TKey, TEntry> {
-	first(): Promise<Path<TKey, TEntry>>;
-	find(key: TKey): Promise<Path<TKey, TEntry>>;
-	get(key: TKey): Promise<TEntry | undefined>;
-	at(path: Path<TKey, TEntry>): TEntry | undefined;
-	range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>>;
-	ascending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<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(
-		private readonly collection: Collection<TreeReplaceAction<TKey, TEntry>>,
-		private readonly btree: BTree<TKey, TEntry>,
-		/** Captured so {@link readView} can rebuild a BTree over a committed tracker. */
-		private readonly keyFromEntry: (entry: TEntry) => TKey,
-		private readonly compare: (a: TKey, b: TKey) => number,
-	) {
-	}
-
-	/** 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,
-		keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
-		compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
-		/** B-tree node fan-out. Defaults to the BTree default (64). Exposed mainly so tests can
-		 *  force a multi-level tree with few entries (a small capacity), which is what exercises the
-		 *  interior-navigation read-exclusion path — with the default you would need thousands of
-		 *  entries before a descent has any interior branch between root and leaf.
-		 *
-		 *  NOTE: fan-out is NOT persisted in the collection header — it is a per-call construction
-		 *  param. Creating a tree with a non-default capacity and later reopening it (a separate
-		 *  createOrOpen call) without the SAME capacity silently uses 64, so subsequent writes split
-		 *  at a fan-out the existing nodes were not built for. Fine today (only tests pass it, and
-		 *  they pass it consistently); if a persisted tree ever needs a custom fan-out, persist it in
-		 *  the header and read it back on reopen rather than trusting the caller to re-supply it. */
-		nodeCapacity?: number,
-	): Promise<Tree<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
-					// read btree, so `internalTransact`'s all-or-nothing wrapper actually governs this
-					// action: if any entry throws, `atomic.commit()` is skipped and every staged node
-					// write from this action is discarded (whole-action rollback) — identically for
-					// freshly created and reopened trees. Binding a throwaway BTree to `trx` reuses the
-					// public constructor; no btree API change needed.
-					const actionTree = new BTree<TKey, TEntry>(
-						trx,
-						new CollectionTrunk(trx, id),
-						keyFromEntry,
-						compare,
-						nodeCapacity,	// keep the write btree's fan-out in lock-step with the read btree
-					);
-					for (const [key, entry] of actions) {
-						if (entry) {
-							await actionTree.upsert(entry);
-						} else {
-							await actionTree.deleteAt((await actionTree.find(key)));
-						}
-					}
-					// 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.
-					held.btree?.invalidatePaths();
-				}
-			},
-			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;
-				held.btree = BTree.create<TKey, TEntry>(store, (_s, r) => {
-						rootId = r;
-						return new CollectionTrunk(store, hid);
-					}, keyFromEntry, compare, nodeCapacity);
-				return {
-					header: store.createBlockHeader(TreeHeaderBlockType, hid),
-					rootId: rootId!,
-				}
-			}
-		};
-	}
-
-	/** 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> {
-			await this.collection.act({ type: "replace", data });
-			await this.collection.updateAndSync();
-	}
-
-	/** Stage a mutation into the collection's tracker WITHOUT flushing it to the
-	 * transactor. Reads through this same Tree instance see the staged change;
-	 * call {@link sync} to persist it, or {@link snapshot}/{@link restore} to drop it. This
-	 * is the deferred counterpart to {@link replace}, which stages and flushes in
-	 * one step — use {@link stage} when the persist/discard decision belongs to a
-	 * surrounding transaction's commit/rollback. */
-	async stage(data: TreeReplaceAction<TKey, TEntry>): Promise<void> {
-			await this.collection.act({ type: "replace", data });
-	}
-
-	/** Flush all staged (and any other pending) changes to the transactor.
-	 * Equivalent to the flush half of {@link replace}. */
-	async sync(): Promise<void> {
-			await this.collection.updateAndSync();
-	}
-
-	/** Capture the current staged state so it can be restored via {@link restore}.
-	 * Take this BEFORE staging a unit of work that may be rolled back. The snapshot
-	 * is opaque; pass the exact value back to {@link restore}. */
-	snapshot(): CollectionSnapshot<TreeReplaceAction<TKey, TEntry>> {
-			return this.collection.snapshotPending();
-	}
-
-	/** Restore the staged state captured by {@link snapshot}, discarding mutations
-	 * staged since. Counterpart to {@link stage} for transaction rollback —
-	 * preserves a never-synced collection's header/root rather than wiping it. */
-	restore(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): void {
-			this.collection.restorePending(snapshot);
-	}
-
-	/** Build a read-only view of this tree as captured by an earlier {@link snapshot}
-	 * — typically the pre-transaction state recorded before any DML was staged. The
-	 * view reads through a FRESH tracker seeded with the snapshot's transforms over
-	 * the SAME committed source cache, so it observes exactly the snapshot's state:
-	 * it never sees mutations staged into the live tree after the snapshot, and it
-	 * does not disturb the live tree (reads are latch-free and tracker-isolated). This
-	 * is how a `committed.*` scan reads the pre-transaction snapshot while the live
-	 * tree still holds this transaction's in-flight inserts.
-	 *
-	 * `snapshot` is the opaque value returned by {@link snapshot}; pass it back
-	 * verbatim. */
-	readView(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): TreeReadView<TKey, TEntry> {
-			const tracker = this.collection.createReadTracker(snapshot.transforms);
-			return new BTree<TKey, TEntry>(
-				tracker,
-				new CollectionTrunk(tracker, this.collection.id),
-				this.keyFromEntry,
-				this.compare,
-			);
-	}
-
-	/** The underlying {@link Collection} this tree stages mutations into.
-	 *
-	 * Exposed (package-internal intent) so a transaction coordinator can register
-	 * and read the very tracker this tree mutates: session-mode commit reads
-	 * `collection.tracker.transforms` directly, so the coordinator's collection
-	 * map must hold the same instance the tree stages into. Prefer this accessor
-	 * over reaching through `tree['collection']`. */
-	getCollection(): Collection<TreeReplaceAction<TKey, TEntry>> {
-			return this.collection;
-	}
-
-	/** This tree's collection id, as a plain string. Used by consumers that flush
-	 * several trees together (e.g. the Quereus adapter's legacy commit sweep) to
-	 * name a specific tree in diagnostics when a partial flush leaves trees out of
-	 * sync. Structurally satisfies the adapter's `DirtyTree.describe()`. */
-	describe(): string {
-			return String(this.collection.id);
-	}
-
-	/**
-	 * Update the local state from the network.
-	 * Call this before reading to ensure you have the latest data.
-	 */
-	async update(): Promise<void> {
-		await this.collection.update();
-	}
-
-	// Read actions
-
-	async first(): Promise<Path<TKey, TEntry>> {
-		return await this.btree.first();
-	}
-
-	async last(): Promise<Path<TKey, TEntry>> {
-		return await this.btree.last();
-	}
-
-	async find(key: TKey): Promise<Path<TKey, TEntry>> {
-		return await this.btree.find(key);
-	}
-
-	async get(key: TKey): Promise<TEntry | undefined> {
-		return await this.btree.get(key);
-	}
-
-	at(path: Path<TKey, TEntry>): TEntry | undefined {
-		return this.btree.at(path);
-	}
-
-	range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>> {
-		return this.btree.range(range);
-	}
-
-	ascending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
-		return this.btree.ascending(path);
-	}
-
-	descending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
-		return this.btree.descending(path);
-	}
-
-	async getCount(from?: { path: Path<TKey, TEntry>, ascending?: boolean }): Promise<number> {
-		return await this.btree.getCount(from);
-	}
-
-	async next(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
-		return await this.btree.next(path);
-	}
-
-	async moveNext(path: Path<TKey, TEntry>): Promise<void> {
-		await this.btree.moveNext(path);
-	}
-
-	async prior(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
-		return await this.btree.prior(path);
-	}
-
-	async movePrior(path: Path<TKey, TEntry>): Promise<void> {
-		await this.btree.movePrior(path);
-	}
-
-	isValid(path: Path<TKey, TEntry>): boolean {
-		return this.btree.isValid(path);
-	}
-}
+import { Collection, type CollectionInitOptions, type CollectionId, type CollectionSnapshot, type ReadViewOptions } from "../../collection/index.js";
+import type { ITransactor, BlockId, BlockStore, IBlock } from "../../index.js";
+import { BTree, type Path, type KeyRange } from "../../btree/index.js";
+import { CollectionTrunk } from "./collection-trunk.js";
+import { TreeHeaderBlockType, type TreeReplaceAction } from "./struct.js";
+
+/**
+ * Read-only surface of a tree: every navigation/lookup method a reader needs, with
+ * none of the mutation (stage/sync) or network-refresh (update) entry points. Both
+ * the live {@link Tree} and the committed view returned by {@link Tree.readView}
+ * structurally satisfy this, so a consumer can read through either uniformly.
+ */
+export interface TreeReadView<TKey, TEntry> {
+	first(): Promise<Path<TKey, TEntry>>;
+	find(key: TKey): Promise<Path<TKey, TEntry>>;
+	get(key: TKey): Promise<TEntry | undefined>;
+	at(path: Path<TKey, TEntry>): TEntry | undefined;
+	range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>>;
+	ascending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<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(
+		private readonly collection: Collection<TreeReplaceAction<TKey, TEntry>>,
+		private readonly btree: BTree<TKey, TEntry>,
+		/** Captured so {@link readView} can rebuild a BTree over a committed tracker. */
+		private readonly keyFromEntry: (entry: TEntry) => TKey,
+		private readonly compare: (a: TKey, b: TKey) => number,
+	) {
+	}
+
+	/** 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,
+		keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
+		compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
+		/** B-tree node fan-out. Defaults to the BTree default (64). Exposed mainly so tests can
+		 *  force a multi-level tree with few entries (a small capacity), which is what exercises the
+		 *  interior-navigation read-exclusion path — with the default you would need thousands of
+		 *  entries before a descent has any interior branch between root and leaf.
+		 *
+		 *  NOTE: fan-out is NOT persisted in the collection header — it is a per-call construction
+		 *  param. Creating a tree with a non-default capacity and later reopening it (a separate
+		 *  createOrOpen call) without the SAME capacity silently uses 64, so subsequent writes split
+		 *  at a fan-out the existing nodes were not built for. Fine today (only tests pass it, and
+		 *  they pass it consistently); if a persisted tree ever needs a custom fan-out, persist it in
+		 *  the header and read it back on reopen rather than trusting the caller to re-supply it. */
+		nodeCapacity?: number,
+	): Promise<Tree<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
+					// read btree, so `internalTransact`'s all-or-nothing wrapper actually governs this
+					// action: if any entry throws, `atomic.commit()` is skipped and every staged node
+					// write from this action is discarded (whole-action rollback) — identically for
+					// freshly created and reopened trees. Binding a throwaway BTree to `trx` reuses the
+					// public constructor; no btree API change needed.
+					const actionTree = new BTree<TKey, TEntry>(
+						trx,
+						new CollectionTrunk(trx, id),
+						keyFromEntry,
+						compare,
+						nodeCapacity,	// keep the write btree's fan-out in lock-step with the read btree
+					);
+					for (const [key, entry] of actions) {
+						if (entry) {
+							await actionTree.upsert(entry);
+						} else {
+							await actionTree.deleteAt((await actionTree.find(key)));
+						}
+					}
+					// 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.
+					held.btree?.invalidatePaths();
+				}
+			},
+			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;
+				held.btree = BTree.create<TKey, TEntry>(store, (_s, r) => {
+						rootId = r;
+						return new CollectionTrunk(store, hid);
+					}, keyFromEntry, compare, nodeCapacity);
+				return {
+					header: store.createBlockHeader(TreeHeaderBlockType, hid),
+					rootId: rootId!,
+				}
+			}
+		};
+	}
+
+	/** 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> {
+			await this.collection.act({ type: "replace", data });
+			await this.collection.updateAndSync();
+	}
+
+	/** Stage a mutation into the collection's tracker WITHOUT flushing it to the
+	 * transactor. Reads through this same Tree instance see the staged change;
+	 * call {@link sync} to persist it, or {@link snapshot}/{@link restore} to drop it. This
+	 * is the deferred counterpart to {@link replace}, which stages and flushes in
+	 * one step — use {@link stage} when the persist/discard decision belongs to a
+	 * surrounding transaction's commit/rollback. */
+	async stage(data: TreeReplaceAction<TKey, TEntry>): Promise<void> {
+			await this.collection.act({ type: "replace", data });
+	}
+
+	/** Flush all staged (and any other pending) changes to the transactor.
+	 * Equivalent to the flush half of {@link replace}. */
+	async sync(): Promise<void> {
+			await this.collection.updateAndSync();
+	}
+
+	/** Capture the current staged state so it can be restored via {@link restore}.
+	 * Take this BEFORE staging a unit of work that may be rolled back. The snapshot
+	 * is opaque; pass the exact value back to {@link restore}. */
+	snapshot(): CollectionSnapshot<TreeReplaceAction<TKey, TEntry>> {
+			return this.collection.snapshotPending();
+	}
+
+	/** Restore the staged state captured by {@link snapshot}, discarding mutations
+	 * staged since. Counterpart to {@link stage} for transaction rollback —
+	 * preserves a never-synced collection's header/root rather than wiping it. */
+	restore(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): void {
+			this.collection.restorePending(snapshot);
+	}
+
+	/** Build a read-only view of this tree as captured by an earlier {@link snapshot}
+	 * — typically the pre-transaction state recorded before any DML was staged. The
+	 * view reads through a FRESH tracker seeded with the snapshot's transforms over a
+	 * PRIVATE, revision-pinned read path (see {@link Collection.createReadTracker}),
+	 * so it observes exactly the snapshot's state from first read to last: it never
+	 * sees mutations staged into the live tree after the snapshot, it is untouched by
+	 * commits folding into (or clearing) the live tree's cache while it is walked, and
+	 * it does not disturb the live tree. This is how a `committed.*` scan reads the
+	 * pre-transaction snapshot while the live tree still holds this transaction's
+	 * in-flight inserts — and keeps reading it even if the live tree commits mid-scan.
+	 *
+	 * By default the view records no read dependencies into the collection's conflict
+	 * set; pass `{ recordReads: true }` to opt in (see {@link ReadViewOptions}).
+	 *
+	 * The view pins to the snapshot's OWN committed boundary ({@link CollectionSnapshot.context}),
+	 * not the collection's current one — so a snapshot captured before a commit yields a
+	 * coherent pre-commit view even when this tree has already flushed that commit (a
+	 * mid-sweep multi-tree commit). A snapshot with no recorded boundary (an invented
+	 * collection, or a hand-built snapshot) falls back to the current context, which is
+	 * the pre-boundary behaviour.
+	 *
+	 * `snapshot` is the opaque value returned by {@link snapshot}; pass it back
+	 * verbatim. */
+	readView(
+		snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>,
+		options?: ReadViewOptions,
+	): TreeReadView<TKey, TEntry> {
+			const effectiveOptions: ReadViewOptions = {
+				...options,
+				pinContext: options?.pinContext ?? snapshot.context,
+			};
+			const tracker = this.collection.createReadTracker(snapshot.transforms, effectiveOptions);
+			return new BTree<TKey, TEntry>(
+				tracker,
+				new CollectionTrunk(tracker, this.collection.id),
+				this.keyFromEntry,
+				this.compare,
+			);
+	}
+
+	/** The underlying {@link Collection} this tree stages mutations into.
+	 *
+	 * Exposed (package-internal intent) so a transaction coordinator can register
+	 * and read the very tracker this tree mutates: session-mode commit reads
+	 * `collection.tracker.transforms` directly, so the coordinator's collection
+	 * map must hold the same instance the tree stages into. Prefer this accessor
+	 * over reaching through `tree['collection']`. */
+	getCollection(): Collection<TreeReplaceAction<TKey, TEntry>> {
+			return this.collection;
+	}
+
+	/** This tree's collection id, as a plain string. Used by consumers that flush
+	 * several trees together (e.g. the Quereus adapter's legacy commit sweep) to
+	 * name a specific tree in diagnostics when a partial flush leaves trees out of
+	 * sync. Structurally satisfies the adapter's `DirtyTree.describe()`. */
+	describe(): string {
+			return String(this.collection.id);
+	}
+
+	/**
+	 * Update the local state from the network.
+	 * Call this before reading to ensure you have the latest data.
+	 */
+	async update(): Promise<void> {
+		await this.collection.update();
+	}
+
+	// Read actions
+
+	async first(): Promise<Path<TKey, TEntry>> {
+		return await this.btree.first();
+	}
+
+	async last(): Promise<Path<TKey, TEntry>> {
+		return await this.btree.last();
+	}
+
+	async find(key: TKey): Promise<Path<TKey, TEntry>> {
+		return await this.btree.find(key);
+	}
+
+	async get(key: TKey): Promise<TEntry | undefined> {
+		return await this.btree.get(key);
+	}
+
+	at(path: Path<TKey, TEntry>): TEntry | undefined {
+		return this.btree.at(path);
+	}
+
+	range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>> {
+		return this.btree.range(range);
+	}
+
+	ascending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
+		return this.btree.ascending(path);
+	}
+
+	descending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
+		return this.btree.descending(path);
+	}
+
+	async getCount(from?: { path: Path<TKey, TEntry>, ascending?: boolean }): Promise<number> {
+		return await this.btree.getCount(from);
+	}
+
+	async next(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
+		return await this.btree.next(path);
+	}
+
+	async moveNext(path: Path<TKey, TEntry>): Promise<void> {
+		await this.btree.moveNext(path);
+	}
+
+	async prior(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
+		return await this.btree.prior(path);
+	}
+
+	async movePrior(path: Path<TKey, TEntry>): Promise<void> {
+		await this.btree.movePrior(path);
+	}
+
+	isValid(path: Path<TKey, TEntry>): boolean {
+		return this.btree.isValid(path);
+	}
+}