@optimystic/db-core 0.14.1 → 0.16.3

package/src/transactor/network-transactor.ts

@@ -51,6 +51,26 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	private readonly getRepo: (peerId: PeerId) => IRepo;
 	private readonly localChangeNotifier: IBlockChangeNotifier | undefined;
 
+	/**
+	 * Per-transaction coordinator cache: `actionId → (blockId → resolved coordinator)`.
+	 * {@link pend} populates it from its final (retry-adjusted) batch assignment; commit
+	 * reads it via {@link resolveCoordinator} before falling back to a live
+	 * `findCoordinator`, so a block's coordinator is resolved once per transaction across
+	 * the pend→commit window instead of once at pend and again at commit.
+	 *
+	 * Keyed by `actionId`, which is unique per transaction, so an entry is only ever read
+	 * by commits of the SAME transaction — the ones that immediately follow its pend. Once
+	 * those finish, nothing reads the entry again (a later transaction has a fresh
+	 * actionId), so it carries no cross-transaction staleness even if it lingers. The TTL
+	 * and size cap in {@link txnCoordinatorsFor} are therefore only a memory backstop that
+	 * reclaims entries from transactions that pend but never commit — NOT a staleness
+	 * bound. This is why keying by actionId gives the same "thrown away when the
+	 * transaction ends" safety as threading a Map through the call, without touching the
+	 * ITransactor contract.
+	 */
+	private readonly txnCoordinatorCache = new Map<ActionId, { coordinators: Map<BlockId, PeerId>; expires: number }>();
+	private static readonly MAX_TXN_COORDINATOR_CACHE_ENTRIES = 1000;
+
 	constructor(
 		init: NetworkTransactorInit,
 	) {
@@ -109,56 +129,69 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			error = e as Error;
 		}
 
-		// Second-chance retry: if batch failed to respond OR responded with "not found"
-		// Different cluster members may have different views; retry with other coordinators
+		// Second-chance retry: ONLY for a genuine no-response — a batch with no valid
+		// response, or a response missing an entry for a requested block id. An
+		// authoritative "absent" answer (a valid response that carries an entry for
+		// every requested block id, even one whose entry has only `state` and no
+		// materialized `block`) is FINAL and must not retry. A block that genuinely
+		// does not exist yet surfaces as `{ state: {} }` (an entry that is present) —
+		// retrying it doubles the round-trips on the common createOrOpen "does this
+		// block exist?" probe. Cross-member reconciliation for a missing block has
+		// already happened one layer down: CoordinatorRepo.get detects `isMissing` and
+		// consults cluster peers before it responds, so by the time an authoritative
+		// absent reaches here there is nothing left for a transactor-level retry to
+		// discover. See ticket txn-perf-authoritative-notfound.
 		const hasValidResponse = (b: CoordinatorBatch<BlockId[], GetBlockResults>) => {
 			return b.request?.isResponse === true && b.request.response != null;
 		};
 
