@optimystic/db-core 0.14.0 → 0.16.2

package/src/collection/collection.ts

@@ -1,21 +1,31 @@
-import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms } from "../index.js";
+import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId } from "../index.js";
 import { Log, Atomic, Tracker, copyTransforms, CacheSource, isTransformsEmpty, TransactorSource } from "../index.js";
-import type { CollectionHeaderBlock, CollectionId, ICollection } from "./index.js";
+import type { CollectionHeaderBlock, CollectionId, ICollection, SyncOptions } from "./index.js";
+import { SyncRetryExhaustedError } from "./index.js";
 import type { ReadDependency } from "../transaction/transaction.js";
+import { clampPriority } from "../transaction/transaction.js";
+import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
 import { randomBytes } from '@noble/hashes/utils.js';
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
 import { Latches } from "../utility/latches.js";
+import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
 
+/** Default base backoff (and historical fixed delay) between sync retries, in ms. */
 const PendingRetryDelayMs = 100;
+/** Default max consecutive no-progress stale-failure retries before {@link Collection.sync} gives up. */
+const DefaultMaxAttempts = 10;
+/** Default ceiling on a single exponential-backoff sleep, in ms. */
+const DefaultMaxBackoffMs = 5000;
 
 export type CollectionInitOptions<TAction> = {
 	modules: Record<ActionType, ActionHandler<TAction>>;
 	createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => IBlock;
 	/** Called for each local action that is potentially in conflict with a remote action.
 	 * @param action - The local action to check
-	 * @param potential - The remote action that is potentially in conflict
-	 * @returns The original action, a replacement action (return a new instance; will be
-	 * 	applied through act()), or undefined to discard this action
+	 * @param potential - The remote actions that are potentially in conflict
+	 * @returns The original action (return the same instance to keep it as-is), a replacement
+	 * 	action (return a new instance to apply instead of the original — it is re-staged via
+	 * 	the conflict replay), or undefined to discard this action
 	 */
 	filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined
 }
