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

package/src/repo/i-under-replication-ledger.ts

@@ -0,0 +1,89 @@
+import type { ActionId, BlockId, DurabilityQuorum } from "@optimystic/db-core";
+
+/**
+ * The classes a commit can be acknowledged at while still owing somebody a copy. `full` is excluded
+ * by type: a block every cohort member confirmed owes nobody a push, so an entry recording one is
+ * a contradiction rather than a state to handle.
+ */
+export type ShortfallQuorum = Exclude<DurabilityQuorum, 'full'>;
+
+/** One block this node acknowledged below full replication, and who is still missing it. */
+export type UnderReplicatedEntry = {
+	readonly blockId: BlockId;
+	/** The highest under-replicated revision of this block. A later revision SUPERSEDES an earlier
+	 *  one: pushing the newer materialization satisfies the older, so entries are keyed by block
+	 *  alone and this field is overwritten, never appended to. */
+	readonly rev: number;
+	readonly actionId: ActionId;
+	/** The class the commit was acknowledged at — `local`, `unrouted`, or `majority`. */
+	readonly quorum: ShortfallQuorum;
+	/** Cohort members that had not confirmed holding `rev`, by peer-id string.
+	 *  EMPTY when the cohort could not be named (`local`, `unrouted`): there was nobody to name,
+	 *  and the drain must re-resolve the cohort at drain time instead. An empty array therefore
+	 *  means "unknown", not "nobody". */
+	readonly missingPeerIds: readonly string[];
+	/** When this shortfall was first recorded, in milliseconds since the epoch. */
+	readonly recordedAt: number;
+	/** Consecutive unsuccessful drain rounds — the give-up counter the drain owns. */
+	readonly attempts: number;
+};
+
+/**
+ * The durable record of blocks this node acknowledged below full replication. Written by
+ * `CoordinatorRepo.commit` at the moment it answers the writer — the only moment the missing
+ * members are known — and read by whatever pushes the missing copies later.
+ *
+ * Every operation on one block is applied in call order, so each read-compare-write below is atomic
+ * with respect to the others for the same block. That guarantee is per ledger INSTANCE: one node owns
+ * one ledger over its key-value store, and a second instance writing the same store concurrently is
+ * outside it.
+ */
+export interface IUnderReplicationLedger {
+	/**
+	 * Record a block's shortfall. Against an existing entry for the same block:
+	 * - a HIGHER `rev` replaces it outright, `attempts` and `recordedAt` included — a fresh shortfall
+	 *   deserves a fresh give-up budget;
+	 * - the SAME `rev` is the same shortfall observed again: the new `quorum` and `missingPeerIds`
+	 *   replace the old, and the existing `recordedAt` and `attempts` are kept;
+	 * - a LOWER `rev` is skipped, so a slow older commit cannot clobber a newer one.
+	 */
+	record(entry: UnderReplicatedEntry): Promise<void>;
+	/**
+	 * A commit at `rev` reached full replication: delete the block's entry, unless that entry records
+	 * a HIGHER revision — a newer shortfall is not settled by an older commit finishing.
+	 */
+	settle(blockId: BlockId, rev: number): Promise<void>;
+	get(blockId: BlockId): Promise<UnderReplicatedEntry | undefined>;
+	/** Every outstanding entry, oldest `recordedAt` first. The drain pages nothing today: the set is
+	 *  bounded by the node's own owned-block count and shrinks as copies land. */
+	list(): Promise<UnderReplicatedEntry[]>;
+	/** How many entries are outstanding — the drain's "is anything still owed" check between
+	 *  passes, so it must be cheap once warm: answered from memory after the first call. */
+	size(): Promise<number>;
+	/**
+	 * Remove `peerIds` from an entry's missing set, deleting the entry when it empties. Returns the
+	 * remaining entry, or `undefined` when it was deleted or never existed.
+	 *
+	 * An entry whose missing set is UNKNOWN (empty — recorded `local` or `unrouted`) is returned
+	 * unchanged: removing named peers from an unknown set cannot prove it empty. `name` its missing
+	 * set first, or `delete` it once the whole re-resolved cohort has confirmed.
+	 *
+	 * `heldRev` is the revision the peers confirmed holding. When given, an entry recording a HIGHER
+	 * revision is returned unchanged: a copy of an older revision says nothing about a newer
+	 * shortfall recorded while that copy was in flight. A copy of a newer revision satisfies an older
+	 * entry — a later revision supersedes an earlier one — so `heldRev` above the entry's is fine.
+	 */
+	satisfy(blockId: BlockId, peerIds: readonly string[], heldRev?: number): Promise<UnderReplicatedEntry | undefined>;
+	/**
+	 * Give an entry recorded with an UNKNOWN missing set the members the drain has since resolved,
+	 * so `satisfy` has a set to shrink. Applies only to the entry as it stands — at exactly `rev`,
+	 * and still unnamed: an entry recording another revision or already naming its members is
+	 * returned unchanged, and an absent one is NOT created (a `record` here would resurrect an entry a
+	 * concurrent `settle` just removed). `recordedAt` and `attempts` are kept. Returns the entry as it
+	 * now stands, or `undefined` when there is none.
+	 */
+	name(blockId: BlockId, rev: number, missingPeerIds: readonly string[]): Promise<UnderReplicatedEntry | undefined>;
+	/** Bump the give-up counter after an unsuccessful drain round. A no-op for an absent entry. */
+	noteAttempt(blockId: BlockId): Promise<void>;
+	delete(blockId: BlockId): Promise<void>;
+}

