@optimystic/db-p2p 1.0.0-beta.3 → 1.1.0

package/src/reactivity/origination-manager.ts

@@ -174,9 +174,9 @@ export class ReactivityOriginationManager {
 	 * recover serve begins redirecting to the new tree.
 	 *
 	 * **Encoding contract.** `ctx.tailId` is the reactivity tail anchor bytes the node resolved
-	 * (`reactivityTailBytes(event.tailId)` in production — the SAME utf8 encoding origination's membership gate
-	 * and a subscriber's `reactivityTopicId(reactivityTailBytes(tail))` use, NOT the double-hashing
-	 * `blockIdToBytes`). So `oldTopicId = reactivityTopicId(oldAnchorBytes)` is byte-identical to the topic a
+	 * (`reactivityTailBytes(event.tailId)` in production — the SAME raw utf8 encoding origination's membership
+	 * gate and a subscriber's `reactivityTopicId(reactivityTailBytes(tail))` use, never a pre-hashed digest).
+	 * So `oldTopicId = reactivityTopicId(oldAnchorBytes)` is byte-identical to the topic a
 	 * subscriber subscribed under — a mismatch would silently never redirect.
 	 */
 	private detectTailRotation(event: CollectionChangeEvent, ctx: OriginationCollectionContext): void {

package/src/reactivity/recover-transport.ts

@@ -19,7 +19,8 @@
  *  - {@link createRecoverRequestHandler} / {@link registerRecoverHandler} — the **inbound** serve handler.
  *    Decode (bounded) → verify the request's peer-key signature against the dialing peer → reject a
  *    replay/stale request → resolve the live `PushState` → `serveBackfill` / `serveResume` → reply. Any
- *    failure produces **no reply** (the stream aborts) rather than throwing out of the handler.
+ *    failure **declines** rather than throwing out of the handler: the member sends a zero-length reply (no
+ *    result), and the dialing transport falls through to the next cohort candidate.
  *
  * ## Dial-target encoding bridge (load-bearing)
  *
@@ -60,7 +61,7 @@ import {
 	type CorrelationReplayGuard,
 	type RotationRedirectV1,
 } from "@optimystic/db-core";
-import { requestResponse, handleRequestResponse, DEFAULT_STREAM_MAX_BYTES } from "../cohort-topic/stream-util.js";
+import { requestResponse, handleRequestResponse, NoResultReplyError, DEFAULT_STREAM_MAX_BYTES } from "../cohort-topic/stream-util.js";
 import { verifyPeerSig, signPeerSig } from "../cohort-topic/peer-sig.js";
 import { peerIdToBytes, bytesToPeerIdString } from "../cohort-topic/peer-codec.js";
 import { PROTOCOL_REACTIVITY_RECOVER } from "./protocols.js";
@@ -134,8 +135,12 @@ export class RotationRedirectError extends Error {
 
 /** The wire exchange seam: open the recover protocol to `target`, send `frame`, return the bounded reply. */
 export interface RecoverDialer {
-	/** Exchange one request frame for one reply frame with `target` (peer-id string). Rejects on a dial failure. */
-	exchange(target: string, frame: Uint8Array): Promise<Uint8Array>;
+	/**
+	 * Exchange one request frame for one reply frame with `target` (peer-id string). Resolves `undefined` when
+	 * the member declined (no served state, a failed signature / replay check, an undecodable request) — the
+	 * same contract as {@link requestResponse}. Rejects on a dial failure.
+	 */
+	exchange(target: string, frame: Uint8Array): Promise<Uint8Array | undefined>;
 }
 
 /** Build the production libp2p-backed {@link RecoverDialer} over {@link requestResponse}. */
@@ -162,9 +167,11 @@ export interface Libp2pReactivityRecoverTransportOptions {
 /**
  * The outbound recover transport: one instance per node, exposing the two db-core function seams against it.
  * Each returned transport dials the **sticky primary first** (one round trip after a brief flap), falling
- * back to a **cohort-walk** member on a dial failure (any member that holds the topic's gossiped `PushState`
- * can answer). A kind mismatch or all-targets-failed surfaces as a rejection so the caller's retry/escalation
- * policy (the subscription manager's backfill escalation, or `manager.resume()`'s caller) takes over.
+ * back to a **cohort-walk** member on a dial failure *or* when the dialed member declines (any member that
+ * holds the topic's gossiped `PushState` can answer, so one member with nothing to serve must not end the
+ * walk). A kind mismatch, an undecodable reply, or every target failing / declining surfaces as a rejection
+ * so the caller's retry/escalation policy (the subscription manager's backfill escalation, or
+ * `manager.resume()`'s caller) takes over.
  */
 export class Libp2pReactivityRecoverTransport {
 	private readonly dialer: RecoverDialer;
@@ -206,10 +213,13 @@ export class Libp2pReactivityRecoverTransport {
 	}
 
 	/**
-	 * Exchange one recover frame with the first reachable target: sticky primary, then each cohort-walk
-	 * member. A **dial failure** falls through to the next candidate; a successful dial is **terminal** (the
-	 * member answered for the cohort) — a `kind: "rotated"` redirect throws {@link RotationRedirectError}, and
-	 * a reply decoding to the wrong `kind` is a protocol error. Throws when no candidate succeeds.
+	 * Exchange one recover frame with the first target that answers: sticky primary, then each cohort-walk
+	 * member. A **dial failure** and a **declined** request (the member had no result — no served state, a
+	 * failed signature / replay check, an undecodable request) both fall through to the next candidate. A
+	 * reply frame is **terminal** (the member answered for the cohort): a `kind: "rotated"` redirect throws
+	 * {@link RotationRedirectError}, and a reply that fails to decode or decodes to the wrong `kind` is a
+	 * protocol error. When no candidate answers, throws the last candidate's outcome — a
+	 * {@link NoResultReplyError} if it declined, its dial error if it failed to dial.
 	 */
 	private async exchange(kind: RecoverKind, frame: Uint8Array, topicId: Uint8Array, collectionId: string): Promise<RecoverReplyV1> {
 		const targets = this.selectTargets(topicId, collectionId);
@@ -218,7 +228,7 @@ export class Libp2pReactivityRecoverTransport {
 		}
 		let lastErr: unknown;
 		for (const target of targets) {
-			let replyFrame: Uint8Array;
+			let replyFrame: Uint8Array | undefined;
 			try {
 				replyFrame = await this.dialer.exchange(target, frame);
 			} catch (err) {
@@ -226,6 +236,15 @@ export class Libp2pReactivityRecoverTransport {
 				log("recover dial to %s failed, trying next target: %o", target, err);
 				continue;
 			}
+			if (replyFrame === undefined) {
+				// Declined → fall back to the next candidate, resending the same signed frame.
+				// NOTE: the resend is admissible only because each node's `CorrelationReplayGuard` is node-local
+				// (`RecoverServeDeps.replayGuard`). If the guard is ever shared across a cohort, the retried frame
+				// would be rejected everywhere as a replay, and each fallthrough would need a freshly signed request.
+				lastErr = new NoResultReplyError(`reactivity recover ${kind} from ${target}`);
+				log("recover %s declined by %s, trying next target", kind, target);
+				continue;
+			}
 			const reply = decodeRecoverReplyV1(replyFrame, this.maxBytes); // a decode failure here is terminal
 			// A rotated cohort answered authoritatively: surface the redirect and stop the walk (terminal, never
 			// a fallthrough — the dialed member spoke for the cohort).
@@ -298,17 +317,17 @@ export interface RecoverServeDeps {
 /**
  * Verify the request's peer-key signature against the dialing peer, then admit it through the freshness +
  * anti-replay guard. The dialing peer's id **is** the signer (no signer-id field on the wire); the signature
- * bytes are the anti-replay key (globally unique + authenticated). Returns `false` (reject, no reply) on a
+ * bytes are the anti-replay key (globally unique + authenticated). Returns `false` (decline) on a
  * bad signature, a stale/future timestamp, or a replay.
  */
 function verifyAndAdmit(deps: RecoverServeDeps, signerId: string, payload: Uint8Array, signatureB64: string, timestamp: number, now: number): boolean {
 	const signature = b64urlToBytes(signatureB64);
 	if (!verifyPeerSig(signerId, payload, signature)) {
-		log("recover serve: signature verification failed for %s (no reply)", signerId);
+		log("recover serve: signature verification failed for %s (declined)", signerId);
 		return false;
 	}
 	if (!deps.replayGuard.accept(signature, peerIdToBytes(signerId), timestamp, now)) {
-		log("recover serve: replay/stale request from %s (no reply)", signerId);
+		log("recover serve: replay/stale request from %s (declined)", signerId);
 		return false;
 	}
 	return true;
@@ -329,7 +348,7 @@ function serveBackfillReply(deps: RecoverServeDeps, req: BackfillV1, now: number
 	}
 	const ps = deps.pushStateForCollection(req.collectionId);
 	if (ps === undefined) {
-		return undefined; // not a serving member for this collection → no reply (subscriber walks/chain-reads)
+		return undefined; // not a serving member for this collection → decline (the subscriber tries the next member)
 	}
 	const backfillReply = serveBackfill(ps.replayBuffer, req, ps.collectionId);
 	return encodeRecoverReplyV1({ v: 1, kind: "backfill", backfillReply }, maxBytes);
@@ -371,10 +390,8 @@ function serveResumeReply(deps: RecoverServeDeps, req: ResumeV1, now: number): U
  * Build the recover serve callback for {@link handleRequestResponse}: it returns the reply frame, or
  * `undefined` on a decode/verify/replay/resolve failure. It never throws out of the handler.
  *
- * NOTE: `undefined` reaches the dialer as an explicit zero-length frame, and
- * {@link Libp2pReactivityRecoverTransport.exchange} decodes that as a *terminal* protocol error rather
- * than falling through to the next cohort candidate — one member declining ends the whole recover walk.
- * Tracked as `debt-stream-reply-no-result-untyped`.
+ * `undefined` reaches the dialer as a zero-length frame, which {@link requestResponse} resolves as no result
+ * and {@link Libp2pReactivityRecoverTransport} treats as a decline — it tries the next cohort candidate.
  */
 export function createRecoverRequestHandler(deps: RecoverServeDeps): (frame: Uint8Array, fromPeer: PeerId) => Promise<Uint8Array | undefined> {
 	const maxBytes = deps.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
@@ -398,8 +415,8 @@ export function createRecoverRequestHandler(deps: RecoverServeDeps): (frame: Uin
 			return Promise.resolve(serveResumeReply(deps, r, now));
 		} catch (err) {
 			// A malformed/foreign request (decode failure, foreign collectionId from serve*) must never throw
-			// out of the stream handler: log + no reply (a zero-length reply frame; see the note above).
-			log("recover serve: dropping request (no reply): %o", err);
+			// out of the stream handler: log + decline (a zero-length reply; the dialer tries the next member).
+			log("recover serve: dropping request (declined): %o", err);
 			return Promise.resolve(undefined);
 		}
 	};

package/src/reactivity/subscription-manager.ts

@@ -82,8 +82,8 @@ export interface ReactivitySubscriptionManagerOptions {
 	 *
 	 * **Load-bearing encoding contract.** When a production subscribe factory converts a `BlockId` tail to
 	 * these bytes it MUST use `reactivityTailBytes(tailId)` (`reactivity/topic-bytes.ts`) — the SAME function
-	 * origination's membership gate uses — NOT db-core's `blockIdToBytes` (which `sha256`s first → a double
-	 * hash). Origination derives the topic's `coord_0` cohort from `reactivityTopicId(reactivityTailBytes(
+	 * origination's membership gate uses — never a pre-hashed digest of the id, which would double-hash.
+	 * Origination derives the topic's `coord_0` cohort from `reactivityTopicId(reactivityTailBytes(
 	 * tailId))`; if this side feeds differently-encoded bytes it subscribes to a *different* coord and
 	 * origination silently never reaches it (the `topic-bytes-encoding` spec pins the coord-equality).
 	 */

package/src/reactivity/topic-bytes.ts

@@ -1,37 +1,35 @@
-/**
- * Reactivity — the one pinned `BlockId` → raw tail-bytes encoding, shared by origination and subscription.
- *
- * `reactivityTopicId` (db-core) hashes `H(tailBytes ‖ "reactivity")` to derive the topic's `coord_0`
- * cohort. Origination (the cohort-change membership gate, {@link
- * import("../cohort-topic/reactivity-membership-gate.js").createReactivitySelfMembershipGate}) and the
- * subscriber side (the production subscribe factory that converts a `BlockId` `tailIdAtAttach` to the bytes
- * {@link import("./subscription-manager.js").ReactivitySubscriptionManager} feeds `reactivityTopicId`) MUST
- * feed it the **same** bytes for a given tail, or they resolve different coords and origination silently
- * never reaches subscribers (green tests, dead feature).
- *
- * This module is that single source of truth: `reactivityTailBytes(tailId) = TextEncoder().encode(tailId)`,
- * the synchronous block-id→bytes convention the rest of db-p2p already uses for ring hashing of tail ids
- * (`cluster/client.ts`, `repo/client.ts`). db-core's async `blockIdToBytes` (which `sha256`s the utf8 bytes
- * first) is deliberately NOT used: it would (a) double-hash relative to the spec's `H(tailId ‖ "reactivity")`
- * and (b) force the synchronous origination gate to become async.
- *
- * It lives in the reactivity surface (not buried in the gate) so the subscribe path and the gate import the
- * exact same function rather than re-deriving the encoding independently. The
- * `cohort-topic/reactivity-membership-gate.ts` module re-exports it for its existing callers.
- */
-
-import type { BlockId } from "@optimystic/db-core";
-
-const utf8 = new TextEncoder();
-
-/**
- * The pinned `BlockId` → raw tail bytes encoding fed into `reactivityTopicId`: the **raw** utf8 bytes of the
- * tail block-id string (NOT a pre-hashed routing key, NOT db-core's double-hashing `blockIdToBytes`).
- *
- * Load-bearing: origination and the subscriber side must call this **same** function for a given tail (see
- * the module doc) — a mismatch resolves different `coord_0`s and origination silently never reaches
- * subscribers. The `topic-bytes-encoding` spec pins the coord-equality both ways.
- */
-export function reactivityTailBytes(tailId: BlockId): Uint8Array {
-	return utf8.encode(tailId);
-}
+/**
+ * Reactivity — the one pinned `BlockId` → raw tail-bytes encoding, shared by origination and subscription.
+ *
+ * `reactivityTopicId` (db-core) hashes `H(tailBytes ‖ "reactivity")` to derive the topic's `coord_0`
+ * cohort. Origination (the cohort-change membership gate, {@link
+ * import("../cohort-topic/reactivity-membership-gate.js").createReactivitySelfMembershipGate}) and the
+ * subscriber side (the production subscribe factory that converts a `BlockId` `tailIdAtAttach` to the bytes
+ * {@link import("./subscription-manager.js").ReactivitySubscriptionManager} feeds `reactivityTopicId`) MUST
+ * feed it the **same** bytes for a given tail, or they resolve different coords and origination silently
+ * never reaches subscribers (green tests, dead feature).
+ *
+ * This module is that single source of truth: `reactivityTailBytes(tailId)` is the tail's routing key
+ * (db-core's `routingKeyForBlock`, the raw utf8 of the id) — the same bytes every cohort lookup for that
+ * block is keyed on. It must stay raw: a pre-hashed digest would double-hash relative to the spec's
+ * `H(tailId ‖ "reactivity")`.
+ *
+ * It lives in the reactivity surface (not buried in the gate) so the subscribe path and the gate import the
+ * exact same function rather than re-deriving the encoding independently. The
+ * `cohort-topic/reactivity-membership-gate.ts` module re-exports it for its existing callers.
+ */
+
+import type { BlockId } from "@optimystic/db-core";
+import { routingKeyForBlock } from "@optimystic/db-core";
+
+/**
+ * The pinned `BlockId` → raw tail bytes encoding fed into `reactivityTopicId`: the tail's routing key, i.e.
+ * the **raw** utf8 bytes of the tail block-id string (never a pre-hashed digest).
+ *
+ * Load-bearing: origination and the subscriber side must call this **same** function for a given tail (see
+ * the module doc) — a mismatch resolves different `coord_0`s and origination silently never reaches
+ * subscribers. The `topic-bytes-encoding` spec pins the coord-equality both ways.
+ */
+export function reactivityTailBytes(tailId: BlockId): Uint8Array {
+	return routingKeyForBlock(tailId);
+}

package/src/repo/client.ts

@@ -1,173 +1,172 @@
-import type {
-	IRepo, GetBlockResults, PendSuccess, StaleFailure, ActionBlocks, MessageOptions, CommitResult,
-	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 type { RedirectPayload } from "./redirect.js";
-import { MAX_BLOCK_MESSAGE_BYTES } from "../protocol-limits.js";
-import { peerIdFromString } from "@libp2p/peer-id";
-
-export class RepoClient extends ProtocolClient implements IRepo {
-	private constructor(peerId: PeerId, peerNetwork: IPeerNetwork, readonly protocolPrefix?: string) {
-		super(peerId, peerNetwork);
-	}
-
-	/** Create a new client instance */
-	public static create(peerId: PeerId, peerNetwork: IPeerNetwork, protocolPrefix?: string): RepoClient {
-		return new RepoClient(peerId, peerNetwork, protocolPrefix);
-	}
-
-	async get(blockGets: BlockGets, options: MessageOptions): Promise<GetBlockResults> {
-		return this.processRepoMessage<GetBlockResults>(
-			[{ get: blockGets }],
-			options
-		);
-	}
-
-	async pend(request: PendRequest, options: MessageOptions): Promise<PendSuccess | StaleFailure> {
-		return this.processRepoMessage<PendSuccess | StaleFailure>(
-			[{ pend: request }],
-			options
-		);
-	}
-
-	async cancel(actionRef: ActionBlocks, options: MessageOptions): Promise<void> {
-		return this.processRepoMessage<void>(
-			[{ cancel: { actionRef } }],
-			options
-		);
-	}
-
-	async commit(request: CommitRequest, options: MessageOptions): Promise<CommitResult> {
-		return this.processRepoMessage<CommitResult>(
-			[{ commit: request }],
-			options
-		);
-	}
-
-	private extractCorrelationId(operations: RepoMessage['operations']): string | undefined {
-		const op = operations[0];
-		if (!op) return undefined;
-		if ('pend' in op) return op.pend.actionId;
-		if ('commit' in op) return op.commit.actionId;
-		if ('cancel' in op) return op.cancel.actionRef.actionId;
-		return undefined;
-	}
-
-	private async processRepoMessage<T>(
-		operations: RepoMessage['operations'],
-		options: MessageOptions,
-		hop: number = 0
-	): Promise<T> {
-		const message: RepoMessage = {
-			operations,
-			expiration: options.expiration,
-		};
-		const correlationId = this.extractCorrelationId(operations);
-		const deadline = options.expiration ?? (Date.now() + 30_000)
-		const deadlineMs = Math.max(1, deadline - Date.now())
-		const preferred = (this.protocolPrefix ?? '/db-p2p') + '/repo/1.0.0'
-
-		// 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,
-				// A get response carries block data → block cap (not control).
-				maxDataLength: MAX_BLOCK_MESSAGE_BYTES,
-			})
-		} finally {
-			clearTimeout(timer)
-		}
-
-		// Type the redirect branch against the payload the service actually produces
-		// (`RedirectPayload`) rather than reading it off the `any` response — the untyped read
-		// is what let the `addrs` the sender embedded fall on the floor.
-		const redirectResponse = response as Partial<RedirectPayload>
-		if (redirectResponse?.redirect?.peers?.length) {
-			if (hop >= 2) {
-				throw new Error('Redirect loop detected in RepoClient (max hops reached)')
-			}
-			const currentIdStr = this.peerId.toString()
-			const peers = redirectResponse.redirect.peers
-			const next = peers.find((p) => p.id !== currentIdStr) ?? peers[0]!
-			const nextId = peerIdFromString(next.id)
-			if (next.id === currentIdStr) {
-				throw new Error('Redirect loop detected in RepoClient (same peer)')
-			}
-			// Learn the redirect target's addresses BEFORE dialing it: the redirect is the only
-			// notice we get that this peer matters, and if it is relay-only we have no address
-			// for it at all. Merging after the dial would help only some later hop.
-			this.peerNetwork.recordPeerAddresses?.(nextId, next.addrs ?? [])
-			// 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)
-		}
-		return response as T;
-	}
-
-	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 ? await blockIdToBytes(id) : undefined;
-		}
-		if ('pend' in op) {
-			// 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) {
-			// 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 ? await blockIdToBytes(id) : undefined;
-		}
-		return undefined;
-	}
-
-	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)
-		}
-	}
-
-}
+import type {
+	IRepo, GetBlockResults, PendSuccess, StaleFailure, ActionBlocks, MessageOptions, CommitResult,
+	PendRequest, CommitRequest, BlockGets, IPeerNetwork, PeerId, BlockId
+} from "@optimystic/db-core";
+import type { RepoMessage } from "@optimystic/db-core";
+import { blockIdsForTransforms } from "@optimystic/db-core";
+import { ProtocolClient } from "../protocol-client.js";
+import type { RedirectPayload } from "./redirect.js";
+import { MAX_BLOCK_MESSAGE_BYTES } from "../protocol-limits.js";
+import { peerIdFromString } from "@libp2p/peer-id";
+
+export class RepoClient extends ProtocolClient implements IRepo {
+	private constructor(peerId: PeerId, peerNetwork: IPeerNetwork, readonly protocolPrefix?: string) {
+		super(peerId, peerNetwork);
+	}
+
+	/** Create a new client instance */
+	public static create(peerId: PeerId, peerNetwork: IPeerNetwork, protocolPrefix?: string): RepoClient {
+		return new RepoClient(peerId, peerNetwork, protocolPrefix);
+	}
+
+	async get(blockGets: BlockGets, options: MessageOptions): Promise<GetBlockResults> {
+		return this.processRepoMessage<GetBlockResults>(
+			[{ get: blockGets }],
+			options
+		);
+	}
+
+	async pend(request: PendRequest, options: MessageOptions): Promise<PendSuccess | StaleFailure> {
+		return this.processRepoMessage<PendSuccess | StaleFailure>(
+			[{ pend: request }],
+			options
+		);
+	}
+
+	async cancel(actionRef: ActionBlocks, options: MessageOptions): Promise<void> {
+		return this.processRepoMessage<void>(
+			[{ cancel: { actionRef } }],
+			options
+		);
+	}
+
+	async commit(request: CommitRequest, options: MessageOptions): Promise<CommitResult> {
+		return this.processRepoMessage<CommitResult>(
+			[{ commit: request }],
+			options
+		);
+	}
+
+	private extractCorrelationId(operations: RepoMessage['operations']): string | undefined {
+		const op = operations[0];
+		if (!op) return undefined;
+		if ('pend' in op) return op.pend.actionId;
+		if ('commit' in op) return op.commit.actionId;
+		if ('cancel' in op) return op.cancel.actionRef.actionId;
+		return undefined;
+	}
+
+	private async processRepoMessage<T>(
+		operations: RepoMessage['operations'],
+		options: MessageOptions,
+		hop: number = 0
+	): Promise<T> {
+		const message: RepoMessage = {
+			operations,
+			expiration: options.expiration,
+		};
+		const correlationId = this.extractCorrelationId(operations);
+		const deadline = options.expiration ?? (Date.now() + 30_000)
+		const deadlineMs = Math.max(1, deadline - Date.now())
+		const preferred = (this.protocolPrefix ?? '/db-p2p') + '/repo/1.0.0'
+
+		// 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
+		)
+		// Explicit combinator rather than the native `AbortSignal.any`, which Hermes
+		// (React Native's JS engine) does not provide. This has to forward whichever
+		// source signal's *reason* fired — that's how the caller-facing 'RepoClient
+		// timeout' message above (and any reason a caller's own `options.signal` carries)
+		// survives the combine. `any-signal` (the package libp2p itself uses for this) was
+		// tried and rejected here: it calls the composite `AbortController.abort()` with no
+		// argument, which discards the source reason and replaces it with a generic
+		// AbortError — confirmed against both Node's native `AbortSignal.any` and
+		// `any-signal@4.1.1` directly. Listeners are removed in the `finally` below so a
+		// long-lived caller `options.signal` never accumulates one per call.
+		const abortController = new AbortController()
+		const forwardAbort = (source: AbortSignal) => (): void => abortController.abort(source.reason)
+		const onCallerAbort = options?.signal ? forwardAbort(options.signal) : undefined
+		const onDeadlineAbort = forwardAbort(deadlineController.signal)
+		deadlineController.signal.addEventListener('abort', onDeadlineAbort, { once: true })
+		if (options?.signal) {
+			if (options.signal.aborted) abortController.abort(options.signal.reason)
+			else options.signal.addEventListener('abort', onCallerAbort!, { once: true })
+		}
+		const combinedSignal = abortController.signal
+		let response: any
+		try {
+			response = await super.processMessage<any>(message, preferred, {
+				signal: combinedSignal,
+				correlationId,
+				dialTimeoutMs: options?.dialTimeoutMs,
+				// A get response carries block data → block cap (not control).
+				maxDataLength: MAX_BLOCK_MESSAGE_BYTES,
+			})
+		} finally {
+			clearTimeout(timer)
+			deadlineController.signal.removeEventListener('abort', onDeadlineAbort)
+			if (onCallerAbort) options?.signal?.removeEventListener('abort', onCallerAbort)
+		}
+
+		// Type the redirect branch against the payload the service actually produces
+		// (`RedirectPayload`) rather than reading it off the `any` response — the untyped read
+		// is what let the `addrs` the sender embedded fall on the floor.
+		const redirectResponse = response as Partial<RedirectPayload>
+		if (redirectResponse?.redirect?.peers?.length) {
+			if (hop >= 2) {
+				throw new Error('Redirect loop detected in RepoClient (max hops reached)')
+			}
+			const currentIdStr = this.peerId.toString()
+			const peers = redirectResponse.redirect.peers
+			const next = peers.find((p) => p.id !== currentIdStr) ?? peers[0]!
+			const nextId = peerIdFromString(next.id)
+			if (next.id === currentIdStr) {
+				throw new Error('Redirect loop detected in RepoClient (same peer)')
+			}
+			// Learn the redirect target's addresses BEFORE dialing it: the redirect is the only
+			// notice we get that this peer matters, and if it is relay-only we have no address
+			// for it at all. Merging after the dial would help only some later hop.
+			this.peerNetwork.recordPeerAddresses?.(nextId, next.addrs ?? [])
+			// Cache hint: a follow-up op on this block can dial the target directly.
+			const coordinated = this.coordinatedBlockId(operations)
+			if (coordinated) this.recordCoordinatorHint(coordinated, 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)
+		}
+		return response as T;
+	}
+
+	/**
+	 * The block a redirected op is coordinated on — the block `RepoService.deriveBlockKey` redirected
+	 * it by, and so the block its coordinator hint belongs to.
+	 */
+	private coordinatedBlockId(ops: RepoMessage['operations']): BlockId | undefined {
+		const op = ops[0];
+		if (!op) return undefined;
+		if ('get' in op) return op.get.blockIds[0];
+		// Key on a real block id the pend touches, NOT a structural transforms field
+		// name ('inserts'/'updates'/'deletes'); see RepoService.deriveBlockKey.
+		if ('pend' in op) return blockIdsForTransforms(op.pend.transforms)[0];
+		// Anchor on blockIds[0] (where CoordinatorRepo.commit runs consensus +
+		// verifyResponsibility), NOT tailId — they differ for a non-tail batch.
+		if ('commit' in op) return op.commit.blockIds[0];
+		if ('cancel' in op) return op.cancel.actionRef.blockIds[0];
+		return undefined;
+	}
+
+}