-		const hasBlockInResponse = (b: CoordinatorBatch<BlockId[], GetBlockResults>) => {
+		// A batch is answered when its response carries an entry for EVERY requested
+		// block id. An entry present with only `state` (no `block`) is an authoritative
+		// "absent", which counts as answered — not a gap.
+		const isAuthoritative = (b: CoordinatorBatch<BlockId[], GetBlockResults>) => {
 			if (!hasValidResponse(b)) return false;
 			const resp = b.request!.response! as GetBlockResults;
-			return b.payload.some(bid => {
-				const entry = resp[bid];
-				return entry && typeof entry === 'object' && 'block' in entry && entry.block != null;
-			});
+			return b.payload.every(bid => resp[bid] !== undefined);
 		};
 
-		// Retry batches that either failed to respond OR responded with "not found"
-		// This provides tolerance for different cluster member views
+		// Retry only genuine no-response / partial-response batches. An authoritative
+		// absent answer is not retried.
 		const retryable = Array.from(allBatches(batches)).filter(b =>
-			!hasValidResponse(b as any) || !hasBlockInResponse(b as any)
+			!isAuthoritative(b as any)
 		) as CoordinatorBatch<BlockId[], GetBlockResults>[];
 
 		if (retryable.length > 0 && Date.now() < expiration) {
 			log('get:retry retryable=%d', retryable.length);
-			try {
-				const excludedByRoot = new Map<CoordinatorBatch<BlockId[], GetBlockResults>, Set<PeerId>>();
-				for (const b of retryable) {
-					const excluded = new Set<PeerId>([b.peerId, ...((b.excludedPeers ?? []) as PeerId[])]);
-					excludedByRoot.set(b, excluded);
-					const retries = await createBatchesForPayload<BlockId[], GetBlockResults>(
-						b.payload,
-						b.payload,
+			// Fan out the per-batch retries concurrently. Each root batch builds its own
+			// excluded-peer set and attaches its own `subsumedBy`, so the retry rounds are
+			// independent per root and safe to run in parallel.
+			const retryOutcomes = await Promise.allSettled(retryable.map(async b => {
+				const excluded = new Set<PeerId>([b.peerId, ...((b.excludedPeers ?? []) as PeerId[])]);
+				const retries = await createBatchesForPayload<BlockId[], GetBlockResults>(
+					b.payload,
+					b.payload,
+					(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)],
+					Array.from(excluded),
+					async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+				);
+				if (retries.length > 0) {
+					b.subsumedBy = [...(b.subsumedBy ?? []), ...retries];
+					await processBatches(
+						retries,
+						(batch) => this.getRepo(batch.peerId).get({ blockIds: batch.payload, context: blockGets.context }, { expiration, dialTimeoutMs: this.dialTimeoutMs }),
+						batch => batch.payload,
 						(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)],
-						Array.from(excluded),
+						expiration,
 						async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
 					);
-					if (retries.length > 0) {
-						b.subsumedBy = [...(b.subsumedBy ?? []), ...retries];
-						await processBatches(
-							retries,
-							(batch) => this.getRepo(batch.peerId).get({ blockIds: batch.payload, context: blockGets.context }, { expiration, dialTimeoutMs: this.dialTimeoutMs }),
-							batch => batch.payload,
-							(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)],
-							expiration,
-							async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
-						);
-					}
 				}
-			} catch (e) {
-				// keep original error if any
-				if (!error) error = e as Error;
+			}));
+			// First-error-wins: keep any pre-existing error, otherwise adopt the first
+			// rejection across the concurrent retries (retryable order is preserved).
+			for (const outcome of retryOutcomes) {
+				if (outcome.status === 'rejected' && !error) {
+					error = outcome.reason instanceof Error ? outcome.reason : new Error(String(outcome.reason));
+				}
 			}
 		}
 
@@ -437,7 +470,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 						expiration,
 						dialTimeoutMs: this.dialTimeoutMs,
 						coordinatingBlockIds: batch.coordinatingBlockIds
-					} as any
+					}
 				),
 				batch => blockIdsForTransforms(batch.payload),
 				transformForBlock,
@@ -446,13 +479,10 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			);
 			// Cache resolved coordinators for follow-up commit to hit the same peers
 			try {
-				const pn: any = this.keyNetwork as any;
-				if (typeof pn?.recordCoordinator === 'function') {
-					for (const b of Array.from(allBatches(batches))) {
-						pn.recordCoordinator(await blockIdToBytes(b.blockId), b.peerId);
-					}
+				for (const b of Array.from(allBatches(batches))) {
+					this.keyNetwork.recordCoordinator?.(await blockIdToBytes(b.blockId), b.peerId);
 				}
-			} catch (e) { console.warn('Failed to record coordinator hint', e); }
+			} catch (e) { log('WARN: Failed to record coordinator hint %o', e); }
 		} catch (e) {
 			error = e as Error;
 		}
