@optimystic/db-core 0.21.0 → 0.24.0

package/src/utility/backoff.ts

@@ -1,95 +1,95 @@
-import { randomBytes } from '@noble/hashes/utils.js';
-
-/**
- * Jittered exponential backoff shared by the retry loops in db-core
- * ({@link Collection.sync} and {@link TransactionCoordinator.commit}).
- *
- * The point of the jitter is fairness under contention: when many clients lose the SAME
- * optimistic-concurrency race at t=0, a bare exponential curve makes them all re-attempt at the
- * identical next tick — a thundering herd that just re-collides. Multiplying the exponential value
- * by a random factor spreads those re-attempts across a window so offered load per tick sheds
- * instead of cascading. This is the same shape as `cohort-topic`'s `backoffRetryMs`, with the
- * proportional-jitter term added.
- */
-
-/** A source of uniform randomness in [0, 1). Injected in tests so a deterministic sequence can be
- * asserted; production uses {@link cryptoRand}. */
-export type RandFn = () => number;
-
-/** Uniform value in [0, 1) drawn from the same CSPRNG (`@noble/hashes` `randomBytes`) the rest of
- * db-core uses — deliberately NOT `Math.random`, so backoff jitter shares the package's randomness
- * source rather than introducing a second, weaker one. */
-export function cryptoRand(): number {
-	const b = randomBytes(4);
-	// Assemble a uint32 (>>> 0 clears the sign bit the shifts would otherwise set), then normalise.
-	const u = (((b[0]! << 24) | (b[1]! << 16) | (b[2]! << 8) | b[3]!) >>> 0);
-	return u / 0x1_0000_0000;
-}
-
-export interface JitteredBackoffConfig {
-	/** Base delay (ms) for attempt 0, before jitter. */
-	baseMs: number;
-	/** Hard ceiling (ms) on the pre-jitter exponential value. */
-	capMs: number;
-	/** Geometric growth per attempt. Default 2 (doubling). */
-	factor?: number;
-	/** Fraction of the exponential value that jitter may subtract, in [0, 1]. Default 0.5, so the
-	 * returned delay lands uniformly in `((1 - jitterFraction) · exp, exp]` — i.e. `(0.5·exp, exp]`. */
-	jitterFraction?: number;
-}
-
-/**
- * Delay (ms) for retry `attempt` (0-based):
- *
- *   exp   = min(baseMs · factor^attempt, capMs)
- *   delay = exp · (1 - jitterFraction · rand())     // rand() ∈ [0, 1)
- *
- * With the defaults (factor 2, jitterFraction 0.5) the delay is uniform in `(0.5·exp, exp]`: never
- * zero (as long as `baseMs > 0`) and never above `capMs`. `attempt` must be a non-negative integer
- * — pass `consecutiveFailures - 1` so the first retry backs off by ~`baseMs`.
- */
-export function jitteredBackoffMs(
-	attempt: number,
-	config: JitteredBackoffConfig,
-	rand: RandFn = cryptoRand,
-): number {
-	if (!Number.isInteger(attempt) || attempt < 0) {
-		throw new RangeError(`attempt must be a non-negative integer, got ${attempt}`);
-	}
-	const factor = config.factor ?? 2;
-	const jitterFraction = config.jitterFraction ?? 0.5;
-	const exp = Math.min(config.baseMs * factor ** attempt, config.capMs);
-	return exp * (1 - jitterFraction * rand());
-}
-
-/** Build an AbortError for a cooperatively-aborted wait. Prefers the signal's own reason when it is
- * an Error (so callers who passed a custom abort reason see it), otherwise a `name='AbortError'`
- * Error. */
-export function makeAbortError(signal?: AbortSignal): Error {
-	if (signal && signal.reason instanceof Error) {
-		return signal.reason;
-	}
-	const err = new Error('The operation was aborted');
-	err.name = 'AbortError';
-	return err;
-}
-
-/** Sleep for `ms`, resolving early (rejecting with an AbortError) if `signal` aborts — so a retry
- * loop waiting out a backoff rejects promptly instead of finishing the sleep. */
-export function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
-	return new Promise<void>((resolve, reject) => {
-		if (signal?.aborted) {
-			reject(makeAbortError(signal));
-			return;
-		}
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(makeAbortError(signal!));
-		};
-		const timer = setTimeout(() => {
-			signal?.removeEventListener('abort', onAbort);
-			resolve();
-		}, ms);
-		signal?.addEventListener('abort', onAbort, { once: true });
-	});
-}
+import { randomBytes } from '@noble/hashes/utils.js';
+
+/**
+ * Jittered exponential backoff shared by the retry loops in db-core
+ * ({@link Collection.sync} and {@link TransactionCoordinator.commit}).
+ *
+ * The point of the jitter is fairness under contention: when many clients lose the SAME
+ * optimistic-concurrency race at t=0, a bare exponential curve makes them all re-attempt at the
+ * identical next tick — a thundering herd that just re-collides. Multiplying the exponential value
+ * by a random factor spreads those re-attempts across a window so offered load per tick sheds
+ * instead of cascading. This is the same shape as `cohort-topic`'s `backoffRetryMs`, with the
+ * proportional-jitter term added.
+ */
+
+/** A source of uniform randomness in [0, 1). Injected in tests so a deterministic sequence can be
+ * asserted; production uses {@link cryptoRand}. */
+export type RandFn = () => number;
+
+/** Uniform value in [0, 1) drawn from the same CSPRNG (`@noble/hashes` `randomBytes`) the rest of
+ * db-core uses — deliberately NOT `Math.random`, so backoff jitter shares the package's randomness
+ * source rather than introducing a second, weaker one. */
+export function cryptoRand(): number {
+	const b = randomBytes(4);
+	// Assemble a uint32 (>>> 0 clears the sign bit the shifts would otherwise set), then normalise.
+	const u = (((b[0]! << 24) | (b[1]! << 16) | (b[2]! << 8) | b[3]!) >>> 0);
+	return u / 0x1_0000_0000;
+}
+
+export interface JitteredBackoffConfig {
+	/** Base delay (ms) for attempt 0, before jitter. */
+	baseMs: number;
+	/** Hard ceiling (ms) on the pre-jitter exponential value. */
+	capMs: number;
+	/** Geometric growth per attempt. Default 2 (doubling). */
+	factor?: number;
+	/** Fraction of the exponential value that jitter may subtract, in [0, 1]. Default 0.5, so the
+	 * returned delay lands uniformly in `((1 - jitterFraction) · exp, exp]` — i.e. `(0.5·exp, exp]`. */
+	jitterFraction?: number;
+}
+
+/**
+ * Delay (ms) for retry `attempt` (0-based):
+ *
+ *   exp   = min(baseMs · factor^attempt, capMs)
+ *   delay = exp · (1 - jitterFraction · rand())     // rand() ∈ [0, 1)
+ *
+ * With the defaults (factor 2, jitterFraction 0.5) the delay is uniform in `(0.5·exp, exp]`: never
+ * zero (as long as `baseMs > 0`) and never above `capMs`. `attempt` must be a non-negative integer
+ * — pass `consecutiveFailures - 1` so the first retry backs off by ~`baseMs`.
+ */
+export function jitteredBackoffMs(
+	attempt: number,
+	config: JitteredBackoffConfig,
+	rand: RandFn = cryptoRand,
+): number {
+	if (!Number.isInteger(attempt) || attempt < 0) {
+		throw new RangeError(`attempt must be a non-negative integer, got ${attempt}`);
+	}
+	const factor = config.factor ?? 2;
+	const jitterFraction = config.jitterFraction ?? 0.5;
+	const exp = Math.min(config.baseMs * factor ** attempt, config.capMs);
+	return exp * (1 - jitterFraction * rand());
+}
+
+/** Build an AbortError for a cooperatively-aborted wait. Prefers the signal's own reason when it is
+ * an Error (so callers who passed a custom abort reason see it), otherwise a `name='AbortError'`
+ * Error. */
+export function makeAbortError(signal?: AbortSignal): Error {
+	if (signal && signal.reason instanceof Error) {
+		return signal.reason;
+	}
+	const err = new Error('The operation was aborted');
+	err.name = 'AbortError';
+	return err;
+}
+
+/** Sleep for `ms`, resolving early (rejecting with an AbortError) if `signal` aborts — so a retry
+ * loop waiting out a backoff rejects promptly instead of finishing the sleep. */
+export function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise<void>((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(makeAbortError(signal));
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(makeAbortError(signal!));
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener('abort', onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener('abort', onAbort, { once: true });
+	});
+}

