@optimystic/db-p2p 0.13.4 → 0.14.0

package/src/repo/client.ts

@@ -3,6 +3,7 @@ import type {
 	PendRequest, CommitRequest, BlockGets, IPeerNetwork, PeerId
 } from "@optimystic/db-core";
 import type { RepoMessage } from "@optimystic/db-core";
+import { blockIdsForTransforms, blockIdToBytes } from "@optimystic/db-core";
 import { ProtocolClient } from "../protocol-client.js";
 import { peerIdFromString } from "@libp2p/peer-id";
 
@@ -64,16 +65,39 @@ export class RepoClient extends ProtocolClient implements IRepo {
 		};
 		const correlationId = this.extractCorrelationId(operations);
 		const deadline = options.expiration ?? (Date.now() + 30_000)
-		const msLeft = Math.max(1, deadline - Date.now())
-		const withTimeout = async <U>(fn: () => Promise<U>): Promise<U> => {
-			return await Promise.race<U>([
-				fn(),
-				new Promise<never>((_, reject) => setTimeout(() => reject(new Error('RepoClient timeout')), msLeft))
-			])
-		}
-		let response: any
+		const deadlineMs = Math.max(1, deadline - Date.now())
 		const preferred = (this.protocolPrefix ?? '/db-p2p') + '/repo/1.0.0'