@@ -477,7 +507,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 
 		if (error) { // If any failures, cancel all pending actions as background microtask
 			log('pend:cancel actionId=%s', blockAction.actionId);
-			void Promise.resolve().then(() => this.cancelBatch(batches, { blockIds, actionId: blockAction.actionId }));
+			void Promise.resolve().then(() => this.cancelBatch(batches, { blockIds, actionId: blockAction.actionId })).catch(e => log('WARN: cancel after pend failure rejected: %o', e));
 			const stale = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
 			if (stale.length > 0) {	// Any active stale failures should preempt reporting connection or other potential transient errors (we have information)
 				log('pend:stale actionId=%s staleCount=%d', blockAction.actionId, stale.length);
@@ -491,6 +521,26 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 
 		// Collect replies back into result structure
 		const completed = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && b.request!.response!.success));
+
+		// Seed the per-transaction coordinator cache from the final (retry-adjusted) batch
+		// assignment so the follow-up commit reuses pend's resolution without a fresh
+		// findCoordinator round or a hop through the optional recordCoordinator hint. We read
+		// blockIdsForTransforms(b.payload) rather than the anchor b.blockId so EVERY block a
+		// consolidated batch coordinates is recorded — and against the peer that actually
+		// pended it, since a block re-homed by a retry lands in the retry batch's payload.
+		// NOTE: this cache assumes cluster membership is stable for the transaction's
+		// lifetime — the coordinator resolved here is reused verbatim at commit. Transactions
+		// are short, so that holds today. If a future change lets clusters churn *within* a
+		// single transaction (e.g. very long-running commits), a cached coordinator could
+		// point at a peer no longer in the cohort; commit self-heals (a failed cached peer is
+		// excluded and re-resolved live by processBatches), at the cost of one wasted round-trip.
+		const txnCoordinators = this.txnCoordinatorsFor(blockAction.actionId);
+		for (const b of completed) {
+			for (const bid of blockIdsForTransforms(b.payload)) {
+				txnCoordinators.set(bid, b.peerId);
+			}
+		}
+
 		log('pend:done actionId=%s ms=%d batches=%d', blockAction.actionId, Date.now() - t0, batches.length);
 		return {
 			success: true,
@@ -558,7 +608,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			if (error) {
 				// Non-tail block commit failures should not fail the overall action once the tail has committed.
 				// Proceed and rely on reconciliation paths (e.g. reads with context) to finalize state on lagging peers.
-				try { console.warn('[NetworkTransactor] non-tail commit had errors; proceeding after tail commit:', error.message); } catch { /* ignore */ }
+				try { log('WARN: non-tail commit had errors; proceeding after tail commit: %s', error.message); } catch { /* ignore */ }
 			}
 		}
 
@@ -569,12 +619,18 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	private async commitBlock(blockId: BlockId, blockIds: BlockId[], actionId: ActionId, rev: number, tailId?: BlockId): Promise<CommitResult> {
 		const { batches: tailBatches, error: tailError } = await this.commitBlocks({ blockIds: [blockId], actionId, rev, tailId });
 		if (tailError) {
-			// Cancel all pending actions as background microtask
-			Promise.resolve().then(() => this.cancel({ blockIds, actionId }));
+			// commit is a pure attempt: stale → { success:false }, transient → throw. Cancellation
+			// is the CALLER's responsibility (coordinator cancelPhase; TransactorSource.transact),
+			// which owns the retry budget and the committed-vs-pending picture — self-cancelling here
+			// would tear down a pend a caller's retry loop is still working against, and double-cancel.
 			// Collect and return any active stale failures
 			const stale = Array.from(allBatches(tailBatches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
 			if (stale.length > 0) {
-				return { missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing!)), success: false as const };
+				// NOTE: a reason-only StaleFailure (success:false, no `missing`) lands here too and
+				// returns { missing: [], success:false } — the `reason` string is dropped rather than
+				// surfaced via `throw tailError`. Fine today (failure still propagates); if reason-only
+				// commit rejections ever need their diagnostic reason, gate this branch on non-empty missing.
+				return { missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing).filter((x): x is ActionTransforms => x !== undefined)), success: false as const };
 			}
 			throw tailError;
 		}