package/src/utility/batch-coordinator.ts

@@ -1,191 +1,191 @@
-import type { PeerId } from "../network/types.js";
-import type { BlockId } from "../index.js";
-import { Pending } from "./pending.js";
-import { createLogger } from "../logger.js";
-
-const log = createLogger('batch-coordinator');
-
-/**
- * Represents a batch of operations for a specific block coordinated by a peer
- */
-export type CoordinatorBatch<TPayload, TResponse> = {
-	peerId: PeerId;
-	blockId: BlockId;
-	payload: TPayload;
-	request?: Pending<TResponse>;
-	/** Whether this batch has been subsumed by other successful batches */
-	subsumedBy?: CoordinatorBatch<TPayload, TResponse>[];
-	/** Peers that have already been tried (and failed) */
-	excludedPeers?: PeerId[];
-	/** When a batch coordinates multiple blocks (via cluster intersection), lists all block IDs */
-	coordinatingBlockIds?: BlockId[];
-}
-
-/**
- * Creates batches for a given payload, grouped by the coordinating peer for each block id
- */
-export function makeBatchesByPeer<TPayload, TResponse>(
-	blockPeers: (readonly [BlockId, PeerId])[],
-	payload: TPayload,
-	getBlockPayload: (payload: TPayload, blockId: BlockId, mergeWithPayload: TPayload | undefined) => TPayload,
-	excludedPeers?: PeerId[]
-): CoordinatorBatch<TPayload, TResponse>[] {
-	const groups = blockPeers.reduce((acc, [blockId, peerId]) => {
-		const peerId_str = peerId.toString();
-		const coordinator = acc.get(peerId_str) ?? { peerId, blockId, excludedPeers } as Partial<CoordinatorBatch<TPayload, TResponse>>;
-		acc.set(peerId_str, { ...coordinator, payload: getBlockPayload(payload, blockId, coordinator.payload) } as CoordinatorBatch<TPayload, TResponse>);
-		return acc;
-	}, new Map<string, CoordinatorBatch<TPayload, TResponse>>());
-	return Array.from(groups.values());
-}
-
-/**
- * Iterates over all batches that have not completed, whether subsumed or not
- */
-export function* incompleteBatches<TPayload, TResponse>(batches: CoordinatorBatch<TPayload, TResponse>[]): IterableIterator<CoordinatorBatch<TPayload, TResponse>> {
-    const stack: CoordinatorBatch<TPayload, TResponse>[] = [...batches];
-    while (stack.length > 0) {
-        const batch = stack.pop()!;
-        if (!batch.request || !batch.request.isResponse) {
-            yield batch;
-        }
-        if (batch.subsumedBy && batch.subsumedBy.length) {
-            stack.push(...batch.subsumedBy);
-        }
-    }
-}
-
-/**
- * Checks if all completed batches (ignoring failures) satisfy a predicate
- */
-export function everyBatch<TPayload, TResponse>(batches: CoordinatorBatch<TPayload, TResponse>[], predicate: (batch: CoordinatorBatch<TPayload, TResponse>) => boolean): boolean {
-    // For each root batch require that SOME node in its retry tree satisfies the predicate.
-    // Use iterative DFS to avoid recursion depth and minimize allocations.
-    for (const root of batches) {
-        let found = false;
-        const stack: CoordinatorBatch<TPayload, TResponse>[] = [root];
-        while (stack.length > 0) {
-            const node = stack.pop()!;
-            if (predicate(node)) { found = true; break; }
-            if (node.subsumedBy && node.subsumedBy.length) {
-                for (let i = 0; i < node.subsumedBy.length; i++) stack.push(node.subsumedBy[i]!);
-            }
-        }
-        if (!found) return false;
-    }
-    return true;
-}
-
-/**
- * Iterates over all batches that satisfy an optional predicate, whether subsumed or not
- */
-export function* allBatches<TPayload, TResponse>(batches: CoordinatorBatch<TPayload, TResponse>[], predicate?: (batch: CoordinatorBatch<TPayload, TResponse>) => boolean): IterableIterator<CoordinatorBatch<TPayload, TResponse>> {
-    const stack: CoordinatorBatch<TPayload, TResponse>[] = [...batches];
-    while (stack.length > 0) {
-        const batch = stack.pop()!;
-        if (!predicate || predicate(batch)) {
-            yield batch;
-        }
-        if (batch.subsumedBy && batch.subsumedBy.length) {
-            stack.push(...batch.subsumedBy);
-        }
-    }
-}
-
-/**
- * Returns a new blockId list payload with the given block id appended
- */
-export function mergeBlocks(_payload: BlockId[], blockId: BlockId, mergeWithPayload: BlockId[] | undefined): BlockId[] {
-	return [...(mergeWithPayload ?? []), blockId];
-}
-
-/**
- * Processes a set of batches, retrying any failures until success or expiration
- * @param batches - The batches to process - each represents a group of blocks centered on a coordinating peer
- * @param process - The function to call for a given batch
- * @param getBlockIds - The function to call to get the block ids for a given batch
- * @param getBlockPayload - The function to call to get the payload given a parent payload and block id, and optionally merge with an existing payload
- * @param expiration - The expiration time for the operation
- * @param findCoordinator - The function to call to find a coordinator for a block id
- */
-export async function processBatches<TPayload, TResponse>(
-	batches: CoordinatorBatch<TPayload, TResponse>[],
-	process: (batch: CoordinatorBatch<TPayload, TResponse>) => Promise<TResponse>,
-	getBlockIds: (batch: CoordinatorBatch<TPayload, TResponse>) => BlockId[],
-	getBlockPayload: (payload: TPayload, blockId: BlockId, mergeWithPayload: TPayload | undefined) => TPayload,
-	expiration: number,
-	findCoordinator: (blockId: BlockId, options: { excludedPeers: PeerId[] }) => Promise<PeerId>
-): Promise<void> {
-    // Root-map ensures retries are recorded on the original batch to avoid deep trees
-    const rootOf = new WeakMap<CoordinatorBatch<TPayload, TResponse>, CoordinatorBatch<TPayload, TResponse>>();
-    for (const b of batches) rootOf.set(b, b);
-
-    // Process a set of batches concurrently and enqueue retries flatly onto the root's subsumedBy list
-    const processSet = async (set: CoordinatorBatch<TPayload, TResponse>[]) => {
-        await Promise.all(set.map(async (batch) => {
-            batch.request = new Pending(process(batch)
-                .catch(async e => {
-                    // Always rethrow the ORIGINAL first-attempt error `e` so batch.request.error
-                    // preserves the root cause. If retry setup itself fails (e.g., findCoordinator
-                    // throws "self-exhausted" on a solo node), that retry error MUST NOT mask `e`.
-                    if (expiration > Date.now()) {
-                        const excludedPeers = [batch.peerId, ...(batch.excludedPeers ?? [])];
-                        log('retry peer=%s excluded=%d', batch.peerId.toString(), excludedPeers.length);
-                        try {
-                            const retries = await createBatchesForPayload<TPayload, TResponse>(
-                                getBlockIds(batch),
-                                batch.payload,
-                                getBlockPayload,
-                                excludedPeers,
-                                findCoordinator
-                            );
-                            if (retries.length > 0 && expiration > Date.now()) {
-                                const root = rootOf.get(batch) ?? batch;
-                                root.subsumedBy = [...(root.subsumedBy ?? []), ...retries];
-                                for (const r of retries) rootOf.set(r, root);
-                                // Process retries, but ensure further failures also attach to the same root
-                                await processSet(retries);
-                            }
-                        } catch (retryErr) {
-                            log('retry:setup-failed peer=%s original=%o retry=%o',
-                                batch.peerId.toString(), e, retryErr);
-                            // Swallow retryErr; the original `e` is authoritative.
-                        }
-                    }
-                    throw e;
-                }));
-        }));
-
-        // Wait for all in this set to settle
-        await Promise.all(set.map(b => b.request?.result().catch(() => { /* ignore */ })));
-    };
-
-    await processSet(batches);
-}
-
-/**
- * Creates batches for a given payload, grouped by the coordinating peer for each block id
- * This is a placeholder function that will be implemented by the caller
- */
-export async function createBatchesForPayload<TPayload, TResponse>(
-	blockIds: BlockId[],
-	payload: TPayload,
-	getBlockPayload: (payload: TPayload, blockId: BlockId, mergeWithPayload: TPayload | undefined) => TPayload,
-	excludedPeers: PeerId[],
-	findCoordinator: (blockId: BlockId, options: { excludedPeers: PeerId[] }) => Promise<PeerId>
-): Promise<CoordinatorBatch<TPayload, TResponse>[]> {
-	// Group by block id
-	const distinctBlockIds = new Set(blockIds);
-
-	// Find coordinator for each key
-	const blockIdPeerId = await Promise.all(
-		Array.from(distinctBlockIds).map(async (bid) =>
-			[bid, await findCoordinator(bid, { excludedPeers })] as const
-		)
-	);
-
-	// Group blocks around their coordinating peers
-	const batches = makeBatchesByPeer<TPayload, TResponse>(blockIdPeerId, payload, getBlockPayload, excludedPeers);
-	log('createBatches blockIds=%d batches=%d excluded=%d', distinctBlockIds.size, batches.length, excludedPeers.length);
-	return batches;
-}
+import type { PeerId } from "../network/types.js";
+import type { BlockId } from "../index.js";
+import { Pending } from "./pending.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('batch-coordinator');
+
+/**
+ * Represents a batch of operations for a specific block coordinated by a peer
+ */
+export type CoordinatorBatch<TPayload, TResponse> = {
+	peerId: PeerId;
+	blockId: BlockId;
+	payload: TPayload;
+	request?: Pending<TResponse>;
+	/** Whether this batch has been subsumed by other successful batches */
+	subsumedBy?: CoordinatorBatch<TPayload, TResponse>[];
+	/** Peers that have already been tried (and failed) */
+	excludedPeers?: PeerId[];
+	/** When a batch coordinates multiple blocks (via cluster intersection), lists all block IDs */
+	coordinatingBlockIds?: BlockId[];
+}
+
+/**
+ * Creates batches for a given payload, grouped by the coordinating peer for each block id
+ */
+export function makeBatchesByPeer<TPayload, TResponse>(
+	blockPeers: (readonly [BlockId, PeerId])[],
+	payload: TPayload,
+	getBlockPayload: (payload: TPayload, blockId: BlockId, mergeWithPayload: TPayload | undefined) => TPayload,
+	excludedPeers?: PeerId[]
+): CoordinatorBatch<TPayload, TResponse>[] {
+	const groups = blockPeers.reduce((acc, [blockId, peerId]) => {
+		const peerId_str = peerId.toString();
+		const coordinator = acc.get(peerId_str) ?? { peerId, blockId, excludedPeers } as Partial<CoordinatorBatch<TPayload, TResponse>>;
+		acc.set(peerId_str, { ...coordinator, payload: getBlockPayload(payload, blockId, coordinator.payload) } as CoordinatorBatch<TPayload, TResponse>);
+		return acc;
+	}, new Map<string, CoordinatorBatch<TPayload, TResponse>>());
+	return Array.from(groups.values());
+}
+
+/**
+ * Iterates over all batches that have not completed, whether subsumed or not
+ */
+export function* incompleteBatches<TPayload, TResponse>(batches: CoordinatorBatch<TPayload, TResponse>[]): IterableIterator<CoordinatorBatch<TPayload, TResponse>> {
+    const stack: CoordinatorBatch<TPayload, TResponse>[] = [...batches];
+    while (stack.length > 0) {
+        const batch = stack.pop()!;
+        if (!batch.request || !batch.request.isResponse) {
+            yield batch;
+        }
+        if (batch.subsumedBy && batch.subsumedBy.length) {
+            stack.push(...batch.subsumedBy);
+        }
+    }
+}
+
+/**
+ * Checks if all completed batches (ignoring failures) satisfy a predicate
+ */
+export function everyBatch<TPayload, TResponse>(batches: CoordinatorBatch<TPayload, TResponse>[], predicate: (batch: CoordinatorBatch<TPayload, TResponse>) => boolean): boolean {
+    // For each root batch require that SOME node in its retry tree satisfies the predicate.
+    // Use iterative DFS to avoid recursion depth and minimize allocations.
+    for (const root of batches) {
+        let found = false;
+        const stack: CoordinatorBatch<TPayload, TResponse>[] = [root];
+        while (stack.length > 0) {
+            const node = stack.pop()!;
+            if (predicate(node)) { found = true; break; }
+            if (node.subsumedBy && node.subsumedBy.length) {
+                for (let i = 0; i < node.subsumedBy.length; i++) stack.push(node.subsumedBy[i]!);
+            }
+        }
+        if (!found) return false;
+    }
+    return true;
+}
+
+/**
+ * Iterates over all batches that satisfy an optional predicate, whether subsumed or not
+ */
+export function* allBatches<TPayload, TResponse>(batches: CoordinatorBatch<TPayload, TResponse>[], predicate?: (batch: CoordinatorBatch<TPayload, TResponse>) => boolean): IterableIterator<CoordinatorBatch<TPayload, TResponse>> {
+    const stack: CoordinatorBatch<TPayload, TResponse>[] = [...batches];
+    while (stack.length > 0) {
+        const batch = stack.pop()!;
+        if (!predicate || predicate(batch)) {
+            yield batch;
+        }
+        if (batch.subsumedBy && batch.subsumedBy.length) {
+            stack.push(...batch.subsumedBy);
+        }
+    }
+}
+
+/**
+ * Returns a new blockId list payload with the given block id appended
+ */
+export function mergeBlocks(_payload: BlockId[], blockId: BlockId, mergeWithPayload: BlockId[] | undefined): BlockId[] {
+	return [...(mergeWithPayload ?? []), blockId];
+}
+
+/**
+ * Processes a set of batches, retrying any failures until success or expiration
+ * @param batches - The batches to process - each represents a group of blocks centered on a coordinating peer
+ * @param process - The function to call for a given batch
+ * @param getBlockIds - The function to call to get the block ids for a given batch
+ * @param getBlockPayload - The function to call to get the payload given a parent payload and block id, and optionally merge with an existing payload
+ * @param expiration - The expiration time for the operation
+ * @param findCoordinator - The function to call to find a coordinator for a block id
+ */
+export async function processBatches<TPayload, TResponse>(
+	batches: CoordinatorBatch<TPayload, TResponse>[],
+	process: (batch: CoordinatorBatch<TPayload, TResponse>) => Promise<TResponse>,
+	getBlockIds: (batch: CoordinatorBatch<TPayload, TResponse>) => BlockId[],
+	getBlockPayload: (payload: TPayload, blockId: BlockId, mergeWithPayload: TPayload | undefined) => TPayload,
+	expiration: number,
+	findCoordinator: (blockId: BlockId, options: { excludedPeers: PeerId[] }) => Promise<PeerId>
+): Promise<void> {
+    // Root-map ensures retries are recorded on the original batch to avoid deep trees
+    const rootOf = new WeakMap<CoordinatorBatch<TPayload, TResponse>, CoordinatorBatch<TPayload, TResponse>>();
+    for (const b of batches) rootOf.set(b, b);
+
+    // Process a set of batches concurrently and enqueue retries flatly onto the root's subsumedBy list
+    const processSet = async (set: CoordinatorBatch<TPayload, TResponse>[]) => {
+        await Promise.all(set.map(async (batch) => {
+            batch.request = new Pending(process(batch)
+                .catch(async e => {
+                    // Always rethrow the ORIGINAL first-attempt error `e` so batch.request.error
+                    // preserves the root cause. If retry setup itself fails (e.g., findCoordinator
+                    // throws "self-exhausted" on a solo node), that retry error MUST NOT mask `e`.
+                    if (expiration > Date.now()) {
+                        const excludedPeers = [batch.peerId, ...(batch.excludedPeers ?? [])];
+                        log('retry peer=%s excluded=%d', batch.peerId.toString(), excludedPeers.length);
+                        try {
+                            const retries = await createBatchesForPayload<TPayload, TResponse>(
+                                getBlockIds(batch),
+                                batch.payload,
+                                getBlockPayload,
+                                excludedPeers,
+                                findCoordinator
+                            );
+                            if (retries.length > 0 && expiration > Date.now()) {
+                                const root = rootOf.get(batch) ?? batch;
+                                root.subsumedBy = [...(root.subsumedBy ?? []), ...retries];
+                                for (const r of retries) rootOf.set(r, root);
+                                // Process retries, but ensure further failures also attach to the same root
+                                await processSet(retries);
+                            }
+                        } catch (retryErr) {
+                            log('retry:setup-failed peer=%s original=%o retry=%o',
+                                batch.peerId.toString(), e, retryErr);
+                            // Swallow retryErr; the original `e` is authoritative.
+                        }
+                    }
+                    throw e;
+                }));
+        }));
+
+        // Wait for all in this set to settle
+        await Promise.all(set.map(b => b.request?.result().catch(() => { /* ignore */ })));
+    };
+
+    await processSet(batches);
+}
+
+/**
+ * Creates batches for a given payload, grouped by the coordinating peer for each block id
+ * This is a placeholder function that will be implemented by the caller
+ */
+export async function createBatchesForPayload<TPayload, TResponse>(
+	blockIds: BlockId[],
+	payload: TPayload,
+	getBlockPayload: (payload: TPayload, blockId: BlockId, mergeWithPayload: TPayload | undefined) => TPayload,
+	excludedPeers: PeerId[],
+	findCoordinator: (blockId: BlockId, options: { excludedPeers: PeerId[] }) => Promise<PeerId>
+): Promise<CoordinatorBatch<TPayload, TResponse>[]> {
+	// Group by block id
+	const distinctBlockIds = new Set(blockIds);
+
+	// Find coordinator for each key
+	const blockIdPeerId = await Promise.all(
+		Array.from(distinctBlockIds).map(async (bid) =>
+			[bid, await findCoordinator(bid, { excludedPeers })] as const
+		)
+	);
+
+	// Group blocks around their coordinating peers
+	const batches = makeBatchesByPeer<TPayload, TResponse>(blockIdPeerId, payload, getBlockPayload, excludedPeers);
+	log('createBatches blockIds=%d batches=%d excluded=%d', distinctBlockIds.size, batches.length, excludedPeers.length);
+	return batches;
+}