package/src/repo/kv-under-replication-ledger.ts

@@ -0,0 +1,302 @@
+import type { BlockId } from "@optimystic/db-core";
+import type { IKVStore } from "../storage/i-kv-store.js";
+import type { IUnderReplicationLedger, ShortfallQuorum, UnderReplicatedEntry } from "./i-under-replication-ledger.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('under-replication-ledger');
+
+/**
+ * Key namespace: `under-replicated/<blockId>` → JSON(UnderReplicatedEntry). A fixed literal first
+ * segment, which is what keeps this store safe to share a base path with `FileRawStorage` — see
+ * the NOTE on `FileKVStore.keyToPath` for the condition sharing would break under.
+ */
+export const UNDER_REPLICATED_KEY_PREFIX = 'under-replicated/';
+
+/**
+ * The backstop cap. Generous on purpose: the drain's give-up counter is what retires entries, and
+ * this only stops a node whose partner never returns from growing the ledger without limit.
+ * NOTE: every entry is one small file under `FileKVStore` and one block id held in memory by the
+ * eviction index; if a deployment ever sits at this cap, measure both before raising it.
+ */
+export const DEFAULT_UNDER_REPLICATION_MAX_ENTRIES = 100_000;
+
+export type KvUnderReplicationLedgerOptions = {
+	/** Hard cap on outstanding entries; the oldest-recorded entry is evicted beyond it. Default
+	 *  {@link DEFAULT_UNDER_REPLICATION_MAX_ENTRIES}. Must be at least 1. */
+	maxEntries?: number;
+};
+
+const SHORTFALL_QUORUMS: readonly ShortfallQuorum[] = ['majority', 'local', 'unrouted'];
+
+/**
+ * {@link IUnderReplicationLedger} over the portable {@link IKVStore}, the same shape
+ * `PersistentTransactionStateStore` uses for its node-local state.
+ *
+ * Two pieces of in-memory state sit beside the store, neither authoritative:
+ * - a per-block operation queue, so each read-compare-write is atomic against the others for the
+ *   same block (`IKVStore` has no compare-and-set);
+ * - an eviction index of recorded block ids in oldest-first order, loaded lazily from the store on
+ *   the first mutation, so enforcing `maxEntries` costs neither a directory listing nor a read per
+ *   record. It is only as good as this instance's ownership of the key prefix — the reason the
+ *   interface scopes its guarantees to one instance per store.
+ */
+export class KvUnderReplicationLedger implements IUnderReplicationLedger {
+	private readonly maxEntries: number;
+	private readonly queues = new Map<BlockId, Promise<void>>();
+	private indexLoad: Promise<Set<BlockId>> | undefined;
+
+	constructor(private readonly kv: IKVStore, options?: KvUnderReplicationLedgerOptions) {
+		const maxEntries = options?.maxEntries ?? DEFAULT_UNDER_REPLICATION_MAX_ENTRIES;
+		if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+			throw new Error(`KvUnderReplicationLedger: maxEntries must be a positive integer, got ${maxEntries}`);
+		}
+		this.maxEntries = maxEntries;
+	}
+
+	async record(entry: UnderReplicatedEntry): Promise<void> {
+		await this.serialized(entry.blockId, async () => {
+			const index = await this.index();
+			const existing = await this.read(entry.blockId);
+			if (existing !== undefined && existing.rev > entry.rev) {
+				log('record:skip-lower-rev %o', { blockId: entry.blockId, rev: entry.rev, recordedRev: existing.rev });
+				return;
+			}
+			const sameShortfall = existing !== undefined && existing.rev === entry.rev;
+			const stored: UnderReplicatedEntry = sameShortfall
+				? { ...entry, recordedAt: existing.recordedAt, attempts: existing.attempts }
+				: entry;
+			await this.kv.set(keyFor(entry.blockId), JSON.stringify(stored));
+			if (!sameShortfall) {
+				// A new shortfall is the newest one: move it to the young end of the eviction order.
+				index.delete(entry.blockId);
+				index.add(entry.blockId);
+			}
+		});
+		await this.evictBeyondCap();
+	}
+
+	async settle(blockId: BlockId, rev: number): Promise<void> {
+		await this.serialized(blockId, async () => {
+			// Every fully replicated commit settles each of its blocks, and almost none has an entry:
+			// answer those from the index instead of a store read. An entry missing from the index is
+			// one `read` would report absent anyway (malformed), so nothing is skipped that could be settled.
+			const index = await this.index();
+			if (!index.has(blockId)) return;
+			const existing = await this.read(blockId);
+			if (existing === undefined) return;
+			if (existing.rev > rev) {
+				log('settle:keep-higher-rev %o', { blockId, rev, recordedRev: existing.rev });
+				return;
+			}
+			await this.remove(blockId);
+		});
+	}
+
+	async get(blockId: BlockId): Promise<UnderReplicatedEntry | undefined> {
+		return this.read(blockId);
+	}
+
+	/**
+	 * A full scan. The FIRST scan after start also becomes the eviction index's load, so the drain's
+	 * start pass warms the index for free and the first commit after a restart finds it loaded
+	 * instead of paying for the scan itself.
+	 */
+	async list(): Promise<UnderReplicatedEntry[]> {
+		if (this.indexLoad === undefined) {
+			const scan = this.scan();
+			this.indexLoad = this.indexFrom(scan);
+			return scan;
+		}
+		return this.scan();
+	}
+
+	async size(): Promise<number> {
+		return (await this.index()).size;
+	}
+
+	private async scan(): Promise<UnderReplicatedEntry[]> {
+		const keys = await this.kv.list(UNDER_REPLICATED_KEY_PREFIX);
+		const entries: UnderReplicatedEntry[] = [];
+		// Sequential on purpose: a ledger at its cap under `FileKVStore` is that many files, and
+		// opening them all at once would trade a slower scan for file-descriptor exhaustion.
+		for (const key of keys) {
+			const entry = await this.read(key.slice(UNDER_REPLICATED_KEY_PREFIX.length) as BlockId);
+			if (entry !== undefined) entries.push(entry);
+		}
+		return entries.sort((a, b) => a.recordedAt - b.recordedAt);
+	}
+
+	async satisfy(blockId: BlockId, peerIds: readonly string[], heldRev?: number): Promise<UnderReplicatedEntry | undefined> {
+		return this.serialized(blockId, async () => {
+			const existing = await this.read(blockId);
+			if (existing === undefined) return undefined;
+			if (heldRev !== undefined && existing.rev > heldRev) {
+				log('satisfy:keep-higher-rev %o', { blockId, heldRev, recordedRev: existing.rev });
+				return existing;
+			}
+			// Unknown is not empty: see `IUnderReplicationLedger.satisfy`.
+			if (existing.missingPeerIds.length === 0) return existing;
+			const confirmed = new Set(peerIds);
+			const remaining = existing.missingPeerIds.filter(peerId => !confirmed.has(peerId));
+			if (remaining.length === 0) {
+				await this.remove(blockId);
+				return undefined;
+			}
+			if (remaining.length === existing.missingPeerIds.length) return existing;
+			const updated: UnderReplicatedEntry = { ...existing, missingPeerIds: remaining };
+			await this.kv.set(keyFor(blockId), JSON.stringify(updated));
+			return updated;
+		});
+	}
+
+	async name(blockId: BlockId, rev: number, missingPeerIds: readonly string[]): Promise<UnderReplicatedEntry | undefined> {
+		return this.serialized(blockId, async () => {
+			const existing = await this.read(blockId);
+			if (existing === undefined) return undefined;
+			if (existing.rev !== rev) {
+				log('name:keep-other-rev %o', { blockId, rev, recordedRev: existing.rev });
+				return existing;
+			}
+			if (existing.missingPeerIds.length > 0) return existing;
+			const updated: UnderReplicatedEntry = { ...existing, missingPeerIds: [...missingPeerIds] };
+			await this.kv.set(keyFor(blockId), JSON.stringify(updated));
+			return updated;
+		});
+	}
+
+	async noteAttempt(blockId: BlockId): Promise<void> {
+		await this.serialized(blockId, async () => {
+			const existing = await this.read(blockId);
+			if (existing === undefined) return;
+			const updated: UnderReplicatedEntry = { ...existing, attempts: existing.attempts + 1 };
+			await this.kv.set(keyFor(blockId), JSON.stringify(updated));
+		});
+	}
+
+	async delete(blockId: BlockId): Promise<void> {
+		await this.serialized(blockId, () => this.remove(blockId));
+	}
+
+	/** Delete from the store and the eviction index. Callers hold the block's queue. */
+	private async remove(blockId: BlockId): Promise<void> {
+		const index = await this.index();
+		await this.kv.delete(keyFor(blockId));
+		index.delete(blockId);
+	}
+
+	/**
+	 * Evict oldest-recorded entries until the ledger is back within `maxEntries`. Runs AFTER the
+	 * recording block's queue is released and takes each victim's own queue, so no call ever holds
+	 * two blocks' queues at once and two recordings evicting each other cannot deadlock. A victim a
+	 * concurrent operation already removed is skipped, and the loop re-measures, so concurrent
+	 * recordings at the cap never evict more than the overflow.
+	 *
+	 * An eviction failure is logged and ends the pass rather than failing the recording that
+	 * triggered it: that entry is already written, and the next recording tries again.
+	 */
+	private async evictBeyondCap(): Promise<void> {
+		const index = await this.index();
+		while (index.size > this.maxEntries) {
+			const victim = index.values().next().value;
+			if (victim === undefined) return;
+			try {
+				await this.serialized(victim, async () => {
+					if (!index.has(victim)) return;
+					await this.remove(victim);
+					log('evict:over-cap %o', { blockId: victim, maxEntries: this.maxEntries });
+				});
+			} catch (err) {
+				log.error('evict:failed %o', { blockId: victim, error: (err as Error).message });
+				return;
+			}
+		}
+	}
+
+	/**
+	 * The eviction index, loaded once from the store: every entry's block id, oldest `recordedAt`
+	 * first. A failed load is not cached, so the next mutation retries it instead of the ledger
+	 * failing every write for the life of the process.
+	 *
+	 * NOTE: the load is one read per stored entry. It runs on the first `list`, `size` or mutation
+	 * after start. With the drain wired that is its start pass on every node — `list` when a pushable
+	 * peer is connected, otherwise the `size` that decides whether to arm its re-check — so the load
+	 * runs at boot, off the commit path; without the drain it is the first commit. A solo node keeps
+	 * an entry per block it writes, so a commit that arrives before the load finishes still waits on
+	 * it and can stall on slow storage — see
+	 * `backlog/debt-solo-node-ledger-is-reread-whole-on-first-commit-after-restart`.
+	 */
+	private index(): Promise<Set<BlockId>> {
+		if (this.indexLoad === undefined) {
+			this.indexLoad = this.indexFrom(this.scan());
+		}
+		return this.indexLoad;
+	}
+
+	private indexFrom(scan: Promise<UnderReplicatedEntry[]>): Promise<Set<BlockId>> {
+		return scan
+			.then(entries => new Set(entries.map(entry => entry.blockId)))
+			.catch((err: unknown) => {
+				this.indexLoad = undefined;
+				throw err;
+			});
+	}
+
+	private async read(blockId: BlockId): Promise<UnderReplicatedEntry | undefined> {
+		const raw = await this.kv.get(keyFor(blockId));
+		return raw === undefined ? undefined : parseEntry(blockId, raw);
+	}
+
+	/**
+	 * Run `operation` after every earlier operation queued for `blockId`, whatever their outcome.
+	 * The queue entry is dropped once nothing is waiting behind it, so the map holds only blocks with
+	 * work in flight.
+	 */
+	private async serialized<T>(blockId: BlockId, operation: () => Promise<T>): Promise<T> {
+		const previous = this.queues.get(blockId) ?? Promise.resolve();
+		const run = previous.then(operation);
+		const tail = run.then(() => undefined, () => undefined);
+		this.queues.set(blockId, tail);
+		try {
+			return await run;
+		} finally {
+			if (this.queues.get(blockId) === tail) this.queues.delete(blockId);
+		}
+	}
+}
+
+function keyFor(blockId: BlockId): string {
+	return `${UNDER_REPLICATED_KEY_PREFIX}${blockId}`;
+}
+
+/**
+ * An entry as stored, or `undefined` for one that is not a well-formed entry for `blockId`. Stored
+ * bytes are this class's own output, but they outlive the process that wrote them, so they are
+ * checked rather than cast. A malformed entry is logged and read as absent — never deleted by a
+ * read — and the next recording for the block overwrites it.
+ */
+function parseEntry(blockId: BlockId, raw: string): UnderReplicatedEntry | undefined {
+	let value: unknown;
+	try {
+		value = JSON.parse(raw);
+	} catch (err) {
+		log.error('read:unparseable %o', { blockId, error: (err as Error).message });
+		return undefined;
+	}
+	if (!isEntryFor(blockId, value)) {
+		log.error('read:malformed %o', { blockId, raw });
+		return undefined;
+	}
+	return value;
+}
+
+function isEntryFor(blockId: BlockId, value: unknown): value is UnderReplicatedEntry {
+	if (typeof value !== 'object' || value === null) return false;
+	const entry = value as Record<string, unknown>;
+	return entry.blockId === blockId
+		&& Number.isInteger(entry.rev)
+		&& typeof entry.actionId === 'string'
+		&& SHORTFALL_QUORUMS.includes(entry.quorum as ShortfallQuorum)
+		&& Array.isArray(entry.missingPeerIds) && entry.missingPeerIds.every(peerId => typeof peerId === 'string')
+		&& typeof entry.recordedAt === 'number'
+		&& Number.isInteger(entry.attempts);
+}

