@optimystic/db-p2p 0.14.1 → 0.16.2

package/src/dispute/arbitrator-selection.ts

@@ -1,28 +1,138 @@
-import type { PeerId } from '@libp2p/interface';
-import { sortPeersByDistance, type KnownPeer } from '../routing/responsibility.js';
-
-/**
- * Select arbitrators for a dispute using XOR-distance from the block ID.
- * Selects the next K peers beyond the original cluster (positions K+1 through 2K).
- * This ensures independence (arbitrators are not in the original cluster)
- * and determinism (all parties agree on who arbitrates).
- */
-export function selectArbitrators(
-	allPeers: KnownPeer[],
-	blockIdBytes: Uint8Array,
-	excludePeerIds: Set<string>,
-	count: number,
-): PeerId[] {
-	// Sort all peers by XOR distance to the block ID
-	const sorted = sortPeersByDistance(allPeers, blockIdBytes);
-
-	// Skip peers in the original cluster (and self), select the next K
-	const arbitrators: PeerId[] = [];
-	for (const peer of sorted) {
-		if (arbitrators.length >= count) break;
-		if (excludePeerIds.has(peer.id.toString())) continue;
-		arbitrators.push(peer.id);
-	}
-
-	return arbitrators;
-}
+/**
+ * Verifiable dispersed arbitrator sampling.
+ *
+ * The old selection walked the ring positions *immediately adjacent* to the disputed block (sort every
+ * peer by XOR distance to `hash(blockId)`, skip the original cluster, take the next K). That recruits
+ * from exactly the neighborhood an attacker already had to own to capture the block's cluster — so
+ * "independent" arbitration drew from the *least* independent population (see `docs/correctness.md` §7.1
+ * Sybil, Theorems 8 & 10).
+ *
+ * Instead we derive `count` pseudo-random ring coordinates from `hash(blockId ‖ round ‖ epoch ‖ i)` and
+ * pick the peer nearest each coordinate. SHA-256 output is uniform over the ring, so the coordinates land
+ * spread across the whole keyspace and the sampled arbitrators are drawn from the whole population, not
+ * the block's neighborhood. To capture them an attacker needs IDs near many independent random points —
+ * a fraction of the *entire* network, not one locale.
+ *
+ * Two properties both hold:
+ *  - **Deterministic & independently verifiable** — every honest node, given the same
+ *    `(blockId, round, epoch)` and the same agreed membership, computes the identical set. This is what
+ *    lets the dispute verify path re-derive the eligible set instead of trusting a declared one.
+ *  - **Unpredictable / not pre-positionable** — the coordinates for round r are pinned only once
+ *    `(blockId, round, epoch)` are all fixed. `round` advances in real time during the dispute; `epoch`
+ *    is the agreed membership epoch, which rotates with membership and cannot be freely advanced by the
+ *    attacker. So the attacker cannot know far enough ahead which coordinates to migrate IDs toward.
+ */
+
+/**
+ * Resolve the peer-id strings nearest a ring coordinate, in ascending distance order.
+ * Production: FRET `assembleCohort(coord, wants)`. Tests: sort a fixed `KnownPeer[]` by XOR distance.
+ * May return fewer than `wants` — that signals the whole eligible membership fit in the slice.
+ */
+export type NearestResolver = (coord: Uint8Array, wants: number) => string[] | Promise<string[]>;
+
+/** FRET-compatible ring hash of arbitrary bytes → coordinate (SHA-256; see db-core `RingHash.H` / FRET `hashKey`). */
+export type RingHashFn = (bytes: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+
+export interface ArbitratorSamplingParams {
+	/** Disputed block id bytes (messageHash fallback), as bound into the dispute. */
+	readonly blockId: Uint8Array;
+	/** Escalation round, 0-based. Round 0 is the first arbitration. */
+	readonly round: number;
+	/**
+	 * Agreed membership epoch bytes. Pins the draw to an epoch the attacker cannot freely advance.
+	 * Interim source (until `design-cluster-membership-agreement` lands): hash of the agreed responsible
+	 * set the admission gate already converges on (`cluster-membership-admission-gate`).
+	 */
+	readonly epoch: Uint8Array;
+	/** Number of fresh, distinct arbitrators to draw this round. */
+	readonly count: number;
+	/** Peer-id strings to exclude: original cluster + self + arbitrators already drawn in prior rounds. */
+	readonly exclude: ReadonlySet<string>;
+}
+
+/** Little-endian u32 encoding of `n` — the canonical wire encoding for `round` and the coordinate index. */
+function u32le(n: number): Uint8Array {
+	const out = new Uint8Array(4);
+	new DataView(out.buffer).setUint32(0, n >>> 0, true);
+	return out;
+}
+
+/** Concatenate byte spans left-to-right. */
+function concatBytes(parts: Uint8Array[]): Uint8Array {
+	let total = 0;
+	for (const p of parts) total += p.length;
+	const out = new Uint8Array(total);
+	let off = 0;
+	for (const p of parts) { out.set(p, off); off += p.length; }
+	return out;
+}
+
+/**
+ * The exact preimage the i-th coordinate of a round hashes: `blockId ‖ u32le(round) ‖ epoch ‖ u32le(i)`.
+ * Folding `round`, `epoch`, and `i` in gives: (a) each round samples a distinct population (round changes
+ * every coordinate); (b) each of the `count` coordinates is an independent uniform draw (dispersion);
+ * (c) a replacement for an offline/duplicate pick is the *next* peer in the same coordinate's ordering,
+ * never a fresh challenger-chosen peer. The canonical little-endian encoding is asserted by a golden
+ * vector so two implementations hash identical bytes.
+ */
+export function coordinatePreimage(blockId: Uint8Array, round: number, epoch: Uint8Array, i: number): Uint8Array {
+	return concatBytes([blockId, u32le(round), epoch, u32le(i)]);
+}
+
+/**
+ * Deterministic dispersed arbitrator draw. Returns up to `count` distinct peer-id strings; fewer only
+ * when the network is too small to yield that many (small-network fallback) — never duplicates, never
+ * loops. In the degenerate all-peers-in-cluster case, returns `[]`.
+ *
+ * For each coordinate `i` the nearest unseen peer is chosen. When a coordinate's nearest slice is
+ * entirely `seen` (excluded, or already picked for an earlier coordinate) the slice is widened
+ * (`wants` grows) and retried; if widening exposes the whole eligible membership with nobody fresh, the
+ * entire membership is exhausted and the (short) picks are returned. Replacement of an offline/duplicate
+ * pick is thus the deterministic next peer in the same coordinate's ordering, identical on every honest
+ * node, so disputing parties cannot steer it.
+ */
+export async function sampleArbitrators(
+	params: ArbitratorSamplingParams,
+	nearest: NearestResolver,
+	hash: RingHashFn,
+): Promise<string[]> {
+	const { blockId, round, epoch, count, exclude } = params;
+	const picks: string[] = [];
+	if (count <= 0) return picks;
+
+	const seen = new Set<string>(exclude);
+
+	for (let i = 0; picks.length < count; i++) {
+		const coord = await hash(coordinatePreimage(blockId, round, epoch, i));
+
+		// Walk this coordinate's ascending-distance ordering for the first peer we have not yet seen,
+		// widening the slice until we find one or have proven the whole eligible membership is exhausted.
+		// NOTE: `wants` starts at `seen.size + 1` (conservative — guarantees exhaustion is provable in one
+		// widen). Starting at 1 and widening only on a seen-collision is also correct and asks the resolver
+		// for far fewer peers per coordinate; if `assembleCohort` ever shows up as hot here, start smaller.
+		let wants = seen.size + 1;
+		let prevLen = -1;
+		let picked: string | undefined;
+		let membershipExhausted = false;
+		for (;;) {
+			const cands = await nearest(coord, wants);
+			const fresh = cands.find(c => !seen.has(c));
+			if (fresh !== undefined) { picked = fresh; break; }
+			// No fresh peer in this slice. If the resolver returned fewer than we asked (or the slice
+			// stopped growing), we have seen the whole eligible membership from this coordinate — and
+			// since every one of them is already `seen`, no future coordinate can yield anything new.
+			if (cands.length < wants || cands.length <= prevLen) { membershipExhausted = true; break; }
+			prevLen = cands.length;
+			wants *= 2;
+		}
+
+		if (picked !== undefined) {
+			picks.push(picked);
+			seen.add(picked);
+		} else if (membershipExhausted) {
+			break;
+		}
+	}
+
+	return picks;
+}

package/src/dispute/cascade.ts

@@ -40,6 +40,13 @@ export type CollectionEnv = {
 	readonly collectionId: CollectionId;
 	readonly log: Log<unknown>;
 	readonly createBlockStorage: (blockId: BlockId) => IBlockStorage;
+	/**
+	 * Optional per-block commit-latch runner threaded into each cascade child's {@link applyInvalidation}
+	 * so the child's compensating write serializes against a concurrent commit on the same block — the
+	 * same mutual-exclusion the root apply gets (see `InvalidationContext.withBlockCommitLatch`). Omitted
+	 * → child writes run unlatched (today's behavior).
+	 */
+	readonly withBlockCommitLatch?: <T>(blockId: BlockId, fn: () => Promise<T>) => Promise<T>;
 };
 
 // ─── Invalidated (blockId, revision) pairs ───
@@ -347,7 +354,7 @@ export async function cascadeInvalidate(input: CascadeInput): Promise<CascadeRes
 
 			const env = cand.env;
 			const result = await applyInvalidation(
-				{ log: env.log, createBlockStorage: env.createBlockStorage },
+				{ log: env.log, createBlockStorage: env.createBlockStorage, withBlockCommitLatch: env.withBlockCommitLatch },
 				{
 					invalidatedActionId: cand.actionId,
 					invalidatedRev: cand.rev,

package/src/dispute/client.ts

@@ -1,6 +1,7 @@
 import type { PeerId, IPeerNetwork } from '@optimystic/db-core';
 import { ProtocolClient } from '../protocol-client.js';
 import { DEFAULT_DIAL_TIMEOUT_MS, withRpcDeadlineDefaults, type RpcDeadlineOptions } from '../rpc-deadline.js';
+import { MAX_CONTROL_MESSAGE_BYTES } from '../protocol-limits.js';
 import type { DisputeChallenge, DisputeResolution, ArbitrationVote, DisputeMessage } from './types.js';
 
 /**
@@ -32,7 +33,7 @@ export class DisputeClient extends ProtocolClient {
 		const response = await this.processMessage<{ type: 'vote'; vote: ArbitrationVote }>(
 			message,
 			this.protocol,
-			{ signal, dialTimeoutMs: DEFAULT_DIAL_TIMEOUT_MS }
+			{ signal, dialTimeoutMs: DEFAULT_DIAL_TIMEOUT_MS, maxDataLength: MAX_CONTROL_MESSAGE_BYTES }
 		);
 		return response.vote;
 	}
@@ -45,7 +46,7 @@ export class DisputeClient extends ProtocolClient {
 		await this.processMessage<{ type: 'ack' }>(
 			message,
 			this.protocol,
-			withRpcDeadlineDefaults(options),
+			{ ...withRpcDeadlineDefaults(options), maxDataLength: MAX_CONTROL_MESSAGE_BYTES },
 		);
 	}
 }

package/src/dispute/dispute-service.ts

@@ -1,11 +1,12 @@
 import type { ClusterRecord, ITransactionValidator, InvalidateRequest, CommitRequest, PendRequest, CollectionId } from '@optimystic/db-core';
-import { blockIdsForTransforms } from '@optimystic/db-core';
+import { blockIdsForTransforms, computeClusterPromiseHash, recordMembershipDigest } from '@optimystic/db-core';
 import { buildDisputeResolutionProof, computeTargetHash, computeArbitratorSetHash, voteSigningPayload, arbitratorSetSigningPayload, VOTE_VERSION, type CertificateTarget } from './invalidation.js';
 import type { PeerId, PrivateKey } from '@libp2p/interface';
 import { sha256 } from 'multiformats/hashes/sha2';
 import { base58btc } from 'multiformats/bases/base58';
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
 import { publicKeyFromRaw } from '@libp2p/crypto/keys';
+import { peerIdBindsPublicKey } from '../cluster/peer-key-binding.js';
 import type {
 	ValidationEvidence,
 	DisputeChallenge,
@@ -39,8 +40,14 @@ export interface DisputeServiceInit {
 	validator?: ITransactionValidator;
 	revalidate?: RevalidateTransaction;
 	config?: Partial<DisputeConfig>;
-	/** Select arbitrators for a dispute (next K peers beyond the original cluster) */
-	selectArbitrators: (blockId: string, excludePeers: string[], count: number) => Promise<PeerId[]>;
+	/**
+	 * Select arbitrators for a dispute via verifiable dispersed sampling (see `sampleArbitrators`): draw
+	 * `count` distinct peers from coordinates spread across the whole keyspace, not the block's neighborhood.
+	 * `round` (0-based escalation round) and `epoch` (agreed membership epoch bytes) are folded into every
+	 * coordinate so the draw is deterministic yet not pre-positionable — an honest node re-derives the
+	 * identical set from the same `(blockId, round, epoch)` + agreed membership.
+	 */
+	selectArbitrators: (blockId: string, excludePeers: string[], count: number, round: number, epoch: Uint8Array) => Promise<PeerId[]>;
 	/**
 	 * Originates the durable reversal when a dispute resolves `challenger-wins`. The dissent
 	 * coordinator (the node that initiated the dispute, holding the original record) builds the
@@ -163,9 +170,18 @@ export class DisputeService {
 		const originalPeers = Object.keys(record.peers);
 		const arbitratorCount = this.config.arbitratorCount ?? originalPeers.length;
 
+		// Round 0 is the only round today (single-round arbitration); `design-dispute-synchronous-escalation`
+		// drives real-time round progression. `epoch` pins the dispersed draw to a membership the attacker
+		// cannot freely advance.
+		// NOTE: interim agreed-membership epoch — hash of the admission-gate-agreed responsible set
+		// (`Object.keys(record.peers)`). When `design-cluster-membership-agreement` lands, `epoch` becomes
+		// the agreed membership epoch rather than this locally-hashed stand-in.
+		const round = 0;
+		const epoch = await this.computeEpochBytes(originalPeers);
+
 		let arbitrators: PeerId[];
 		try {
-			arbitrators = await this.selectArbitrators(blockId, originalPeers, arbitratorCount);
+			arbitrators = await this.selectArbitrators(blockId, originalPeers, arbitratorCount, round, epoch);
 		} catch (err) {
 			log('dispute-arbitrator-selection-failed', { disputeId, error: err instanceof Error ? err.message : String(err) });
 			return undefined;
@@ -195,7 +211,7 @@ export class DisputeService {
 
 		// Send challenge to all arbitrators and collect votes
 		const votes = await this.collectVotes(challenge, arbitrators);
-		const resolution = this.resolveDispute(challenge, votes);
+		const resolution = await this.resolveDispute(challenge, votes);
 
 		this.resolvedChallenges.set(disputeId, challenge);
 		this.activeDisputes.delete(disputeId);
@@ -234,10 +250,12 @@ export class DisputeService {
 		const targetHash = await this.computeChallengeTargetHash(challenge);
 		const setHash = await computeArbitratorSetHash(challenge.arbitratorSet ?? []);
 
-		// Verify the challenge signature
+		// Verify the challenge signature — bound to the challenger's id so a relay cannot attach a key it
+		// controls under some other peer's id and pass a forged challenge as that peer.
 		const validSignature = await this.verifyDisputeSignature(
 			challenge.disputeId,
 			challenge.signature,
+			challenge.challengerPeerId,
 			challenge.originalRecord.peers[challenge.challengerPeerId]?.publicKey
 		);
 
@@ -351,7 +369,7 @@ export class DisputeService {
 	}
 
 	/** Determine dispute resolution from collected votes */
-	resolveDispute(challenge: DisputeChallenge, votes: ArbitrationVote[]): DisputeResolution {
+	async resolveDispute(challenge: DisputeChallenge, votes: ArbitrationVote[]): Promise<DisputeResolution> {
 		const challengerVotes = votes.filter(v => v.vote === 'agree-with-challenger').length;
 		const majorityVotes = votes.filter(v => v.vote === 'agree-with-majority').length;
 		const totalDecisive = challengerVotes + majorityVotes;
@@ -366,11 +384,21 @@ export class DisputeService {
 			outcome = 'inconclusive';
 		} else if (challengerVotes >= superMajorityThreshold) {
 			outcome = 'challenger-wins';
-			// Penalize majority peers who approved the transaction
+			// Penalize majority peers who approved the transaction. The promise signatures in a challenge's
+			// originalRecord are NOT otherwise verified on the dispute path, so an attacker who crafts a
+			// challenge carrying a fabricated originalRecord could attach a forged approval under an honest
+			// peer's id to get that peer a FalseApproval penalty. Gate each false-approval on the approval
+			// being binding-valid (key bound to the id AND signature verifies); skip — never penalize —
+			// any approval that is unbound or invalid.
 			const originalRecord = challenge.originalRecord;
+			const promiseHash = await this.computePromiseHash(originalRecord);
 			for (const [peerId, signature] of Object.entries(originalRecord.promises)) {
 				if (signature.type === 'approve' && peerId !== challenge.challengerPeerId) {
-					affectedPeers.push({ peerId, reason: 'false-approval' });
+					if (await this.verifyPromiseSignature(originalRecord, peerId, promiseHash, signature)) {
+						affectedPeers.push({ peerId, reason: 'false-approval' });
+					} else {
+						log('dispute-skip-unverified-approval', { disputeId: challenge.disputeId, peerId });
+					}
 				}
 			}
 		} else if (majorityVotes >= superMajorityThreshold) {
@@ -557,6 +585,19 @@ export class DisputeService {
 		};
 	}
 
+	/**
+	 * Interim agreed-membership epoch bytes for the dispersed arbitrator draw: SHA-256 of the sorted,
+	 * comma-joined responsible peer-id set (the same set the admission gate agrees on). Sorted so the
+	 * digest is independent of enumeration order, so every honest node computes the identical epoch — the
+	 * property that lets the verify path re-derive the same arbitrator set. Replaced by the real agreed
+	 * membership epoch when `design-cluster-membership-agreement` lands.
+	 */
+	private async computeEpochBytes(peers: string[]): Promise<Uint8Array> {
+		const joined = [...peers].sort().join(',');
+		const digest = await sha256.digest(new TextEncoder().encode(joined));
+		return digest.digest;
+	}
+
 	private async computeDisputeId(messageHash: string, peerId: string, timestamp: number): Promise<string> {
 		const input = `${messageHash}+${peerId}+${timestamp}`;
 		const inputBytes = new TextEncoder().encode(input);
@@ -583,6 +624,7 @@ export class DisputeService {
 	private async verifyDisputeSignature(
 		disputeId: string,
 		signature: string,
+		challengerPeerId: string,
 		publicKey?: string | Uint8Array
 	): Promise<boolean> {
 		if (!publicKey?.length) return false;
@@ -590,6 +632,9 @@ export class DisputeService {
 			const keyBytes = typeof publicKey === 'string'
 				? uint8ArrayFromString(publicKey, 'base64url')
 				: publicKey;
+			// The key must be the one the challenger's id provably names, else a forged challenge could be
+			// attributed to any peer id while signed by a key the relay controls.
+			if (!peerIdBindsPublicKey(challengerPeerId, keyBytes)) return false;
 			const pubKey = publicKeyFromRaw(keyBytes);
 			const payload = new TextEncoder().encode(disputeId);
 			const sigBytes = uint8ArrayFromString(signature, 'base64url');
@@ -599,6 +644,46 @@ export class DisputeService {
 		}
 	}
 
+	/**
+	 * Reconstruct the cluster promise-vote hash for `record` — identical to `ClusterMember.computePromiseHash`,
+	 * and version-dispatched the same way: a v2 record folds its membership digest into the preimage, a v1 /
+	 * unversioned record hashes byte-identically to before. The promise signatures in a disputed record were
+	 * produced over this by the cluster path, so re-verifying an approval requires reproducing it here — a v2
+	 * originalRecord whose digest we omitted would fail to verify its (honest) approvals.
+	 */
+	private async computePromiseHash(record: ClusterRecord): Promise<string> {
+		return computeClusterPromiseHash(record.messageHash, record.message, recordMembershipDigest(record));
+	}
+
+	/**
+	 * True iff `signature` on `record` is a binding-valid promise vote from `peerId`: the record's key for
+	 * `peerId` must be the one that id provably names AND the signature must verify over the reconstructed
+	 * promise-vote preimage. Total: returns `false` (never throws) on a missing/unbound/malformed key or an
+	 * undecodable signature. Mirrors `ClusterMember.verifySignature`'s binding-then-verify order.
+	 */
+	private async verifyPromiseSignature(
+		record: ClusterRecord,
+		peerId: string,
+		promiseHash: string,
+		signature: { type: string; signature: string; rejectReason?: string }
+	): Promise<boolean> {
+		const publicKey = record.peers[peerId]?.publicKey;
+		if (!publicKey?.length) return false;
+		try {
+			const keyBytes = typeof publicKey === 'string'
+				? uint8ArrayFromString(publicKey, 'base64url')
+				: publicKey;
+			if (!peerIdBindsPublicKey(peerId, keyBytes)) return false;
+			const pubKey = publicKeyFromRaw(keyBytes);
+			const payloadStr = promiseHash + ':' + signature.type + (signature.rejectReason ? ':' + signature.rejectReason : '');
+			const payload = new TextEncoder().encode(payloadStr);
+			const sigBytes = uint8ArrayFromString(signature.signature, 'base64url');
+			return pubKey.verify(payload, sigBytes);
+		} catch {
+			return false;
+		}
+	}
+
 	private findChallengeForDispute(disputeId: string): DisputeChallenge | undefined {
 		return this.activeDisputes.get(disputeId) ?? this.resolvedChallenges.get(disputeId);
 	}

package/src/dispute/index.ts

@@ -14,7 +14,13 @@ export {
 	type EngineHealthState,
 	DEFAULT_DISPUTE_CONFIG,
 } from './types.js';
-export { selectArbitrators } from './arbitrator-selection.js';
+export {
+	sampleArbitrators,
+	coordinatePreimage,
+	type ArbitratorSamplingParams,
+	type NearestResolver,
+	type RingHashFn,
+} from './arbitrator-selection.js';
 export {
 	buildDisputeResolutionProof,
 	verifyInvalidationCertificate,

package/src/dispute/invalidation.ts

@@ -82,6 +82,21 @@ export type ArbitratorSetRecomputeContext = {
 	readonly blockIds: ReadonlyArray<BlockId>;
 	/** The carried set being judged (peer-id strings). */
 	readonly arbitratorSet: ReadonlyArray<string>;
+	/**
+	 * Escalation round the carried set was drawn at (0-based). A recompute capability MUST feed this to
+	 * `sampleArbitrators` so it re-derives the SAME dispersed draw. Today every dispute is round 0
+	 * (single-round arbitration), so the verify path pins it to 0; `design-dispute-synchronous-escalation`
+	 * threads the real round through the proof and updates this seam.
+	 */
+	readonly round: number;
+	/**
+	 * Agreed membership epoch the carried set was drawn against — the bytes `sampleArbitrators` folds into
+	 * every coordinate. A recompute capability MUST feed this so its re-derivation matches the original
+	 * draw. Optional until `design-dispute-synchronous-escalation` carries/derives it on the proof; while
+	 * absent a recompute cannot reconstruct the draw and should return `{ feasible: false }` (degradation),
+	 * which matches today's behavior — no recompute capability is wired in production.
+	 */
+	readonly epoch?: Uint8Array;
 };
 
 /**
@@ -291,6 +306,11 @@ export async function verifyInvalidationCertificate(proof: DisputeResolutionProo
 			invalidatedActionId: target.invalidatedActionId,
 			blockIds: target.blockIds,
 			arbitratorSet: proof.arbitratorSet,
+			// NOTE: `round` pinned to 0 (single-round arbitration today) and `epoch` omitted until
+			// `design-dispute-synchronous-escalation` threads the real (round, epoch) through the proof, so a
+			// `sampleArbitrators`-based recompute re-derives the identical dispersed set. Until then no recompute
+			// capability is wired in production; the test recomputes ignore these fields.
+			round: 0,
 		});
 		if (verdict.feasible) {
 			if (!verdict.legitimate) {
@@ -458,6 +478,16 @@ export type InvalidationContext = {
 	readonly log: Log<unknown>;
 	/** Resolves a block's storage so the compensating revision can be written. */
 	readonly createBlockStorage: (blockId: BlockId) => IBlockStorage;
+	/**
+	 * Runs `fn` while holding the same per-block commit latch `StorageRepo.commit` and
+	 * `saveReplicatedBlock` hold, so the compensating `saveReplica`/`saveDeletion` read-modify-write of
+	 * `meta.latest` is mutually exclusive with a concurrent local commit on that block. Without it, an
+	 * invalidation advancing `latest` outside that latch is invisible to commit's staleness guard, so a
+	 * commit that read a stale `latest` can clobber it back down — a lost-update / non-monotonic
+	 * regression. Optional: when omitted (unit tests / non-`StorageRepo` hosts) the write runs unlatched,
+	 * preserving today's behavior. The host supplies `StorageRepo`'s `withBlockCommitLatch`.
+	 */
+	readonly withBlockCommitLatch?: <T>(blockId: BlockId, fn: () => Promise<T>) => Promise<T>;
 };
 
 export type ApplyInvalidationParams = {
@@ -552,11 +582,19 @@ export async function applyInvalidation(ctx: InvalidationContext, params: ApplyI
 		// Deterministic compensating-revision actionId — identical on every member, so all converge on
 		// the same (rev, actionId) for both the restore and the tombstone path.
 		const revertActionId = await hashString(`inv:${invalidatedActionId}:${proof.disputeId}:${blockId}:${rev}`);
+		// Hold the per-block commit latch around ONLY the compensating write (matching saveReplicatedBlock's
+		// scope): the monotonic guard inside saveReplica/saveDeletion then runs under the same latch a
+		// concurrent commit holds, so the two RMW of meta.latest serialize and latest stays monotonic.
+		// Acquire per block, one at a time — invalidation never holds two block latches, so it cannot
+		// deadlock against commit's sorted multi-latch acquisition. When no runner is injected, the write
+		// runs unlatched (today's behavior).
+		const runLatched = <T>(fn: () => Promise<T>): Promise<T> =>
+			ctx.withBlockCommitLatch ? ctx.withBlockCommitLatch(blockId, fn) : fn();
 		if (computation.kind === 'delete') {
 			// Block-creation reversal: physically remove the created block by writing a forward tombstone
 			// revision. The `restoredContentHash` is the DELETED_BLOCK_RESTORE sentinel — a deleted block
 			// has no content hash, and the sentinel tells dependents "observed content is gone → invalidate".
-			await storage.saveDeletion({ rev, actionId: revertActionId });
+			await runLatched(() => storage.saveDeletion({ rev, actionId: revertActionId }));
 			log('apply-delete-restore blockId=%s invalidatedRev=%d rev=%d', blockId, invalidatedRev, rev);
 			reverted.push({ blockId, fromRev: computation.fromRev, restoredContentHash: DELETED_BLOCK_RESTORE });
 			continue;
@@ -565,7 +603,7 @@ export async function applyInvalidation(ctx: InvalidationContext, params: ApplyI
 			// Surviving later actions were replayed verbatim; true read-dependents are out of scope here.
 			log('apply-replayed-later-actions blockId=%s count=%d', blockId, computation.laterActions);
 		}
-		await storage.saveReplica(computation.block, { rev, actionId: revertActionId });
+		await runLatched(() => storage.saveReplica(computation.block, { rev, actionId: revertActionId }));
 		reverted.push({ blockId, fromRev: computation.fromRev, restoredContentHash: computation.restoredContentHash });
 	}
 

package/src/dispute/service.ts

@@ -2,6 +2,7 @@ import { pipe } from 'it-pipe';
 import { decode as lpDecode, encode as lpEncode } from 'it-length-prefixed';
 import type { Startable, Logger, Stream, Connection, StreamHandler } from '@libp2p/interface';
 import type { Uint8ArrayList } from 'uint8arraylist';
+import { MAX_CONTROL_MESSAGE_BYTES } from '../protocol-limits.js';
 import type { DisputeMessage } from './types.js';
 import type { DisputeService } from './dispute-service.js';
 
@@ -95,6 +96,11 @@ export class DisputeProtocolService implements Startable {
 				}
 
 				yield new TextEncoder().encode(JSON.stringify(response));
+				// One request per stream: every real DisputeClient sends exactly one
+				// request per dial (see ProtocolClient.processMessage), so complete the
+				// generator after the first response. A second frame a peer queued is then
+				// never read or parsed. Mirrors sync/block-transfer.
+				return;
 			}
 		};
 
@@ -102,7 +108,7 @@ export class DisputeProtocolService implements Startable {
 			try {
 				const responses = pipe(
 					stream,
-					(source) => lpDecode(source),
+					(source) => lpDecode(source, { maxDataLength: MAX_CONTROL_MESSAGE_BYTES }),
 					processStream.bind(this),
 					(source) => lpEncode(source)
 				);

package/src/index.ts

@@ -1,43 +1,46 @@
-export * from "./cluster/client.js";
-export * from "./cluster/cluster-repo.js";
-export * from "./cluster/commit-cert.js";
-export * from "./cluster/service.js";
-export * from "./cluster/rebalance-monitor.js";
-export * from "./cluster/spread-on-churn.js";
-export * from "./cluster/block-transfer.js";
-export * from "./cluster/block-transfer-service.js";
-export * from "./protocol-client.js";
-export * from "./repo/client.js";
-export * from "./repo/cluster-coordinator.js";
-export * from "./repo/coordinator-repo.js";
-export * from "./repo/service.js";
-export * from "./storage/block-storage.js";
-export * from "./storage/memory-storage.js";
-export * from "./storage/i-block-storage.js";
-export * from "./storage/i-raw-storage.js";
-export * from "./storage/struct.js";
-export * from "./storage/storage-repo.js";
-export * from "./storage/restoration-coordinator-v2.js";
-export * from "./storage/ring-selector.js";
-export * from "./storage/storage-monitor.js";
-export * from "./storage/arachnode-fret-adapter.js";
-export * from "./sync/protocol.js";
-export * from "./sync/client.js";
-export * from "./sync/service.js";
-export * from "./it-utility.js";
-export * from "./libp2p-key-network.js";
-export * from "./libp2p-node.js";
-export * from "./routing/responsibility.js";
-export * from "./routing/libp2p-known-peers.js";
-export * from "./network/network-manager-service.js";
-export * from "./network/get-network-manager.js";
-export * from "./reputation/index.js";
-export * from "./dispute/index.js";
-export * from "./cohort-topic/index.js";
-export * from "./matchmaking/index.js";
-export * from "./reactivity/index.js";
-export * from "./cluster/i-transaction-state-store.js";
-export * from "./cluster/memory-transaction-state-store.js";
-export * from "./cluster/persistent-transaction-state-store.js";
-export * from "./storage/i-kv-store.js";
-export * from "./storage/memory-kv-store.js";
+export * from "./cluster/client.js";
+export * from "./cluster/cluster-repo.js";
+export * from "./cluster/commit-cert.js";
+export * from "./cluster/service.js";
+export * from "./cluster/rebalance-monitor.js";
+export * from "./cluster/spread-on-churn.js";
+export * from "./cluster/block-transfer.js";
+export * from "./cluster/block-transfer-service.js";
+export * from "./protocol-client.js";
+export * from "./repo/client.js";
+export * from "./repo/cluster-coordinator.js";
+export * from "./repo/coordinator-repo.js";
+export * from "./repo/service.js";
+export * from "./storage/block-storage.js";
+export * from "./storage/raw-store-driver.js";
+export * from "./storage/kv-raw-storage.js";
+export * from "./storage/memory-store-driver.js";
+export * from "./storage/memory-storage.js";
+export * from "./storage/i-block-storage.js";
+export * from "./storage/i-raw-storage.js";
+export * from "./storage/struct.js";
+export * from "./storage/storage-repo.js";
+export * from "./storage/restoration-coordinator.js";
+export * from "./storage/ring-selector.js";
+export * from "./storage/storage-monitor.js";
+export * from "./storage/arachnode-fret-adapter.js";
+export * from "./sync/protocol.js";
+export * from "./sync/client.js";
+export * from "./sync/service.js";
+export * from "./it-utility.js";
+export * from "./libp2p-key-network.js";
+export * from "./libp2p-node.js";
+export * from "./routing/responsibility.js";
+export * from "./routing/libp2p-known-peers.js";
+export * from "./network/network-manager-service.js";
+export * from "./network/get-network-manager.js";
+export * from "./reputation/index.js";
+export * from "./dispute/index.js";
+export * from "./cohort-topic/index.js";
+export * from "./matchmaking/index.js";
+export * from "./reactivity/index.js";
+export * from "./cluster/i-transaction-state-store.js";
+export * from "./cluster/memory-transaction-state-store.js";
+export * from "./cluster/persistent-transaction-state-store.js";
+export * from "./storage/i-kv-store.js";
+export * from "./storage/memory-kv-store.js";

package/src/it-utility.ts

@@ -1,19 +1,11 @@
 export async function first<T>(
-	createIterable: (signal: AbortSignal) => AsyncIterable<T>,
-	onEmpty: () => T = () => { throw new Error('No items found') },
-	timeoutMs?: number
+	createIterable: () => AsyncIterable<T>,
+	onEmpty: () => T = () => { throw new Error('No items found') }
 ): Promise<T> {
-	const controller = new AbortController();
-	const timer = typeof timeoutMs === 'number' ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
-	try {
-		for await (const item of createIterable(controller.signal)) {
-			return item;
-		}
-		return onEmpty();
-	} finally {
-		if (timer !== undefined) clearTimeout(timer);
-		controller.abort();
+	for await (const item of createIterable()) {
+		return item;
 	}
+	return onEmpty();
 }
 
 export async function asyncIteratorToArray<T>(iterator: AsyncIterable<T>): Promise<T[]> {