-		response = await withTimeout(() => super.processMessage<any>(message, preferred, { signal: options?.signal, correlationId }))
+
+		// Drive the remaining `expiration` budget through an AbortController whose
+		// abort *reason* is the caller-facing `'RepoClient timeout'` Error, combined
+		// with any caller signal. processMessage forwards `signal` to both the dial
+		// and the response-read and calls `stream.abort(signal.reason)` on abort, so —
+		// unlike the old `Promise.race`, whose losing branch left the inner read
+		// running and leaked a pending read + stream on every timed-out RPC to a silent
+		// peer — the deadline now genuinely cancels the inner read while the caller
+		// still observes an error whose `.message === 'RepoClient timeout'`.
+		//
+		// Intentionally no `responseTimeoutMs`: the combined signal already bounds the
+		// read at `deadlineMs`. A second, shorter cap would surface as
+		// ResponseTimeoutError and mask the caller-facing 'RepoClient timeout' message.
+		const deadlineController = new AbortController()
+		const timer = setTimeout(
+			() => deadlineController.abort(new Error('RepoClient timeout')),
+			deadlineMs
+		)
+		const combinedSignal = options?.signal
+			? AbortSignal.any([options.signal, deadlineController.signal])
+			: deadlineController.signal
+		let response: any
+		try {
+			response = await super.processMessage<any>(message, preferred, {
+				signal: combinedSignal,
+				correlationId,
+				dialTimeoutMs: options?.dialTimeoutMs,
+			})
+		} finally {
+			clearTimeout(timer)
+		}
 
 		if (response?.redirect?.peers?.length) {
 			if (hop >= 2) {
@@ -85,8 +109,10 @@ export class RepoClient extends ProtocolClient implements IRepo {
 			if (next.id === currentIdStr) {
 				throw new Error('Redirect loop detected in RepoClient (same peer)')
 			}
-			// cache hint
-			this.recordCoordinatorForOpsIfSupported(operations, nextId)
+			// cache hint — await so the recorded key bytes match what findCoordinator
+			// later looks up (blockIdToBytes is async); deterministic ordering also
+			// keeps the hint testable. The redirect retry below is async anyway.
+			await this.recordCoordinatorForOpsIfSupported(operations, nextId)
 			// single-hop retry against target peer using repo protocol
 			const nextClient = RepoClient.create(nextId, this.peerNetwork, this.protocolPrefix)
 			return await nextClient.processRepoMessage<T>(operations, options, hop + 1)
@@ -94,28 +120,37 @@ export class RepoClient extends ProtocolClient implements IRepo {
 		return response as T;
 	}
 
-	private extractKeyFromOperations(ops: RepoMessage['operations']): Uint8Array | undefined {
+	private async extractKeyFromOperations(ops: RepoMessage['operations']): Promise<Uint8Array | undefined> {
 		const op = ops[0];
+		// The recorded key MUST be the sha256 digest produced by blockIdToBytes — the
+		// exact bytes findCoordinator/recordCoordinator key the coordinator cache on
+		// (NetworkTransactor passes blockIdToBytes(blockId)). Raw utf8 of the id would
+		// never match, so the hint would silently never be retrieved.
 		if ('get' in op) {
 			const id = op.get.blockIds[0];
-			return id ? new TextEncoder().encode(id) : undefined;
+			return id ? await blockIdToBytes(id) : undefined;
 		}
 		if ('pend' in op) {
-			const id = Object.keys(op.pend.transforms)[0];
-			return id ? new TextEncoder().encode(id) : undefined;
+			// Key on a real block id the pend touches, NOT a structural transforms field
+			// name ('inserts'/'updates'/'deletes'); see RepoService.deriveBlockKey.
+			const id = blockIdsForTransforms(op.pend.transforms)[0];
+			return id ? await blockIdToBytes(id) : undefined;
 		}
 		if ('commit' in op) {
-			return new TextEncoder().encode(op.commit.tailId);
+			// Anchor on blockIds[0] (where CoordinatorRepo.commit runs consensus +
+			// verifyResponsibility), NOT tailId — they differ for a non-tail batch.
+			const id = op.commit.blockIds[0];
+			return id ? await blockIdToBytes(id) : undefined;
 		}
 		if ('cancel' in op) {
 			const id = op.cancel.actionRef.blockIds[0];
-			return id ? new TextEncoder().encode(id) : undefined;
+			return id ? await blockIdToBytes(id) : undefined;
 		}
 		return undefined;
 	}
 
-	private recordCoordinatorForOpsIfSupported(ops: RepoMessage['operations'], peerId: PeerId): void {
-		const keyBytes = this.extractKeyFromOperations(ops)
+	private async recordCoordinatorForOpsIfSupported(ops: RepoMessage['operations'], peerId: PeerId): Promise<void> {
+		const keyBytes = await this.extractKeyFromOperations(ops)
 		const pn: any = this.peerNetwork as any
 		if (keyBytes != null && typeof pn?.recordCoordinator === 'function') {
 			pn.recordCoordinator(keyBytes, peerId)

package/src/repo/cluster-coordinator.ts

@@ -37,10 +37,11 @@ interface ClusterTransactionState {
 /** Manages distributed transactions across clusters */
 export class ClusterCoordinator {
 	private transactions: Map<string, ClusterTransactionState> = new Map();
-	private readonly retryInitialIntervalMs = 2000;
-	private readonly retryBackoffFactor = 2;
-	private readonly retryMaxIntervalMs = 30000;
-	private readonly retryMaxAttempts = 5;
+	private readonly retryInitialIntervalMs: number;
+	private readonly retryBackoffFactor: number;
+	private readonly retryMaxIntervalMs: number;
+	private readonly retryMaxAttempts: number;
+	private readonly commitBroadcastImmediateRetries: number;
 
 	constructor(
 		private readonly keyNetwork: IKeyNetwork,
@@ -54,7 +55,13 @@ export class ClusterCoordinator {
 		private readonly fretService?: FretService,
 		private readonly reputation?: IPeerReputation,
 		private readonly stateStore?: ITransactionStateStore
-	) { }
+	) {
+		this.retryInitialIntervalMs = cfg.commitBroadcastRetryInitialMs ?? 250;
+		this.retryBackoffFactor = cfg.commitBroadcastRetryBackoffFactor ?? 2;
+		this.retryMaxIntervalMs = cfg.commitBroadcastRetryMaxIntervalMs ?? 8000;
+		this.retryMaxAttempts = cfg.commitBroadcastRetryMaxAttempts ?? 5;
+		this.commitBroadcastImmediateRetries = cfg.commitBroadcastImmediateRetries ?? 1;
+	}
 
 	/**
 	 * Creates a base 58 BTC string hash for a message to uniquely identify a transaction
@@ -528,27 +535,7 @@ export class ClusterCoordinator {
 			// so each peer can independently reach consensus and execute the operations.
 			// Without this, only the coordinator's local cluster executes — remote peers
 			// never see enough commits to reach consensus on their own.
-			const broadcastResults = await Promise.allSettled(
-				peerIds.map(peerIdStr => {
-					const isLocal = this.localCluster && peerIdStr === this.localCluster.peerId.toString();
-					return isLocal
-						? this.localCluster!.update(record)
-						: this.createClusterClient(peerIdFromString(peerIdStr)).update(record).catch(err => {
-							log('cluster-tx:consensus-broadcast-error', { messageHash: record.messageHash, peerId: peerIdStr, error: (err as Error).message });
-							return null;
-						});
-				})
-			);
-
-			// Check for broadcast failures (excluding local)
-			const broadcastFailures: string[] = [];
-			broadcastResults.forEach((result, idx) => {
-				const peerId = peerIds[idx]!;
-				const isLocal = this.localCluster && peerId === this.localCluster.peerId.toString();
-				if (!isLocal && (result.status === 'rejected' || result.value === null)) {
-					broadcastFailures.push(peerId);
-				}
-			});
+			const { failures: broadcastFailures } = await this.broadcastMergedRecord(record, peerIds);
 			if (broadcastFailures.length > 0) {
 				this.scheduleCommitRetry(record.messageHash, record, broadcastFailures);
 			} else {
@@ -565,6 +552,59 @@ export class ClusterCoordinator {
 		return record;
 	}
 
+	/**
+	 * Broadcast the merged commit record to every peer, with `commitBroadcastImmediateRetries`
+	 * in-line re-attempts per peer before giving up. The libp2p connection used during
+	 * the prior commit phase is typically still warm, so a single immediate retry recovers
+	 * most transient stream errors without falling back to the scheduled retry timer.
+	 * Local cluster is invoked exactly once — local failures are fatal, not transient.
+	 */
+	private async broadcastMergedRecord(record: ClusterRecord, peerIds: string[]): Promise<{ failures: string[] }> {
+		const maxAttempts = 1 + Math.max(0, this.commitBroadcastImmediateRetries);
+		const results = await Promise.all(peerIds.map(async peerIdStr => {
+			const isLocal = this.localCluster && peerIdStr === this.localCluster.peerId.toString();
+			if (isLocal) {
+				try {
+					await this.localCluster!.update(record);
+					return { peerId: peerIdStr, success: true as const };
+				} catch (err) {
+					log('cluster-tx:consensus-broadcast-error', {
+						messageHash: record.messageHash,
+						peerId: peerIdStr,
+						error: (err as Error).message
+					});
+					return { peerId: peerIdStr, success: false as const };
+				}
+			}
+			let lastError: unknown;
+			for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+				try {
+					await this.createClusterClient(peerIdFromString(peerIdStr)).update(record);
+					return { peerId: peerIdStr, success: true as const };
+				} catch (err) {
+					lastError = err;
+					if (attempt < maxAttempts) {
+						log('cluster-tx:consensus-broadcast-retry', {
+							messageHash: record.messageHash,
+							peerId: peerIdStr,
+							attempt,
+							error: (err as Error).message
+						});
+					}
+				}
+			}
+			log('cluster-tx:consensus-broadcast-error', {
+				messageHash: record.messageHash,
+				peerId: peerIdStr,
+				attempts: maxAttempts,
+				error: lastError instanceof Error ? lastError.message : String(lastError)
+			});
+			return { peerId: peerIdStr, success: false as const };
+		}));
+		const failures = results.filter(r => !r.success).map(r => r.peerId);
+		return { failures };
+	}
+
 	private updateTransactionRecord(record: ClusterRecord, stage: string): void {
 		const state = this.transactions.get(record.messageHash);
 		if (!state) {

package/src/repo/coordinator-repo.ts

@@ -65,6 +65,14 @@ export class CoordinatorRepo implements IRepo {
 	private readonly localPeerId?: PeerId;
 	private readonly responsibilityCache = new LruMap<string, { inCluster: boolean, expires: number }>(1000);
 	private static readonly RESPONSIBILITY_TTL_MS = 60_000;
+	private readonly lastSeenCommitMs = new LruMap<string, number>(1000);
+	private readonly readRepairMode: 'off' | 'lazy' | 'paranoid';
+	private readonly readRepairWindowMs: number;
+	private readonly readRepairSampleRate: number;
+	/** Test seam: overridable clock for window-based read-repair gating. */
+	now: () => number = () => Date.now();
+	/** Test seam: overridable RNG (0..1) for sample-rate gating. */
+	rand: () => number = () => Math.random();
 
 	constructor(
 		readonly keyNetwork: IKeyNetwork,
@@ -86,8 +94,19 @@ export class CoordinatorRepo implements IRepo {
 			minAbsoluteClusterSize: cfg?.minAbsoluteClusterSize ?? 3,
 			allowClusterDownsize: cfg?.allowClusterDownsize ?? true,
 			clusterSizeTolerance: cfg?.clusterSizeTolerance ?? 0.5,
-			partitionDetectionWindow: cfg?.partitionDetectionWindow ?? 60000
+			partitionDetectionWindow: cfg?.partitionDetectionWindow ?? 60000,
+			commitBroadcastRetryInitialMs: cfg?.commitBroadcastRetryInitialMs ?? 250,
+			commitBroadcastRetryBackoffFactor: cfg?.commitBroadcastRetryBackoffFactor ?? 2,
+			commitBroadcastRetryMaxIntervalMs: cfg?.commitBroadcastRetryMaxIntervalMs ?? 8000,
+			commitBroadcastRetryMaxAttempts: cfg?.commitBroadcastRetryMaxAttempts ?? 5,
+			commitBroadcastImmediateRetries: cfg?.commitBroadcastImmediateRetries ?? 1,
+			readRepairMode: cfg?.readRepairMode ?? 'lazy',
+			readRepairWindowMs: cfg?.readRepairWindowMs ?? 10000,
+			readRepairSampleRate: cfg?.readRepairSampleRate ?? 0
 		};
+		this.readRepairMode = policy.readRepairMode!;
+		this.readRepairWindowMs = policy.readRepairWindowMs!;
+		this.readRepairSampleRate = policy.readRepairSampleRate!;
 		const localClusterRef = localCluster && localPeerId ? {
 			update: localCluster.update.bind(localCluster),
 			peerId: localPeerId,
@@ -159,24 +178,44 @@ export class CoordinatorRepo implements IRepo {
 		// First try local storage
 		const localResult = await this.storageRepo.get(blockGets, options);
 
-		// Check for blocks that weren't found locally - try to fetch from cluster peers
-		// Skip cluster fetch if this is already a sync request (to prevent recursive queries)
+		// Decide per-block whether to consult cluster peers. Two triggers:
+		//   (a) Missing — block isn't present locally at all (legacy behavior).
+		//   (b) Stale-by-policy — block is present but read-repair policy says verify.
+		// Skip cluster fetch if this is already a sync request (to prevent recursive queries).
 		const skipClusterFetch = (options as any)?.skipClusterFetch;
 		if (this.clusterLatestCallback && !skipClusterFetch) {
 			for (const blockId of blockGets.blockIds) {
 				const localEntry = localResult[blockId];
-				// If block not found locally (no state), try cluster peers
-				if (!localEntry?.state?.latest) {
-					try {
-						await this.fetchBlockFromCluster(blockId, blockGets.context);
-						// Re-fetch after sync
-						const refreshed = await this.storageRepo.get({ blockIds: [blockId], context: blockGets.context }, options);
-						if (refreshed[blockId]) {
-							localResult[blockId] = refreshed[blockId];
+				const localRev = localEntry?.state?.latest?.rev;
+				const isMissing = !localEntry?.state?.latest;
+				const isStale = !isMissing && this.shouldReadRepair(blockId);
+				if (!isMissing && !isStale) continue;
+
+				if (isStale) {
+					log('cluster-tx:read-repair-triggered', {
+						blockId,
+						mode: this.readRepairMode,
+						ageMs: this.ageMs(blockId),
+						localRev
+					});
+				}
+
+				try {
+					await this.fetchBlockFromCluster(blockId, blockGets.context);
+					const refreshed = await this.storageRepo.get({ blockIds: [blockId], context: blockGets.context }, options);
+					const newRev = refreshed[blockId]?.state?.latest?.rev;
+					if (refreshed[blockId]) {
+						localResult[blockId] = refreshed[blockId];
+					}
+					if (isStale) {
+						if (typeof newRev === 'number' && typeof localRev === 'number' && newRev > localRev) {
+							log('cluster-tx:read-repair-applied', { blockId, oldRev: localRev, newRev });
+						} else {
+							log('cluster-tx:read-repair-noop', { blockId });
 						}
-					} catch (err) {
-						log('cluster-fetch:error', { blockId, error: (err as Error).message });
 					}
+				} catch (err) {
+					log('cluster-fetch:error', { blockId, error: (err as Error).message });
 				}
 			}
 		}
@@ -184,6 +223,44 @@ export class CoordinatorRepo implements IRepo {
 		return localResult;
 	}
 
+	/** Decide whether the read-repair policy wants us to consult the cluster for a present-but-possibly-stale block. */
+	private shouldReadRepair(blockId: BlockId): boolean {
+		switch (this.readRepairMode) {
+			case 'off': return false;
+			case 'paranoid': return true;
+			case 'lazy': {
+				const lastSeen = this.lastSeenCommitMs.get(blockId);
+				if (lastSeen == null) return true;
+				if (this.now() - lastSeen > this.readRepairWindowMs) return true;
+				if (this.readRepairSampleRate > 0 && this.rand() < this.readRepairSampleRate) return true;
+				return false;
+			}
+		}
+	}
+
+	/** Milliseconds since we last marked this block fresh, or undefined if never. */
+	private ageMs(blockId: BlockId): number | undefined {
+		const lastSeen = this.lastSeenCommitMs.get(blockId);
+		return lastSeen == null ? undefined : this.now() - lastSeen;
+	}
+
+	/** Mark blocks as freshly observed from cluster authority (post-commit or post-fetch). */
+	private markBlocksSeen(blockIds: BlockId[]): void {
+		const now = this.now();
+		for (const id of blockIds) {
+			this.lastSeenCommitMs.set(id, now);
+		}
+	}
+
+	/**
+	 * Test seam: directly set the last-seen timestamp for a block. Used by read-repair
+	 * specs to simulate "the local commit happened at time T" without needing to drive
+	 * a full pend/commit cycle through the cluster coordinator.
+	 */
+	setLastSeenForTest(blockId: BlockId, ts: number): void {
+		this.lastSeenCommitMs.set(blockId, ts);
+	}
+
 	private async fetchBlockFromCluster(blockId: BlockId, context?: ActionContext): Promise<void> {
 		if (!this.clusterLatestCallback) return;
 
@@ -210,6 +287,7 @@ export class CoordinatorRepo implements IRepo {
 			// Found on cluster - trigger restoration to sync the block
 			await this.storageRepo.get({ blockIds: [blockId], context: { committed: [clusterLatest], rev: clusterLatest.rev } });
 			log('cluster-fetch:synced', { blockId, rev: clusterLatest.rev });
+			this.markBlocksSeen([blockId]);
 		}
 	}
 
@@ -327,7 +405,9 @@ export class CoordinatorRepo implements IRepo {
 
 		const peerCount = await this.coordinator.getClusterSize(blockIds[0]!);
 		if (peerCount <= 1) {
-			return await this.storageRepo.commit(request, options);
+			const result = await this.storageRepo.commit(request, options);
+			if (result.success) this.markBlocksSeen(blockIds);
+			return result;
 		}
 
 		const message: RepoMessage = {
@@ -338,6 +418,7 @@ export class CoordinatorRepo implements IRepo {
 		try {
 			const { record, localExecuted } = await this.coordinator.executeClusterTransaction(blockIds[0]!, message, options);
 			if (localExecuted) {
+				this.markBlocksSeen(blockIds);
 				return { success: true };
 			}
 			// Local cluster didn't execute during consensus. Attempt a local commit,
@@ -346,13 +427,16 @@ export class CoordinatorRepo implements IRepo {
 			// after missing the pend phase (unreachable during pend, fresh join, etc.).
 			// The cluster's majority is authoritative; this peer will catch up via sync.
 			try {
-				return await this.storageRepo.commit(request, options);
+				const result = await this.storageRepo.commit(request, options);
+				if (result.success) this.markBlocksSeen(blockIds);
+				return result;
 			} catch (err) {
 				if (clusterReachedCommitConsensus(record)) {
 					log('coordinator-repo:commit-local-failed-cluster-succeeded', {
 						actionId: request.actionId,
 						error: (err as Error).message
 					});
+					this.markBlocksSeen(blockIds);
 					return { success: true };
 				}
 				throw err;

package/src/repo/service.ts

@@ -1,9 +1,9 @@
 import { pipe } from 'it-pipe'
 import { decode as lpDecode, encode as lpEncode } from 'it-length-prefixed'
-import type { Startable, Logger, Stream, Connection, StreamHandler, PeerId } from '@libp2p/interface'
+import type { Startable, Logger, Stream, Connection, StreamHandler, PeerId, Libp2p } from '@libp2p/interface'
 import type { IRepo, RepoMessage } from '@optimystic/db-core'
+import { blockIdsForTransforms } from '@optimystic/db-core'
 import { peersEqual } from '../peer-utils.js'
-import { sha256 } from 'multiformats/hashes/sha2'
 import { encodePeers, type RedirectPayload } from './redirect.js'
 import type { Uint8ArrayList } from 'uint8arraylist'
 import { createLogger } from '../logger.js'
@@ -28,6 +28,13 @@ export type RepoServiceComponents = BaseComponents & {
 	networkManager?: NetworkManagerLike
 	peerId?: PeerId
 	getConnectionAddrs?: (peerId: PeerId) => string[]
+	/**
+	 * Optional libp2p node. The production wiring injects the node post-construction
+	 * via {@link RepoService.setLibp2p} (the `components.libp2p` proxy does not
+	 * reliably resolve from inside a service at request time); this field is a
+	 * best-effort fallback resolver used only when no node has been injected.
+	 */
+	libp2p?: Libp2p
 }
 
 export type RepoServiceInit = {
@@ -65,6 +72,14 @@ export class RepoService implements Startable {
 	private running: boolean
 	/** Responsibility K - how many peers are responsible for a key (for redirect decisions) */
 	private readonly responsibilityK: number
+	/**
+	 * The libp2p node, injected post-construction by the node wiring (see
+	 * libp2p-node-base.ts, mirroring how `networkManager`/`fret` receive theirs).
+	 * The libp2p `components.libp2p` proxy does NOT reliably resolve from inside a
+	 * service at request time, so the redirect path resolves the network manager,
+	 * self identity, and connection addrs through this explicitly-set reference.
+	 */
+	private libp2pRef: Libp2p | undefined
 
 	constructor(components: RepoServiceComponents, init: RepoServiceInit = {}) {
 		this.components = components
@@ -80,6 +95,19 @@ export class RepoService implements Startable {
 
 	readonly [Symbol.toStringTag] = '@libp2p/repo-service'
 
+	/**
+	 * Inject the running libp2p node. Called once post-construction by the node
+	 * wiring so the redirect path can resolve the network manager / self id / addrs.
+	 */
+	setLibp2p(libp2p: Libp2p): void {
+		this.libp2pRef = libp2p
+	}
+
+	/** Resolve the libp2p node: the injected ref first, then the (best-effort) components proxy. */
+	private getLibp2p(): Libp2p | undefined {
+		return this.libp2pRef ?? (this.components as any).libp2p
+	}
+
 	/**
 	 * Start the service
 	 */
@@ -110,17 +138,17 @@ export class RepoService implements Startable {
 
 	private getNetworkManager(): NetworkManagerLike | undefined {
 		if (this.components.networkManager) return this.components.networkManager
-		return (this.components as any).libp2p?.services?.networkManager as NetworkManagerLike | undefined
+		return (this.getLibp2p() as any)?.services?.networkManager as NetworkManagerLike | undefined
 	}
 
 	private getSelfId(): PeerId | undefined {
 		if (this.components.peerId) return this.components.peerId
-		return (this.components as any).libp2p?.peerId as PeerId | undefined
+		return this.getLibp2p()?.peerId as PeerId | undefined
 	}
 
 	private getPeerAddrs(peerId: PeerId): string[] {
 		if (this.components.getConnectionAddrs) return this.components.getConnectionAddrs(peerId)
-		const libp2p = (this.components as any).libp2p
+		const libp2p = this.getLibp2p() as any
 		if (!libp2p?.getConnections) return []
 		const conns: any[] = libp2p.getConnections(peerId) ?? []
 		const addrs: string[] = []
@@ -131,6 +159,41 @@ export class RepoService implements Startable {
 		return addrs
 	}
 
+	/**
+	 * Derive the redirect routing key and op name for a single operation.
+	 *
+	 * The key MUST be the block the corresponding handler actually coordinates and
+	 * verifies responsibility on, so redirect routing stays consistent with where the
+	 * op is executed:
+	 *   - get    → blockIds[0]
+	 *   - pend   → blockIdsForTransforms(transforms)[0]
+	 *   - cancel → actionRef.blockIds[0]
+	 *   - commit → blockIds[0]  (CoordinatorRepo.commit anchors consensus on
+	 *     getClusterSize(blockIds[0]) / executeClusterTransaction(blockIds[0]) and guards
+	 *     with verifyResponsibility(blockIds) — NOT tailId; for a per-block commit batch
+	 *     whose blockIds[0] !== tailId, keying on tailId redirected the commit to the
+	 *     collection tail's cluster, which then fails verifyResponsibility for the non-tail block.)
+	 *
+	 * Returns blockKey === undefined when the op carries no routable key (e.g. a cancel
+	 * with an empty blockIds list), in which case the caller handles it locally without a
+	 * redirect check.
+	 */
+	deriveBlockKey(operation: RepoMessage['operations'][number]): { blockKey: string | undefined, opName: string } {
+		if ('get' in operation) {
+			return { blockKey: operation.get.blockIds[0], opName: 'get' }
+		}
+		if ('pend' in operation) {
+			return { blockKey: blockIdsForTransforms(operation.pend.transforms)[0], opName: 'pend' }
+		}
+		if ('cancel' in operation) {
+			return { blockKey: operation.cancel.actionRef.blockIds[0], opName: 'cancel' }
+		}
+		if ('commit' in operation) {
+			return { blockKey: operation.commit.blockIds[0], opName: 'commit' }
+		}
+		return { blockKey: undefined, opName: 'unknown' }
+	}
+
 	/**
 	 * Check if this node should redirect the request for a given key.
 	 * Returns a RedirectPayload if not responsible, null if should handle locally.
@@ -140,8 +203,14 @@ export class RepoService implements Startable {
 		const nm = this.getNetworkManager()
 		if (!nm) return null
 
-		const mh = await sha256.digest(new TextEncoder().encode(blockKey))
-		const key = mh.digest
+		// Pass the RAW encoded block-key bytes to getCluster. getCluster hashes
+		// internally (hashKey == sha256), so the responsible-set coordinate becomes
+		// hashKey(encode(blockKey)) — identical to how the cluster coordinator
+		// derives it (ClusterCoordinator.getClusterForBlock → findCluster(encode(blockId))).
+		// Pre-hashing here would double-hash (hashKey(sha256(encode(blockKey)))), placing
+		// the cohort at an unrelated ring coordinate and redirecting requests the
+		// coordinator legitimately routed to this peer.
+		const key = new TextEncoder().encode(blockKey)
 		const cluster = await nm.getCluster(key)
 		;(message as any).cluster = cluster.map((p: PeerId) => p.toString?.() ?? String(p))
 
@@ -175,46 +244,25 @@ export class RepoService implements Startable {
 				const decoded = new TextDecoder().decode(msg.subarray())
 				const message = JSON.parse(decoded) as RepoMessage
 
-				// Process each operation
+				// Process each operation. Derive the redirect routing key once (keyed on the
+				// block the handler actually coordinates), redirect-check it, then dispatch.
 				const operation = message.operations[0]
-				let response: any
+				const { blockKey, opName } = this.deriveBlockKey(operation)
+				const redirect = blockKey !== undefined
+					? await this.checkRedirect(blockKey, opName, message)
+					: null
 
-				if ('get' in operation) {
-					const blockKey = operation.get.blockIds[0]!
-					const redirect = await this.checkRedirect(blockKey, 'get', message)
-					if (redirect) {
-						response = redirect
-					} else {
-						response = await this.repo.get(operation.get, { expiration: message.expiration, skipClusterFetch: true } as any)
-					}
+				let response: any
+				if (redirect) {
+					response = redirect
+				} else if ('get' in operation) {
+					response = await this.repo.get(operation.get, { expiration: message.expiration, skipClusterFetch: true } as any)
 				} else if ('pend' in operation) {
-					const blockKey = Object.keys(operation.pend.transforms)[0]!
-					const redirect = await this.checkRedirect(blockKey, 'pend', message)
-					if (redirect) {
-						response = redirect
-					} else {
-						response = await this.repo.pend(operation.pend, { expiration: message.expiration })
-					}
+					response = await this.repo.pend(operation.pend, { expiration: message.expiration })
 				} else if ('cancel' in operation) {
-					const blockKey = operation.cancel.actionRef.blockIds[0]
-					if (blockKey) {
-						const redirect = await this.checkRedirect(blockKey, 'cancel', message)
-						if (redirect) {
-							response = redirect
-						} else {
-							response = await this.repo.cancel(operation.cancel.actionRef, { expiration: message.expiration })
-						}
-					} else {
-						response = await this.repo.cancel(operation.cancel.actionRef, { expiration: message.expiration })
-					}
+					response = await this.repo.cancel(operation.cancel.actionRef, { expiration: message.expiration })
 				} else if ('commit' in operation) {
-					const blockKey = operation.commit.tailId
-					const redirect = await this.checkRedirect(blockKey, 'commit', message)
-					if (redirect) {
-						response = redirect
-					} else {
-						response = await this.repo.commit(operation.commit, { expiration: message.expiration })
-					}
+					response = await this.repo.commit(operation.commit, { expiration: message.expiration })
 				}
 
 				// Encode and yield the response

package/src/rpc-deadline.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-RPC deadline knobs shared by the simple {@link ProtocolClient} subclasses
+ * (cluster / sync / dispute). `dialTimeoutMs` bounds connecting; `responseTimeoutMs`
+ * bounds waiting for the reply once connected (so a peer that connects then goes
+ * silent throws {@link ResponseTimeoutError} instead of hanging the caller forever);
+ * `signal` cancels the whole request. All optional.
+ */
+export type RpcDeadlineOptions = {
+	signal?: AbortSignal;
+	dialTimeoutMs?: number;
+	responseTimeoutMs?: number;
+};
+
+/**
+ * Default per-peer dial deadline. Matches `spread-on-churn.ts` `pushDialTimeoutMs`
+ * (3000ms) — an unreachable peer fails the dial fast so the caller can re-pick a
+ * different coordinator rather than blocking on a dead route.
+ */
+export const DEFAULT_DIAL_TIMEOUT_MS = 3000;
+
+/**
+ * Default per-peer response deadline. Matches `spread-on-churn.ts`
+ * `pushResponseTimeoutMs` (10000ms) — a peer that connects then never writes a
+ * reply is abandoned instead of hanging the caller forever.
+ */
+export const DEFAULT_RESPONSE_TIMEOUT_MS = 10000;
+
+/**
+ * Merge caller-supplied deadline options with the client-level defaults. An
+ * explicitly-supplied value wins (including a deliberate `0`, which
+ * {@link ProtocolClient.processMessage} reads as "no cap"); an absent key falls
+ * back to the default so a caller that passes nothing still gets a deadline.
+ * `signal` has no default — cancellation is always caller-driven.
+ *
+ * Unlike `BlockTransferClient` (which leaves its defaults to the owning
+ * `SpreadOnChurnMonitor` config), these clients have many callers and no single
+ * owning monitor, so the deadline default belongs here on the client.
+ */
+export function withRpcDeadlineDefaults(options?: RpcDeadlineOptions): RpcDeadlineOptions {
+	return {
+		dialTimeoutMs: options?.dialTimeoutMs ?? DEFAULT_DIAL_TIMEOUT_MS,
+		responseTimeoutMs: options?.responseTimeoutMs ?? DEFAULT_RESPONSE_TIMEOUT_MS,
+		signal: options?.signal,
+	};
+}