@optimystic/db-p2p 0.24.2 → 0.25.0

package/src/dispute/invalidation.ts

@@ -1,11 +1,12 @@
 import { peerIdFromString } from '@libp2p/peer-id';
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string';
 import type {
-	ActionId, BlockId, IBlock, Log,
+	ActionId, ActionRev, BlockId, IBlock, Log,
 	DisputeResolutionProof, ArbitrationVoteProof, RevertedBlock,
 } from '@optimystic/db-core';
 import { applyTransform, hashString } from '@optimystic/db-core';
 import type { IBlockStorage } from '../storage/i-block-storage.js';
+import { acquireBlockWriteLatches } from '../storage/block-latch.js';
 import type { DisputeResolution, ArbitrationVote } from './types.js';
 import { createLogger } from '../logger.js';
 
@@ -478,16 +479,6 @@ 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 = {
@@ -499,8 +490,19 @@ export type ApplyInvalidationParams = {
 	readonly proof: DisputeResolutionProof;
 	/**
 	 * Consensus-assigned revision slot for the compensating revision (collection-global). When
-	 * omitted, computed as one past the highest current tip across the reverted blocks — the value a
-	 * local/single-node apply uses; the consensus path passes the agreed slot.
+	 * omitted, computed as one past the highest current tip across the reverted blocks — read under
+	 * the blocks' write latches, so an omitted slot is strictly past every tip and its compensating
+	 * writes can never be refused by the monotonic guard.
+	 *
+	 * An explicit slot at or below any affected block's tip is refused wholesale (`applied: false`,
+	 * reason `stale-revision`) rather than partially written.
+	 *
+	 * NOTE: nothing on the wire supplies this today. `InvalidateRequest`
+	 * (`db-core/src/network/struct.ts`) carries `invalidatedActionId` / `invalidatedRev` / `blockIds` /
+	 * `collectionId` / `resolution` and NO compensating-revision field, so the network-facing apply
+	 * path leaves this undefined and every member computes its own slot locally. The `stale-revision`
+	 * path is therefore reachable only from tests and from a future caller that does pass an agreed
+	 * slot; adding that wire field is out of scope here.
 	 */
 	readonly rev?: number;
 	/**
@@ -526,11 +528,40 @@ export type ApplyInvalidationParams = {
 
 export type ApplyInvalidationResult = {
 	readonly applied: boolean;
-	readonly reason?: 'already-applied' | 'invalid-certificate';
+	/**
+	 *  - `already-applied` — a re-receipt; the log already holds this `(invalidatedActionId, disputeId)`.
+	 *    `reverted` carries the EXISTING entry's blocks, so a caller can reuse them.
+	 *  - `invalid-certificate` — the proof is not a valid challenger-wins certificate for the target.
+	 *  - `stale-revision` — at least one affected block already sits at or past the compensating
+	 *    revision slot, so the compensating write would be refused by the monotonic guard. Nothing was
+	 *    written and nothing was appended (all-or-nothing); the invalidation is safely re-deliverable
+	 *    once the caller supplies a slot past every affected block's tip. Reachable only when the
+	 *    caller supplies an explicit {@link ApplyInvalidationParams.rev} — a slot this function
+	 *    computes itself is strictly past every tip by construction.
+	 */
+	readonly reason?: 'already-applied' | 'invalid-certificate' | 'stale-revision';
 	readonly rev?: number;
 	readonly reverted: ReadonlyArray<RevertedBlock>;
 };
 
+/**
+ * Boundary invariant for the compensating write: the effective `ActionRev` a forward write returns
+ * must be the one we intended. The precheck above already establishes that, so a mismatch means a
+ * write path refused for a reason the precheck does not model — an internal contradiction (a write
+ * refused while its latch was held and its tip was checked), not a condition to degrade around. It
+ * throws rather than returning `applied: false`: `ClusterRepo.applyConsensusInvalidation` tolerates a
+ * sink throw, logs it, and rolls back its dedup marker so a re-broadcast retries.
+ */
+function assertWriteLanded(blockId: BlockId, intended: ActionRev, effective: ActionRev): void {
+	if (effective.rev !== intended.rev || effective.actionId !== intended.actionId) {
+		throw new Error(
+			`Invalidation compensating write did not land for block ${blockId}: intended ` +
+			`{ rev: ${intended.rev}, actionId: ${intended.actionId} }, effective ` +
+			`{ rev: ${effective.rev}, actionId: ${effective.actionId} }`
+		);
+	}
+}
+
 /**
  * Deterministically applies a single-collection invalidation: the durable reversal primitive every
  * cluster member runs identically (it carries the `reverted` targets and proof, exactly as the
@@ -540,15 +571,29 @@ export type ApplyInvalidationResult = {
  *  1. **Dedup** — if the log already holds an invalidation for `(invalidatedActionId, disputeId)`,
  *     this is a re-receipt (rebroadcast / sync / retry): no-op, append nothing.
  *  2. **Certificate** — reject (append nothing) unless `proof` is a valid challenger-wins certificate.
- *  3. **Reverted revisions** — for each block, recompute the as-if-`T_inv`-absent content and write a
- *     new monotonic revision (a forward compensating transform; prior revisions are retained).
+ *  3. **Reverted revisions** — holding EVERY affected block's write latch, recompute each block's
+ *     as-if-`T_inv`-absent content and write a new monotonic revision (a forward compensating
+ *     transform; prior revisions are retained). All-or-nothing: if any block already sits at or past
+ *     the compensating slot, nothing is written and nothing is appended.
  *  4. **Log entry** — append the {@link InvalidationEntry} carrying the proof and `reverted` targets,
  *     making `committed-invalidated` durable and recoverable on sync.
+ *
+ * The `reverted` entries an applied result carries therefore describe writes that ACTUALLY landed,
+ * at the revision and with the content hash they name — the property `cascade.ts` relies on when it
+ * decides a read-dependent's fate by comparing observed content against `restoredContentHash`.
  */
 export async function applyInvalidation(ctx: InvalidationContext, params: ApplyInvalidationParams): Promise<ApplyInvalidationResult> {
 	const { invalidatedActionId, invalidatedRev, blockIds, proof } = params;
 
 	// 1. Idempotent re-receipt — keyed on (invalidatedActionId, disputeId).
+	// NOTE: this read is outside the block latches taken in step 3, so two OVERLAPPING applies of the
+	// same invalidation would both pass here and both write a compensating revision (the second at a
+	// slot one past the first), appending two entries for one invalidation. Not reachable today: the
+	// network path serializes through consensus and dedups in memory first
+	// (`ClusterRepo.applyConsensusInvalidation`), and the cascade applies its children sequentially.
+	// If a caller ever applies the same invalidation concurrently, this dedup has to move inside the
+	// critical section — which means keying it on something the block latches actually cover, since
+	// `ctx.log` is not latched by them.
 	const existing = await ctx.log.findInvalidation(invalidatedActionId);
 	if (existing && existing.resolution.disputeId === proof.disputeId) {
 		log('apply-skip-duplicate actionId=%s disputeId=%s', invalidatedActionId, proof.disputeId);
@@ -567,48 +612,113 @@ export async function applyInvalidation(ctx: InvalidationContext, params: ApplyI
 		return { applied: false, reason: 'invalid-certificate', reverted: [] };
 	}
 
-	// 3. Compute compensating content + the collection-global revision slot.
-	const computations = await Promise.all(
-		blockIds.map(async (blockId) => {
-			const storage = ctx.createBlockStorage(blockId);
-			return { blockId, storage, computation: await computeRevertedBlock(storage, invalidatedRev) };
-		})
-	);
-	const maxFromRev = computations.reduce((max, c) => Math.max(max, c.computation.fromRev), invalidatedRev);
-	const rev = params.rev ?? maxFromRev + 1;
-
-	const reverted: RevertedBlock[] = [];
-	for (const { blockId, storage, computation } of computations) {
-		// 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 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;
+	// 3. Compensating revisions — ONE critical section spanning every affected block.
+	//
+	// Latch discipline: hold ALL affected blocks' write latches across compute → revision slot →
+	// precheck → writes. `acquireBlockWriteLatches` is the package's single multi-latch entry point
+	// (it dedups and acquires in the one global sorted order), so this cannot deadlock against the
+	// other multi-latch holder, `StorageRepo.commit`. (The previous code took each block's latch
+	// around only its own write, which left the tips it computed from — and the revision slot derived
+	// from them — read outside any latch: a concurrent commit could land a newer revision in the gap,
+	// the monotonic guard in saveReplica/saveDeletion would correctly refuse the compensating write,
+	// and the log entry appended in step 4 would then assert a restore that never happened.)
+	//
+	// Collapsing duplicate ids is why `uniqueBlockIds` drives the writes and `reverted` too: one
+	// latched block yields one compensating write and one entry. The certificate target above
+	// deliberately still uses the caller's `blockIds` verbatim — the arbitrators signed over that list.
+	const uniqueBlockIds = Array.from(new Set(blockIds));
+	const { latches, release } = await acquireBlockWriteLatches(uniqueBlockIds);
+	let reverted: RevertedBlock[];
+	let rev: number;
+	try {
+		// --- Start of critical section ---
+
+		// Compute compensating content from tips read UNDER the latches. `computeRevertedBlock` reads
+		// only through getLatest/listRevisions/getBlock/getTransaction — none of which acquire a latch
+		// or touch the network (`BlockStorage.getBlock` throws `RevisionNotCoveredError` rather than
+		// restoring; the healing re-read lives one layer up in `StorageRepo.get`), so it is safe to
+		// call while holding them. Keep it that way: routing it through the healing path, which
+		// restores under the block latch, would self-deadlock here.
+		//
+		// NOTE: this compute now runs inside the critical section, so every commit and pend on these
+		// blocks queues behind it, and its cost grows with the number of revisions between T_inv and
+		// the tip (`listRevisions` + a transform apply each). Fine at invalidation's rate — a reversal
+		// is rare and its blocks are few. If invalidations ever become frequent, or reversals of very
+		// old transactions show up delaying commits, compute optimistically outside the latches and
+		// re-verify the tips inside (recomputing only the blocks that moved).
+		const computations = await Promise.all(
+			uniqueBlockIds.map(async (blockId) => {
+				const storage = ctx.createBlockStorage(blockId);
+				return {
+					blockId,
+					storage,
+					latch: latches.get(blockId)!,
+					latest: await storage.getLatest(),
+					computation: await computeRevertedBlock(storage, invalidatedRev),
+				};
+			})
+		);
+		const maxFromRev = computations.reduce((max, c) => Math.max(max, c.computation.fromRev), invalidatedRev);
+		rev = params.rev ?? maxFromRev + 1;
+
+		// All-or-nothing precheck, mirroring the monotonic guard in `BlockStorage.saveForwardRevision`
+		// (`meta.latest.rev >= rev` ⇒ refuse). With the tips read under these same latches, a computed
+		// slot is strictly greater than every tip by construction, so this can only trip when the CALLER
+		// supplied an explicit `rev` at or below a current tip. Writing nothing is the right outcome:
+		// skipping the block or retrying at a higher slot would make one member's durable entry differ
+		// from another's for the same invalidation, and step 1 dedups on (invalidatedActionId, disputeId)
+		// so an invalidation that appended nothing is simply re-deliverable.
+		const stale = computations.find(c => c.latest !== undefined && c.latest.rev >= rev);
+		if (stale) {
+			log('apply-reject-stale-revision actionId=%s disputeId=%s rev=%d blockId=%s held=%d',
+				invalidatedActionId, proof.disputeId, rev, stale.blockId, stale.latest!.rev);
+			return { applied: false, reason: 'stale-revision', reverted: [] };
 		}
-		if (computation.laterActions > 0) {
-			// 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);
+
+		reverted = [];
+		for (const { blockId, storage, latch, computation } of computations) {
+			// 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}`);
+			const intended: ActionRev = { rev, actionId: revertActionId };
+			let effective: ActionRev;
+			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".
+				effective = await storage.saveDeletion(intended, latch);
+				assertWriteLanded(blockId, intended, effective);
+				log('apply-delete-restore blockId=%s invalidatedRev=%d rev=%d', blockId, invalidatedRev, rev);
+				reverted.push({ blockId, fromRev: computation.fromRev, restoredContentHash: DELETED_BLOCK_RESTORE });
+				continue;
+			}
+			if (computation.laterActions > 0) {
+				// 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);
+			}
+			effective = await storage.saveReplica(computation.block, intended, undefined, latch);
+			assertWriteLanded(blockId, intended, effective);
+			reverted.push({ blockId, fromRev: computation.fromRev, restoredContentHash: computation.restoredContentHash });
 		}
-		await runLatched(() => storage.saveReplica(computation.block, { rev, actionId: revertActionId }));
-		reverted.push({ blockId, fromRev: computation.fromRev, restoredContentHash: computation.restoredContentHash });
+
+		// --- End of critical section ---
+	} finally {
+		// Every acquired latch is released even if a compute or a write threw.
+		release();
 	}
 
 	// 4. Durable, append-only invalidation entry (the source of truth for committed-invalidated).
+	//    Appended OUTSIDE the block latches on purpose: `ctx.log` writes through a `BlockStore` that may
+	//    itself be repo-backed, and `Latches` has no re-entrancy — appending under a block latch could
+	//    self-deadlock.
 	//    `cascadeRoot` is set when this is a cascade step (a reverted read-dependent), undefined for a root.
+	//
+	// NOTE: the gap between the writes landing and this append is a crash window — a crash inside it
+	// leaves compensating revisions with no entry naming them. Deliberate, and the recoverable
+	// direction of the invariant this function establishes: an entry never over-claims, it can only
+	// under-claim, and re-delivery re-applies (step 1 dedups on the entry, which is not there). The
+	// asymmetry only stops being acceptable if a consumer starts treating "revision present, entry
+	// absent" as authoritative rather than as a state to re-sync.
 	await ctx.log.addInvalidation(invalidatedActionId, invalidatedRev, proof, reverted, rev, params.cascadeRoot, params.timestamp);
 	log('apply-complete actionId=%s disputeId=%s rev=%d blocks=%d', invalidatedActionId, proof.disputeId, rev, reverted.length);
 

package/src/dispute/service.ts

@@ -1,125 +1,126 @@
-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';
-
-interface BaseComponents {
-	logger: { forComponent: (name: string) => Logger };
-	registrar: {
-		handle: (protocol: string, handler: StreamHandler, options: any) => Promise<void>;
-		unhandle: (protocol: string) => Promise<void>;
-	};
-}
-
-export interface DisputeProtocolServiceComponents extends BaseComponents {
-	disputeService: DisputeService;
-}
-
-export interface DisputeProtocolServiceInit {
-	protocol?: string;
-	protocolPrefix?: string;
-	maxInboundStreams?: number;
-	maxOutboundStreams?: number;
-}
-
-export function disputeProtocolService(init: DisputeProtocolServiceInit = {}): (components: DisputeProtocolServiceComponents) => DisputeProtocolService {
-	return (components: DisputeProtocolServiceComponents) => new DisputeProtocolService(components, init);
-}
-
-/**
- * Libp2p service that handles dispute protocol messages.
- * Follows the same pattern as ClusterService.
- */
-export class DisputeProtocolService implements Startable {
-	private readonly protocol: string;
-	private readonly maxInboundStreams: number;
-	private readonly maxOutboundStreams: number;
-	private readonly log: Logger;
-	private readonly disputeService: DisputeService;
-	private readonly components: DisputeProtocolServiceComponents;
-	private running: boolean;
-
-	constructor(components: DisputeProtocolServiceComponents, init: DisputeProtocolServiceInit = {}) {
-		this.components = components;
-		this.protocol = init.protocol ?? (init.protocolPrefix ?? '/db-p2p') + '/dispute/1.0.0';
-		this.maxInboundStreams = init.maxInboundStreams ?? 16;
-		this.maxOutboundStreams = init.maxOutboundStreams ?? 32;
-		this.log = components.logger.forComponent('db-p2p:dispute');
-		this.disputeService = components.disputeService;
-		this.running = false;
-	}
-
-	readonly [Symbol.toStringTag] = '@libp2p/dispute';
-
-	async start(): Promise<void> {
-		if (this.running) return;
-
-		await this.components.registrar.handle(this.protocol, this.handleIncomingStream.bind(this), {
-			maxInboundStreams: this.maxInboundStreams,
-			maxOutboundStreams: this.maxOutboundStreams,
-		});
-
-		this.running = true;
-	}
-
-	async stop(): Promise<void> {
-		if (!this.running) return;
-		await this.components.registrar.unhandle(this.protocol);
-		this.running = false;
-	}
-
-	private handleIncomingStream(stream: Stream, connection: Connection): void {
-		const peerId = connection.remotePeer;
-
-		const processStream = async function* (this: DisputeProtocolService, source: AsyncIterable<Uint8ArrayList>) {
-			for await (const msg of source) {
-				const decoded = new TextDecoder().decode(msg.subarray());
-				const message = JSON.parse(decoded) as DisputeMessage;
-
-				let response: any;
-				switch (message.type) {
-					case 'challenge': {
-						const vote = await this.disputeService.handleChallenge(message.challenge);
-						response = { type: 'vote', vote };
-						break;
-					}
-					case 'resolution': {
-						this.disputeService.handleResolution(message.resolution);
-						response = { type: 'ack' };
-						break;
-					}
-					default:
-						throw new Error(`Unknown dispute message type: ${(message as any).type}`);
-				}
-
-				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;
-			}
-		};
-
-		void (async () => {
-			try {
-				const responses = pipe(
-					stream,
-					(source) => lpDecode(source, { maxDataLength: MAX_CONTROL_MESSAGE_BYTES }),
-					processStream.bind(this),
-					(source) => lpEncode(source)
-				);
-				for await (const chunk of responses) {
-					stream.send(chunk);
-				}
-				await stream.close();
-			} catch (err) {
-				this.log.error('error handling dispute protocol message from %p - %e', peerId, err);
-				stream.abort(err instanceof Error ? err : new Error(String(err)));
-			}
-		})();
-	}
-}
+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';
+import { registerProtocolHandler } from '../network/register-protocol-handler.js';
+
+interface BaseComponents {
+	logger: { forComponent: (name: string) => Logger };
+	registrar: {
+		handle: (protocol: string, handler: StreamHandler, options: any) => Promise<void>;
+		unhandle: (protocol: string) => Promise<void>;
+	};
+}
+
+export interface DisputeProtocolServiceComponents extends BaseComponents {
+	disputeService: DisputeService;
+}
+
+export interface DisputeProtocolServiceInit {
+	protocol?: string;
+	protocolPrefix?: string;
+	maxInboundStreams?: number;
+	maxOutboundStreams?: number;
+}
+
+export function disputeProtocolService(init: DisputeProtocolServiceInit = {}): (components: DisputeProtocolServiceComponents) => DisputeProtocolService {
+	return (components: DisputeProtocolServiceComponents) => new DisputeProtocolService(components, init);
+}
+
+/**
+ * Libp2p service that handles dispute protocol messages.
+ * Follows the same pattern as ClusterService.
+ */
+export class DisputeProtocolService implements Startable {
+	private readonly protocol: string;
+	private readonly maxInboundStreams: number;
+	private readonly maxOutboundStreams: number;
+	private readonly log: Logger;
+	private readonly disputeService: DisputeService;
+	private readonly components: DisputeProtocolServiceComponents;
+	private running: boolean;
+
+	constructor(components: DisputeProtocolServiceComponents, init: DisputeProtocolServiceInit = {}) {
+		this.components = components;
+		this.protocol = init.protocol ?? (init.protocolPrefix ?? '/db-p2p') + '/dispute/1.0.0';
+		this.maxInboundStreams = init.maxInboundStreams ?? 16;
+		this.maxOutboundStreams = init.maxOutboundStreams ?? 32;
+		this.log = components.logger.forComponent('db-p2p:dispute');
+		this.disputeService = components.disputeService;
+		this.running = false;
+	}
+
+	readonly [Symbol.toStringTag] = '@libp2p/dispute';
+
+	async start(): Promise<void> {
+		if (this.running) return;
+
+		await registerProtocolHandler(this.components.registrar, this.protocol, this.handleIncomingStream.bind(this), {
+			maxInboundStreams: this.maxInboundStreams,
+			maxOutboundStreams: this.maxOutboundStreams,
+		});
+
+		this.running = true;
+	}
+
+	async stop(): Promise<void> {
+		if (!this.running) return;
+		await this.components.registrar.unhandle(this.protocol);
+		this.running = false;
+	}
+
+	private handleIncomingStream(stream: Stream, connection: Connection): void {
+		const peerId = connection.remotePeer;
+
+		const processStream = async function* (this: DisputeProtocolService, source: AsyncIterable<Uint8ArrayList>) {
+			for await (const msg of source) {
+				const decoded = new TextDecoder().decode(msg.subarray());
+				const message = JSON.parse(decoded) as DisputeMessage;
+
+				let response: any;
+				switch (message.type) {
+					case 'challenge': {
+						const vote = await this.disputeService.handleChallenge(message.challenge);
+						response = { type: 'vote', vote };
+						break;
+					}
+					case 'resolution': {
+						this.disputeService.handleResolution(message.resolution);
+						response = { type: 'ack' };
+						break;
+					}
+					default:
+						throw new Error(`Unknown dispute message type: ${(message as any).type}`);
+				}
+
+				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;
+			}
+		};
+
+		void (async () => {
+			try {
+				const responses = pipe(
+					stream,
+					(source) => lpDecode(source, { maxDataLength: MAX_CONTROL_MESSAGE_BYTES }),
+					processStream.bind(this),
+					(source) => lpEncode(source)
+				);
+				for await (const chunk of responses) {
+					stream.send(chunk);
+				}
+				await stream.close();
+			} catch (err) {
+				this.log.error('error handling dispute protocol message from %p - %e', peerId, err);
+				stream.abort(err instanceof Error ? err : new Error(String(err)));
+			}
+		})();
+	}
+}

package/src/index.ts

@@ -1,7 +1,9 @@
 export * from "./cluster/client.js";
+export * from "./cluster/client-signature-verifier.js";
 export * from "./cluster/cluster-repo.js";
 export * from "./cluster/cluster-policy.js";
 export * from "./cluster/commit-cert.js";
+export * from "./cluster/commit-proof.js";
 export * from "./cluster/service.js";
 export * from "./cluster/rebalance-monitor.js";
 export * from "./cluster/spread-on-churn.js";
@@ -12,18 +14,23 @@ 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/served-repo-proxy.js";
 export * from "./repo/service.js";
 export * from "./storage/block-storage.js";
+export * from "./storage/block-latch.js";
+export * from "./storage/store-identity.js";
 export * from "./storage/raw-store-driver.js";
 export * from "./storage/kv-raw-storage.js";
 export * from "./storage/shared-cache-pool.js";
 export * from "./storage/cached-store-driver.js";
 export * from "./storage/cached-raw-storage.js";
+export * from "./storage/with-read-cache.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/block-archive.js";
 export * from "./storage/storage-repo.js";
 export * from "./storage/restoration-coordinator.js";
 export * from "./storage/ring-selector.js";