package/src/repo/responsibility.ts

@@ -0,0 +1,48 @@
+import type { BlockId } from "@optimystic/db-core";
+
+/**
+ * How long one node's answer to "is this node in the block's cohort?" is reused before it is looked up
+ * again. Shared by the two places that ask it — `CoordinatorRepo`'s write-path responsibility check and
+ * `RepoService`'s redirect check — as a VALUE, never as a cache: they sit on either side of the served-repo
+ * boundary and each keeps its own memo. With one TTL, the two can disagree about a block only inside the
+ * same minute after its cohort changed, and in that window the coordinator's refusal is the backstop.
+ */
+export const RESPONSIBILITY_TTL_MS = 60_000;
+
+/**
+ * Why a node refused a request on responsibility grounds.
+ *  - `not-responsible`: the cohort lookup answered, and this node is not in the cohort for these blocks.
+ *    The request was sent to the wrong machine; the writer re-picks inside the cohort.
+ *  - `undetermined`: the cohort lookup THREW, so this node cannot tell whether it is responsible. A routing
+ *    fault on this node, not a misrouted request — and not a licence to accept: accepting there is what
+ *    let a write commit on a phone that consulted nobody (GitHub #19).
+ */
+export type ResponsibilityRefusalKind = 'not-responsible' | 'undetermined';
+
+/**
+ * A write refused because this node is not, or cannot tell whether it is, responsible for the blocks it
+ * names. Typed so a caller matches on {@link kind} and {@link blockIds} rather than on message text.
+ *
+ * Local only: over the repo protocol a thrown error aborts the stream, so a remote writer sees a failed
+ * batch, not this class. Either way the writer's transactor excludes the peer and re-picks, which is the
+ * whole remedy for both kinds.
+ */
+export class ResponsibilityRefusalError extends Error {
+	constructor(
+		readonly kind: ResponsibilityRefusalKind,
+		/** Every block the refusal is about — all of them, so one log line names the whole misroute. */
+		readonly blockIds: readonly BlockId[],
+		/** Extra context for the message; never parsed. */
+		detail?: string
+	) {
+		super(responsibilityRefusalMessage(kind, blockIds, detail));
+		this.name = 'ResponsibilityRefusalError';
+	}
+}
+
+function responsibilityRefusalMessage(kind: ResponsibilityRefusalKind, blockIds: readonly BlockId[], detail: string | undefined): string {
+	const head = kind === 'not-responsible'
+		? `Not responsible for block(s): ${blockIds.join(', ')}`
+		: `Cannot determine responsibility for block(s): ${blockIds.join(', ')}`;
+	return detail === undefined ? head : `${head} (${detail})`;
+}

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, 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 type { IKeyNetwork, IRepo, RepoMessage } from '@optimystic/db-core'
+import { LruMap, blockIdsForTransforms, routingKeyForBlock } from '@optimystic/db-core'
+import { peerIdFromString } from '@libp2p/peer-id'
 import { encodePeers, type RedirectPayload } from './redirect.js'
 import { MAX_BLOCK_MESSAGE_BYTES } from '../protocol-limits.js'
 import type { Uint8ArrayList } from 'uint8arraylist'