@@ -584,7 +640,9 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	/** Attempts to commit a set of blocks, and handles failures and errors */
 	private async commitBlocks({ blockIds, actionId, rev, tailId }: RepoCommitRequest) {
 		const expiration = Date.now() + this.timeoutMs;
-		const batches = await this.batchesForPayload<BlockId[], CommitResult>(blockIds, blockIds, mergeBlocks, []);
+		// Thread the transaction's actionId so both the initial batch assembly and any
+		// per-block retry re-resolution prefer the coordinator pend already resolved.
+		const batches = await this.batchesForPayload<BlockId[], CommitResult>(blockIds, blockIds, mergeBlocks, [], actionId);
 		log('commitBlocks actionId=%s rev=%d batches=%d', actionId, rev, batches.length);
 		let error: Error | undefined;
 		try {
@@ -594,7 +652,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				batch => batch.payload,
 				mergeBlocks,
 				expiration,
-				async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+				async (blockId, options) => this.resolveCoordinator(blockId, options, actionId)
 			);
 		} catch (e) {
 			error = e as Error;
@@ -623,17 +681,74 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		blockIds: BlockId[],
 		payload: TPayload,
 		getBlockPayload: (payload: TPayload, blockId: BlockId, mergeWithPayload: TPayload | undefined) => TPayload,
-		excludedPeers: PeerId[]
+		excludedPeers: PeerId[],
+		/** When set, prefer a coordinator this transaction already resolved at pend (see {@link resolveCoordinator}). */
+		actionId?: ActionId
 	): Promise<CoordinatorBatch<TPayload, TResponse>[]> {
 		return createBatchesForPayload<TPayload, TResponse>(
 			blockIds,
 			payload,
 			getBlockPayload,
 			excludedPeers,
-			async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+			async (blockId, options) => this.resolveCoordinator(blockId, options, actionId)
 		);
 	}
 
+	/**
+	 * Resolve the coordinator for `blockId`, preferring one this transaction already
+	 * resolved during pend (the per-transaction cache) before falling back to a live
+	 * `findCoordinator`. A cached coordinator that is in `excludedPeers` (already tried and
+	 * failed during a retry) is skipped so a retry can't loop on a dead coordinator. A
+	 * cache miss — including every call with no `actionId` (get/cancel) — never fails; it
+	 * always falls through to live resolution.
+	 */
+	private async resolveCoordinator(
+		blockId: BlockId,
+		options: { excludedPeers: PeerId[] },
+		actionId: ActionId | undefined
+	): Promise<PeerId> {
+		if (actionId !== undefined) {
+			const cached = this.txnCoordinatorCache.get(actionId)?.coordinators.get(blockId);
+			if (cached && !options.excludedPeers.some(p => p.toString() === cached.toString())) {
+				return cached;
+			}
+		}
+		return this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options);
+	}
+
+	/**
+	 * Get (creating if absent) the per-transaction coordinator map for `actionId`,
+	 * refreshing its expiry and lazily sweeping expired sibling entries. See
+	 * {@link txnCoordinatorCache} for why the TTL/size cap here is a memory backstop and
+	 * not a staleness bound.
+	 */
+	private txnCoordinatorsFor(actionId: ActionId): Map<BlockId, PeerId> {
+		const now = Date.now();
+		// Reclaim entries from transactions that pended but never committed. A live entry is
+		// never stale (unique actionId; read only by its own transaction's commit), so
+		// sweeping lazily on write is safe.
+		for (const [aid, entry] of this.txnCoordinatorCache) {
+			if (entry.expires <= now) this.txnCoordinatorCache.delete(aid);
+		}
+		// Comfortably covers a normal pend→commit gap (~2 op budgets) with a fixed floor;
+		// an entry outliving this only loses the optimization (commit re-resolves live),
+		// never correctness.
+		const ttlMs = Math.max(this.timeoutMs * 2, 60_000);
+		const existing = this.txnCoordinatorCache.get(actionId);
+		if (existing) {
+			existing.expires = now + ttlMs;
+			return existing.coordinators;
+		}
+		const created = { coordinators: new Map<BlockId, PeerId>(), expires: now + ttlMs };
+		this.txnCoordinatorCache.set(actionId, created);
+		while (this.txnCoordinatorCache.size > NetworkTransactor.MAX_TXN_COORDINATOR_CACHE_ENTRIES) {
+			const oldest = this.txnCoordinatorCache.keys().next().value as ActionId | undefined;
+			if (oldest == null || oldest === actionId) break;
+			this.txnCoordinatorCache.delete(oldest);
+		}
+		return created.coordinators;
+	}
+
 	/** Cancels a pending transaction by canceling all blocks associated with the transaction, including failed peers */
 	private async cancelBatch<TPayload, TResponse>(
 		batches: CoordinatorBatch<TPayload, TResponse>[],

package/src/transactor/transactor-source.ts

@@ -1,16 +1,26 @@
 import { randomBytes } from '@noble/hashes/utils.js'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, StaleFailure, ActionContext, BlockType, BlockSource, Transforms } from "../index.js";