@@ -48,9 +58,12 @@ export class Collection<TAction> implements ICollection<TAction> {
 	}
 
 	static async createOrOpen<TAction>(transactor: ITransactor, id: CollectionId, init: CollectionInitOptions<TAction>) {
-		// Start with a context that has an infinite revision number to ensure that we always fetch the latest log information
-		const source = new TransactorSource(id, transactor, undefined);
-		const sourceCache = new CacheSource(source);
+		// Start with a context that has an infinite revision number to ensure that we always fetch the latest log information.
+		// One shared read-dependency collector feeds both the source (direct structural reads) and the cache (every
+		// cache hit/miss), so a block read from either layer records a dependency — cache hits included.
+		const collector = new ReadDependencyCollector();
+		const source = new TransactorSource(id, transactor, undefined, collector);
+		const sourceCache = new CacheSource(source, undefined, collector);
 		const tracker = new Tracker(sourceCache);
 		const header = await source.tryGet(id) as CollectionHeaderBlock | undefined;
 
@@ -129,11 +142,22 @@ export class Collection<TAction> implements ICollection<TAction> {
 		// Process the entries and track the blocks they affect
 		let anyConflicts = false;
 		for (const entry of latest?.entries ?? []) {
-			// Filter any pending actions that conflict with the remote actions
-			this.pending = this.pending.map(p => this.doFilterConflict(p, entry.actions) ? p : undefined)
-				.filter(Boolean) as Action<TAction>[];
+			// Filter any pending actions that conflict with the remote actions. Each pending
+			// action maps to its effective form: the original, a replacement, or dropped.
+			const before = this.pending;
+			const after = before
+				.map(p => this.doFilterConflict(p, entry.actions))
+				.filter((a): a is Action<TAction> => a !== undefined);
+			// A replacement or a discard changes the pending set; the tracker still holds the
+			// pre-filter transforms, so force a replay to re-stage against the effective actions.
+			// Identity comparison per the contract: keep => same instance, replace => new instance.
+			// NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead
+			// of returning the same one forces a replay on every update — if that ever shows up as a
+			// hot path, compare by value/id here instead of by reference.
+			const mutated = after.length !== before.length || after.some((a, i) => a !== before[i]);
+			this.pending = after;
 			this.sourceCache.clear(entry.blockIds);
-			anyConflicts = anyConflicts || this.tracker.conflicts(new Set(entry.blockIds)).length > 0;
+			anyConflicts = anyConflicts || mutated || this.tracker.conflicts(new Set(entry.blockIds)).length > 0;
 		}
 
 		// React to durable invalidations that landed since we last synced. getFrom intentionally skips
@@ -223,26 +247,67 @@ export class Collection<TAction> implements ICollection<TAction> {
 	 * this, a collection that already had committed state (e.g. a pre-synced index
 	 * tree, or any collection on its second commit) keeps serving the stale prior
 	 * revision because {@link update} sees its rev is already current and refetches
-	 * nothing. Call BEFORE resetting the tracker (the transforms are read live). */
-	applyCommittedToCache(transforms: Transforms): void {
-		this.sourceCache.transformCache(transforms);
+	 * nothing. Call BEFORE resetting the tracker (the transforms are read live).
+	 *
+	 * @param revision - the committed revision these transforms land at (from
+	 * {@link recordCommitted}), so cached read-dependency revisions advance to it. */
+	applyCommittedToCache(transforms: Transforms, revision: number): void {
+		this.sourceCache.transformCache(transforms, revision);
+	}
+
+	/** Next revision this collection would commit at (current committed rev + 1). */
+	getNextRev(): number {
+		return (this.source.actionContext?.rev ?? 0) + 1;
+	}
+
+	/** Record a just-committed action: append its ActionRev to the committed list
+	 *  and advance the revision. Returns the new revision. Mirrors the inline bump
+	 *  in {@link syncInternal}. */
+	recordCommitted(actionId: ActionId): number {
+		const rev = this.getNextRev();
+		this.source.actionContext = {
+			committed: [...(this.source.actionContext?.committed ?? []), { actionId, rev }],
+			rev,
+		};
+		return rev;
 	}
 
 	/** Push our pending actions to the transactor */
-	async sync() {
+	async sync(options?: SyncOptions) {
 		const release = await Latches.acquire(this.latchId);
 		try {
-			await this.syncInternal();
+			await this.syncInternal(options);
 		} finally {
 			release();
 		}
 	}
 
-	private async syncInternal() {
+	private async syncInternal(options?: SyncOptions) {
 		const bytes = randomBytes(16);
 		const actionId = uint8ArrayToString(bytes, 'base64url');
 
+		const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
+		const baseBackoffMs = options?.baseBackoffMs ?? PendingRetryDelayMs;
+		const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
+		const deadlineMs = options?.deadlineMs;
+		const signal = options?.signal;
+		const startedAt = Date.now();
+
+		// Count of consecutive stale failures that made no forward progress. Reset to 0 on every
+		// successful transact, so the cap bounds only a persistently-failing sync — a legitimate
+		// large multi-batch sync (which iterates many times committing progress) never trips it.
+		let consecutiveFailures = 0;
+		let lastReason: string | undefined;
+
 		while (this.pending.length || !isTransformsEmpty(this.tracker.transforms)) {
+			if (signal?.aborted) {
+				throw makeAbortError(signal);
+			}
+			// Progress-agnostic ceiling: give up if the wall-clock deadline passed.
+			if (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs) {
+				throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason ?? 'deadline exceeded');
+			}
+
 			// Snapshot the pending actions so that any new actions aren't assumed to be part of this action
 			const pending = [...this.pending];
 
@@ -258,22 +323,46 @@ export class Collection<TAction> implements ICollection<TAction> {
 			const newRev = (this.source.actionContext?.rev ?? 0) + 1;
 			const addResult = await log.addActions(pending, actionId, newRev, () => tracker.transformedBlockIds());
 
-			// Commit the action to the transactor
-			const staleFailure = await this.source.transact(tracker.transforms, actionId, newRev, this.id, addResult.tailPath.block.header.id);
+			// Commit the action to the transactor. Carry the aged retry priority derived from the
+			// consecutive-failure count so a sync that keeps losing concurrent races out-ranks fresh
+			// (priority-0) rivals in the cluster's resolveRace (fairness-only; capped at MaxPriority).
+			// First attempt has consecutiveFailures == 0, so priority 0 — the common pend is unchanged.
+			const staleFailure = await this.source.transact(tracker.transforms, actionId, newRev, this.id, addResult.tailPath.block.header.id, clampPriority(consecutiveFailures));
 			if (staleFailure) {
-				if (staleFailure.pending) {
-					// Wait for short time to allow the pending actions to commit (bounded backoff)
-					await new Promise(resolve => setTimeout(resolve, PendingRetryDelayMs));
+				consecutiveFailures++;
+				lastReason = staleFailure.reason ?? lastReason;
+				// Give up once the consecutive no-progress budget is exhausted, so a transactor that
+				// persistently rejects the sync can no longer hold the collection latch forever.
+				// NOTE: this also bounds the legitimate `pending`-wait case (retrying the same action
+				// while another commit is in flight), which used to retry indefinitely. Default 10
+				// attempts ≈ 21s of exponential backoff. If a high-contention workload legitimately
+				// needs to wait longer for a pending commit to clear, raise maxAttempts for that caller.
+				if (consecutiveFailures >= maxAttempts) {
+					throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason);
 				}
+				// Back off before every retry (any stale failure — reason/missing/pending), growing
+				// exponentially from the base delay up to the cap, with proportional random jitter so a
+				// herd of clients that lost the same race does not re-collide on the next tick (see
+				// utility/backoff.ts). The abortable sleep lets an aborted sync reject promptly instead
+				// of finishing the sleep.
+				// NOTE: the `missing`/`reason` conflict paths now pay this backoff too (they previously
+				// retried with zero delay); that is what stops the persistent-`reason` hot spin. If a
+				// high-contention workload ever shows this base delay as recovery latency, lower
+				// baseBackoffMs for that caller rather than reintroducing the zero-delay retry.
+				const delay = jitteredBackoffMs(consecutiveFailures - 1, { baseMs: baseBackoffMs, capMs: maxBackoffMs }, options?.rand);
+				await abortableDelay(delay, signal);
 				// Fetch latest state - updateInternal() will call replayActions() if there are conflicts
 				await this.updateInternal();
 			} else {
+				// Forward progress: reset the no-progress budget.
+				consecutiveFailures = 0;
+				lastReason = undefined;
 				// Clear the pending actions that were part of this action
 				this.pending = this.pending.slice(pending.length);
 				// Reset cache and replay any actions that were added during the action
 				const transforms = tracker.reset();
 				await this.replayActions();
-				this.sourceCache.transformCache(transforms);
+				this.sourceCache.transformCache(transforms, newRev);
 				this.source.actionContext = this.source.actionContext
 					? { committed: [...this.source.actionContext.committed, { actionId, rev: newRev }], rev: newRev }
 					: { committed: [{ actionId, rev: newRev }], rev: newRev };
@@ -281,11 +370,11 @@ export class Collection<TAction> implements ICollection<TAction> {
 		}
 	}
 
-	async updateAndSync() {
+	async updateAndSync(options?: SyncOptions) {
 		const release = await Latches.acquire(this.latchId);
 		try {
 			await this.updateInternal();
-			await this.syncInternal();
+			await this.syncInternal(options);
 		} finally {
 			release();
 		}
@@ -298,7 +387,9 @@ export class Collection<TAction> implements ICollection<TAction> {
 		}
 		for await (const entry of log.select(undefined, forward)) {
 			if (entry.action) {
-				yield* forward ? entry.action.actions : entry.action.actions.reverse();
+				// NOTE: copy-then-reverse to avoid mutating the stored log entry array.
+				// Once tsconfig targets ES2023, `entry.action.actions.toReversed()` is cleaner.
+				yield* forward ? entry.action.actions : [...entry.action.actions].reverse();
 			}
 		}
 	}
@@ -321,20 +412,12 @@ export class Collection<TAction> implements ICollection<TAction> {
 
 	/** Called for each local action that may be in conflict with a remote action (always called under latch).
 	 * @param action - The local action to check
-	 * @param potential - The remote action that is potentially in conflict
-	 * @returns true if the action should be kept, false to discard it
+	 * @param potential - The remote actions that are potentially in conflict
+	 * @returns The effective action to keep: the original (unchanged), a replacement
+	 * 	instance (applied instead of the original), or undefined to discard it.
 	 */
-	protected doFilterConflict(action: Action<TAction>, potential: Action<TAction>[]) {
-		if (this.filterConflict) {
-			const replacement = this.filterConflict(action, potential);
-			if (!replacement) {
-				return false;
-			} else if (replacement !== action) {
-				// Queue replacement - it will be applied in replayActions()
-				this.pending.push(replacement);
-			}
-		}
-		return true;
+	protected doFilterConflict(action: Action<TAction>, potential: Action<TAction>[]): Action<TAction> | undefined {
+		return this.filterConflict ? this.filterConflict(action, potential) : action;
 	}
 
 	/** Bootstrap ActionContext from the committed tail block's state.

package/src/collection/struct.ts

@@ -1,16 +1,58 @@
 import type { IBlock, BlockId, Action } from "../index.js";
 import type { IChainHeader } from "../chain/chain-nodes.js";
+import type { RandFn } from "../utility/backoff.js";
 
 export type CollectionId = BlockId;
 
 export type CollectionHeaderBlock = IBlock & Partial<IChainHeader>;
 
+/** Bounds the retry loop inside {@link ICollection.sync} / {@link ICollection.updateAndSync}
+ * so a transactor that keeps rejecting the sync can no longer spin the collection latch forever.
+ * All fields are optional; unset fields fall back to conservative defaults. */
+export interface SyncOptions {
+	/** Max consecutive stale-failure retries that make no progress before giving up.
+	 * The counter resets to 0 on every successful commit, so a legitimate large multi-batch
+	 * sync (which iterates many times making forward progress) is never falsely tripped.
+	 * Default 10. */
+	maxAttempts?: number;
+	/** Optional wall-clock deadline in ms measured from the start of the sync call. Independent
+	 * of the attempt count — a progress-agnostic ceiling. Unset means no deadline. */
+	deadlineMs?: number;
+	/** Base backoff delay in ms applied before the first retry; subsequent retries grow the delay
+	 * exponentially up to {@link maxBackoffMs}. Default 100. */
+	baseBackoffMs?: number;
+	/** Upper bound on any single backoff sleep, in ms. Default 5000. */
+	maxBackoffMs?: number;
+	/** Optional abort signal. Checked at the top of each loop iteration and raced against the
+	 * backoff sleep, so an aborted sync rejects promptly (with an AbortError) rather than finishing
+	 * the current sleep. */
+	signal?: AbortSignal;
+	/** Advanced/testing hook: source of uniform [0,1) randomness for the backoff jitter. Defaults to
+	 * the package CSPRNG; inject a deterministic sequence to assert exact retry delays. */
+	rand?: RandFn;
+}
+
+/** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when the retry budget
+ * (attempt count or deadline) is exhausted while the transactor keeps returning stale failures.
+ * Catchable so callers can surface a clear "gave up syncing" condition instead of hanging. */
+export class SyncRetryExhaustedError extends Error {
+	constructor(
+		readonly collectionId: CollectionId,
+		readonly attempts: number,
+		readonly lastReason?: string,
+	) {
+		super(`sync for collection ${collectionId} exhausted ${attempts} retries` +
+			(lastReason ? `: ${lastReason}` : ''));
+		this.name = 'SyncRetryExhaustedError';
+	}
+}
+
 export interface ICollection<TAction> {
 	readonly id: CollectionId;
 	act(...actions: Action<TAction>[]): Promise<void>;
 	update(): Promise<void>;
-	sync(): Promise<void>;
-	updateAndSync(): Promise<void>;
+	sync(options?: SyncOptions): Promise<void>;
+	updateAndSync(options?: SyncOptions): Promise<void>;
 	selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
 }
 

package/src/collections/tree/tree.ts

@@ -36,20 +36,49 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 		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>> {
 		// Tricky bootstrapping here:
 		// We need the root id to initialize the collection header, so we create the btree in the create collection header callback.
 		let btree: BTree<TKey, TEntry> | undefined;
 		const init: CollectionInitOptions<TreeReplaceAction<TKey, TEntry>> = {
 			modules: {
-				"replace": async ({ data: actions }, _trx) => {
+				"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 btree!.upsert(entry);
+							await actionTree.upsert(entry);
 						} else {
-							await btree!.deleteAt((await btree!.find(key)));
+							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.
+					btree?.invalidatePaths();
 				}
 			},
 			createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => {	// Only called if the collection does not exist
@@ -57,7 +86,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 				btree = BTree.create<TKey, TEntry>(store, (_s, r) => {
 						rootId = r;
 						return new CollectionTrunk(store, id);
-					}, keyFromEntry, compare);
+					}, keyFromEntry, compare, nodeCapacity);
 				return {
 					header: store.createBlockHeader(TreeHeaderBlockType, id),
 					rootId: rootId!,
@@ -66,7 +95,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 		};
 
 		const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
-		btree = btree ?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare);
+		btree = btree ?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare, nodeCapacity);
 		return new Tree<TKey, TEntry>(collection, btree, keyFromEntry, compare);
 	}
 
@@ -137,6 +166,14 @@ export class Tree<TKey, TEntry> implements TreeReadView<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.

package/src/index.ts

@@ -20,3 +20,4 @@ export * from "./utility/ensured.js";
 export * from "./utility/pending.js";
 export * from "./utility/block-id-to-bytes.js";
 export * from "./utility/lru-map.js";
+export * from "./utility/backoff.js";

package/src/log/log.ts

@@ -10,12 +10,32 @@ import type { GetFromResult } from './struct.js';
 
 export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
 	& {
-		/** Base64url encoded Sha256 hash of the next block - present on every block except the head */
+		/** Base64url encoded Sha256 hash of the prior (predecessor) block - present on every block except the head */
 		priorHash?: string,
 	};
 
 export const priorHash$ = nameof<LogBlock<any>>("priorHash");
 
+/**
+ * Canonical byte payload covered by {@link LogBlock.priorHash}: every field of a log block EXCEPT
+ * the mutable structural links (`nextId`/`priorId`). Those links are rewritten *after* the hash is
+ * taken — `nextId` when the following block is appended ({@link Chain.add}), and `priorId`/`nextId`
+ * when blocks are removed ({@link Chain.pop}/{@link Chain.dequeue}) — so hashing the raw block would
+ * not match the bytes that end up stored. The content-bearing fields (`header`, `entries`,
+ * `priorHash`) are covered. Any verifier that re-hashes a stored block to check `priorHash` MUST
+ * reproduce exactly this payload (strip `nextId` and `priorId`; hash the rest).
+ *
+ * NOTE: the caller hashes `JSON.stringify` of this object, which is key-order dependent and not a
+ * canonical encoding. Fine today (blocks are built with a stable key order and the in-process store
+ * preserves it), but if a block is ever re-serialized by a store/codec that reorders keys or drops
+ * `undefined`s differently, a re-hash won't match the recorded priorHash — switch to a canonical
+ * encoding (sorted keys / dag-cbor) before that happens.
+ */
+export function logBlockHashPayload<TAction>(block: LogBlock<TAction>) {
+	const { nextId, priorId, ...covered } = block;
+	return covered;
+}
+
 export class Log<TAction> {
 	protected constructor(
 		private readonly chain: Chain<LogEntry<TAction>>,
@@ -151,8 +171,9 @@ export class Log<TAction> {
 
 	/** Gets the actions from startRev (exclusive), to latest in the log. */
 	async getFrom(startRev: number | undefined): Promise<GetFromResult<TAction>> {
-		const entries: ActionEntry<TAction>[] = [];
-		const pendings: ActionRev[] = [];
+		const entriesFromTail: ActionEntry<TAction>[] = [];
+		const pendingActions: ActionRev[] = [];
+		let checkpointPendings: ActionRev[] = [];
 		let rev: number | undefined;
 		let checkpointPath: ChainPath<LogEntry<TAction>> | undefined;
 		// Step through collecting both pending and entries until a checkpoint is found
@@ -161,7 +182,7 @@ export class Log<TAction> {
 			rev = rev ?? entry.rev;
 			if (entry.checkpoint) {
 				checkpointPath = path;
-				pendings.unshift(...entry.checkpoint.pendings);
+				checkpointPendings = entry.checkpoint.pendings;
 				break;
 			}
 			// Invalidation entries take a rev slot but are not pending actions — skip them in
@@ -169,24 +190,27 @@ export class Log<TAction> {
 			if (!entry.action) {
 				continue;
 			}
-			pendings.unshift({ actionId: entry.action.actionId, rev: entry.rev });
+			pendingActions.push({ actionId: entry.action.actionId, rev: entry.rev });
 			if (startRev !== undefined && entry.rev > startRev) {
-				entries.unshift(entry.action);
+				entriesFromTail.push(entry.action);
 			}	// Can't stop at rev, because we need to collect all pending actions for the context
 		}
 		// Continue stepping past the checkpoint until the given rev is reached
+		const entriesFromCheckpoint: ActionEntry<TAction>[] = [];
 		if (checkpointPath) {
 			for await (const path of this.chain.select(checkpointPath, false)) {
 				const entry = entryAt<LogEntry<TAction>>(path)!;
 				if (startRev !== undefined && entry.rev > startRev) {
 					if (entry.action) {
-						entries.unshift(entry.action!);
+						entriesFromCheckpoint.push(entry.action);
 					}
 				} else {
 					break;
 				}
 			}
 		}
+		const pendings = [...checkpointPendings, ...pendingActions.reverse()];
+		const entries = [...entriesFromCheckpoint.reverse(), ...entriesFromTail.reverse()];
 		return { context: rev ? { committed: pendings, rev } : undefined, entries };
 	}
 
@@ -224,13 +248,17 @@ export class Log<TAction> {
 		return pendings;
 	}
 
-	private static getChainOptions<TAction>(store: BlockStore<IBlock>) {
+	/** Chain options used by every log: block type factories plus the priorHash `newBlock` hook.
+	 *  Exposed (not private) so tests can drive a raw {@link Chain} through the exact same hook. */
+	static getChainOptions<TAction>(store: BlockStore<IBlock>) {
 		return {
 			createDataBlock: () => ({ header: store.createBlockHeader(LogDataBlockType) }),
 			createHeaderBlock: (id?: BlockId) => ({ header: store.createBlockHeader(LogHeaderBlockType, id) }),
 			newBlock: async (newTail: LogBlock<TAction>, oldTail: LogBlock<TAction> | undefined) => {
 				if (oldTail) {
-					const hash = await sha256.digest(new TextEncoder().encode(JSON.stringify(oldTail)));
+					// Hash the canonical payload (excludes the mutable nextId/priorId links) so the
+					// recorded priorHash matches a later re-hash of the stored predecessor block.
+					const hash = await sha256.digest(new TextEncoder().encode(JSON.stringify(logBlockHashPayload(oldTail))));
 					newTail.priorHash = uint8ArrayToString(hash.digest, 'base64url');
 				}
 			},

package/src/log/struct.ts

@@ -105,10 +105,11 @@ export type DisputeResolutionProof = {
 	 */
 	readonly challengerPeerId: string;
 	/**
-	 * The legitimately-selected arbitrator set — the K peer-ids the challenger computed via
-	 * `selectArbitrators` (the next K peers beyond the original cluster by XOR distance to the disputed
-	 * block). Every counted vote's `arbitratorPeerId` must be a member; the set is bound to the originator
-	 * by {@link arbitratorSetSignature} and, when feasible, re-derived from the verifying member's topology.
+	 * The legitimately-selected arbitrator set — the K peer-ids the challenger computed via `sampleArbitrators`
+	 * (verifiable dispersed sampling: the peers nearest K pseudo-random ring coordinates derived from
+	 * `hash(blockId ‖ round ‖ epoch ‖ i)`, spread across the whole keyspace rather than drawn from the disputed
+	 * block's neighborhood). Every counted vote's `arbitratorPeerId` must be a member; the set is bound to the
+	 * originator by {@link arbitratorSetSignature} and, when feasible, re-derived from the verifying member's topology.
 	 */
 	readonly arbitratorSet: ReadonlyArray<string>;
 	/**