@@ -11,6 +11,8 @@ import { createLogger, type Logger } from '../logger.js'
 import { publishableAddrsForPeer, type AddressLog, type DirectionalConnection } from '../peer-address-book.js'
 import { createInboundStreamAuthorization, type InboundStreamAuthorization, type InboundStreamAuthorizationInit } from '../inbound-authorization.js'
 import { registerProtocolHandler } from '../network/register-protocol-handler.js'
+import type { OptimysticNodeAttachments } from '../optimystic-node.js'
+import { RESPONSIBILITY_TTL_MS } from './responsibility.js'
 
 // Define Components interface
 interface BaseComponents {
@@ -20,13 +22,17 @@ interface BaseComponents {
 	}
 }
 
-export interface NetworkManagerLike {
-	getCluster(key: Uint8Array): Promise<PeerId[]>
-}
+/** The one key-network call the redirect check makes. The node's own `Libp2pKeyPeerNetwork` satisfies it. */
+export type ClusterLookup = Pick<IKeyNetwork, 'findCluster'>
 
 export type RepoServiceComponents = BaseComponents & {
 	repo: IRepo
-	networkManager?: NetworkManagerLike
+	/**
+	 * Where the redirect check asks who is responsible for a block. Absent → the `keyNetwork` attachment of
+	 * the node injected by {@link RepoService.setLibp2p}, which is the production source: the same key
+	 * network the writer's transactor and this node's coordinator ask, so all three apply one rule.
+	 */
+	keyNetwork?: ClusterLookup
 	peerId?: PeerId
 	/**
 	 * Optional resolver for the addresses this node may publish for a redirect target. Async
@@ -58,12 +64,10 @@ export type RepoServiceInit = InboundStreamAuthorizationInit & {
 	logPrefix?: string,
 	kBucketSize?: number,
 	/**
-	 * Responsibility K - the replica set size for determining cluster membership.
-	 * This is distinct from kBucketSize (DHT routing).
-	 * When set, this determines how many peers (by XOR distance) are considered
-	 * responsible for a key. If this node is not in the top responsibilityK peers,
-	 * it will redirect requests to closer peers.
-	 * Default: 1 (only the closest peer handles requests)
+	 * Small-mesh bypass for the redirect check: when the block's cohort has fewer than this many peers,
+	 * the request is handled locally without a membership test (and the coordinator's own responsibility
+	 * check then decides). It does not size the cohort — the key network's `clusterSize` does.
+	 * Default: 1 (only an empty cohort bypasses)
 	 */
 	responsibilityK?: number,
 }
