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

package/src/libp2p-key-network.ts

@@ -1,1260 +1,1377 @@
-import type { AbortOptions, Libp2p, PeerId, Stream } from "@libp2p/interface";
-import { toString as u8ToString } from 'uint8arrays'
-import type { ClusterPeers, CoordinatorIntent, FindCoordinatorOptions, IKeyNetwork, IPeerNetwork } from "@optimystic/db-core";
-import { peerIdFromString } from '@libp2p/peer-id'
-import type { FretService, SerializedTable } from 'p2p-fret'
-import { hashKey } from 'p2p-fret'
-import { createLogger, verbose } from './logger.js'
-import { classifySelfDialability, mergePeerAddresses, publishableConnectionAddr, unionPublishableAddrs, type AddressLog } from './peer-address-book.js'
-import type { IPeerReputation } from './reputation/types.js'
-import { openProtocolStream } from './network/open-protocol-stream.js'
-
-interface WithFretService { services?: { fret?: FretService } }
-
-export type NetworkMode = 'forming' | 'joining';
-
-/**
- * Error codes surfaced by {@link Libp2pKeyPeerNetwork.findCoordinator}. Callers
- * (notably the batch-retry logic in `NetworkTransactor`) can inspect `.code`
- * to distinguish between "transient — try again with different excludes" and
- * "terminal — stop retrying".
- */
-export const FIND_COORDINATOR_ERROR_CODES = {
-	/**
-	 * Last-resort self-coordination was blocked by a HARD verdict from the
-	 * self-coordination guard — self-coordination switched off by config, or a detected
-	 * partition / suspicious shrinkage on a WRITE. Retrying is unlikely to help. A
-	 * *deferrable* denial (see {@link SelfCoordinationDecision.deferrable}) never produces
-	 * this code: selection degrades to self with a warning instead.
-	 */
-	SELF_COORDINATION_BLOCKED: 'SELF_COORDINATION_BLOCKED',
-	/**
-	 * Self-coordination was already attempted and self is now excluded. On a solo
-	 * or bootstrap node with no other peers, this means retries are exhausted and
-	 * the original error from the prior attempt should be surfaced instead.
-	 */
-	SELF_COORDINATION_EXHAUSTED: 'SELF_COORDINATION_EXHAUSTED',
-	/** No peer (including self) is an eligible coordinator. */
-	NO_COORDINATOR_AVAILABLE: 'NO_COORDINATOR_AVAILABLE',
-	/**
-	 * The candidate set was non-empty but every non-self candidate serves a
-	 * DIFFERENT network's protocol (or none of this network's). Distinct from
-	 * NO_COORDINATOR_AVAILABLE so a Sereus-style trace points at the real cause —
-	 * "peer(s) do not serve this network's protocol" — instead of a generic
-	 * "all candidates excluded" / super-majority failure.
-	 */
-	NO_NETWORK_COORDINATOR: 'NO_NETWORK_COORDINATOR'
-} as const;
-
-export type FindCoordinatorErrorCode =
-	typeof FIND_COORDINATOR_ERROR_CODES[keyof typeof FIND_COORDINATOR_ERROR_CODES];
-
-/**
- * Network-membership classification of a peer relative to THIS node's network,
- * derived from the peer's libp2p peerStore protocol list:
- * - `serves`   — advertises this network's namespaced `cluster`/`repo` protocol.
- * - `foreign`  — has a non-empty protocol list but none for this network → another network.
- * - `unknown`  — protocol list empty / peer absent → identify not yet completed. This is
- *                both a fresh same-network peer (will flip to `serves`) AND a cross-network
- *                peer (whose network-namespaced identify can NEVER complete, so it stays
- *                `unknown` forever) — indistinguishable at a single instant, separated over
- *                the retry/stabilization window.
- */
-export type NetworkMembership = 'serves' | 'foreign' | 'unknown';
-
-export class FindCoordinatorError extends Error {
-	readonly code: FindCoordinatorErrorCode;
-	constructor(code: FindCoordinatorErrorCode, message: string) {
-		super(message);
-		this.name = 'FindCoordinatorError';
-		this.code = code;
-	}
-}
-
-/**
- * `.code` on {@link SelfRelayOnlyAddressesError}. A stable string so it survives the
- * `ClusterErrorEnvelope` round trip (`toClusterErrorEnvelope` carries `name` and `code`) and shows
- * up as `code=SELF_RELAY_ONLY_ADDRESSES` on `ProtocolClient`'s `dial:fail` line instead of `none`.
- */
-export const SELF_RELAY_ONLY_ERROR_CODE = 'SELF_RELAY_ONLY_ADDRESSES';
-
-/**
- * Thrown by {@link Libp2pKeyPeerNetwork.connect} when we hold addresses for a peer but EVERY one
- * of them reaches it by relaying through this node.
- *
- * This is the steady state a relay reaches for its own reservation holders: the address such a
- * client advertises is `/<our transport addr>/p2p/<our peer id>/p2p-circuit`, which is correct and
- * useful to every node except us. Dialing it asks us to relay to the client through ourselves, so
- * it can only fail — with an error text (`NoValidAddressesError`, or an `AggregateError` of
- * `Can not dial self`, depending on whether the circuit transport is registered as a dialer here)
- * that is indistinguishable from "nobody ever taught us an address". Retrying cannot help: once the
- * client's connection drops, only the client can re-initiate. So we fail fast and distinctly,
- * letting the caller's existing exclude-and-continue logic move to another cohort member instead of
- * burning a dial timeout.
- */
-export class SelfRelayOnlyAddressesError extends Error {
-	readonly code = SELF_RELAY_ONLY_ERROR_CODE;
-	constructor(peer: string, protocol: string, addrCount: number) {
-		super(
-			`Peer ${peer} is reachable only through a circuit on THIS node: all ${addrCount} address(es) ` +
-			`we hold route back through us, so no dial for ${protocol} can succeed. ` +
-			`Only that peer can re-establish the connection.`
-		);
-		this.name = 'SelfRelayOnlyAddressesError';
-	}
-}
-
-/** Snapshot format this build writes and is willing to read. Bump on any incompatible change. */
-export const PERSISTED_STATE_VERSION = 2 as const;
-
-/**
- * On-disk snapshot of what this node learned about the network last run.
- *
- * `version` is a compatibility fence, not a migration hook: a snapshot that does not carry
- * `PERSISTED_STATE_VERSION` is discarded whole rather than translated. Version 2 exists because
- * FRET 1.0.0-beta.1 made `SerializedPeerEntry.avgLatencyMs` nullable, where `null` means "never
- * measured". Earlier FRET wrote `0` for that case, and 0 now reads as a genuine zero-millisecond
- * round trip — the best possible score, ahead of every honestly measured peer. Since relevance
- * drives next-hop preference *and* capacity eviction, importing such a table would both misroute
- * and permanently evict good peers in favour of phantoms.
- */
-export interface PersistedNetworkState {
-	version: typeof PERSISTED_STATE_VERSION;
-	networkHighWaterMark: number;
-	lastConnectedTimestamp: number;
-	consecutiveIsolatedSessions: number;
-	fretTable?: SerializedTable;
-}
-
-export interface NetworkStatePersistence {
-	load(): Promise<PersistedNetworkState | undefined>;
-	save(state: PersistedNetworkState): Promise<void>;
-}
-
-/**
- * Configuration options for self-coordination behavior
- */
-export interface SelfCoordinationConfig {
-	/** Time (ms) after last connection before allowing self-coordination. Default: 30000 */
-	gracePeriodMs?: number;
-	/** Threshold for suspicious network shrinkage (0-1). >50% drop is suspicious. Default: 0.5 */
-	shrinkageThreshold?: number;
-	/** Allow self-coordination at all. Default: true (for testing). Set false in production. */
-	allowSelfCoordination?: boolean;
-}
-
-/**
- * Decision result from self-coordination guard
- */
-export interface SelfCoordinationDecision {
-	allow: boolean;
-	reason: 'bootstrap-node' | 'partition-detected' | 'suspicious-shrinkage' | 'grace-period-not-elapsed' | 'extended-isolation' | 'hwm-decay' | 'disabled';
-	warn?: boolean;
-	/**
-	 * Set on a denial. `true` means "self is not the PREFERRED coordinator right now, but
-	 * nothing says it is unsafe" — the last-resort tier degrades to self with a warning
-	 * rather than failing the caller. `false` means there is a positive reason to refuse
-	 * (operator config, or evidence of a partition) and the caller is failed.
-	 *
-	 * Hardness by reason, given the caller's {@link CoordinatorIntent}:
-	 *
-	 * | reason                    | write      | read       |
-	 * | ------------------------- | ---------- | ---------- |
-	 * | `disabled`                | hard       | hard       |
-	 * | `grace-period-not-elapsed`| deferrable | deferrable |
-	 * | `partition-detected`      | hard       | deferrable |
-	 * | `suspicious-shrinkage`    | hard       | deferrable |
-	 *
-	 * `grace-period-not-elapsed` is deferrable for BOTH because it is a timing condition
-	 * with no evidence behind it: the same node, with the same FRET table and the same zero
-	 * connections, is allowed to self-coordinate once the clock passes `gracePeriodMs`. It
-	 * postpones an isolated write rather than preventing it (a self-only cohort commits
-	 * under `allowClusterDownsize`, the default), so failing the caller buys no safety.
-	 *
-	 * The read column is uniformly deferrable because none of these reasons protects a
-	 * read: self-coordinating a read means "answer from my own replica", which is what an
-	 * isolated node must accept anyway, and the layers below already report the quality of
-	 * that answer (`CoordinatorRepo.fetchBlockFromCluster` short-circuits a self-only cohort
-	 * as conclusive; an unreachable cohort comes back flagged `unavailable`). `disabled` is
-	 * the exception for both intents — it is an explicit operator switch, not an inference.
-	 *
-	 * NOTE: optional, so a NEW denial branch that forgets to set it silently reads as HARD
-	 * (`findCoordinator` tests `deferrable !== true`) — safe for a write, but it reinstates
-	 * the original defect for a read: an outright lookup failure where degrading to our own
-	 * replica would do. Every denial branch today sets it explicitly. If a fifth reason is
-	 * ever added, either set it there too or split this into a discriminated union
-	 * (`{ allow: true, … } | { allow: false, deferrable: boolean, … }`) so omission is a
-	 * compile error.
-	 */
-	deferrable?: boolean;
-}
-
-export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
-	private readonly selfCoordinationConfig: Required<SelfCoordinationConfig>;
-	private networkHighWaterMark = 1;
-	private lastConnectedTime = Date.now();
-	private consecutiveIsolatedSessions = 0;
-	/**
-	 * NOTE: diagnostic-only — no decision consults this any more. It used to gate the
-	 * coordinator retry window, but it is computed once at construction
-	 * (`bootstrapNodes.length > 0` in `libp2p-node-base.ts`) and never re-derived, so a node
-	 * configured with a bootstrap address it has never reached read as "company is coming"
-	 * forever; {@link retryCouldImprove} asks libp2p for live evidence instead. It still earns
-	 * its keep in the `retry-futile` log line ("configured
-	 * to expect company" vs. "solo by design"). Drop it, or re-derive it from live state, when
-	 * the constructor becomes an options bag — removing the positional parameter now would
-	 * churn ~50 construction sites in `test/libp2p-key-network.spec.ts` for no behaviour change.
-	 */
-	private readonly networkMode: NetworkMode;
-	private readonly persistence?: NetworkStatePersistence;
-
-	// NOTE: seven positional parameters, and the list stays that way for now — converting to an
-	// options bag would touch ~50 construction sites in `test/libp2p-key-network.spec.ts` alone.
-	// Revisit if an eighth parameter is ever needed, or if that spec is being rewritten anyway.
-	constructor(
-		private readonly libp2p: Libp2p,
-		/**
-		 * Replication factor / target cohort breadth for peer selection. REQUIRED, deliberately:
-		 * a silent default here meant a caller that did not know the node's cluster size quietly
-		 * selected a different-width cohort than the node's own consensus path used for the same
-		 * key. Reuse the node's own instance (`node.keyNetwork`) where one exists; a caller that
-		 * genuinely must construct standalone passes `DEFAULT_CLUSTER_SIZE` (`cluster/cluster-policy.ts`).
-		 */
-		private readonly clusterSize: number,
-		selfCoordinationConfig?: SelfCoordinationConfig,
-		networkMode?: NetworkMode,
-		persistence?: NetworkStatePersistence,
-		private readonly reputation?: IPeerReputation,
-		/**
-		 * Network-namespaced protocol prefix (`/optimystic/<networkName>`). When
-		 * provided, coordinator/cohort selection is scoped to peers that serve THIS
-		 * network's `cluster`/`repo` protocol, so a peer that only belongs to another
-		 * network sharing the same physical nodes/bootstraps is never chosen. When
-		 * ABSENT, the membership filter is disabled.
-		 *
-		 * NOTE: optional for the same reason `clusterSize` used to be — "most call sites don't
-		 * know the network name" — and that reason no longer holds: both production sites now
-		 * pass it (`libp2p-node-base.ts`, and the foreign-node fallback in the Quereus
-		 * collection-factory), and only the mock-based cases in `test/libp2p-key-network.spec.ts`
-		 * omit it. So a caller omitting it today gets the filter silently off, exactly the shape
-		 * that let a second key network be built with a wrong cohort width. Left optional because
-		 * making it required would touch ~50 construction sites in that one spec and no reachable
-		 * caller is affected. Make it required (or take the whole list as an options bag) the
-		 * moment a THIRD production construction site appears, or when that spec is rewritten.
-		 */
-		private readonly protocolPrefix?: string
-	) {
-		// Built here rather than as a field initializer: field initializers run before the
-		// constructor body, where `this.libp2p` (a parameter property) is not yet assigned.
-		this.log = createLogger('libp2p-key-network', this.libp2p.peerId.toString())
-		// NOTE: no production construction site in this repo passes a SelfCoordinationConfig —
-		// both leave it `undefined` (libp2p-node-base.ts, and the foreign-node fallback in
-		// quereus-plugin-optimystic's collection-factory.ts), so these defaults are always what
-		// is in force and no operator can tune them. If tuning `gracePeriodMs` is ever needed,
-		// those two sites have to thread the config through first. Low urgency: a grace-period denial no longer fails the caller, it only costs
-		// a write the findCoordinator retry window before self-coordinating — and only when that
-		// window is worth paying at all (see `retryCouldImprove`), so an isolated node pays nothing.
-		this.selfCoordinationConfig = {
-			gracePeriodMs: selfCoordinationConfig?.gracePeriodMs ?? 30_000,
-			shrinkageThreshold: selfCoordinationConfig?.shrinkageThreshold ?? 0.5,
-			allowSelfCoordination: selfCoordinationConfig?.allowSelfCoordination ?? true
-		};
-		this.networkMode = networkMode ?? 'forming';
-		this.persistence = persistence;
-		this.setupConnectionTracking();
-		this.setupSelfAddressTracking();
-	}
-
-	/** The cluster size this instance actually resolved to, for `assertClusterSizeCoupling`. */
-	get effectiveClusterSize(): number {
-		return this.clusterSize;
-	}
-
-	/**
-	 * The network-namespaced protocol prefix (`/optimystic/<networkName>`) selection is scoped to,
-	 * or `undefined` when the network-membership filter is off. Readable so a spec can assert the
-	 * node's attached instance really is network-scoped without reaching into a private field.
-	 */
-	get effectiveProtocolPrefix(): string | undefined {
-		return this.protocolPrefix;
-	}
-
-	// coordinator cache: key (base64url) -> peerId until expiry (bounded LRU-ish via Map insertion order)
-	private readonly coordinatorCache = new Map<string, { id: PeerId, expires: number }>()
-	private static readonly MAX_CACHE_ENTRIES = 1000
-	private readonly log: ReturnType<typeof createLogger>
-	/**
-	 * This instance's logger, in the shape `peer-address-book.ts` accepts. Declared once so the
-	 * five address predicates that take a sink all report under the same peer-id-suffixed
-	 * namespace, rather than five separately-written adapters drifting apart.
-	 */
-	private readonly addressLog: AddressLog = (fmt, ...args) => this.log(fmt, ...args)
-
-	private toCacheKey(key: Uint8Array): string { return u8ToString(key, 'base64url') }
-
-	/**
-	 * Set up connection event tracking to update high water mark and last connected time.
-	 */
-	private setupConnectionTracking(): void {
-		this.libp2p.addEventListener('connection:open', () => {
-			this.updateNetworkObservations();
-		});
-	}
-
-	/**
-	 * This node's own dialable addresses, as strings, memoized between address changes.
-	 *
-	 * `libp2p.getMultiaddrs()` is NOT cheap **when this node has a wildcard listen address**:
-	 * expanding `0.0.0.0` across the host's interfaces goes through `os.networkInterfaces()`, a
-	 * full NIC sweep measured at **3.19 ms of a 3.49 ms call**. Measured per configuration on one
-	 * host: 4.44 ms/call with a TCP listener, **0.001 ms/call with no listen addrs at all** (an
-	 * edge/mobile client dialling out over websockets — nothing to expand, empty address list).
-	 * So the win here is real for listening peers (service and reference nodes, which commit too)
-	 * and near-zero for a dial-only client; do not quote the headline figure at a profile that
-	 * never pays it. Every
-	 * `findCluster` builds a cluster record containing self's addresses, and every commit calls
-	 * `findCluster` through `getClusterPeerIds` — so a cold `apply schema` paid one NIC sweep per
-	 * commit. On a solo node with zero peers that was ~13.8 ms per call and **49% of the whole
-	 * apply** (issue #8); the addresses it recomputed were identical every time.
-	 *
-	 * Invalidated on `self:peer:update`, which libp2p emits whenever this node's own address set
-	 * changes (a transport binding, a relay reservation, an observed-address promotion), so the
-	 * cache cannot outlive its answer. A fresh array is returned on every call: the value goes
-	 * into a `ClusterPeers` record the caller owns and may mutate.
-	 *
-	 * NOTE: the invalidation is not instantaneous, and it is not unconditional. libp2p reaches
-	 * that event through `AddressManager._updatePeerStoreAddresses`, which is **debounced by
-	 * 1000 ms** and then writes the peer record — so for up to about a second after a transport
-	 * starts or stops listening, a record published here can carry the previous address set.
-	 * That write is also fire-and-forget (`.catch` logs and swallows), so a peerStore failure
-	 * leaves this memo stale until the next successful address change. Both are acceptable
-	 * today: addresses change at startup and at relay-reservation time, not per commit, and a
-	 * momentarily-stale record lands on paths that already handle it — a missing address reads
-	 * as `addressless` and a departed one fails the dial, and the caller retries or excludes in
-	 * either case. Revisit if address churn ever becomes routine (frequent relay rotation, a
-	 * mobile node changing networks under load), or if a stale published address ever shows up
-	 * as a dial failure nobody can explain — this memo is the first thing to suspect.
-	 */
-	private selfMultiaddrsCache: string[] | undefined;
-
-	private setupSelfAddressTracking(): void {
-		this.libp2p.addEventListener('self:peer:update', () => {
-			this.selfMultiaddrsCache = undefined;
-		});
-	}
-
-	/** {@link selfMultiaddrsCache}, populated on first use. */
-	private getSelfMultiaddrs(): string[] {
-		this.selfMultiaddrsCache ??= this.libp2p.getMultiaddrs().map(ma => ma.toString());
-		return this.selfMultiaddrsCache.slice();
-	}
-
-	/**
-	 * Update network high water mark and last connected time.
-	 * Called on new connections.
-	 */
-	private updateNetworkObservations(): void {
-		const connections = this.libp2p.getConnections?.() ?? [];
-		if (connections.length > 0) {
-			this.lastConnectedTime = Date.now();
-			this.consecutiveIsolatedSessions = 0;
-		}
-
-		try {
-			const fret = this.getFret();
-			const estimate = fret.getNetworkSizeEstimate();
-			if (estimate.size_estimate > this.networkHighWaterMark) {
-				this.networkHighWaterMark = estimate.size_estimate;
-				this.log('network-hwm-updated mark=%d confidence=%f', this.networkHighWaterMark, estimate.confidence);
-			}
-		} catch {
-			// FRET not available - use connection count as fallback
-			const connectionCount = this.libp2p.getConnections?.().length ?? 0;
-			const observedSize = connectionCount + 1; // +1 for self
-			if (observedSize > this.networkHighWaterMark) {
-				this.networkHighWaterMark = observedSize;
-				this.log('network-hwm-updated mark=%d (from connections)', this.networkHighWaterMark);
-			}
-		}
-
-		this.persistState();
-	}
-
-	async initFromPersistedState(): Promise<void> {
-		if (!this.persistence) return;
-		const state = await this.persistence.load();
-		if (!state) return;
-
-		// Discard, don't translate. A foreign-version snapshot is cheap to replace — the high-water
-		// mark and the peer table are both re-learned within a few stabilization ticks — and far
-		// cheaper than reasoning about what an older FRET meant by any given field.
-		if (state.version !== PERSISTED_STATE_VERSION) {
-			this.log('init:state-discarded version=%o want=%d', state.version, PERSISTED_STATE_VERSION);
-			return;
-		}
-
-		this.networkHighWaterMark = state.networkHighWaterMark;
-		this.lastConnectedTime = state.lastConnectedTimestamp;
-		this.consecutiveIsolatedSessions = state.consecutiveIsolatedSessions;
-
-		if (state.fretTable) {
-			try {
-				// Must be awaited: importTable is async as of FRET 1.0.0-beta.1 and enforces capacity
-				// against the self ring coordinate it hashes on demand. Left floating, the restore
-				// races that enforcement against whatever runs next, and a rejection escapes this
-				// catch entirely rather than being logged as a skipped import.
-				await this.getFret().importTable(state.fretTable);
-			} catch (err) { this.log('init:fret-import-skipped %o', err); }
-		}
-
-		// If HWM > 1 but FRET table is empty/self-only, increment isolated sessions
-		if (state.networkHighWaterMark > 1) {
-			const fretEntryCount = state.fretTable?.entries?.length ?? 0;
-			if (fretEntryCount <= 1) {
-				this.consecutiveIsolatedSessions++;
-				this.log('init:isolated-session count=%d hwm=%d', this.consecutiveIsolatedSessions, this.networkHighWaterMark);
-			}
-		}
-	}
-
-	/**
-	 * Can another attempt plausibly return a BETTER answer than this one did? Consulted ONLY
-	 * when the current attempt found no candidate and the node holds zero connections — i.e.
-	 * purely to decide whether the 500ms inter-attempt sleep is worth paying.
-	 *
-	 * Answered from evidence available NOW, never from configuration or history (`networkMode`
-	 * is frozen at construction and `networkHighWaterMark` is monotonic, so both used to keep
-	 * the window open forever on a node that could never fill it):
-	 *  - a non-self candidate in the FRET neighbourhood for this key — a peer we know of and
-	 *    route to; a connection to it landing during the sleep makes it selectable.
-	 *  - a dial in flight (`queued` / `active` in libp2p's dial queue) — a connection attempt
-	 *    that can complete inside the sleep. This is the signal that covers a
-	 *    configured-but-not-yet-reached bootstrap peer: while its dial runs, the window is
-	 *    worth paying; once the dial has failed, it is not.
-	 *
-	 * Neither present → nothing this call can wait for; break to the last-resort tier.
-	 *
-	 * NOTE: accepted regression — a node with no known peers and no dial in flight that
-	 * received an INBOUND connection during a sleep it now skips will route that one lookup to
-	 * self instead of to the arriving peer. A self pick is never cached, so the next lookup
-	 * picks the peer up; the benefit is that every genuinely isolated lookup stops paying ~1s
-	 * per block. Inbound reachability is deliberately NOT a futility signal: it holds for
-	 * nearly every node with a listen address, so it would neuter the test.
-	 * NOTE: deliberately no `peerStore` scan — "we have a record of a peer" is not "a peer can
-	 * arrive in the next 500ms". A peerStore entry with no FRET entry and no in-flight dial is
-	 * a peer nobody is currently attempting, and the scan is an async datastore iteration on a
-	 * per-lookup hot path.
-	 */
-	private retryCouldImprove(candidateIds: string[]): boolean {
-		if (candidateIds.some(id => id !== this.libp2p.peerId.toString())) return true;
-		return this.dialsInFlight() > 0;
-	}
-
-	/**
-	 * Number of dials libp2p is currently attempting (`queued` or `active`) — a connection
-	 * that can plausibly complete inside the inter-attempt sleep.
-	 *
-	 * Over-inclusive by design: the queue may hold a dial to an excluded, banned, or
-	 * foreign-network peer. That keeps the retry window (conservative, matches the behaviour
-	 * before the futility test existed); cross-referencing it would cost more than the sleep
-	 * it saves. `getDialQueue` is non-optional on the Libp2p interface, so an absent method
-	 * only ever means a test mock — treated as "no evidence of an in-flight dial", exactly as
-	 * `getConnections?.()` is handled elsewhere.
-	 *
-	 * NOTE: this bounds — it does not eliminate — the futile window for the motivating case (a
-	 * node whose only configured bootstrap is unreachable). FRET re-probes such a peer at most
-	 * once per its capped 32s backoff (`fret-service.ts` `recordBackoff`: base 1000ms × factor
-	 * ≤32), and each probe's dial can sit `active` for libp2p's 10s `DIAL_TIMEOUT` — so up to
-	 * roughly a third of wall-clock still has a dial in flight, and lookups in those stretches
-	 * still pay ~1s. Paying there is correct (a succeeding probe makes the peer selectable);
-	 * revisit only if either upstream constant moves far enough to make the duty cycle ~1.
-	 */
-	private dialsInFlight(): number {
-		return (this.libp2p.getDialQueue?.() ?? [])
-			.filter(d => d.status === 'queued' || d.status === 'active').length;
-	}
-
-	/**
-	 * The caller-independent half of eligibility: this peer is neither excluded by the caller
-	 * nor banned by reputation. Shared by all three places `findCoordinator` narrows a candidate
-	 * list — the FRET tier, the connected-peer fallback, and the retry-futility input — so the
-	 * futility test can never disagree with the tiers about who is pickable.
-	 *
-	 * NOTE: eligibility here is deliberately blind to self-dialability, so on a relay
-	 * `findCoordinator` can still pick one of our own reservation holders and only then fail fast
-	 * with `SelfRelayOnlyAddressesError`. The caller's exclude-and-continue walk
-	 * (`db-core/utility/batch-coordinator.ts`) absorbs it, and each such pick now costs an
-	 * instant refusal rather than a burned dial timeout, so it is a selection round-trip, not a
-	 * stall — and the verdict is a live peerStore read that a stale eligibility filter would have
-	 * to guess at. If a relay serving many reservation holders is ever measured spending real time
-	 * walking through them, feed the verdict into the tiers instead of discovering it at dial.
-	 */
-	private isSelectable(id: string, excluded: Set<string>): boolean {
-		return !excluded.has(id) && !(this.reputation?.isBanned(id));
-	}
-
-	private persistState(): void {
-		if (!this.persistence) return;
-		const state: PersistedNetworkState = {
-			version: PERSISTED_STATE_VERSION,
-			networkHighWaterMark: this.networkHighWaterMark,
-			lastConnectedTimestamp: this.lastConnectedTime,
-			consecutiveIsolatedSessions: this.consecutiveIsolatedSessions,
-		};
-		try {
-			const fret = this.getFret();
-			state.fretTable = fret.exportTable();
-		} catch { /* FRET not available */ }
-		void this.persistence.save(state).catch(err => this.log('persist-state-failed %o', err));
-	}
-
-	/**
-	 * Determine if self-coordination should be allowed based on network observations.
-	 *
-	 * Principle: If we've ever seen a larger network, assume our connectivity is the problem,
-	 * not the network shrinking.
-	 *
-	 * A denial is classified as HARD or DEFERRABLE via {@link SelfCoordinationDecision.deferrable}
-	 * — see that field for the reason/intent table. A hard denial fails the caller; a deferrable
-	 * one only means "self is not the preferred coordinator", and the last-resort tier degrades
-	 * to self with a warning.
-	 *
-	 * @param intent What the caller means to do with the coordinator. Defaults to `'write'`,
-	 * the conservative reading, so callers that don't know are held to the stricter bar.
-	 */
-	shouldAllowSelfCoordination(intent: CoordinatorIntent = 'write'): SelfCoordinationDecision {
-		// A read never coordinates a mutation, so every evidence-based denial below is merely
-		// a preference for a better-placed peer — the caller can always be answered from this
-		// node's own replica. Only the explicit `disabled` switch is absolute for a read.
-		const deferrableOnEvidence = intent === 'read';
-
-		// Check global disable
-		if (!this.selfCoordinationConfig.allowSelfCoordination) {
-			return { allow: false, reason: 'disabled', deferrable: false };
-		}
-
-		// Case 1: New/bootstrap node (never seen larger network)
-		if (this.networkHighWaterMark <= 1) {
-			return { allow: true, reason: 'bootstrap-node' };
-		}
-
-		// Case 1b: Repeated isolation across sessions — decay HWM to allow eventual self-coordination
-		if (this.consecutiveIsolatedSessions >= 3) {
-			this.log('self-coord-allowed: hwm-decayed sessions=%d', this.consecutiveIsolatedSessions);
-			return { allow: true, reason: 'hwm-decay', warn: true };
-		}
-
-		// Case 2: Check for partition via FRET
-		try {
-			const fret = this.getFret();
-			if (fret.detectPartition()) {
-				this.log('self-coord-blocked: partition-detected intent=%s', intent);
-				return { allow: false, reason: 'partition-detected', deferrable: deferrableOnEvidence };
-			}
-
-			// Case 3: Suspicious network shrinkage (>threshold drop)
-			const estimate = fret.getNetworkSizeEstimate();
-			const shrinkage = 1 - (estimate.size_estimate / this.networkHighWaterMark);
-			if (shrinkage > this.selfCoordinationConfig.shrinkageThreshold) {
-				this.log('self-coord-blocked: suspicious-shrinkage current=%d hwm=%d shrinkage=%f intent=%s',
-					estimate.size_estimate, this.networkHighWaterMark, shrinkage, intent);
-				return { allow: false, reason: 'suspicious-shrinkage', deferrable: deferrableOnEvidence };
-			}
-		} catch {
-			// FRET not available - be conservative
-			const connections = this.libp2p.getConnections?.() ?? [];
-			if (this.networkHighWaterMark > 1 && connections.length === 0) {
-				// We've seen peers before but have none now - suspicious
-				const timeSinceConnection = Date.now() - this.lastConnectedTime;
-				if (timeSinceConnection < this.selfCoordinationConfig.gracePeriodMs) {
-					this.log('self-coord-blocked: grace-period-not-elapsed since=%dms', timeSinceConnection);
-					return { allow: false, reason: 'grace-period-not-elapsed', deferrable: true };
-				}
-			}
-		}
-
-		// Case 4: Recently connected (grace period not elapsed)
-		const timeSinceConnection = Date.now() - this.lastConnectedTime;
-		if (timeSinceConnection < this.selfCoordinationConfig.gracePeriodMs) {
-			const connections = this.libp2p.getConnections?.() ?? [];
-			// Only block if we have no connections but did recently
-			if (connections.length === 0) {
-				this.log('self-coord-blocked: grace-period-not-elapsed since=%dms', timeSinceConnection);
-				// Deferrable for BOTH intents: nothing here is evidence, only a clock. The same
-				// node with the same information self-coordinates once gracePeriodMs elapses.
-				return { allow: false, reason: 'grace-period-not-elapsed', deferrable: true };
-			}
-		}
-
-		// Case 5: Extended isolation with gradual shrinkage - allow with warning
-		this.log('self-coord-allowed: extended-isolation (warn)');
-		return { allow: true, reason: 'extended-isolation', warn: true };
-	}
-
-	/**
-	 * Memoize the coordinator for a key. A pick of SELF is deliberately ignored — the
-	 * cache is consulted ahead of every selection tier, so a self entry would keep the
-	 * key routed at our own (possibly stale) replica for the full TTL long after a
-	 * better-placed peer became reachable, and would return self without re-consulting
-	 * {@link shouldAllowSelfCoordination}, letting a partitioned node silently serve its
-	 * own data. Self needs no memoizing anyway: every tier that can select it re-derives
-	 * it from a local lookup with no dial and no retry sleep.
-	 *
-	 * The gate lives here rather than at each call site because most writers are OUTSIDE
-	 * this class — `recordCoordinator` is public and is fed self-valued picks by
-	 * `NetworkTransactor` (it writes back whatever `findCoordinator` returned, including
-	 * self) and by `RepoClient`/`ClusterClient` on redirect responses.
-	 */
-	public recordCoordinator(key: Uint8Array, peerId: PeerId, ttlMs = 30 * 60 * 1000): void {
-		if (peerId.toString() === this.libp2p.peerId.toString()) {
-			this.log('coordinator-cache:self-write-ignored key=%s', this.toCacheKey(key).substring(0, 12))
-			return
-		}
-		const k = this.toCacheKey(key)
-		const now = Date.now()
-		for (const [ck, entry] of this.coordinatorCache) {
-			if (entry.expires <= now) this.coordinatorCache.delete(ck)
-		}
-		this.coordinatorCache.set(k, { id: peerId, expires: now + ttlMs })
-		while (this.coordinatorCache.size > Libp2pKeyPeerNetwork.MAX_CACHE_ENTRIES) {
-			const firstKey = this.coordinatorCache.keys().next().value as string | undefined
-			if (firstKey == null) break
-			this.coordinatorCache.delete(firstKey)
-		}
-	}
-
-	/**
-	 * Learn how to reach `peerId` from addresses carried by an application-level message
-	 * (a cluster record's peer map, a redirect payload). See {@link mergePeerAddresses} for
-	 * the rules and the trust boundary; this is the {@link IPeerNetwork} entry point every
-	 * protocol client dials through.
-	 */
-	public recordPeerAddresses(peerId: PeerId, multiaddrs: string[]): void {
-		mergePeerAddresses(this.libp2p, peerId, multiaddrs, this.addressLog)
-	}
-
-	private getCachedCoordinator(key: Uint8Array): PeerId | undefined {
-		const k = this.toCacheKey(key)
-		const hit = this.coordinatorCache.get(k)
-		if (hit && hit.expires > Date.now()) return hit.id
-		if (hit) this.coordinatorCache.delete(k)
-		return undefined
-	}
-
-	/**
-	 * Open a stream to `peerId` on `protocol` — reusing a live connection when we hold one, and
-	 * otherwise dialing.
-	 *
-	 * Connection selection (prefer a direct connection over a resettable circuit-relay one, skip
-	 * entries libp2p has not yet evicted, opt in to limited connections) lives in
-	 * {@link openProtocolStream}, the single place in this package that opens a protocol stream.
-	 *
-	 * `negotiateFully: false` is safe here and saves a round trip: this is request/response and the
-	 * caller always reads a reply, so an unsupported-protocol failure deferred to the first read is
-	 * still observed. The caller's `AbortSignal` is forwarded so a per-peer dial deadline (enforced
-	 * upstream by `ProtocolClient.processMessage`) can actually cancel a stuck dial — without it,
-	 * libp2p falls back to its built-in connection-manager `dialTimeout` and the caller's tighter
-	 * deadline is decorative.
-	 *
-	 * The cold path pays one `peerStore.get` before dialing, to separate two failures libp2p
-	 * reports identically: "nobody ever taught us an address" and "every address we hold routes
-	 * back through us" (see {@link SelfRelayOnlyAddressesError}). Only the second is diagnosed
-	 * here; the first still dials, so an unknown peer produces libp2p's own `NoValidAddressesError`
-	 * exactly as before. It rides `beforeDial`, which never runs on the reuse path — the warm path
-	 * is deliberately kept clear of that read, since a live connection is the case this method
-	 * exists to make cheap.
-	 */
-	async connect(peerId: PeerId, protocol: string, options?: AbortOptions): Promise<Stream> {
-		return await openProtocolStream(this.libp2p, peerId, protocol, {
-			signal: options?.signal,
-			negotiateFully: false,
-			beforeDial: () => this.assertNotSelfRelayOnly(peerId, protocol, options)
-		})
-	}
-
-	/**
-	 * Throw {@link SelfRelayOnlyAddressesError} when every address we hold for `peerId` routes
-	 * through us, so the caller skips a dial that cannot succeed.
-	 *
-	 * Holding NOTHING is left alone on purpose — that dial still happens and still fails with
-	 * libp2p's `NoValidAddressesError`, because "we were never told an address" is a genuinely
-	 * different condition with a genuinely different remedy (someone teaches us one; see
-	 * `recordPeerAddresses`).
-	 */
-	private async assertNotSelfRelayOnly(peerId: PeerId, protocol: string, options?: AbortOptions): Promise<void> {
-		// NOTE: this costs one `peerStore.get` on EVERY cold dial, not only on relays, and libp2p's
-		// own dial queue reads the same record moments later — so a cold dial pays the peerStore
-		// twice. Unmeasured, and negligible against a dial's own cost; if cold-dial latency or
-		// peerStore contention ever shows up in a profile, hoist the verdict into the dial path
-		// rather than reading ahead of it.
-		const idStr = peerId.toString()
-		const held = (await this.getPeerStoreAddrsByPeer([idStr]))[idStr] ?? []
-		// A caller that cancelled while we were reading the peerStore is owed ITS reason, not a
-		// verdict we computed from a snapshot it no longer cares about.
-		options?.signal?.throwIfAborted()
-		if (classifySelfDialability(held, this.libp2p.peerId.toString(), this.addressLog) !== 'self-relay-only') return
-		this.log('connect:self-relay-only peer=%s protocol=%s addrs=%d',
-			idStr.substring(0, 12), protocol, held.length)
-		throw new SelfRelayOnlyAddressesError(idStr, protocol, held.length)
-	}
-
-	private getFret(): FretService {
-		const svc = (this.libp2p as unknown as WithFretService).services?.fret
-		if (svc == null) throw new Error('FRET service is not registered on this libp2p node')
-		return svc
-	}
-
-	private async getNeighborIdsForKey(key: Uint8Array, wants: number): Promise<string[]> {
-		const fret = this.getFret()
-		const coord = await hashKey(key)
-		const both = fret.getNeighbors(coord, 'both', wants)
-		return Array.from(new Set(both)).slice(0, wants)
-	}
-
-	async findCoordinator(key: Uint8Array, _options?: Partial<FindCoordinatorOptions>): Promise<PeerId> {
-		const t0 = Date.now();
-		const excludedSet = new Set<string>((_options?.excludedPeers ?? []).map(p => p.toString()))
-		// Unset means 'write' — the conservative reading, so a caller that doesn't declare an
-		// intent is held to the stricter self-coordination bar.
-		const intent: CoordinatorIntent = _options?.intent ?? 'write';
-		const keyStr = this.toCacheKey(key).substring(0, 12);
-		// Tracks whether the network-membership filter excluded an UNCONFIRMED candidate
-		// — `foreign` (another network) OR `unknown` (not yet confirmed to serve this
-		// network) — during any attempt. If selection ultimately fails with self
-		// unavailable, this lets us surface NO_NETWORK_COORDINATOR (the real cause)
-		// instead of the generic NO_COORDINATOR_AVAILABLE.
-		let droppedUnconfirmedAnyAttempt = false;
-
-		this.log('findCoordinator:start key=%s excluded=%o', keyStr, Array.from(excludedSet).map(s => s.substring(0, 12)))
-
-		// honor cache if not excluded
-		const cached = this.getCachedCoordinator(key)
-		if (cached != null && !excludedSet.has(cached.toString())) {
-			this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'cache')
-			return cached
-		}
-
-		// Retry logic: connections can be temporarily down, so retry a few times with delay
-		const maxRetries = 3;
-		const retryDelayMs = 500;
-
-		for (let attempt = 0; attempt < maxRetries; attempt++) {
-			// Get currently connected peers for filtering
-			const connected = (this.libp2p.getConnections?.() ?? []).map((c: any) => c.remotePeer) as PeerId[]
-			const connectedSet = new Set(connected.map(p => p.toString()))
-			this.log('findCoordinator:connected-peers key=%s count=%d peers=%o attempt=%d', keyStr, connected.length, connected.map(p => p.toString().substring(0, 12)), attempt)
-
-			// prefer FRET neighbors that are also connected, pick first non-excluded
-			let ids: string[] = [];
-			try {
-				ids = await this.getNeighborIdsForKey(key, this.clusterSize)
-				this.log('findCoordinator:fret-neighbors key=%s candidates=%d', keyStr, ids.length)
-				if (verbose) this.log('findCoordinator:fret-candidates key=%s ids=%o connected=%o', keyStr, ids, Array.from(connectedSet))
-
-				// Filter to only connected FRET neighbors, excluding banned peers. Self is
-				// never "connected" to itself, so it is admitted by the explicit self clause
-				// below — but ONLY when the self-coordination guard allows it, otherwise a
-				// node whose FRET neighborhood contains self (essentially always on a small or
-				// forming network) would bypass the guard and the last-resort tier's
-				// SELF_COORDINATION_BLOCKED would never fire. On refusal self is merely DROPPED
-				// from the candidate list, so the connected-peer fallback below still gets its
-				// chance at a good remote peer; only if that also comes up empty does the
-				// last-resort tier raise the accurate error.
-				//
-				// An ISOLATED READ is the exception: with no connection left there is no better
-				// answer to wait for, and a deferrable denial is not evidence that answering
-				// from our own replica is wrong — so self is admitted here and the read resolves
-				// immediately instead of paying the ~1s retry loop before the last-resort tier
-				// degrades to the same answer. A WRITE keeps dropping self exactly as before,
-				// so a peer that lands during the retry window still wins the key.
-				const selfStr = this.libp2p.peerId.toString()
-				let selfAllowedThisAttempt: boolean | undefined
-				// Memoized per ATTEMPT, and evaluated lazily so an all-remote neighborhood never
-				// pays detectPartition() / getNetworkSizeEstimate(). Re-evaluated on each attempt
-				// because a connection can land during the 500ms inter-attempt sleep and
-				// legitimately flip the answer — as filterByMembership re-reads the peerStore.
-				// NOTE: on a small network self is a neighbor of nearly every key, so this runs
-				// per findCoordinator call and self-coordinated keys are never cached to absorb
-				// it. Fine while detectPartition()/getNetworkSizeEstimate() stay local FRET
-				// table reads; if either ever grows a probe or other network round-trip, cache
-				// the decision with a short TTL on the instance instead of per attempt.
-				// NOTE: the guard re-reads getConnections() live, while `connectedSet` above was
-				// snapshotted at the top of this attempt. A connection landing between the two
-				// lifts the guard's grace-period denial while the new peer is still absent from
-				// the candidate filter — so self can win an attempt on evidence that attempt
-				// cannot yet use. Bounded to one attempt (the next re-snapshots and prefers the
-				// peer) and self picks are never cached, so it costs at most one lookup's
-				// routing. If that ever matters, pass the snapshot into the guard instead.
-				const isSelfAdmissible = (): boolean => {
-					if (selfAllowedThisAttempt === undefined) {
-						const decision = this.shouldAllowSelfCoordination(intent)
-						// Gated on ISOLATION, not just on the read intent. Self carries no reputation
-						// record, so it scores 0 and sorts ahead of every remote candidate in the rank
-						// below — admitting it while a connection is live would hand the key to a node
-						// its own guard just called partitioned, over a reachable FRET neighbour. And
-						// waiting costs a connected read nothing: the inter-attempt sleep further down
-						// only runs when `connected.length === 0`, so with peers present the remaining
-						// attempts and the last-resort degrade run back-to-back with no delay.
-						const degradedRead = !decision.allow && decision.deferrable === true
-							&& intent === 'read' && connected.length === 0
-						selfAllowedThisAttempt = decision.allow || degradedRead
-						if (degradedRead) {
-							this.log('findCoordinator:fret-self-degraded key=%s reason=%s intent=read attempt=%d', keyStr, decision.reason, attempt)
-						} else if (!decision.allow) {
-							this.log('findCoordinator:fret-self-dropped key=%s reason=%s intent=%s attempt=%d', keyStr, decision.reason, intent, attempt)
-						}
-					}
-					return selfAllowedThisAttempt
-				}
-				const connectedFretIds = ids
-					.filter(id => this.isSelectable(id, excludedSet))
-					.filter(id => connectedSet.has(id) || (id === selfStr && isSelfAdmissible()))
-					.sort((a, b) => (this.reputation?.getScore(a) ?? 0) - (this.reputation?.getScore(b) ?? 0))
-				this.log('findCoordinator:fret-connected key=%s count=%d peers=%o', keyStr, connectedFretIds.length, connectedFretIds.map(s => s.substring(0, 12)))
-
-				// Network-membership scoping (no-op when protocolPrefix is unset): only a peer
-				// CONFIRMED to serve this network ('serves') is eligible — both `foreign`
-				// (another network) and `unknown` (not yet identified) peers are excluded
-				// from selection. A cross-network peer is permanently 'unknown' (its
-				// namespaced identify never completes), so it is never gambled on; over the
-				// 3×500ms retry window a genuine same-network peer flips to 'serves' on a
-				// re-read of the peerStore and is selected normally on that attempt. Self
-				// always classifies as 'serves' and stays eligible.
-				const { ranked, droppedUnconfirmed } = await this.filterByMembership(connectedFretIds)
-				if (droppedUnconfirmed) droppedUnconfirmedAnyAttempt = true
-				const pick = ranked[0]
-				if (pick) {
-					const pid = peerIdFromString(pick)
-					// A self pick is a no-op here — recordCoordinator ignores self-valued
-					// writes (see its doc comment), matching the last-resort self tier below.
-					this.recordCoordinator(key, pid)
-					this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'fret')
-					return pid
-				}
-			} catch (err) {
-				this.log('findCoordinator getNeighborIdsForKey failed - %o', err)
-			}
-
-			// fallback: prefer any existing connected peer that's not excluded or banned,
-			// scoped to this network's serving peers (a `foreign` or not-yet-confirmed
-			// `unknown` peer is never picked). Note this candidate set is built from
-			// connected REMOTE peers and never includes self, so when no serving peer is
-			// present selection falls through to the last-resort self-coordination block.
-			// Being remote-only, this tier needs no self-coordination guard check, unlike the
-			// FRET tier above.
-			const connectedCandidates = connected
-				.filter(p => this.isSelectable(p.toString(), excludedSet))
-				.sort((a, b) => (this.reputation?.getScore(a.toString()) ?? 0) - (this.reputation?.getScore(b.toString()) ?? 0))
-				.map(p => p.toString())
-			const { ranked: connRanked, droppedUnconfirmed: connDroppedUnconfirmed } = await this.filterByMembership(connectedCandidates)
-			if (connDroppedUnconfirmed) droppedUnconfirmedAnyAttempt = true
-			const connectedPick = connRanked[0]
-			if (connectedPick) {
-				const pid = peerIdFromString(connectedPick)
-				this.recordCoordinator(key, pid)
-				this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'connected-fallback')
-				return pid
-			}
-
-			// If no connections and not the last attempt, wait and retry
-			if (connected.length === 0 && attempt < maxRetries - 1) {
-				// Exclusion/ban filtered — a neighbour we may never pick is not something to
-				// wait for. This network's membership filter (peerStore protocols) is deliberately
-				// NOT applied: a neighbour still `unknown` to it is exactly the peer that flips to
-				// `serves` inside the retry window, so its presence must keep the window. FRET's
-				// own ring membership has already applied a stricter cut upstream — `getNeighbors`
-				// returns confirmed ring members only — so a configured-but-never-reached bootstrap
-				// peer is absent from `ids` entirely, and only the dial-in-flight signal below can
-				// keep the window for it.
-				const knowable = ids.filter(id => this.isSelectable(id, excludedSet));
-				if (!this.retryCouldImprove(knowable)) {
-					this.log('findCoordinator:retry-futile key=%s neighbors=%d dialsInFlight=%d mode=%s hwm=%d',
-						keyStr, knowable.length, this.dialsInFlight(), this.networkMode, this.networkHighWaterMark);
-					break;
-				}
-				this.log('findCoordinator:no-connections-retry key=%s attempt=%d delay=%dms', keyStr, attempt, retryDelayMs)
-				await new Promise(resolve => setTimeout(resolve, retryDelayMs))
-				continue
-			}
-		}
-
-		// last resort: prefer self only if not excluded and guard allows
-		const self = this.libp2p.peerId
-		if (!excludedSet.has(self.toString())) {
-			const decision = this.shouldAllowSelfCoordination(intent);
-			// Only a HARD denial fails the caller. A deferrable one (see
-			// SelfCoordinationDecision.deferrable) means self is merely not the preferred
-			// coordinator — by this point every better tier has already come up empty and the
-			// retry window has been spent, so refusing here would just convert "serve from my
-			// own replica, degraded" into an outright failure of the whole operation.
-			if (!decision.allow && decision.deferrable !== true) {
-				this.log('findCoordinator:self-coord-blocked key=%s reason=%s intent=%s', keyStr, decision.reason, intent);
-				throw new FindCoordinatorError(
-					FIND_COORDINATOR_ERROR_CODES.SELF_COORDINATION_BLOCKED,
-					`Self-coordination blocked: ${decision.reason}. No coordinator available for key.`
-				);
-			}
-			if (!decision.allow) {
-				this.log('findCoordinator:self-selected-degraded key=%s coordinator=%s reason=%s intent=%s',
-					keyStr, self.toString().substring(0, 12), decision.reason, intent);
-				this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'self-degraded')
-				return self
-			}
-			if (decision.warn) {
-				this.log('findCoordinator:self-selected-warn key=%s coordinator=%s reason=%s',
-					keyStr, self.toString().substring(0, 12), decision.reason);
-			} else {
-				this.log('findCoordinator:self-selected key=%s coordinator=%s reason=%s',
-					keyStr, self.toString().substring(0, 12), decision.reason);
-			}
-			this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'self')
-			return self
-		}
-
-		// Self is excluded and selection found no eligible peer. If the membership filter is
-		// the reason the candidate set emptied (the only other peers are `foreign` — serving
-		// a DIFFERENT network — or `unknown` — not yet confirmed to serve this network),
-		// surface a distinct, accurate cause instead of the generic codes below.
-		if (droppedUnconfirmedAnyAttempt) {
-			this.log('findCoordinator:no-network-coordinator key=%s prefix=%s self=%s',
-				keyStr, this.protocolPrefix ?? '?', self.toString().substring(0, 12))
-			throw new FindCoordinatorError(
-				FIND_COORDINATOR_ERROR_CODES.NO_NETWORK_COORDINATOR,
-				`No coordinator available for key on network ${this.protocolPrefix ?? '?'}: ` +
-				`the remaining candidate peer(s) are foreign or not-yet-confirmed to serve this network's cluster/repo protocol.`
-			);
-		}
-
-		// Self is excluded. On a solo/bootstrap node (HWM<=1 and no other connected/FRET peers),
-		// this means the caller already tried self and the retry has nowhere to go — surface a
-		// distinct error so retry logic stops and the original first-attempt cause is preserved.
-		const isSoloBootstrap = this.networkHighWaterMark <= 1;
-		if (isSoloBootstrap) {
-			this.log('findCoordinator:self-exhausted-solo key=%s self=%s', keyStr, self.toString().substring(0, 12))
-			throw new FindCoordinatorError(
-				FIND_COORDINATOR_ERROR_CODES.SELF_COORDINATION_EXHAUSTED,
-				'Self-coordination exhausted on solo/bootstrap node (self already attempted). ' +
-				'The original first-attempt error describes the actual failure cause.'
-			);
-		}
-
-		this.log('findCoordinator:all-excluded key=%s self=%s', keyStr, self.toString().substring(0, 12))
-		throw new FindCoordinatorError(
-			FIND_COORDINATOR_ERROR_CODES.NO_COORDINATOR_AVAILABLE,
-			'No coordinator available for key (all candidates excluded)'
-		);
-	}
-
-	/**
-	 * Connection-derived addresses for the cluster record, keyed by peer id.
-	 *
-	 * Only OUTBOUND connections contribute — see {@link publishableConnectionAddr} for why an
-	 * inbound connection's `remoteAddr` is an ephemeral source socket that no third party can
-	 * reach. This is the only place `findCluster` derives addresses from connections, so the
-	 * rule has exactly one site.
-	 */
-	private getConnectedAddrsByPeer(): Record<string, string[]> {
-		const conns = this.libp2p.getConnections()
-		const byPeer: Record<string, string[]> = {}
-		for (const c of conns) {
-			const addr = publishableConnectionAddr(c, this.addressLog)
-			if (addr === undefined) continue
-			const id = c.remotePeer.toString()
-			const forPeer = byPeer[id] ??= []
-			forPeer.push(addr)
-		}
-		return byPeer
-	}
-
-	// NOTE: accepted tradeoff — a node with no peers recomputes the self-only cohort on every call
-	// (~2 per distinct block read; 144 calls in a 67-object cold apply). Measured 0.009 ms/call on
-	// Node with a wildcard TCP listener (test/bench-findcluster.mjs, N=2000, 2026-09-11), so a memo
-	// would save ~1.3 ms per apply while adding an invalidation hazard: a node that gains a peer, or
-	// finishes identifying one, must stop answering self-only immediately, and read-repair recovery
-	// relies on that widening. Revisit if an on-device (React Native) profile shows findCluster as
-	// material; then memoize ONLY the solo answer, invalidated on connection:open and peer:identify.
-	async findCluster(key: Uint8Array): Promise<ClusterPeers> {
-		const t0 = Date.now();
-		const fret = this.getFret()
-		const coord = await hashKey(key)
-		// When membership scoping is active, over-fetch a wider proximity band so the
-		// nearest peers that SERVE this network are in the candidate pool even if cross-
-		// network peers sit nearer the key (see membershipOverfetch).
-		const wants = this.protocolPrefix != null ? this.membershipOverfetch() : this.clusterSize
-		const cohort = fret.assembleCohort(coord, wants)
-		const keyStr = this.toCacheKey(key).substring(0, 12);
-		this.log('findCluster:start key=%s', keyStr);
-
-		// Include self in the cohort
-		const selfId = this.libp2p.peerId.toString()
-		let ids = Array.from(new Set([...cohort, selfId]))
-
-		// Network-membership scoping (no-op when protocolPrefix is unset): a cohort
-		// member that serves a DIFFERENT network's protocol can never negotiate THIS
-		// network's cluster/repo dial, so it guarantees a super-majority failure rather
-		// than contributing a promise. Drop such 'foreign' members; build the cohort from
-		// positively-'serves' members only and NEVER admit a not-yet-identified ('unknown')
-		// member. A permanently cross-network peer and a freshly-discovered same-network
-		// peer mid-identify are indistinguishable while 'unknown' (both have an empty
-		// peerStore protocol list), so admitting an 'unknown' on the strength of a viability
-		// floor risks pulling a cross-network contaminant into the cohort — its repo dial
-		// then negotiates a different network's protocol and the whole write fails. A fresh
-		// same-network peer is not starved: it flips to 'serves' once identify completes and
-		// is re-included on the caller's retry, and in the meantime a self-only cohort still
-		// completes the write under allowClusterDownsize (the default).
-		// Scoped path only: one peerStore read per cohort member yields both protocols
-		// (for membership classification here) and addresses (reused at backfill below),
-		// so a finally-selected member isn't fetched from the peerStore twice. Left
-		// undefined on the unscoped path, which never classifies membership.
-		let peerStoreRecords: Record<string, { protocols: string[]; addrs: string[] }> | undefined
-		if (this.protocolPrefix != null) {
-			// `cohort` is the over-fetched nearest-first band. Classify each non-self
-			// member, preserving proximity order within each tier.
-			const nonSelf = cohort.filter(id => id !== selfId)
-			peerStoreRecords = await this.getPeerStoreRecordsByPeer(nonSelf)
-			const serves: string[] = []
-			const unknown: string[] = []
-			let foreignDropped = 0
-			for (const id of nonSelf) {
-				const m = this.membershipOf(id, peerStoreRecords[id]?.protocols)
-				if (m === 'serves') serves.push(id)
-				else if (m === 'unknown') unknown.push(id)
-				else foreignDropped++
-			}
-			// Take the nearest `clusterSize - 1` SERVING peers. Self is ALWAYS added below and
-			// counts toward `clusterSize` (matching the unscoped path, where `assembleCohort`
-			// returns the nearest `clusterSize` peers INCLUDING self when self is near the key —
-			// the coordinator case), so reserving a slot for self keeps a healthy same-network
-			// cohort at exactly `clusterSize` members rather than `clusterSize + 1`. Over-sizing
-			// would inflate the super-majority promise count (ceil(peerCount * threshold)) above
-			// what the configured `clusterSize` intends and hurt write availability. 'unknown'
-			// members are never backfilled: an 'unknown' peer may be a permanently cross-network
-			// contaminant whose repo dial cannot negotiate this network's protocol, and a fresh
-			// same-network peer mid-identify is indistinguishable from it. We therefore admit
-			// only positively-'serves' peers; when self is the sole serving member the cohort is
-			// self-only, which completes the write under allowClusterDownsize (the default) and
-			// re-includes any legitimate peer as 'serves' on the caller's retry once identify
-			// completes. `unknown.length` is still computed above for the diagnostic log line.
-			const nonSelfTarget = Math.max(0, this.clusterSize - 1)
-			const others = serves.slice(0, nonSelfTarget)
-			ids = Array.from(new Set([selfId, ...others]))
-			this.log('findCluster:membership key=%s serves=%d unknown=%d foreignDropped=%d kept=%d',
-				keyStr, serves.length, unknown.length, foreignDropped, ids.length)
-		}
-
-		const connectedByPeer = this.getConnectedAddrsByPeer()
-		const connectedPeerIds = Object.keys(connectedByPeer)
-
-		// Backfill addresses from the peerStore for cohort members we don't have
-		// a live connection to. The cohort is keyspace-determined and can include
-		// peers we know-of but haven't dialed yet; without this backfill those
-		// would be silently dropped. On the scoped path reuse the addresses already
-		// read into `peerStoreRecords` above (no second store.get per member); on the
-		// unscoped path (no record map) do the single peerStore read as before.
-		const backfillIds = ids.filter(id => id !== selfId)
-		const peerStoreAddrs = peerStoreRecords
-			? Object.fromEntries(
-				backfillIds
-					.map(id => [id, peerStoreRecords![id]?.addrs ?? []] as const)
-					.filter(([, addrs]) => addrs.length > 0)
-			)
-			: await this.getPeerStoreAddrsByPeer(backfillIds)
-
-		this.log('findCluster key=%s fretCohort=%d connected=%d', keyStr, cohort.length, connectedPeerIds.length)
-		if (verbose) this.log('findCluster:detail key=%s cohortPeers=%o connectedPeers=%o', keyStr, ids, connectedPeerIds)
-
-		const peers: ClusterPeers = {}
-		// Cohort members we have no dialable address for. Admitting them is deliberate (see
-		// the note at the assignment below), but staying SILENT about it is what produced the
-		// reported symptom: clean membership logs on every node while every dial to the
-		// addressless member died instantly and the write never completed.
-		const addressless: string[] = []
-		// The OTHER way a member can be undialable by us: we hold addresses, but every one of
-		// them is a circuit through this node — the steady state for our own reservation holders.
-		// Counted separately because the two have different remedies (be taught an address, vs.
-		// wait for the client to re-dial us) and libp2p's dial error cannot tell them apart.
-		// These addresses are still PUBLISHED: a cohort sibling reaching the member through our
-		// relay is the working path, and dropping them would break it.
-		const selfRelayOnly: string[] = []
-
-		for (const idStr of ids) {
-			if (idStr === selfId) {
-				const raw = this.libp2p.peerId.publicKey?.raw ?? new Uint8Array()
-				peers[idStr] = { multiaddrs: this.getSelfMultiaddrs(), publicKey: u8ToString(raw, 'base64url') }
-				continue
-			}
-			const connectedStrings = connectedByPeer[idStr] ?? []
-			const peerStoreStrings = peerStoreAddrs[idStr] ?? []
-			// The union rule — connected-first, de-duplicated, validated — lives in
-			// `unionPublishableAddrs` so a cluster record and a redirect payload cannot describe
-			// the same peer differently. The sync form is used here (rather than
-			// `publishableAddrsForPeer`) because both halves are already in hand: the peerStore
-			// read above is batched across the whole cohort, and on the membership-scoped path it
-			// is the same `store.get` that fetched protocols.
-			const parsed = unionPublishableAddrs(connectedStrings, peerStoreStrings, this.addressLog)
-			const remotePeerId = peerIdFromString(idStr)
-			const raw = remotePeerId.publicKey?.raw ?? new Uint8Array()
-			// Note: parsed may be empty for a cohort member we have neither a
-			// live connection to nor a peerStore entry for. The dial will then
-			// surface as `code=none msg="no valid addresses"` and the caller's
-			// retry/exclude logic takes over — we intentionally do NOT drop
-			// addressless members here, because shrinking the cohort below
-			// `clusterSize` puts consensus supermajority out of reach.
-			const dialability = classifySelfDialability(parsed, selfId, this.addressLog)
-			if (dialability === 'none') addressless.push(idStr.substring(0, 12))
-			else if (dialability === 'self-relay-only') selfRelayOnly.push(idStr.substring(0, 12))
-			peers[idStr] = { multiaddrs: parsed, publicKey: u8ToString(raw, 'base64url') }
-		}
-
-		// Unconditional (not gated on `verbose`): this is the one line that turns a silent
-		// hang into a diagnosable one. A non-zero count means the cohort LOOKS healthy while
-		// some members cannot be dialed at all until someone teaches us their addresses
-		// (see `recordPeerAddresses` / `peer-address-book.ts`).
-		if (addressless.length > 0) {
-			this.log('findCluster:addressless-members key=%s count=%d of=%d peers=%o',
-				keyStr, addressless.length, Object.keys(peers).length, addressless)
-		}
-
-		// Same reasoning, second condition: a non-zero count here means we DO hold addresses for
-		// these members and still cannot dial them, because the only route we know runs through
-		// our own relay. No amount of retrying changes that (see `SelfRelayOnlyAddressesError`).
-		if (selfRelayOnly.length > 0) {
-			this.log('findCluster:self-relay-only-members key=%s count=%d of=%d peers=%o',
-				keyStr, selfRelayOnly.length, Object.keys(peers).length, selfRelayOnly)
-		}
-
-		this.log('findCluster:done key=%s ms=%d peers=%d addressless=%d selfRelayOnly=%d',
-			keyStr, Date.now() - t0, Object.keys(peers).length, addressless.length, selfRelayOnly.length)
-		return peers
-	}
-
-	/**
-	 * Look up the libp2p peerStore for known multiaddrs of the given peer ids.
-	 * Returns a map from peer-id string to multiaddr strings — empty/missing
-	 * when the peerStore has no entry. Errors are swallowed; we'd rather fail
-	 * back to the defense-in-depth drop than throw out of findCluster.
-	 */
-	private async getPeerStoreAddrsByPeer(ids: string[]): Promise<Record<string, string[]>> {
-		const out: Record<string, string[]> = {}
-		const store = (this.libp2p as { peerStore?: { get?: (id: PeerId) => Promise<{ addresses?: Array<{ multiaddr: { toString(): string } }> }> } }).peerStore
-		if (!store?.get) return out
-		await Promise.all(ids.map(async (idStr) => {
-			try {
-				const pid = peerIdFromString(idStr)
-				const peer = await store.get!(pid)
-				const addrs = (peer?.addresses ?? []).map(a => a.multiaddr.toString())
-				if (addrs.length > 0) out[idStr] = addrs
-			} catch {
-				// Unknown peer or peerStore failure — leave out of the map.
-			}
-		}))
-		return out
-	}
-
-	/**
-	 * Single-pass peerStore read returning BOTH protocols and addresses per peer from one
-	 * `store.get` call. Used on the membership-scoped `findCluster` hot path, where the
-	 * cohort needs protocols (to classify membership) AND addresses (to backfill dial
-	 * targets) for the same peers — reading them together avoids a second `store.get` per
-	 * finally-selected member. Same error handling as {@link getPeerStoreProtocolsByPeer}
-	 * and {@link getPeerStoreAddrsByPeer}: a missing peer or peerStore failure is left
-	 * absent from the map (caller treats absent protocols as 'unknown', absent addrs as none).
-	 */
-	private async getPeerStoreRecordsByPeer(ids: string[]): Promise<Record<string, { protocols: string[]; addrs: string[] }>> {
-		const out: Record<string, { protocols: string[]; addrs: string[] }> = {}
-		const store = (this.libp2p as { peerStore?: { get?: (id: PeerId) => Promise<{ protocols?: string[]; addresses?: Array<{ multiaddr: { toString(): string } }> }> } }).peerStore
-		if (!store?.get) return out
-		await Promise.all(ids.map(async (idStr) => {
-			try {
-				const pid = peerIdFromString(idStr)
-				const peer = await store.get!(pid)
-				const addrs = (peer?.addresses ?? []).map(a => a.multiaddr.toString())
-				out[idStr] = { protocols: peer?.protocols ?? [], addrs }
-			} catch {
-				// Unknown peer or peerStore failure — leave out of the map.
-			}
-		}))
-		return out
-	}
-
-	/**
-	 * Prefetch each peer's advertised protocol list from the libp2p peerStore.
-	 * Returns a map from peer-id string to its protocols (empty array when the peer
-	 * is absent or has not yet been identified). Mirrors {@link getPeerStoreAddrsByPeer};
-	 * errors are swallowed so a peerStore hiccup degrades to "unknown" rather than throwing.
-	 */
-	private async getPeerStoreProtocolsByPeer(ids: string[]): Promise<Record<string, string[]>> {
-		const out: Record<string, string[]> = {}
-		const store = (this.libp2p as { peerStore?: { get?: (id: PeerId) => Promise<{ protocols?: string[] }> } }).peerStore
-		if (!store?.get) return out
-		await Promise.all(ids.map(async (idStr) => {
-			try {
-				const pid = peerIdFromString(idStr)
-				const peer = await store.get!(pid)
-				out[idStr] = peer?.protocols ?? []
-			} catch {
-				// Unknown peer or peerStore failure — leave out (treated as 'unknown').
-			}
-		}))
-		return out
-	}
-
-	/**
-	 * Over-fetch width for network-membership scoping. A cross-network peer can sit
-	 * NEARER the key than a legitimate same-network peer and displace it from the
-	 * nearest-`clusterSize` window, so when scoping is active we ask FRET for a wider
-	 * proximity band and then keep the nearest peers that actually serve this network.
-	 * (A ring polluted by more cross-network peers than this band is the domain of the
-	 * separate FRET-side eviction follow-up; this band covers realistic co-location.)
-	 */
-	private membershipOverfetch(): number {
-		return Math.max(this.clusterSize * 4, this.clusterSize + 16)
-	}
-
-	/**
-	 * Classify a peer's network membership from its advertised protocols. Self always
-	 * `serves` (it trivially serves its own network). When no `protocolPrefix` is
-	 * configured the filter is disabled and EVERY peer is reported `serves`, so all
-	 * callers behave exactly as before this scoping was added.
-	 */
-	private membershipOf(idStr: string, protocols: string[] | undefined): NetworkMembership {
-		if (this.protocolPrefix == null) return 'serves'
-		if (idStr === this.libp2p.peerId.toString()) return 'serves'
-		if (protocols == null || protocols.length === 0) return 'unknown'
-		if (protocols.includes(`${this.protocolPrefix}/cluster/1.0.0`)
-			|| protocols.includes(`${this.protocolPrefix}/repo/1.0.0`)) return 'serves'
-		return 'foreign'
-	}
-
-	/**
-	 * Scope a reputation-ordered candidate id list to this network for COORDINATOR
-	 * selection: keep ONLY peers confirmed to serve this network (`serves`, which always
-	 * includes self), dropping both `foreign` peers (serving another network) and
-	 * `unknown` peers (peerStore protocol list empty — not yet confirmed). Incoming
-	 * (reputation) order is preserved among the surviving `serves` peers. A no-op
-	 * (returns the input unchanged, no drops) when `protocolPrefix` is unset or the list
-	 * is empty — the membership-disabled path is therefore untouched.
-	 *
-	 * `droppedUnconfirmed` reports whether any candidate was excluded because it was not
-	 * confirmed to serve this network — `foreign` OR `unknown` under scoping — so the
-	 * caller can surface a distinct "no network coordinator" failure rather than a generic
-	 * one. An `unknown` peer is not gambled on as coordinator: a permanent cross-network
-	 * contaminant and a fresh same-network peer mid-identify are indistinguishable at an
-	 * instant, but the filter re-reads the peerStore on every retry attempt, so a genuine
-	 * same-network peer that completes `identify` within the retry window flips to `serves`
-	 * and is selected normally on that attempt.
-	 */
-	private async filterByMembership(ids: string[]): Promise<{ ranked: string[]; droppedUnconfirmed: boolean }> {
-		if (this.protocolPrefix == null || ids.length === 0) return { ranked: ids, droppedUnconfirmed: false }
-		const selfStr = this.libp2p.peerId.toString()
-		const protocolsByPeer = await this.getPeerStoreProtocolsByPeer(ids.filter(id => id !== selfStr))
-		const serves: string[] = []
-		let droppedUnconfirmed = false
-		for (const id of ids) {
-			const m = this.membershipOf(id, protocolsByPeer[id])
-			if (m === 'serves') serves.push(id)
-			else droppedUnconfirmed = true
-		}
-		return { ranked: serves, droppedUnconfirmed }
-	}
-}
+import type { AbortOptions, Libp2p, PeerId, Stream } from "@libp2p/interface";
+import { toString as u8ToString } from 'uint8arrays'
+import type { ClusterPeers, CoordinatorIntent, FindCoordinatorOptions, IKeyNetwork, IPeerNetwork, RoutingKey } from "@optimystic/db-core";
+import { peerIdFromString } from '@libp2p/peer-id'
+import type { FretService, SerializedTable } from 'p2p-fret'
+import { hashKey } from 'p2p-fret'
+import { createLogger, verbose } from './logger.js'
+import { classifySelfDialability, mergePeerAddresses, publishableConnectionAddr, unionPublishableAddrs, type AddressLog } from './peer-address-book.js'
+import type { IPeerReputation } from './reputation/types.js'
+import { openProtocolStream } from './network/open-protocol-stream.js'
+
+interface WithFretService { services?: { fret?: FretService } }
+
+export type NetworkMode = 'forming' | 'joining';
+
+/**
+ * Error codes surfaced by {@link Libp2pKeyPeerNetwork.findCoordinator}. Callers
+ * (notably the batch-retry logic in `NetworkTransactor`) can inspect `.code`
+ * to distinguish between "transient — try again with different excludes" and
+ * "terminal — stop retrying".
+ */
+export const FIND_COORDINATOR_ERROR_CODES = {
+	/**
+	 * Last-resort self-coordination was blocked by a HARD verdict from the
+	 * self-coordination guard — self-coordination switched off by config, or a detected
+	 * partition / suspicious shrinkage on a WRITE. Retrying is unlikely to help. A
+	 * *deferrable* denial (see {@link SelfCoordinationDecision.deferrable}) never produces
+	 * this code: selection degrades to self with a warning instead.
+	 */
+	SELF_COORDINATION_BLOCKED: 'SELF_COORDINATION_BLOCKED',
+	/**
+	 * Self-coordination was already attempted and self is now excluded. On a solo
+	 * or bootstrap node with no other peers, this means retries are exhausted and
+	 * the original error from the prior attempt should be surfaced instead.
+	 */
+	SELF_COORDINATION_EXHAUSTED: 'SELF_COORDINATION_EXHAUSTED',
+	/** No peer (including self) is an eligible coordinator. */
+	NO_COORDINATOR_AVAILABLE: 'NO_COORDINATOR_AVAILABLE',
+	/**
+	 * The candidate set was non-empty but every non-self candidate serves a
+	 * DIFFERENT network's protocol (or none of this network's). Distinct from
+	 * NO_COORDINATOR_AVAILABLE so a Sereus-style trace points at the real cause —
+	 * "peer(s) do not serve this network's protocol" — instead of a generic
+	 * "all candidates excluded" / super-majority failure.
+	 */
+	NO_NETWORK_COORDINATOR: 'NO_NETWORK_COORDINATOR'
+} as const;
+
+export type FindCoordinatorErrorCode =
+	typeof FIND_COORDINATOR_ERROR_CODES[keyof typeof FIND_COORDINATOR_ERROR_CODES];
+
+/**
+ * Network-membership classification of a peer relative to THIS node's network,
+ * derived from the peer's libp2p peerStore protocol list:
+ * - `serves`   — advertises this network's namespaced `cluster`/`repo` protocol.
+ * - `foreign`  — has a non-empty protocol list but none for this network → another network.
+ * - `unknown`  — protocol list empty / peer absent → identify not yet completed. This is
+ *                both a fresh same-network peer (will flip to `serves`) AND a cross-network
+ *                peer (whose network-namespaced identify can NEVER complete, so it stays
+ *                `unknown` forever) — indistinguishable at a single instant, separated over
+ *                the retry/stabilization window.
+ */
+export type NetworkMembership = 'serves' | 'foreign' | 'unknown';
+
+export class FindCoordinatorError extends Error {
+	readonly code: FindCoordinatorErrorCode;
+	constructor(code: FindCoordinatorErrorCode, message: string) {
+		super(message);
+		this.name = 'FindCoordinatorError';
+		this.code = code;
+	}
+}
+
+/**
+ * `.code` on {@link SelfRelayOnlyAddressesError}. A stable string so it survives the
+ * `ClusterErrorEnvelope` round trip (`toClusterErrorEnvelope` carries `name` and `code`) and shows
+ * up as `code=SELF_RELAY_ONLY_ADDRESSES` on `ProtocolClient`'s `dial:fail` line instead of `none`.
+ */
+export const SELF_RELAY_ONLY_ERROR_CODE = 'SELF_RELAY_ONLY_ADDRESSES';
+
+/**
+ * Thrown by {@link Libp2pKeyPeerNetwork.connect} when we hold addresses for a peer but EVERY one
+ * of them reaches it by relaying through this node.
+ *
+ * This is the steady state a relay reaches for its own reservation holders: the address such a
+ * client advertises is `/<our transport addr>/p2p/<our peer id>/p2p-circuit`, which is correct and
+ * useful to every node except us. Dialing it asks us to relay to the client through ourselves, so
+ * it can only fail — with an error text (`NoValidAddressesError`, or an `AggregateError` of
+ * `Can not dial self`, depending on whether the circuit transport is registered as a dialer here)
+ * that is indistinguishable from "nobody ever taught us an address". Retrying cannot help: once the
+ * client's connection drops, only the client can re-initiate. So we fail fast and distinctly,
+ * letting the caller's existing exclude-and-continue logic move to another cohort member instead of
+ * burning a dial timeout.
+ */
+export class SelfRelayOnlyAddressesError extends Error {
+	readonly code = SELF_RELAY_ONLY_ERROR_CODE;
+	constructor(peer: string, protocol: string, addrCount: number) {
+		super(
+			`Peer ${peer} is reachable only through a circuit on THIS node: all ${addrCount} address(es) ` +
+			`we hold route back through us, so no dial for ${protocol} can succeed. ` +
+			`Only that peer can re-establish the connection.`
+		);
+		this.name = 'SelfRelayOnlyAddressesError';
+	}
+}
+
+/** Snapshot format this build writes and is willing to read. Bump on any incompatible change. */
+export const PERSISTED_STATE_VERSION = 2 as const;
+
+/**
+ * On-disk snapshot of what this node learned about the network last run.
+ *
+ * `version` is a compatibility fence, not a migration hook: a snapshot that does not carry
+ * `PERSISTED_STATE_VERSION` is discarded whole rather than translated. Version 2 exists because
+ * FRET 1.0.0-beta.1 made `SerializedPeerEntry.avgLatencyMs` nullable, where `null` means "never
+ * measured". Earlier FRET wrote `0` for that case, and 0 now reads as a genuine zero-millisecond
+ * round trip — the best possible score, ahead of every honestly measured peer. Since relevance
+ * drives next-hop preference *and* capacity eviction, importing such a table would both misroute
+ * and permanently evict good peers in favour of phantoms.
+ */
+export interface PersistedNetworkState {
+	version: typeof PERSISTED_STATE_VERSION;
+	networkHighWaterMark: number;
+	lastConnectedTimestamp: number;
+	consecutiveIsolatedSessions: number;
+	fretTable?: SerializedTable;
+}
+
+export interface NetworkStatePersistence {
+	load(): Promise<PersistedNetworkState | undefined>;
+	save(state: PersistedNetworkState): Promise<void>;
+}
+
+/**
+ * Configuration options for self-coordination behavior
+ */
+export interface SelfCoordinationConfig {
+	/** Time (ms) after last connection before allowing self-coordination. Default: 30000 */
+	gracePeriodMs?: number;
+	/** Threshold for suspicious network shrinkage (0-1). >50% drop is suspicious. Default: 0.5 */
+	shrinkageThreshold?: number;
+	/** Allow self-coordination at all. Default: true (for testing). Set false in production. */
+	allowSelfCoordination?: boolean;
+}
+
+/**
+ * Decision result from self-coordination guard
+ */
+export interface SelfCoordinationDecision {
+	allow: boolean;
+	reason: 'bootstrap-node' | 'partition-detected' | 'suspicious-shrinkage' | 'grace-period-not-elapsed' | 'extended-isolation' | 'hwm-decay' | 'disabled';
+	warn?: boolean;
+	/**
+	 * Set on a denial. `true` means "self is not the PREFERRED coordinator right now, but
+	 * nothing says it is unsafe" — the last-resort tier degrades to self with a warning
+	 * rather than failing the caller. `false` means there is a positive reason to refuse
+	 * (operator config, or evidence of a partition) and the caller is failed.
+	 *
+	 * Hardness by reason, given the caller's {@link CoordinatorIntent}:
+	 *
+	 * | reason                    | write      | read       |
+	 * | ------------------------- | ---------- | ---------- |
+	 * | `disabled`                | hard       | hard       |
+	 * | `grace-period-not-elapsed`| deferrable | deferrable |
+	 * | `partition-detected`      | hard       | deferrable |
+	 * | `suspicious-shrinkage`    | hard       | deferrable |
+	 *
+	 * `grace-period-not-elapsed` is deferrable for BOTH because it is a timing condition
+	 * with no evidence behind it: the same node, with the same FRET table and the same zero
+	 * connections, is allowed to self-coordinate once the clock passes `gracePeriodMs`. It
+	 * postpones an isolated write rather than preventing it (a self-only cohort commits
+	 * under `allowClusterDownsize`, the default), so failing the caller buys no safety.
+	 *
+	 * The read column is uniformly deferrable because none of these reasons protects a
+	 * read: self-coordinating a read means "answer from my own replica", which is what an
+	 * isolated node must accept anyway, and the layers below already report the quality of
+	 * that answer (`CoordinatorRepo.fetchBlockFromCluster` short-circuits a self-only cohort
+	 * as conclusive; an unreachable cohort comes back flagged `unavailable`). `disabled` is
+	 * the exception for both intents — it is an explicit operator switch, not an inference.
+	 *
+	 * NOTE: optional, so a NEW denial branch that forgets to set it silently reads as HARD
+	 * (`findCoordinator` tests `deferrable !== true`) — safe for a write, but it reinstates
+	 * the original defect for a read: an outright lookup failure where degrading to our own
+	 * replica would do. Every denial branch today sets it explicitly. If a fifth reason is
+	 * ever added, either set it there too or split this into a discriminated union
+	 * (`{ allow: true, … } | { allow: false, deferrable: boolean, … }`) so omission is a
+	 * compile error.
+	 */
+	deferrable?: boolean;
+}
+
+/** One peerStore record as the cohort assembly reads it: advertised protocols plus known addresses. */
+type PeerStoreRecord = { protocols: string[]; addrs: string[] }
+
+/**
+ * What `Libp2pKeyPeerNetwork.assembleServingCohort` derives for a key — the one answer both
+ * `findCluster` and `findCoordinator` work from.
+ */
+interface ServingCohort {
+	/**
+	 * The responsible peers for the key: the nearest `clusterSize` serving members in proximity
+	 * order (nearest first). This node is present exactly when it is one of them.
+	 */
+	cohort: string[]
+	/**
+	 * The proximity band the cohort was cut from, BEFORE membership classification: every live
+	 * ring member FRET returned for the key (the over-fetch width on the scoped path), plus this
+	 * node when it serves. Wider than the cohort; used for the retry-futility test, which must
+	 * see not-yet-identified members too.
+	 */
+	band: string[]
+	/**
+	 * Scoped path only: the peerStore records read for the band's non-self members, so a caller
+	 * that also needs their addresses (`findCluster`'s backfill) does not read them twice.
+	 */
+	peerStoreRecords?: Record<string, PeerStoreRecord>
+	/** Scoped path only: the `protocols` half of `peerStoreRecords`, in the shape `filterByMembership` takes. */
+	protocolsByPeer?: Record<string, string[]>
+}
+
+export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
+	private readonly selfCoordinationConfig: Required<SelfCoordinationConfig>;
+	private networkHighWaterMark = 1;
+	private lastConnectedTime = Date.now();
+	private consecutiveIsolatedSessions = 0;
+	/**
+	 * NOTE: diagnostic-only — no decision consults this any more. It used to gate the
+	 * coordinator retry window, but it is computed once at construction
+	 * (`bootstrapNodes.length > 0` in `libp2p-node-base.ts`) and never re-derived, so a node
+	 * configured with a bootstrap address it has never reached read as "company is coming"
+	 * forever; {@link retryCouldImprove} asks libp2p for live evidence instead. It still earns
+	 * its keep in the `retry-futile` log line ("configured
+	 * to expect company" vs. "solo by design"). Drop it, or re-derive it from live state, when
+	 * the constructor becomes an options bag — removing the positional parameter now would
+	 * churn ~50 construction sites in `test/libp2p-key-network.spec.ts` for no behaviour change.
+	 */
+	private readonly networkMode: NetworkMode;
+	private readonly persistence?: NetworkStatePersistence;
+
+	// NOTE: seven positional parameters, and the list stays that way for now — converting to an
+	// options bag would touch ~50 construction sites in `test/libp2p-key-network.spec.ts` alone.
+	// Revisit if an eighth parameter is ever needed, or if that spec is being rewritten anyway.
+	constructor(
+		private readonly libp2p: Libp2p,
+		/**
+		 * Replication factor / target cohort breadth for peer selection. REQUIRED, deliberately:
+		 * a silent default here meant a caller that did not know the node's cluster size quietly
+		 * selected a different-width cohort than the node's own consensus path used for the same
+		 * key. Reuse the node's own instance (`node.keyNetwork`) where one exists; a caller that
+		 * genuinely must construct standalone passes `DEFAULT_CLUSTER_SIZE` (`cluster/cluster-policy.ts`).
+		 */
+		private readonly clusterSize: number,
+		selfCoordinationConfig?: SelfCoordinationConfig,
+		networkMode?: NetworkMode,
+		persistence?: NetworkStatePersistence,
+		private readonly reputation?: IPeerReputation,
+		/**
+		 * Network-namespaced protocol prefix (`/optimystic/<networkName>`). When
+		 * provided, coordinator/cohort selection is scoped to peers that serve THIS
+		 * network's `cluster`/`repo` protocol, so a peer that only belongs to another
+		 * network sharing the same physical nodes/bootstraps is never chosen. When
+		 * ABSENT, the membership filter is disabled.
+		 *
+		 * NOTE: optional for the same reason `clusterSize` used to be — "most call sites don't
+		 * know the network name" — and that reason no longer holds: both production sites now
+		 * pass it (`libp2p-node-base.ts`, and the foreign-node fallback in the Quereus
+		 * collection-factory), and only the mock-based cases in `test/libp2p-key-network.spec.ts`
+		 * omit it. So a caller omitting it today gets the filter silently off, exactly the shape
+		 * that let a second key network be built with a wrong cohort width. Left optional because
+		 * making it required would touch ~50 construction sites in that one spec and no reachable
+		 * caller is affected. Make it required (or take the whole list as an options bag) the
+		 * moment a THIRD production construction site appears, or when that spec is rewritten.
+		 */
+		private readonly protocolPrefix?: string
+	) {
+		// Built here rather than as a field initializer: field initializers run before the
+		// constructor body, where `this.libp2p` (a parameter property) is not yet assigned.
+		this.log = createLogger('libp2p-key-network', this.libp2p.peerId.toString())
+		// NOTE: no production construction site in this repo passes a SelfCoordinationConfig —
+		// both leave it `undefined` (libp2p-node-base.ts, and the foreign-node fallback in
+		// quereus-plugin-optimystic's collection-factory.ts), so these defaults are always what
+		// is in force and no operator can tune them. If tuning `gracePeriodMs` is ever needed,
+		// those two sites have to thread the config through first. Low urgency: a grace-period denial no longer fails the caller, it only costs
+		// a write the findCoordinator retry window before self-coordinating — and only when that
+		// window is worth paying at all (see `retryCouldImprove`), so an isolated node pays nothing.
+		this.selfCoordinationConfig = {
+			gracePeriodMs: selfCoordinationConfig?.gracePeriodMs ?? 30_000,
+			shrinkageThreshold: selfCoordinationConfig?.shrinkageThreshold ?? 0.5,
+			allowSelfCoordination: selfCoordinationConfig?.allowSelfCoordination ?? true
+		};
+		this.networkMode = networkMode ?? 'forming';
+		this.persistence = persistence;
+		this.setupConnectionTracking();
+		this.setupSelfAddressTracking();
+	}
+
+	/** The cluster size this instance actually resolved to, for `assertClusterSizeCoupling`. */
+	get effectiveClusterSize(): number {
+		return this.clusterSize;
+	}
+
+	/**
+	 * The network-namespaced protocol prefix (`/optimystic/<networkName>`) selection is scoped to,
+	 * or `undefined` when the network-membership filter is off. Readable so a spec can assert the
+	 * node's attached instance really is network-scoped without reaching into a private field.
+	 */
+	get effectiveProtocolPrefix(): string | undefined {
+		return this.protocolPrefix;
+	}
+
+	// coordinator cache: key (base64url) -> peerId until expiry (bounded LRU-ish via Map insertion order)
+	private readonly coordinatorCache = new Map<string, { id: PeerId, expires: number }>()
+	private static readonly MAX_CACHE_ENTRIES = 1000
+	private readonly log: ReturnType<typeof createLogger>
+	/**
+	 * This instance's logger, in the shape `peer-address-book.ts` accepts. Declared once so the
+	 * five address predicates that take a sink all report under the same peer-id-suffixed
+	 * namespace, rather than five separately-written adapters drifting apart.
+	 */
+	private readonly addressLog: AddressLog = (fmt, ...args) => this.log(fmt, ...args)
+
+	private toCacheKey(key: Uint8Array): string { return u8ToString(key, 'base64url') }
+
+	/**
+	 * Set up connection event tracking to update high water mark and last connected time.
+	 */
+	private setupConnectionTracking(): void {
+		this.libp2p.addEventListener('connection:open', () => {
+			this.updateNetworkObservations();
+		});
+	}
+
+	/**
+	 * This node's own dialable addresses, as strings, memoized between address changes.
+	 *
+	 * `libp2p.getMultiaddrs()` is NOT cheap **when this node has a wildcard listen address**:
+	 * expanding `0.0.0.0` across the host's interfaces goes through `os.networkInterfaces()`, a
+	 * full NIC sweep measured at **3.19 ms of a 3.49 ms call**. Measured per configuration on one
+	 * host: 4.44 ms/call with a TCP listener, **0.001 ms/call with no listen addrs at all** (an
+	 * edge/mobile client dialling out over websockets — nothing to expand, empty address list).
+	 * So the win here is real for listening peers (service and reference nodes, which commit too)
+	 * and near-zero for a dial-only client; do not quote the headline figure at a profile that
+	 * never pays it. Every
+	 * `findCluster` builds a cluster record containing self's addresses, and every commit calls
+	 * `findCluster` through `ClusterCoordinator.resolveCohort` — so a cold `apply schema` paid one NIC sweep per
+	 * commit. On a solo node with zero peers that was ~13.8 ms per call and **49% of the whole
+	 * apply** (issue #8); the addresses it recomputed were identical every time.
+	 *
+	 * Invalidated on `self:peer:update`, which libp2p emits whenever this node's own address set
+	 * changes (a transport binding, a relay reservation, an observed-address promotion), so the
+	 * cache cannot outlive its answer. A fresh array is returned on every call: the value goes
+	 * into a `ClusterPeers` record the caller owns and may mutate.
+	 *
+	 * NOTE: the invalidation is not instantaneous, and it is not unconditional. libp2p reaches
+	 * that event through `AddressManager._updatePeerStoreAddresses`, which is **debounced by
+	 * 1000 ms** and then writes the peer record — so for up to about a second after a transport
+	 * starts or stops listening, a record published here can carry the previous address set.
+	 * That write is also fire-and-forget (`.catch` logs and swallows), so a peerStore failure
+	 * leaves this memo stale until the next successful address change. Both are acceptable
+	 * today: addresses change at startup and at relay-reservation time, not per commit, and a
+	 * momentarily-stale record lands on paths that already handle it — a missing address reads
+	 * as `addressless` and a departed one fails the dial, and the caller retries or excludes in
+	 * either case. Revisit if address churn ever becomes routine (frequent relay rotation, a
+	 * mobile node changing networks under load), or if a stale published address ever shows up
+	 * as a dial failure nobody can explain — this memo is the first thing to suspect.
+	 */
+	private selfMultiaddrsCache: string[] | undefined;
+
+	private setupSelfAddressTracking(): void {
+		this.libp2p.addEventListener('self:peer:update', () => {
+			this.selfMultiaddrsCache = undefined;
+		});
+	}
+
+	/** {@link selfMultiaddrsCache}, populated on first use. */
+	private getSelfMultiaddrs(): string[] {
+		this.selfMultiaddrsCache ??= this.libp2p.getMultiaddrs().map(ma => ma.toString());
+		return this.selfMultiaddrsCache.slice();
+	}
+
+	/**
+	 * Update network high water mark and last connected time.
+	 * Called on new connections.
+	 */
+	private updateNetworkObservations(): void {
+		const connections = this.libp2p.getConnections?.() ?? [];
+		if (connections.length > 0) {
+			this.lastConnectedTime = Date.now();
+			this.consecutiveIsolatedSessions = 0;
+		}
+
+		try {
+			const fret = this.getFret();
+			const estimate = fret.getNetworkSizeEstimate();
+			if (estimate.size_estimate > this.networkHighWaterMark) {
+				this.networkHighWaterMark = estimate.size_estimate;
+				this.log('network-hwm-updated mark=%d confidence=%f', this.networkHighWaterMark, estimate.confidence);
+			}
+		} catch {
+			// FRET not available - use connection count as fallback
+			const connectionCount = this.libp2p.getConnections?.().length ?? 0;
+			const observedSize = connectionCount + 1; // +1 for self
+			if (observedSize > this.networkHighWaterMark) {
+				this.networkHighWaterMark = observedSize;
+				this.log('network-hwm-updated mark=%d (from connections)', this.networkHighWaterMark);
+			}
+		}
+
+		this.persistState();
+	}
+
+	async initFromPersistedState(): Promise<void> {
+		if (!this.persistence) return;
+		const state = await this.persistence.load();
+		if (!state) return;
+
+		// Discard, don't translate. A foreign-version snapshot is cheap to replace — the high-water
+		// mark and the peer table are both re-learned within a few stabilization ticks — and far
+		// cheaper than reasoning about what an older FRET meant by any given field.
+		if (state.version !== PERSISTED_STATE_VERSION) {
+			this.log('init:state-discarded version=%o want=%d', state.version, PERSISTED_STATE_VERSION);
+			return;
+		}
+
+		this.networkHighWaterMark = state.networkHighWaterMark;
+		this.lastConnectedTime = state.lastConnectedTimestamp;
+		this.consecutiveIsolatedSessions = state.consecutiveIsolatedSessions;
+
+		if (state.fretTable) {
+			try {
+				// Must be awaited: importTable is async as of FRET 1.0.0-beta.1 and enforces capacity
+				// against the self ring coordinate it hashes on demand. Left floating, the restore
+				// races that enforcement against whatever runs next, and a rejection escapes this
+				// catch entirely rather than being logged as a skipped import.
+				await this.getFret().importTable(state.fretTable);
+			} catch (err) { this.log('init:fret-import-skipped %o', err); }
+		}
+
+		// If HWM > 1 but FRET table is empty/self-only, increment isolated sessions
+		if (state.networkHighWaterMark > 1) {
+			const fretEntryCount = state.fretTable?.entries?.length ?? 0;
+			if (fretEntryCount <= 1) {
+				this.consecutiveIsolatedSessions++;
+				this.log('init:isolated-session count=%d hwm=%d', this.consecutiveIsolatedSessions, this.networkHighWaterMark);
+			}
+		}
+	}
+
+	/**
+	 * Can another attempt plausibly return a BETTER answer than this one did? Consulted ONLY
+	 * when the current attempt found no candidate and the node holds zero connections — i.e.
+	 * purely to decide whether the 500ms inter-attempt sleep is worth paying.
+	 *
+	 * Answered from evidence available NOW, never from configuration or history (`networkMode`
+	 * is frozen at construction and `networkHighWaterMark` is monotonic, so both used to keep
+	 * the window open forever on a node that could never fill it):
+	 *  - a non-self candidate in the FRET neighbourhood for this key — a peer we know of and
+	 *    route to; a connection to it landing during the sleep makes it selectable.
+	 *  - a dial in flight (`queued` / `active` in libp2p's dial queue) — a connection attempt
+	 *    that can complete inside the sleep. This is the signal that covers a
+	 *    configured-but-not-yet-reached bootstrap peer: while its dial runs, the window is
+	 *    worth paying; once the dial has failed, it is not.
+	 *
+	 * Neither present → nothing this call can wait for; break to the last-resort tier.
+	 *
+	 * NOTE: accepted regression — a node with no known peers and no dial in flight that
+	 * received an INBOUND connection during a sleep it now skips will route that one lookup to
+	 * self instead of to the arriving peer. A self pick is never cached, so the next lookup
+	 * picks the peer up; the benefit is that every genuinely isolated lookup stops paying ~1s
+	 * per block. Inbound reachability is deliberately NOT a futility signal: it holds for
+	 * nearly every node with a listen address, so it would neuter the test.
+	 * NOTE: deliberately no `peerStore` scan — "we have a record of a peer" is not "a peer can
+	 * arrive in the next 500ms". A peerStore entry with no FRET entry and no in-flight dial is
+	 * a peer nobody is currently attempting, and the scan is an async datastore iteration on a
+	 * per-lookup hot path.
+	 */
+	private retryCouldImprove(candidateIds: string[]): boolean {
+		if (candidateIds.some(id => id !== this.libp2p.peerId.toString())) return true;
+		return this.dialsInFlight() > 0;
+	}
+
+	/**
+	 * Number of dials libp2p is currently attempting (`queued` or `active`) — a connection
+	 * that can plausibly complete inside the inter-attempt sleep.
+	 *
+	 * Over-inclusive by design: the queue may hold a dial to an excluded, banned, or
+	 * foreign-network peer. That keeps the retry window (conservative, matches the behaviour
+	 * before the futility test existed); cross-referencing it would cost more than the sleep
+	 * it saves. `getDialQueue` is non-optional on the Libp2p interface, so an absent method
+	 * only ever means a test mock — treated as "no evidence of an in-flight dial", exactly as
+	 * `getConnections?.()` is handled elsewhere.
+	 *
+	 * NOTE: this bounds — it does not eliminate — the futile window for the motivating case (a
+	 * node whose only configured bootstrap is unreachable). FRET re-probes such a peer at most
+	 * once per its capped 32s backoff (`fret-service.ts` `recordBackoff`: base 1000ms × factor
+	 * ≤32), and each probe's dial can sit `active` for libp2p's 10s `DIAL_TIMEOUT` — so up to
+	 * roughly a third of wall-clock still has a dial in flight, and lookups in those stretches
+	 * still pay ~1s. Paying there is correct (a succeeding probe makes the peer selectable);
+	 * revisit only if either upstream constant moves far enough to make the duty cycle ~1.
+	 */
+	private dialsInFlight(): number {
+		return (this.libp2p.getDialQueue?.() ?? [])
+			.filter(d => d.status === 'queued' || d.status === 'active').length;
+	}
+
+	/**
+	 * The caller-independent half of eligibility: this peer is neither excluded by the caller
+	 * nor banned by reputation. Shared by all three places `findCoordinator` narrows a candidate
+	 * list — the cohort tier, the connected-peer fallback, and the retry-futility input — so the
+	 * futility test can never disagree with the tiers about who is pickable.
+	 *
+	 * NOTE: eligibility here is deliberately blind to self-dialability, so on a relay
+	 * `findCoordinator` can still pick one of our own reservation holders and only then fail fast
+	 * with `SelfRelayOnlyAddressesError`. The caller's exclude-and-continue walk
+	 * (`db-core/utility/batch-coordinator.ts`) absorbs it, and each such pick now costs an
+	 * instant refusal rather than a burned dial timeout, so it is a selection round-trip, not a
+	 * stall — and the verdict is a live peerStore read that a stale eligibility filter would have
+	 * to guess at. If a relay serving many reservation holders is ever measured spending real time
+	 * walking through them, feed the verdict into the tiers instead of discovering it at dial.
+	 */
+	private isSelectable(id: string, excluded: Set<string>): boolean {
+		return !excluded.has(id) && !(this.reputation?.isBanned(id));
+	}
+
+	private persistState(): void {
+		if (!this.persistence) return;
+		const state: PersistedNetworkState = {
+			version: PERSISTED_STATE_VERSION,
+			networkHighWaterMark: this.networkHighWaterMark,
+			lastConnectedTimestamp: this.lastConnectedTime,
+			consecutiveIsolatedSessions: this.consecutiveIsolatedSessions,
+		};
+		try {
+			const fret = this.getFret();
+			state.fretTable = fret.exportTable();
+		} catch { /* FRET not available */ }
+		void this.persistence.save(state).catch(err => this.log('persist-state-failed %o', err));
+	}
+
+	/**
+	 * Determine if self-coordination should be allowed based on network observations.
+	 *
+	 * Principle: If we've ever seen a larger network, assume our connectivity is the problem,
+	 * not the network shrinking.
+	 *
+	 * A denial is classified as HARD or DEFERRABLE via {@link SelfCoordinationDecision.deferrable}
+	 * — see that field for the reason/intent table. A hard denial fails the caller; a deferrable
+	 * one only means "self is not the preferred coordinator", and the last-resort tier degrades
+	 * to self with a warning.
+	 *
+	 * @param intent What the caller means to do with the coordinator. Defaults to `'write'`,
+	 * the conservative reading, so callers that don't know are held to the stricter bar.
+	 */
+	shouldAllowSelfCoordination(intent: CoordinatorIntent = 'write'): SelfCoordinationDecision {
+		// A read never coordinates a mutation, so every evidence-based denial below is merely
+		// a preference for a better-placed peer — the caller can always be answered from this
+		// node's own replica. Only the explicit `disabled` switch is absolute for a read.
+		const deferrableOnEvidence = intent === 'read';
+
+		// Check global disable
+		if (!this.selfCoordinationConfig.allowSelfCoordination) {
+			return { allow: false, reason: 'disabled', deferrable: false };
+		}
+
+		// Case 1: New/bootstrap node (never seen larger network)
+		if (this.networkHighWaterMark <= 1) {
+			return { allow: true, reason: 'bootstrap-node' };
+		}
+
+		// Case 1b: Repeated isolation across sessions — decay HWM to allow eventual self-coordination
+		if (this.consecutiveIsolatedSessions >= 3) {
+			this.log('self-coord-allowed: hwm-decayed sessions=%d', this.consecutiveIsolatedSessions);
+			return { allow: true, reason: 'hwm-decay', warn: true };
+		}
+
+		// Case 2: Check for partition via FRET
+		try {
+			const fret = this.getFret();
+			if (fret.detectPartition()) {
+				this.log('self-coord-blocked: partition-detected intent=%s', intent);
+				return { allow: false, reason: 'partition-detected', deferrable: deferrableOnEvidence };
+			}
+
+			// Case 3: Suspicious network shrinkage (>threshold drop)
+			const estimate = fret.getNetworkSizeEstimate();
+			const shrinkage = 1 - (estimate.size_estimate / this.networkHighWaterMark);
+			if (shrinkage > this.selfCoordinationConfig.shrinkageThreshold) {
+				this.log('self-coord-blocked: suspicious-shrinkage current=%d hwm=%d shrinkage=%f intent=%s',
+					estimate.size_estimate, this.networkHighWaterMark, shrinkage, intent);
+				return { allow: false, reason: 'suspicious-shrinkage', deferrable: deferrableOnEvidence };
+			}
+		} catch {
+			// FRET not available - be conservative
+			const connections = this.libp2p.getConnections?.() ?? [];
+			if (this.networkHighWaterMark > 1 && connections.length === 0) {
+				// We've seen peers before but have none now - suspicious
+				const timeSinceConnection = Date.now() - this.lastConnectedTime;
+				if (timeSinceConnection < this.selfCoordinationConfig.gracePeriodMs) {
+					this.log('self-coord-blocked: grace-period-not-elapsed since=%dms', timeSinceConnection);
+					return { allow: false, reason: 'grace-period-not-elapsed', deferrable: true };
+				}
+			}
+		}
+
+		// Case 4: Recently connected (grace period not elapsed)
+		const timeSinceConnection = Date.now() - this.lastConnectedTime;
+		if (timeSinceConnection < this.selfCoordinationConfig.gracePeriodMs) {
+			const connections = this.libp2p.getConnections?.() ?? [];
+			// Only block if we have no connections but did recently
+			if (connections.length === 0) {
+				this.log('self-coord-blocked: grace-period-not-elapsed since=%dms', timeSinceConnection);
+				// Deferrable for BOTH intents: nothing here is evidence, only a clock. The same
+				// node with the same information self-coordinates once gracePeriodMs elapses.
+				return { allow: false, reason: 'grace-period-not-elapsed', deferrable: true };
+			}
+		}
+
+		// Case 5: Extended isolation with gradual shrinkage - allow with warning
+		this.log('self-coord-allowed: extended-isolation (warn)');
+		return { allow: true, reason: 'extended-isolation', warn: true };
+	}
+
+	/**
+	 * Memoize the coordinator for a key. A pick of SELF is deliberately ignored — the
+	 * cache is consulted ahead of every selection tier, so a self entry would keep the
+	 * key routed at our own (possibly stale) replica for the full TTL long after a
+	 * better-placed peer became reachable, and would return self without re-consulting
+	 * {@link shouldAllowSelfCoordination}, letting a partitioned node silently serve its
+	 * own data. Self needs no memoizing anyway: every tier that can select it re-derives
+	 * it from a local lookup with no dial and no retry sleep.
+	 *
+	 * The gate lives here rather than at each call site because most writers are OUTSIDE
+	 * this class — `recordCoordinator` is public and is fed self-valued picks by
+	 * `NetworkTransactor` (it writes back whatever `findCoordinator` returned, including
+	 * self) and by `RepoClient`/`ClusterClient` on redirect responses.
+	 */
+	public recordCoordinator(key: RoutingKey, peerId: PeerId, ttlMs = 30 * 60 * 1000): void {
+		if (peerId.toString() === this.libp2p.peerId.toString()) {
+			this.log('coordinator-cache:self-write-ignored key=%s', this.toCacheKey(key).substring(0, 12))
+			return
+		}
+		const k = this.toCacheKey(key)
+		const now = Date.now()
+		for (const [ck, entry] of this.coordinatorCache) {
+			if (entry.expires <= now) this.coordinatorCache.delete(ck)
+		}
+		this.coordinatorCache.set(k, { id: peerId, expires: now + ttlMs })
+		while (this.coordinatorCache.size > Libp2pKeyPeerNetwork.MAX_CACHE_ENTRIES) {
+			const firstKey = this.coordinatorCache.keys().next().value as string | undefined
+			if (firstKey == null) break
+			this.coordinatorCache.delete(firstKey)
+		}
+	}
+
+	/**
+	 * Learn how to reach `peerId` from addresses carried by an application-level message
+	 * (a cluster record's peer map, a redirect payload). See {@link mergePeerAddresses} for
+	 * the rules and the trust boundary; this is the {@link IPeerNetwork} entry point every
+	 * protocol client dials through.
+	 */
+	public recordPeerAddresses(peerId: PeerId, multiaddrs: string[]): void {
+		mergePeerAddresses(this.libp2p, peerId, multiaddrs, this.addressLog)
+	}
+
+	/**
+	 * NOTE: a cached coordinator is trusted without re-deriving the key's cohort. A peer that
+	 * has since LEFT the cohort (ring growth shifted the nearest set) is corrected on the next
+	 * hop rather than here: the server-side responsibility check redirects to a current member
+	 * (`RepoService.checkRedirect`, whose target overwrites this hint), and a peer that has gone
+	 * away fails its dial and is excluded by the caller. Re-deriving the cohort on every cache
+	 * hit would cost the same FRET walk and peerStore reads the cache exists to skip.
+	 */
+	private getCachedCoordinator(key: RoutingKey): PeerId | undefined {
+		const k = this.toCacheKey(key)
+		const hit = this.coordinatorCache.get(k)
+		if (hit && hit.expires > Date.now()) return hit.id
+		if (hit) this.coordinatorCache.delete(k)
+		return undefined
+	}
+
+	/**
+	 * Open a stream to `peerId` on `protocol` — reusing a live connection when we hold one, and
+	 * otherwise dialing.
+	 *
+	 * Connection selection (prefer a direct connection over a resettable circuit-relay one, skip
+	 * entries libp2p has not yet evicted, opt in to limited connections) lives in
+	 * {@link openProtocolStream}, the single place in this package that opens a protocol stream.
+	 *
+	 * `negotiateFully: false` is safe here and saves a round trip: this is request/response and the
+	 * caller always reads a reply, so an unsupported-protocol failure deferred to the first read is
+	 * still observed. The caller's `AbortSignal` is forwarded so a per-peer dial deadline (enforced
+	 * upstream by `ProtocolClient.processMessage`) can actually cancel a stuck dial — without it,
+	 * libp2p falls back to its built-in connection-manager `dialTimeout` and the caller's tighter
+	 * deadline is decorative.
+	 *
+	 * The cold path pays one `peerStore.get` before dialing, to separate two failures libp2p
+	 * reports identically: "nobody ever taught us an address" and "every address we hold routes
+	 * back through us" (see {@link SelfRelayOnlyAddressesError}). Only the second is diagnosed
+	 * here; the first still dials, so an unknown peer produces libp2p's own `NoValidAddressesError`
+	 * exactly as before. It rides `beforeDial`, which never runs on the reuse path — the warm path
+	 * is deliberately kept clear of that read, since a live connection is the case this method
+	 * exists to make cheap.
+	 */
+	async connect(peerId: PeerId, protocol: string, options?: AbortOptions): Promise<Stream> {
+		return await openProtocolStream(this.libp2p, peerId, protocol, {
+			signal: options?.signal,
+			negotiateFully: false,
+			beforeDial: () => this.assertNotSelfRelayOnly(peerId, protocol, options)
+		})
+	}
+
+	/**
+	 * Throw {@link SelfRelayOnlyAddressesError} when every address we hold for `peerId` routes
+	 * through us, so the caller skips a dial that cannot succeed.
+	 *
+	 * Holding NOTHING is left alone on purpose — that dial still happens and still fails with
+	 * libp2p's `NoValidAddressesError`, because "we were never told an address" is a genuinely
+	 * different condition with a genuinely different remedy (someone teaches us one; see
+	 * `recordPeerAddresses`).
+	 */
+	private async assertNotSelfRelayOnly(peerId: PeerId, protocol: string, options?: AbortOptions): Promise<void> {
+		// NOTE: this costs one `peerStore.get` on EVERY cold dial, not only on relays, and libp2p's
+		// own dial queue reads the same record moments later — so a cold dial pays the peerStore
+		// twice. Unmeasured, and negligible against a dial's own cost; if cold-dial latency or
+		// peerStore contention ever shows up in a profile, hoist the verdict into the dial path
+		// rather than reading ahead of it.
+		const idStr = peerId.toString()
+		const held = (await this.getPeerStoreAddrsByPeer([idStr]))[idStr] ?? []
+		// A caller that cancelled while we were reading the peerStore is owed ITS reason, not a
+		// verdict we computed from a snapshot it no longer cares about.
+		options?.signal?.throwIfAborted()
+		if (classifySelfDialability(held, this.libp2p.peerId.toString(), this.addressLog) !== 'self-relay-only') return
+		this.log('connect:self-relay-only peer=%s protocol=%s addrs=%d',
+			idStr.substring(0, 12), protocol, held.length)
+		throw new SelfRelayOnlyAddressesError(idStr, protocol, held.length)
+	}
+
+	private getFret(): FretService {
+		const svc = (this.libp2p as unknown as WithFretService).services?.fret
+		if (svc == null) throw new Error('FRET service is not registered on this libp2p node')
+		return svc
+	}
+
+	async findCoordinator(key: RoutingKey, _options?: Partial<FindCoordinatorOptions>): Promise<PeerId> {
+		const t0 = Date.now();
+		const excludedSet = new Set<string>((_options?.excludedPeers ?? []).map(p => p.toString()))
+		// Unset means 'write' — the conservative reading, so a caller that doesn't declare an
+		// intent is held to the stricter self-coordination bar.
+		const intent: CoordinatorIntent = _options?.intent ?? 'write';
+		const keyStr = this.toCacheKey(key).substring(0, 12);
+		const selfStr = this.libp2p.peerId.toString()
+		// Tracks whether the network-membership filter excluded an UNCONFIRMED candidate
+		// — `foreign` (another network) OR `unknown` (not yet confirmed to serve this
+		// network) — during any attempt. If selection ultimately fails with self
+		// unavailable, this lets us surface NO_NETWORK_COORDINATOR (the real cause)
+		// instead of the generic NO_COORDINATOR_AVAILABLE.
+		let droppedUnconfirmedAnyAttempt = false;
+		// The most recent attempt's cohort, kept for the last-resort tier below: self may
+		// coordinate a key only when it is among that key's responsible peers, and the
+		// verdict is the one the attempt that gave up on every better tier was working from.
+		let lastCohort: string[] | undefined
+
+		this.log('findCoordinator:start key=%s excluded=%o', keyStr, Array.from(excludedSet).map(s => s.substring(0, 12)))
+
+		// honor cache if not excluded
+		const cached = this.getCachedCoordinator(key)
+		if (cached != null && !excludedSet.has(cached.toString())) {
+			this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'cache')
+			return cached
+		}
+
+		// Retry logic: connections can be temporarily down, so retry a few times with delay
+		const maxRetries = 3;
+		const retryDelayMs = 500;
+
+		for (let attempt = 0; attempt < maxRetries; attempt++) {
+			// Get currently connected peers for filtering
+			const connected = (this.libp2p.getConnections?.() ?? []).map((c: any) => c.remotePeer) as PeerId[]
+			const connectedSet = new Set(connected.map(p => p.toString()))
+			this.log('findCoordinator:connected-peers key=%s count=%d peers=%o attempt=%d', keyStr, connected.length, connected.map(p => p.toString().substring(0, 12)), attempt)
+
+			// The proximity band this attempt's cohort was cut from, for the retry-futility
+			// test below. Empty when the assembly threw.
+			let band: string[] = []
+			// Cohort tier: the key's responsible peers, in proximity order, from the SAME
+			// assembly `findCluster` builds the replica set with — so the coordinator is
+			// always one of the peers that will hold the block, never a neighbour just
+			// outside that set.
+			try {
+				const assembled = await this.assembleServingCohort(key)
+				lastCohort = assembled.cohort
+				band = assembled.band
+				this.log('findCoordinator:cohort key=%s size=%d selfInCohort=%s', keyStr, assembled.cohort.length, assembled.cohort.includes(selfStr))
+				if (verbose) this.log('findCoordinator:cohort-candidates key=%s ids=%o connected=%o', keyStr, assembled.cohort, Array.from(connectedSet))
+
+				// Filter to only connected cohort members, excluding banned peers. Self is
+				// never "connected" to itself, so it is admitted by the explicit self clause
+				// below — but ONLY when it is in the cohort (the list being filtered) AND the
+				// self-coordination guard allows it, otherwise a node that heads the cohort
+				// of nearly every key on a small or forming network would bypass the guard
+				// and the last-resort tier's SELF_COORDINATION_BLOCKED would never fire. On
+				// refusal self is merely DROPPED from the candidate list, so the connected-peer
+				// fallback below still gets its chance at a good remote peer; only if that also
+				// comes up empty does the last-resort tier raise the accurate error.
+				//
+				// An ISOLATED READ is the exception: with no connection left there is no better
+				// answer to wait for, and a deferrable denial is not evidence that answering
+				// from our own replica is wrong — so self is admitted here and the read resolves
+				// immediately instead of paying the ~1s retry loop before the last-resort tier
+				// degrades to the same answer. A WRITE keeps dropping self exactly as before,
+				// so a peer that lands during the retry window still wins the key.
+				let selfAllowedThisAttempt: boolean | undefined
+				// Memoized per ATTEMPT, and evaluated lazily so an all-remote cohort never
+				// pays detectPartition() / getNetworkSizeEstimate(). Re-evaluated on each attempt
+				// because a connection can land during the 500ms inter-attempt sleep and
+				// legitimately flip the answer — as the assembly re-reads the peerStore.
+				// NOTE: on a small network self is in the cohort of nearly every key, so this runs
+				// per findCoordinator call and self-coordinated keys are never cached to absorb
+				// it. Fine while detectPartition()/getNetworkSizeEstimate() stay local FRET
+				// table reads; if either ever grows a probe or other network round-trip, cache
+				// the decision with a short TTL on the instance instead of per attempt.
+				// NOTE: the guard re-reads getConnections() live, while `connectedSet` above was
+				// snapshotted at the top of this attempt. A connection landing between the two
+				// lifts the guard's grace-period denial while the new peer is still absent from
+				// the candidate filter — so self can win an attempt on evidence that attempt
+				// cannot yet use. Bounded to one attempt (the next re-snapshots and prefers the
+				// peer) and self picks are never cached, so it costs at most one lookup's
+				// routing. If that ever matters, pass the snapshot into the guard instead.
+				const isSelfAdmissible = (): boolean => {
+					if (selfAllowedThisAttempt === undefined) {
+						const decision = this.shouldAllowSelfCoordination(intent)
+						// Gated on ISOLATION, not just on the read intent. Self carries no reputation
+						// record, so it scores 0 and sorts ahead of every remote candidate in the rank
+						// below — admitting it while a connection is live would hand the key to a node
+						// its own guard just called partitioned, over a reachable cohort member. And
+						// waiting costs a connected read nothing: the inter-attempt sleep further down
+						// only runs when `connected.length === 0`, so with peers present the remaining
+						// attempts and the last-resort degrade run back-to-back with no delay.
+						const degradedRead = !decision.allow && decision.deferrable === true
+							&& intent === 'read' && connected.length === 0
+						selfAllowedThisAttempt = decision.allow || degradedRead
+						if (degradedRead) {
+							this.log('findCoordinator:cohort-self-degraded key=%s reason=%s intent=read attempt=%d', keyStr, decision.reason, attempt)
+						} else if (!decision.allow) {
+							this.log('findCoordinator:cohort-self-dropped key=%s reason=%s intent=%s attempt=%d', keyStr, decision.reason, intent, attempt)
+						}
+					}
+					return selfAllowedThisAttempt
+				}
+				const reachable = assembled.cohort
+					.filter(id => this.isSelectable(id, excludedSet))
+					.filter(id => connectedSet.has(id) || (id === selfStr && isSelfAdmissible()))
+					// Ranked by reputation, best (lowest) score first. The sort MUST be stable so
+					// that equal-score members keep their proximity order — otherwise two writers
+					// with the same cohort could name different coordinators for one block.
+					// `Array.prototype.sort` is stable in every supported runtime (ES2019+).
+					.sort((a, b) => (this.reputation?.getScore(a) ?? 0) - (this.reputation?.getScore(b) ?? 0))
+				this.log('findCoordinator:cohort-reachable key=%s count=%d peers=%o', keyStr, reachable.length, reachable.map(s => s.substring(0, 12)))
+
+				// Network-membership scoping (no-op when protocolPrefix is unset). The cohort
+				// was already cut to peers CONFIRMED to serve this network by the assembly, so
+				// this is the final scope check over the same peerStore records — it costs no
+				// second read and cannot disagree with the assembly.
+				const { ranked, droppedUnconfirmed } = await this.filterByMembership(reachable, assembled.protocolsByPeer)
+				if (droppedUnconfirmed) droppedUnconfirmedAnyAttempt = true
+				const pick = ranked[0]
+				if (pick) {
+					const pid = peerIdFromString(pick)
+					// A self pick is a no-op here — recordCoordinator ignores self-valued
+					// writes (see its doc comment), matching the last-resort self tier below.
+					this.recordCoordinator(key, pid)
+					this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'cohort')
+					return pid
+				}
+			} catch (err) {
+				this.log('findCoordinator:cohort-assembly-failed key=%s attempt=%d - %o', keyStr, attempt, err)
+			}
+
+			// fallback: prefer any existing connected peer that's not excluded or banned,
+			// scoped to this network's serving peers (a `foreign` or not-yet-confirmed
+			// `unknown` peer is never picked). Note this candidate set is built from
+			// connected REMOTE peers and never includes self, so when no serving peer is
+			// present selection falls through to the last-resort self-coordination block.
+			// Being remote-only, this tier needs no self-coordination guard check, unlike the
+			// cohort tier above.
+			// NOTE: this tier can pick a serving peer OUTSIDE the key's cohort when no cohort
+			// member is connected. That is a redirect hop, not a wrong placement: the receiving
+			// node's responsibility check redirects the request to a current cohort member (or
+			// refuses it). If redirect hops ever show up in profiles, prefer a not-connected
+			// cohort member we hold an address for over an out-of-cohort connected peer here.
+			const connectedCandidates = connected
+				.filter(p => this.isSelectable(p.toString(), excludedSet))
+				.sort((a, b) => (this.reputation?.getScore(a.toString()) ?? 0) - (this.reputation?.getScore(b.toString()) ?? 0))
+				.map(p => p.toString())
+			const { ranked: connRanked, droppedUnconfirmed: connDroppedUnconfirmed } = await this.filterByMembership(connectedCandidates)
+			if (connDroppedUnconfirmed) droppedUnconfirmedAnyAttempt = true
+			const connectedPick = connRanked[0]
+			if (connectedPick) {
+				const pid = peerIdFromString(connectedPick)
+				this.recordCoordinator(key, pid)
+				this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'connected-fallback')
+				return pid
+			}
+
+			// If no connections and not the last attempt, wait and retry
+			if (connected.length === 0 && attempt < maxRetries - 1) {
+				// Exclusion/ban filtered — a neighbour we may never pick is not something to
+				// wait for. Fed the whole proximity BAND rather than the cut cohort, and this
+				// network's membership filter (peerStore protocols) is deliberately NOT applied:
+				// a band member still `unknown` to it is exactly the peer that flips to `serves`
+				// inside the retry window, and a connection to ANY serving band member makes the
+				// connected fallback above succeed — so each one's presence must keep the window.
+				// FRET's own ring membership has already applied a stricter cut upstream —
+				// `assembleCohort` returns confirmed live ring members only — so a
+				// configured-but-never-reached bootstrap peer is absent from the band entirely,
+				// and only the dial-in-flight signal below can keep the window for it.
+				const knowable = band.filter(id => this.isSelectable(id, excludedSet));
+				if (!this.retryCouldImprove(knowable)) {
+					this.log('findCoordinator:retry-futile key=%s neighbors=%d dialsInFlight=%d mode=%s hwm=%d',
+						keyStr, knowable.length, this.dialsInFlight(), this.networkMode, this.networkHighWaterMark);
+					break;
+				}
+				this.log('findCoordinator:no-connections-retry key=%s attempt=%d delay=%dms', keyStr, attempt, retryDelayMs)
+				await new Promise(resolve => setTimeout(resolve, retryDelayMs))
+				continue
+			}
+		}
+
+		// last resort: self, only if not excluded, only if self is among the key's responsible
+		// peers, and only if the guard allows. A node that is NOT responsible for the key — one
+		// that does not serve storage at all, or one that `clusterSize` nearer serving peers
+		// outrank — never coordinates it, however isolated it is: a self-only commit there would
+		// leave a copy nobody looks for and a responsible peer without one. `lastCohort` is
+		// undefined only when every attempt's assembly threw (FRET unavailable), which is read
+		// as "not known to be responsible".
+		// NOTE: this also fails an ISOLATED READ of a block this node is not responsible for, even
+		// when an older local copy exists (before the cohort rule, such a read degraded to the
+		// node's own replica). No effect while the serving peers number at most `clusterSize`,
+		// where every node is in every cohort. If offline reads on a wider network ever matter,
+		// let a read fall back to a local copy flagged as unverified rather than widening this tier.
+		const self = this.libp2p.peerId
+		const selfInCohort = lastCohort?.includes(selfStr) ?? false
+		if (!excludedSet.has(selfStr) && selfInCohort) {
+			const decision = this.shouldAllowSelfCoordination(intent);
+			// Only a HARD denial fails the caller. A deferrable one (see
+			// SelfCoordinationDecision.deferrable) means self is merely not the preferred
+			// coordinator — by this point every better tier has already come up empty and the
+			// retry window has been spent, so refusing here would just convert "serve from my
+			// own replica, degraded" into an outright failure of the whole operation.
+			if (!decision.allow && decision.deferrable !== true) {
+				this.log('findCoordinator:self-coord-blocked key=%s reason=%s intent=%s', keyStr, decision.reason, intent);
+				throw new FindCoordinatorError(
+					FIND_COORDINATOR_ERROR_CODES.SELF_COORDINATION_BLOCKED,
+					`Self-coordination blocked: ${decision.reason}. No coordinator available for key.`
+				);
+			}
+			if (!decision.allow) {
+				this.log('findCoordinator:self-selected-degraded key=%s coordinator=%s reason=%s intent=%s',
+					keyStr, selfStr.substring(0, 12), decision.reason, intent);
+				this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'self-degraded')
+				return self
+			}
+			if (decision.warn) {
+				this.log('findCoordinator:self-selected-warn key=%s coordinator=%s reason=%s',
+					keyStr, selfStr.substring(0, 12), decision.reason);
+			} else {
+				this.log('findCoordinator:self-selected key=%s coordinator=%s reason=%s',
+					keyStr, selfStr.substring(0, 12), decision.reason);
+			}
+			this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'self')
+			return self
+		}
+
+		// Self is unavailable (excluded by the caller, or not responsible for the key) and
+		// selection found no eligible peer. If the membership filter is the reason the
+		// candidate set emptied (the only other peers are `foreign` — serving a DIFFERENT
+		// network — or `unknown` — not yet confirmed to serve this network), surface a
+		// distinct, accurate cause instead of the generic codes below.
+		if (droppedUnconfirmedAnyAttempt) {
+			this.log('findCoordinator:no-network-coordinator key=%s prefix=%s self=%s selfInCohort=%s',
+				keyStr, this.protocolPrefix ?? '?', selfStr.substring(0, 12), selfInCohort)
+			throw new FindCoordinatorError(
+				FIND_COORDINATOR_ERROR_CODES.NO_NETWORK_COORDINATOR,
+				`No coordinator available for key on network ${this.protocolPrefix ?? '?'}: ` +
+				`the remaining candidate peer(s) are foreign or not-yet-confirmed to serve this network's cluster/repo protocol.`
+			);
+		}
+
+		// Self is excluded. On a solo/bootstrap node (HWM<=1 and no other connected/FRET peers),
+		// this means the caller already tried self and the retry has nowhere to go — surface a
+		// distinct error so retry logic stops and the original first-attempt cause is preserved.
+		if (excludedSet.has(selfStr) && this.networkHighWaterMark <= 1) {
+			this.log('findCoordinator:self-exhausted-solo key=%s self=%s', keyStr, selfStr.substring(0, 12))
+			throw new FindCoordinatorError(
+				FIND_COORDINATOR_ERROR_CODES.SELF_COORDINATION_EXHAUSTED,
+				'Self-coordination exhausted on solo/bootstrap node (self already attempted). ' +
+				'The original first-attempt error describes the actual failure cause.'
+			);
+		}
+
+		const why = excludedSet.has(selfStr)
+			? 'all candidates excluded'
+			: lastCohort === undefined
+				? 'the responsible cohort could not be derived and no serving peer is connected'
+				: 'this node is not among the responsible peers and none of them is connected'
+		this.log('findCoordinator:no-coordinator key=%s self=%s selfInCohort=%s cohort=%d why=%s',
+			keyStr, selfStr.substring(0, 12), selfInCohort, lastCohort?.length ?? -1, why)
+		throw new FindCoordinatorError(
+			FIND_COORDINATOR_ERROR_CODES.NO_COORDINATOR_AVAILABLE,
+			`No coordinator available for key (${why})`
+		);
+	}
+
+	/**
+	 * Connection-derived addresses for the cluster record, keyed by peer id.
+	 *
+	 * Only OUTBOUND connections contribute — see {@link publishableConnectionAddr} for why an
+	 * inbound connection's `remoteAddr` is an ephemeral source socket that no third party can
+	 * reach. This is the only place `findCluster` derives addresses from connections, so the
+	 * rule has exactly one site.
+	 */
+	private getConnectedAddrsByPeer(): Record<string, string[]> {
+		const conns = this.libp2p.getConnections()
+		const byPeer: Record<string, string[]> = {}
+		for (const c of conns) {
+			const addr = publishableConnectionAddr(c, this.addressLog)
+			if (addr === undefined) continue
+			const id = c.remotePeer.toString()
+			const forPeer = byPeer[id] ??= []
+			forPeer.push(addr)
+		}
+		return byPeer
+	}
+
+	// NOTE: accepted tradeoff — a node with no peers recomputes the self-only cohort on every call
+	// (~2 per distinct block read; 144 calls in a 67-object cold apply). Measured 0.009 ms/call on
+	// Node with a wildcard TCP listener (test/bench-findcluster.mjs, N=2000, 2026-09-11), so a memo
+	// would save ~1.3 ms per apply while adding an invalidation hazard: a node that gains a peer, or
+	// finishes identifying one, must stop answering self-only immediately, and read-repair recovery
+	// relies on that widening. Revisit if an on-device (React Native) profile shows findCluster as
+	// material; then memoize ONLY the solo answer, invalidated on connection:open and peer:identify.
+	async findCluster(key: RoutingKey): Promise<ClusterPeers> {
+		const t0 = Date.now();
+		const keyStr = this.toCacheKey(key).substring(0, 12);
+		this.log('findCluster:start key=%s', keyStr);
+
+		// The responsible peers for the key, in proximity order — self among them only when it
+		// is one of the nearest `clusterSize` serving peers (see `assembleServingCohort`). On the
+		// scoped path the assembly's peerStore reads are handed back so the address backfill
+		// below does not read the same records twice.
+		const { cohort: ids, band, peerStoreRecords } = await this.assembleServingCohort(key)
+		const selfId = this.libp2p.peerId.toString()
+
+		const connectedByPeer = this.getConnectedAddrsByPeer()
+		const connectedPeerIds = Object.keys(connectedByPeer)
+
+		// Backfill addresses from the peerStore for cohort members we don't have
+		// a live connection to. The cohort is keyspace-determined and can include
+		// peers we know-of but haven't dialed yet; without this backfill those
+		// would be silently dropped. On the scoped path reuse the addresses already
+		// read into `peerStoreRecords` above (no second store.get per member); on the
+		// unscoped path (no record map) do the single peerStore read as before.
+		const backfillIds = ids.filter(id => id !== selfId)
+		const peerStoreAddrs = peerStoreRecords
+			? Object.fromEntries(
+				backfillIds
+					.map(id => [id, peerStoreRecords![id]?.addrs ?? []] as const)
+					.filter(([, addrs]) => addrs.length > 0)
+			)
+			: await this.getPeerStoreAddrsByPeer(backfillIds)
+
+		this.log('findCluster key=%s band=%d cohort=%d connected=%d', keyStr, band.length, ids.length, connectedPeerIds.length)
+		if (verbose) this.log('findCluster:detail key=%s cohortPeers=%o connectedPeers=%o', keyStr, ids, connectedPeerIds)
+
+		const peers: ClusterPeers = {}
+		// Cohort members we have no dialable address for. Admitting them is deliberate (see
+		// the note at the assignment below), but staying SILENT about it is what produced the
+		// reported symptom: clean membership logs on every node while every dial to the
+		// addressless member died instantly and the write never completed.
+		const addressless: string[] = []
+		// The OTHER way a member can be undialable by us: we hold addresses, but every one of
+		// them is a circuit through this node — the steady state for our own reservation holders.
+		// Counted separately because the two have different remedies (be taught an address, vs.
+		// wait for the client to re-dial us) and libp2p's dial error cannot tell them apart.
+		// These addresses are still PUBLISHED: a cohort sibling reaching the member through our
+		// relay is the working path, and dropping them would break it.
+		const selfRelayOnly: string[] = []
+
+		for (const idStr of ids) {
+			if (idStr === selfId) {
+				const raw = this.libp2p.peerId.publicKey?.raw ?? new Uint8Array()
+				peers[idStr] = { multiaddrs: this.getSelfMultiaddrs(), publicKey: u8ToString(raw, 'base64url') }
+				continue
+			}
+			const connectedStrings = connectedByPeer[idStr] ?? []
+			const peerStoreStrings = peerStoreAddrs[idStr] ?? []
+			// The union rule — connected-first, de-duplicated, validated — lives in
+			// `unionPublishableAddrs` so a cluster record and a redirect payload cannot describe
+			// the same peer differently. The sync form is used here (rather than
+			// `publishableAddrsForPeer`) because both halves are already in hand: the peerStore
+			// read above is batched across the whole cohort, and on the membership-scoped path it
+			// is the same `store.get` that fetched protocols.
+			const parsed = unionPublishableAddrs(connectedStrings, peerStoreStrings, this.addressLog)
+			const remotePeerId = peerIdFromString(idStr)
+			const raw = remotePeerId.publicKey?.raw ?? new Uint8Array()
+			// Note: parsed may be empty for a cohort member we have neither a
+			// live connection to nor a peerStore entry for. The dial will then
+			// surface as `code=none msg="no valid addresses"` and the caller's
+			// retry/exclude logic takes over — we intentionally do NOT drop
+			// addressless members here, because shrinking the cohort below
+			// `clusterSize` puts consensus supermajority out of reach.
+			const dialability = classifySelfDialability(parsed, selfId, this.addressLog)
+			if (dialability === 'none') addressless.push(idStr.substring(0, 12))
+			else if (dialability === 'self-relay-only') selfRelayOnly.push(idStr.substring(0, 12))
+			peers[idStr] = { multiaddrs: parsed, publicKey: u8ToString(raw, 'base64url') }
+		}
+
+		// Unconditional (not gated on `verbose`): this is the one line that turns a silent
+		// hang into a diagnosable one. A non-zero count means the cohort LOOKS healthy while
+		// some members cannot be dialed at all until someone teaches us their addresses
+		// (see `recordPeerAddresses` / `peer-address-book.ts`).
+		if (addressless.length > 0) {
+			this.log('findCluster:addressless-members key=%s count=%d of=%d peers=%o',
+				keyStr, addressless.length, Object.keys(peers).length, addressless)
+		}
+
+		// Same reasoning, second condition: a non-zero count here means we DO hold addresses for
+		// these members and still cannot dial them, because the only route we know runs through
+		// our own relay. No amount of retrying changes that (see `SelfRelayOnlyAddressesError`).
+		if (selfRelayOnly.length > 0) {
+			this.log('findCluster:self-relay-only-members key=%s count=%d of=%d peers=%o',
+				keyStr, selfRelayOnly.length, Object.keys(peers).length, selfRelayOnly)
+		}
+
+		this.log('findCluster:done key=%s ms=%d peers=%d addressless=%d selfRelayOnly=%d',
+			keyStr, Date.now() - t0, Object.keys(peers).length, addressless.length, selfRelayOnly.length)
+		return peers
+	}
+
+	/**
+	 * Look up the libp2p peerStore for known multiaddrs of the given peer ids.
+	 * Returns a map from peer-id string to multiaddr strings — empty/missing
+	 * when the peerStore has no entry. Errors are swallowed; we'd rather fail
+	 * back to the defense-in-depth drop than throw out of findCluster.
+	 */
+	private async getPeerStoreAddrsByPeer(ids: string[]): Promise<Record<string, string[]>> {
+		const out: Record<string, string[]> = {}
+		const store = (this.libp2p as { peerStore?: { get?: (id: PeerId) => Promise<{ addresses?: Array<{ multiaddr: { toString(): string } }> }> } }).peerStore
+		if (!store?.get) return out
+		await Promise.all(ids.map(async (idStr) => {
+			try {
+				const pid = peerIdFromString(idStr)
+				const peer = await store.get!(pid)
+				const addrs = (peer?.addresses ?? []).map(a => a.multiaddr.toString())
+				if (addrs.length > 0) out[idStr] = addrs
+			} catch {
+				// Unknown peer or peerStore failure — leave out of the map.
+			}
+		}))
+		return out
+	}
+
+	/**
+	 * Single-pass peerStore read returning BOTH protocols and addresses per peer from one
+	 * `store.get` call. Used on the membership-scoped `findCluster` hot path, where the
+	 * cohort needs protocols (to classify membership) AND addresses (to backfill dial
+	 * targets) for the same peers — reading them together avoids a second `store.get` per
+	 * finally-selected member. Same error handling as {@link getPeerStoreProtocolsByPeer}
+	 * and {@link getPeerStoreAddrsByPeer}: a missing peer or peerStore failure is left
+	 * absent from the map (caller treats absent protocols as 'unknown', absent addrs as none).
+	 */
+	private async getPeerStoreRecordsByPeer(ids: string[]): Promise<Record<string, PeerStoreRecord>> {
+		const out: Record<string, PeerStoreRecord> = {}
+		const store = (this.libp2p as { peerStore?: { get?: (id: PeerId) => Promise<{ protocols?: string[]; addresses?: Array<{ multiaddr: { toString(): string } }> }> } }).peerStore
+		if (!store?.get) return out
+		await Promise.all(ids.map(async (idStr) => {
+			try {
+				const pid = peerIdFromString(idStr)
+				const peer = await store.get!(pid)
+				const addrs = (peer?.addresses ?? []).map(a => a.multiaddr.toString())
+				out[idStr] = { protocols: peer?.protocols ?? [], addrs }
+			} catch {
+				// Unknown peer or peerStore failure — leave out of the map.
+			}
+		}))
+		return out
+	}
+
+	/**
+	 * Prefetch each peer's advertised protocol list from the libp2p peerStore.
+	 * Returns a map from peer-id string to its protocols (empty array when the peer
+	 * is absent or has not yet been identified). Mirrors {@link getPeerStoreAddrsByPeer};
+	 * errors are swallowed so a peerStore hiccup degrades to "unknown" rather than throwing.
+	 */
+	private async getPeerStoreProtocolsByPeer(ids: string[]): Promise<Record<string, string[]>> {
+		const out: Record<string, string[]> = {}
+		const store = (this.libp2p as { peerStore?: { get?: (id: PeerId) => Promise<{ protocols?: string[] }> } }).peerStore
+		if (!store?.get) return out
+		await Promise.all(ids.map(async (idStr) => {
+			try {
+				const pid = peerIdFromString(idStr)
+				const peer = await store.get!(pid)
+				out[idStr] = peer?.protocols ?? []
+			} catch {
+				// Unknown peer or peerStore failure — leave out (treated as 'unknown').
+			}
+		}))
+		return out
+	}
+
+	/**
+	 * Over-fetch width for network-membership scoping. A cross-network peer can sit
+	 * NEARER the key than a legitimate same-network peer and displace it from the
+	 * nearest-`clusterSize` window, so when scoping is active we ask FRET for a wider
+	 * proximity band and then keep the nearest peers that actually serve this network.
+	 * (A ring polluted by more cross-network peers than this band is the domain of the
+	 * separate FRET-side eviction follow-up; this band covers realistic co-location.)
+	 */
+	private membershipOverfetch(): number {
+		return Math.max(this.clusterSize * 4, this.clusterSize + 16)
+	}
+
+	/**
+	 * Does an advertised protocol list serve THIS network's storage — its namespaced `cluster`
+	 * or `repo` protocol? The one test behind every membership verdict, self's included.
+	 */
+	private servesThisNetwork(protocols: string[]): boolean {
+		return protocols.includes(`${this.protocolPrefix}/cluster/1.0.0`)
+			|| protocols.includes(`${this.protocolPrefix}/repo/1.0.0`)
+	}
+
+	/**
+	 * Does THIS node serve storage on this network? True when no `protocolPrefix` is
+	 * configured (the unscoped path, where every peer counts as serving), or when libp2p
+	 * advertises this network's `cluster` or `repo` protocol — the same test
+	 * {@link membershipOf} applies to a remote peer's peerStore protocol list, so self is
+	 * classified on exactly the same footing. A libp2p double with no `getProtocols` counts
+	 * as serving, the convention `getConnections?.()` already follows for mocks.
+	 *
+	 * Every production node registers both storage services today (`createLibp2pNode`), so the
+	 * `false` branch is defence in depth: it is what keeps a future client-only node out of every
+	 * cohort and away from every coordinator pick.
+	 */
+	private selfServes(): boolean {
+		if (this.protocolPrefix == null) return true
+		const protocols = this.libp2p.getProtocols?.()
+		if (protocols == null) return true
+		return this.servesThisNetwork(protocols)
+	}
+
+	/**
+	 * Classify a peer's network membership from its advertised protocols. Self is classified
+	 * from its own registered protocols ({@link selfServes}) rather than assumed to serve.
+	 * When no `protocolPrefix` is configured the filter is disabled and EVERY peer is
+	 * reported `serves`, so all callers behave exactly as before this scoping was added.
+	 */
+	private membershipOf(idStr: string, protocols: string[] | undefined): NetworkMembership {
+		if (this.protocolPrefix == null) return 'serves'
+		if (idStr === this.libp2p.peerId.toString()) return this.selfServes() ? 'serves' : 'foreign'
+		if (protocols == null || protocols.length === 0) return 'unknown'
+		return this.servesThisNetwork(protocols) ? 'serves' : 'foreign'
+	}
+
+	/**
+	 * The ordered serving cohort for `key`: the nearest `clusterSize` peers that serve this
+	 * network, in proximity order, with THIS node among them only when it genuinely is one of
+	 * them. Both `findCluster` (the replica set) and `findCoordinator` (the pick) derive from
+	 * this one assembly, so the two can never disagree about who is responsible for a block.
+	 *
+	 * The rule, stated once:
+	 *
+	 *  1. `coord = hashKey(key)` — the only hash between a block id and its cohort.
+	 *  2. `band = fret.assembleCohort(coord, wants)`: the nearest live ring members, alternating
+	 *     successor/predecessor outward from the coordinate; `wants` is the over-fetch width on
+	 *     the scoped path (see {@link membershipOverfetch}) and `clusterSize` otherwise.
+	 *  3. FRET's ring store holds this node as a live member, so `band` already contains self
+	 *     whenever self is among the nearest; absence means self is farther than every band
+	 *     member. A serving self absent from the band is appended LAST, so the cut below keeps
+	 *     it only when the band has room; a non-serving self is removed wherever it sits.
+	 *  4. Scoped path: keep only members whose membership is `serves`, order preserved.
+	 *  5. `cohort` = the first `clusterSize` of what remains.
+	 *
+	 * Consequences: a node with no live ring members other than itself gets a self-only cohort
+	 * (the solo short-circuits downstream are untouched); on a ring no wider than `clusterSize`
+	 * every serving node is in every cohort; on a wider ring self is in a block's cohort iff it
+	 * is among the nearest `clusterSize` serving members; a client-only node is in no cohort at
+	 * any width, and its `findCluster` may legitimately come back empty.
+	 *
+	 * NOTE: on the scoped path this classifies the WHOLE over-fetch band — one peerStore read per
+	 * band member, bounded by the number of live ring members — where the coordinator tier used
+	 * to classify only the connected neighbours. On a small network that is at most one read per
+	 * known peer. If peerStore reads per lookup ever show in a profile, memoize the per-peer
+	 * membership verdict with a short TTL rather than caching cohorts, which would have to be
+	 * invalidated on every ring change.
+	 */
+	private async assembleServingCohort(key: RoutingKey): Promise<ServingCohort> {
+		const fret = this.getFret()
+		// The only hash between a block id and its cohort: `key` is the id's raw utf8 (`routingKeyForBlock`).
+		const coord = await hashKey(key)
+		const scoped = this.protocolPrefix != null
+		// When membership scoping is active, over-fetch a wider proximity band so the nearest
+		// peers that SERVE this network are in the candidate pool even if cross-network peers
+		// sit nearer the key (see membershipOverfetch).
+		const wants = scoped ? this.membershipOverfetch() : this.clusterSize
+		const nearest = fret.assembleCohort(coord, wants)
+		const selfId = this.libp2p.peerId.toString()
+		const band = this.selfServes()
+			? (nearest.includes(selfId) ? nearest : [...nearest, selfId])
+			: nearest.filter(id => id !== selfId)
+		if (!scoped) return { cohort: band.slice(0, this.clusterSize), band }
+
+		// Network-membership scoping: a band member that serves a DIFFERENT network's protocol
+		// can never negotiate THIS network's cluster/repo dial, so it guarantees a super-majority
+		// failure rather than contributing a promise. Drop such 'foreign' members; build the
+		// cohort from positively-'serves' members only and NEVER admit a not-yet-identified
+		// ('unknown') member. A permanently cross-network peer and a freshly-discovered
+		// same-network peer mid-identify are indistinguishable while 'unknown' (both have an
+		// empty peerStore protocol list), so admitting an 'unknown' on the strength of a
+		// viability floor risks pulling a cross-network contaminant into the cohort — its repo
+		// dial then negotiates a different network's protocol and the whole write fails. A fresh
+		// same-network peer is not starved: it flips to 'serves' once identify completes and is
+		// re-included on the caller's retry, and in the meantime a self-only cohort (when self is
+		// the only serving member known) still completes the write under allowClusterDownsize
+		// (the default). One peerStore read per non-self band member yields both protocols (for
+		// the classification here) and addresses (reused by `findCluster`'s backfill).
+		const peerStoreRecords = await this.getPeerStoreRecordsByPeer(band.filter(id => id !== selfId))
+		const serving: string[] = []
+		let unknown = 0
+		let foreign = 0
+		for (const id of band) {
+			const m = this.membershipOf(id, peerStoreRecords[id]?.protocols)
+			if (m === 'serves') serving.push(id)
+			else if (m === 'unknown') unknown++
+			else foreign++
+		}
+		const cohort = serving.slice(0, this.clusterSize)
+		this.log('cohort:membership key=%s band=%d serves=%d unknown=%d foreign=%d cohort=%d selfInCohort=%s',
+			this.toCacheKey(key).substring(0, 12), band.length, serving.length, unknown, foreign, cohort.length, cohort.includes(selfId))
+		const protocolsByPeer = Object.fromEntries(Object.entries(peerStoreRecords).map(([id, r]) => [id, r.protocols]))
+		return { cohort, band, peerStoreRecords, protocolsByPeer }
+	}
+
+	/**
+	 * Scope a reputation-ordered candidate id list to this network for COORDINATOR
+	 * selection: keep ONLY peers confirmed to serve this network (`serves`), dropping both
+	 * `foreign` peers (serving another network) and `unknown` peers (peerStore protocol
+	 * list empty — not yet confirmed). Incoming (reputation) order is preserved among the
+	 * surviving `serves` peers. A no-op (returns the input unchanged, no drops) when
+	 * `protocolPrefix` is unset or the list is empty — the membership-disabled path is
+	 * therefore untouched.
+	 *
+	 * `protocolsByPeer`, when given, is a peerStore read the caller already made for these
+	 * peers (the cohort assembly's); otherwise the protocols are read fresh here.
+	 *
+	 * `droppedUnconfirmed` reports whether any candidate was excluded because it was not
+	 * confirmed to serve this network — `foreign` OR `unknown` under scoping — so the
+	 * caller can surface a distinct "no network coordinator" failure rather than a generic
+	 * one. An `unknown` peer is not gambled on as coordinator: a permanent cross-network
+	 * contaminant and a fresh same-network peer mid-identify are indistinguishable at an
+	 * instant, but the filter re-reads the peerStore on every retry attempt, so a genuine
+	 * same-network peer that completes `identify` within the retry window flips to `serves`
+	 * and is selected normally on that attempt.
+	 */
+	private async filterByMembership(ids: string[], protocolsByPeer?: Record<string, string[]>): Promise<{ ranked: string[]; droppedUnconfirmed: boolean }> {
+		if (this.protocolPrefix == null || ids.length === 0) return { ranked: ids, droppedUnconfirmed: false }
+		const selfStr = this.libp2p.peerId.toString()
+		const protocols = protocolsByPeer ?? await this.getPeerStoreProtocolsByPeer(ids.filter(id => id !== selfStr))
+		const serves: string[] = []
+		let droppedUnconfirmed = false
+		for (const id of ids) {
+			const m = this.membershipOf(id, protocols[id])
+			if (m === 'serves') serves.push(id)
+			else droppedUnconfirmed = true
+		}
+		return { ranked: serves, droppedUnconfirmed }
+	}
+}