+import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, StaleFailure, ActionContext, BlockType, BlockSource, ReadPurpose, Transforms } from "../index.js";
 import type { ReadDependency } from "../transaction/transaction.js";
+import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
 
 export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlock> {
-	private readDependencies: ReadDependency[] = [];
+	/** Shared with this collection's CacheSource so cache hits also record dependencies.
+	 *  Defaults to a private instance so internal log-walk sources (which never need a
+	 *  transaction read set) work standalone. */
+	private readonly collector: ReadDependencyCollector;
+	/** Last revision observed per id, so CacheSource can learn the revision on a miss-load
+	 *  (it calls {@link getReadRevision} right after this source serves the block). */
+	private readRevisions = new Map<BlockId, number>();
 
 	constructor(
 		private readonly collectionId: BlockId,
 		private readonly transactor: ITransactor,
 		public actionContext: ActionContext | undefined,
-	) { }
+		collector?: ReadDependencyCollector,
+	) {
+		this.collector = collector ?? new ReadDependencyCollector();
+	}
 
 	createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader {
 		return {
@@ -25,24 +35,46 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 		return uint8ArrayToString(randomBytes(32), 'base64url')
 	}
 
-	async tryGet(id: BlockId): Promise<TBlock | undefined> {
+	async tryGet(id: BlockId, purpose: ReadPurpose = 'value'): Promise<TBlock | undefined> {
 		const result = await this.transactor.get({ blockIds: [id], context: this.actionContext });
-		if (result) {
-			const { block, state } = result[id]!;
-			// Record read dependency for optimistic concurrency control
-			this.readDependencies.push({ blockId: id, revision: state.latest?.rev ?? 0 });
+		// Guard the per-key entry: some transactors return a sparse result that omits `id`
+		// entirely (e.g. block genuinely not found), so `result` is a truthy object but
+		// `result[id]` is undefined. Destructuring that would throw a TypeError.
+		const entry = result?.[id];
+		if (entry) {
+			const { block, state } = entry;
+			// Record a read dependency only for a block that actually exists. A transactor may return a
+			// populated entry with `block: undefined` for a genuinely-missing block (TestTransactor does;
+			// the Network transactor always populates the key); recording there would add a phantom
+			// dependency for a nonexistent block. This makes the "absent reads nothing" contract uniform
+			// with the sparse-result case (entry omitted) — see transactor-source.spec.ts sparse test.
+			if (block) {
+				// Record read dependency for optimistic concurrency control, carrying the caller's
+				// read purpose (default `value`) so a purely-structural navigation read can later be
+				// dropped from the conflict set (see ReadDependencyCollector / Theorem 5).
+				const rev = state.latest?.rev ?? 0;
+				this.collector.record(id, rev, purpose);
+				this.readRevisions.set(id, rev);
+			}
 			// TODO: if the state reports that there is a pending action, record this so that we are sure to update before syncing
 			//state.pendings
 			return block as TBlock;
 		}
 	}
 
+	/** The revision observed the last time this source served {@link id} (from its committed
+	 *  state), or undefined if this source has never served it. CacheSource reads this on a
+	 *  miss-load to learn the revision to record and store. */
+	getReadRevision(id: BlockId): number | undefined {
+		return this.readRevisions.get(id);
+	}
+
 	getReadDependencies(): ReadDependency[] {
-		return this.readDependencies;
+		return this.collector.getReadDependencies();
 	}
 
 	clearReadDependencies(): void {
-		this.readDependencies = [];
+		this.collector.clear();
 	}
 
 	/**
@@ -55,10 +87,13 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 	 * is transitioning to a new block.  Ignored if the given headerId is not present in the transforms.
 	 * @param tailId - The Id of the collection's log tail block.  If specified, this block's transform is performed next
 	 * (prior to the rest of the block operations), to resolve the "winner" of a race to commit to the collection.
+	 * @param priority - Aged, advisory retry priority (default 0). Rides on the pend so a repeatedly-losing
+	 * single-collection sync out-ranks fresh rivals in a concurrent race (`resolveRace`); fairness-only, never
+	 * affects validity. Omitted from the pend when 0 so the common first-attempt pend serializes exactly as before.
 	 * @returns A promise that resolves to undefined if the action is successful, or a StaleFailure if the action is stale.
 	 */
-	async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId): Promise<undefined | StaleFailure> {
-		const pendResult = await this.transactor.pend({ transforms: transform, actionId, rev, policy: 'r' });
+	async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, priority = 0): Promise<undefined | StaleFailure> {
+		const pendResult = await this.transactor.pend({ transforms: transform, actionId, rev, policy: 'r', ...(priority > 0 ? { priority } : {}) });
 		if (!pendResult.success) {
 			return pendResult;
 		}

package/src/transform/atomic-proxy.ts

@@ -1,49 +1,92 @@
-import { Atomic } from './atomic.js';
-import type { IBlock, BlockId, BlockStore, BlockType, BlockHeader, BlockOperation } from '../index.js';
-
-/**
- * A BlockStore proxy that enables scoped atomic operations.
- * Operations normally delegate directly to the underlying store,
- * but during an `atomic()` call, they route through an Atomic tracker
- * that commits all-or-nothing on success, or rolls back on error.
- *
- * Both the BTree and its trunk should share the same AtomicProxy instance
- * so that all mutations (including root pointer updates) are part of the
- * same atomic batch.
- */
-export class AtomicProxy<T extends IBlock> implements BlockStore<T> {
-	private _base: BlockStore<T>;
-	private _active: BlockStore<T>;
-
-	constructor(store: BlockStore<T>) {
-		this._base = store;
-		this._active = store;
-	}
-
-	async tryGet(id: BlockId): Promise<T | undefined> { return this._active.tryGet(id); }
-	insert(block: T): void { this._active.insert(block); }
-	update(blockId: BlockId, op: BlockOperation): void { this._active.update(blockId, op); }
-	delete(blockId: BlockId): void { this._active.delete(blockId); }
-	generateId(): BlockId { return this._active.generateId(); }
-	createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader { return this._active.createBlockHeader(type, newId); }
-
-	/** Execute fn within an atomic scope. All store mutations are collected
-	 *  and committed on success, or discarded on error. Re-entrant safe. */
-	async atomic<R>(fn: () => Promise<R>): Promise<R> {
-		if (this._active !== this._base) {
-			return fn();	// Already in atomic context
-		}
-		const atomic = new Atomic<T>(this._base);
-		this._active = atomic;
-		try {
-			const result = await fn();
-			atomic.commit();
-			return result;
-		} catch (e) {
-			atomic.reset();
-			throw e;
-		} finally {
-			this._active = this._base;
-		}
-	}
-}
+import { Atomic } from './atomic.js';
+import type { IBlock, BlockId, BlockStore, BlockType, BlockHeader, BlockOperation, ReadPurpose } from '../index.js';
+
+/**
+ * Opaque handle to an in-flight atomic scope.
+ *
+ * A method that opens a scope (via {@link AtomicProxy.atomic}) receives the scope as its
+ * callback argument. To make a *nested* call reuse the enclosing scope — rather than open
+ * (and separately commit) a second one — pass that handle back as the `parent` argument of
+ * the nested `atomic()` call. This is how genuine nesting is distinguished from a second,
+ * unrelated concurrent scope, portably (no `AsyncLocalStorage`, which is Node-only).
+ */
+export interface AtomicScope { readonly __atomicScope: unique symbol; }
+
+/**
+ * A BlockStore proxy that enables scoped atomic operations.
+ * Operations normally delegate directly to the underlying store,
+ * but during an `atomic()` call, they route through an Atomic tracker
+ * that commits all-or-nothing on success, or rolls back on error.
+ *
+ * Both the BTree and its trunk should share the same AtomicProxy instance
+ * so that all mutations (including root pointer updates) are part of the
+ * same atomic batch.
+ *
+ * Concurrency model: top-level `atomic()` calls are *serialized* through a promise queue,
+ * so a second, un-awaited scope started while the first is still in flight waits for the
+ * first to commit/roll back before opening its own tracker — it never shares the first's
+ * tracker. A genuinely nested call (one that hands back its enclosing scope) bypasses the
+ * queue and reuses that scope, so it neither deadlocks on itself nor double-commits.
+ */
+export class AtomicProxy<T extends IBlock> implements BlockStore<T> {
+	private _base: BlockStore<T>;
+	private _active: BlockStore<T>;
+	/** Tail of the serialization queue; each new top-level scope awaits the prior one. */
+	private _tail: Promise<void> = Promise.resolve();
+	/** The scope currently executing, or undefined between scopes. Serialization guarantees
+	 *  at most one is active at a time, so identity against `parent` cleanly separates a
+	 *  nested call (parent === current) from a foreign concurrent one (parent absent/stale). */
+	private _current?: AtomicScope;
+
+	constructor(store: BlockStore<T>) {
+		this._base = store;
+		this._active = store;
+	}
+
+	async tryGet(id: BlockId, purpose?: ReadPurpose): Promise<T | undefined> { return this._active.tryGet(id, purpose); }
+	/** Forward a leaf-value upgrade to the active store (duck-typed; the Tracker/CacheSource chain
+	 *  implements it). Keeps navigation-read filtering working for a B-tree bound to this proxy. */
+	markReadValue(id: BlockId): void { (this._active as { markReadValue?: (id: BlockId) => void }).markReadValue?.(id); }
+	insert(block: T): void { this._active.insert(block); }
+	update(blockId: BlockId, op: BlockOperation): void { this._active.update(blockId, op); }
+	delete(blockId: BlockId): void { this._active.delete(blockId); }
+	generateId(): BlockId { return this._active.generateId(); }
+	createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader { return this._active.createBlockHeader(type, newId); }
+
+	/** Execute fn within an atomic scope. All store mutations are collected and committed on
+	 *  success, or discarded on error. `fn` receives a scope handle; pass it as the `parent`
+	 *  of any nested `atomic()` call that should join this scope instead of opening its own.
+	 *  Re-entrant safe (nesting reuses the parent scope) and concurrency safe (unrelated
+	 *  overlapping scopes serialize rather than sharing a tracker). */
+	async atomic<R>(fn: (scope: AtomicScope) => Promise<R>, parent?: AtomicScope): Promise<R> {
+		// Genuine nesting: the caller handed back the scope it is already inside. Reuse it —
+		// no second tracker, no second commit — and skip the queue, since waiting on the very
+		// scope we are running inside would deadlock.
+		if (parent !== undefined && parent === this._current) {
+			return fn(parent);
+		}
+		// Top-level scope (first, or a foreign call that overlapped one in flight): take a
+		// place in the serialization queue so it runs against its own tracker only after the
+		// prior scope has committed/rolled back.
+		const prior = this._tail;
+		let release!: () => void;
+		this._tail = new Promise<void>(resolve => { release = resolve; });
+		await prior;
+		const atomic = new Atomic<T>(this._base);
+		const scope = atomic as unknown as AtomicScope;
+		this._current = scope;
+		this._active = atomic;
+		try {
+			const result = await fn(scope);
+			atomic.commit();
+			return result;
+		} catch (e) {
+			atomic.reset();
+			throw e;
+		} finally {
+			this._active = this._base;
+			this._current = undefined;
+			release();
+		}
+	}
+}