@@ -89,7 +93,7 @@ export class RepoService implements Startable {
 	 * 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,
+	 * service at request time, so the redirect path resolves the key network,
 	 * self identity, and connection addrs through this explicitly-set reference.
 	 */
 	private libp2pRef: Libp2p | undefined
@@ -101,6 +105,16 @@ export class RepoService implements Startable {
 	 * ingress point, instead of keeping it filterable as the single `peer-address-book` namespace.
 	 */
 	private readonly addressLog: AddressLog
+	/**
+	 * Per block key, the responsible peer ids the key network last named: one cohort lookup per block per
+	 * minute on the inbound path, instead of one per request on top of the coordinator's own.
+	 *
+	 * NOTE: same TTL as `CoordinatorRepo`'s responsibility cache, deliberately not the same cache — the two
+	 * sit on either side of the served-repo boundary. Their verdicts can therefore disagree about a block
+	 * only inside the minute after its cohort changes; a request this check wrongly lets through is refused
+	 * by the coordinator, and one it wrongly redirects is followed by the client to a member that serves it.
+	 */
+	private readonly responsibleIds = new LruMap<string, { peerIds: readonly string[], expires: number }>(1000)
 
 	constructor(components: RepoServiceComponents, init: RepoServiceInit = {}) {
 		this.components = components
@@ -159,9 +173,14 @@ export class RepoService implements Startable {
 		this.running = false
 	}
 
-	private getNetworkManager(): NetworkManagerLike | undefined {
-		if (this.components.networkManager) return this.components.networkManager
-		return (this.getLibp2p() as any)?.services?.networkManager as NetworkManagerLike | undefined
+	/**
+	 * The key network the redirect check asks. Absent only before the node attaches it, which happens after
+	 * `start()`; a request in that window is handled locally, where the served-repo proxy has no
+	 * coordinator to hand it to yet either.
+	 */
+	private getKeyNetwork(): ClusterLookup | undefined {
+		if (this.components.keyNetwork) return this.components.keyNetwork
+		return (this.getLibp2p() as Partial<OptimysticNodeAttachments> | undefined)?.keyNetwork
 	}
 
 	private getSelfId(): PeerId | undefined {
@@ -196,7 +215,7 @@ export class RepoService implements Startable {
 	 *   - pend   → blockIdsForTransforms(transforms)[0]
 	 *   - cancel → actionRef.blockIds[0]
 	 *   - commit → blockIds[0]  (CoordinatorRepo.commit anchors consensus on
-	 *     getClusterSize(blockIds[0]) / executeClusterTransaction(blockIds[0]) and guards
+	 *     resolveCohort(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.)
@@ -224,41 +243,59 @@ export class RepoService implements Startable {
 	/**
 	 * Check if this node should redirect the request for a given key.
 	 * Returns a RedirectPayload if not responsible, null if should handle locally.
-	 * Also attaches cluster info to the message for downstream use.
+	 * Also attaches the responsible peer ids to the message for downstream use.
+	 *
+	 * The responsible set comes from the node's own key network — `findCluster` on the block's routing
+	 * key, the same call and the same bytes the writer's transactor and this node's `CoordinatorRepo` use —
+	 * so a correctly routed request is never redirected, including on machines shared by several networks,
+	 * where FRET's raw cohort would include peers that do not serve this one.
+	 *
+	 * A lookup that THROWS splits by operation: a `get` is handled locally (a read is best-effort, and the
+	 * coordinator flags what it could not confirm); every other operation propagates the error, which
+	 * aborts the stream so the writer excludes this peer and re-picks — the posture `CoordinatorRepo` takes
+	 * on the same fault.
 	 */
 	async checkRedirect(blockKey: string, opName: string, message: RepoMessage): Promise<RedirectPayload | null> {
-		const nm = this.getNetworkManager()
-		if (!nm) return null
-
-		// 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))
-
-		const selfId = this.getSelfId()
+		const keyNetwork = this.getKeyNetwork()
+		if (!keyNetwork) return null
+
+		let cluster: readonly string[]
+		try {
+			cluster = await this.responsiblePeerIds(keyNetwork, blockKey)
+		} catch (err) {
+			this.log.error('redirect lookup failed op=%s blockKey=%s - %e', opName, blockKey, err)
+			if (opName === 'get') return null
+			throw err
+		}
+		;(message as RepoMessage & { cluster?: string[] }).cluster = [...cluster]
+
+		const selfId = this.getSelfId()?.toString()
 		if (!selfId) return null
 
-		const isMember = cluster.some((p: PeerId) => peersEqual(p, selfId))
+		const isMember = cluster.includes(selfId)
 		const smallMesh = cluster.length < this.responsibilityK
 
 		if (!smallMesh && !isMember) {
-			const peers = cluster.filter((p: PeerId) => !peersEqual(p, selfId))
 			this.log('redirect op=%s blockKey=%s cluster=%d', opName, blockKey, cluster.length)
-			return encodePeers(await Promise.all(peers.map(async (pid: PeerId) => ({
-				id: pid.toString(),
-				addrs: await this.getPeerAddrs(pid)
+			return encodePeers(await Promise.all(cluster.map(async id => ({
+				id,
+				addrs: await this.getPeerAddrs(peerIdFromString(id))
 			}))))
 		}
 
 		return null
 	}
 
+	/** The block's responsible peer ids, memoized per block key for {@link RESPONSIBILITY_TTL_MS}. A throw is never memoized. */
+	private async responsiblePeerIds(keyNetwork: ClusterLookup, blockKey: string): Promise<readonly string[]> {
+		const now = Date.now()
+		const memo = this.responsibleIds.get(blockKey)
+		if (memo && memo.expires > now) return memo.peerIds
+		const peerIds = Object.keys(await keyNetwork.findCluster(routingKeyForBlock(blockKey)))
+		this.responsibleIds.set(blockKey, { peerIds, expires: now + RESPONSIBILITY_TTL_MS })
+		return peerIds
+	}
+
 	/**
 	 * Handle incoming streams on the repo protocol
 	 */