package/dist/src/transaction/context.d.ts

@@ -1,60 +0,0 @@
-import type { CollectionId } from "../index.js";
-import type { TransactionCoordinator } from "./coordinator.js";
-import type { ReadDependency, ExecutionResult } from "./transaction.js";
-import type { Action } from "../collection/action.js";
-/**
- * Transaction context for accumulating actions and reads.
- *
- * Usage:
- *   const txn = coordinator.begin();
- *   txn.addAction('users', { type: 'insert', data: {...} });
- *   txn.addAction('users', { type: 'get', data: { key: 1 } });
- *   const result = await txn.commit();
- */
-export declare class TransactionContext {
-    private readonly coordinator;
-    readonly transactionId: string;
-    readonly engine: string;
-    private readonly collectionActions;
-    private readonly reads;
-    constructor(coordinator: TransactionCoordinator, transactionId: string, engine: string);
-    /**
-     * Add an action to a collection.
-     *
-     * Actions are collection-specific:
-     * - Tree: 'insert', 'delete', 'get', 'scan'
-     * - Diary: 'append', 'read'
-     * - etc.
-     */
-    addAction(collectionId: CollectionId, action: Action<any>): Promise<void>;
-    /**
-     * Add a read dependency for optimistic concurrency control.
-     */
-    addRead(read: ReadDependency): void;
-    /**
-     * Commit the transaction.
-     *
-     * This executes all accumulated actions across all affected collections,
-     * coordinating with the network as needed.
-     */
-    commit(): Promise<ExecutionResult>;
-    /**
-     * Rollback the transaction (just discard accumulated state).
-     */
-    rollback(): void;
-    /**
-     * Get all accumulated actions by collection.
-     * Used by coordinator during commit.
-     */
-    getCollectionActions(): Map<CollectionId, Action<any>[]>;
-    /**
-     * Get all accumulated read dependencies.
-     * Used by coordinator during commit.
-     */
-    getReads(): ReadDependency[];
-    /**
-     * Get the set of affected collection IDs.
-     */
-    getAffectedCollections(): Set<CollectionId>;
-}
-//# sourceMappingURL=context.d.ts.map

package/dist/src/transaction/context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/transaction/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAK7B,OAAO,CAAC,QAAQ,CAAC,WAAW;aACZ,aAAa,EAAE,MAAM;aACrB,MAAM,EAAE,MAAM;IAN/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA+C;IACjF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;gBAG5B,WAAW,EAAE,sBAAsB,EACpC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM;IAG/B;;;;;;;OAOG;IACG,SAAS,CAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB/E;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAInC;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC;IAIxC;;OAEG;IACH,QAAQ,IAAI,IAAI;IAKhB;;;OAGG;IACH,oBAAoB,IAAI,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAIxD;;;OAGG;IACH,QAAQ,IAAI,cAAc,EAAE;IAI5B;;OAEG;IACH,sBAAsB,IAAI,GAAG,CAAC,YAAY,CAAC;CAG3C"}