@serfab/cadre-core 1.6.0 → 1.8.0

package/src/peer-dial.ts

@@ -24,8 +24,9 @@
  */
 
 import debug from 'debug';
-import type { Connection } from '@libp2p/interface';
-import type { Multiaddr } from '@multiformats/multiaddr';
+import type { Connection, PeerId } from '@libp2p/interface';
+import { peerIdFromString } from '@libp2p/peer-id';
+import type { Component, Multiaddr } from '@multiformats/multiaddr';
 import { withDeadline } from './control-stream.js';
 import { relayedDialBudgetMs } from './link-budget.js';
 
@@ -33,8 +34,9 @@ const log = debug('sereus:cadre:peer-dial');
 
 /**
  * Default limit on ONE address's dial attempt, in ms, at the DEFAULT declared link round trip:
- * `RELAYED_DIAL_ROUND_TRIPS` (4) x `DECLARED_LINK_ROUND_TRIP_MS` (3500 ms) = 14 000 ms. It was
- * a fixed 8000 ms before it was derived.
+ * `RELAYED_DIAL_ROUND_TRIPS` (4) x `DECLARED_LINK_ROUND_TRIP_MS` (3500 ms) plus the called
+ * machine's `ADMISSION_DECISION_TIMEOUT_MS` (2000 ms) = 16 000 ms (`relayedDialBudgetMs`). It
+ * was a fixed 8000 ms before it was derived.
  *
  * It has to cover the slowest address that should succeed, because an attempt
  * that needs longer fails the same way on every retry. That is a relayed dial on
@@ -117,9 +119,28 @@ export const DEFAULT_PEER_DIAL_BUDGET: Readonly<PeerDialBudget> = {
 
 /** The slice of a libp2p node {@link dialPeerAddrs} uses. */
 export interface AddrDialer {
+	/** This node's id, to recognise an address that relays through this node ({@link relaysThrough}). */
+	readonly peerId: PeerId;
 	dial(addr: Multiaddr, options: { signal: AbortSignal }): Promise<Connection>;
 }
 
+/**
+ * Thrown by {@link dialPeerAddrs} when it was given addresses but every one reaches the peer by
+ * relaying through this node, so none was dialed.
+ *
+ * This is where a relay lands for a peer that holds a reservation on it (a phone, or any node that
+ * cannot listen): the address that peer publishes is `/<relay transport>/p2p/<relay>/p2p-circuit/p2p/<peer>`,
+ * and dialing it from the relay itself fails with libp2p's `Can not dial self`. Nothing this node
+ * does can repair it; once the peer's connection drops, only the peer can reconnect. Callers log it
+ * as that rather than as a dial failure.
+ */
+export class SelfRelayOnlyError extends Error {
+	constructor(label: string) {
+		super(`${label}: every candidate address relays through this node; only the peer can reconnect`);
+		this.name = 'SelfRelayOnlyError';
+	}
+}
+
 /** One candidate's outcome, kept so the thrown error can name every attempt. */
 interface AddrAttemptFailure {
 	addr: Multiaddr;
@@ -131,23 +152,31 @@ interface AddrAttemptFailure {
  * first connection that forms. Direct addresses are tried before relayed ones
  * ({@link directBeforeRelayed}); otherwise the given order is kept.
  *
+ * Addresses that relay through this node are dropped first ({@link relaysThrough}):
+ * dialing one could only fail with `Can not dial self`. When that leaves nothing
+ * of a non-empty list, this throws {@link SelfRelayOnlyError} without dialing.
+ *
  * Addresses naming a transport this node lacks are not filtered out first: a
  * one-address `dial()` rejects those at once (`NoValidAddressesError`), so they
  * cost a log line, not time.
  *
- * Throws when no address connects — see {@link tryAddrsInTurn} for the error.
+ * Otherwise throws when no address connects — see {@link tryAddrsInTurn} for the error.
  *
  * @param label Names the dial in timeout messages and logs, e.g.
  *   `reconcileControlCohort dial of sibling <peerId>`; each attempt reads
  *   `<label> via <addr>`.
  */
-export function dialPeerAddrs(
+export async function dialPeerAddrs(
 	dialer: AddrDialer,
 	addrs: readonly Multiaddr[],
 	budget: PeerDialBudget,
 	label: string,
 ): Promise<Connection> {
-	return tryAddrsInTurn(directBeforeRelayed(addrs), budget, label, (addr, signal) => dialer.dial(addr, { signal }));
+	const dialable = withoutSelfRelayed(dialer, addrs, label);
+	if (addrs.length > 0 && dialable.length === 0) {
+		throw new SelfRelayOnlyError(label);
+	}
+	return tryAddrsInTurn(directBeforeRelayed(dialable), budget, label, (addr, signal) => dialer.dial(addr, { signal }));
 }
 
 /**
@@ -221,6 +250,51 @@ export function directBeforeRelayed(addrs: readonly Multiaddr[]): Multiaddr[] {
 	return [...addrs.filter((addr) => !relayed(addr)), ...addrs.filter(relayed)];
 }
 
+/** `addrs` without those that relay through `dialer` itself, each dropped one logged. */
+function withoutSelfRelayed(dialer: AddrDialer, addrs: readonly Multiaddr[], label: string): Multiaddr[] {
+	return addrs.filter((addr) => {
+		if (!relaysThrough(addr, dialer.peerId)) {
+			return true;
+		}
+		log('%s: skipping %s — it relays through this node', label, addr.toString());
+		return false;
+	});
+}
+
+/**
+ * Whether `addr` reaches its target by relaying through `relay` at any hop.
+ *
+ * A circuit address names its relay in the `p2p` component immediately before
+ * the `p2p-circuit` marker (`/<transport>/p2p/<relay>/p2p-circuit/p2p/<target>`),
+ * so the components are walked rather than the text searched: the target's id
+ * after the marker, a bare `/p2p-circuit` naming no relay, and a multi-hop chain
+ * each read correctly that way. Same rule as db-p2p's `routesThroughRelay`, which
+ * its package does not export.
+ */
+function relaysThrough(addr: Multiaddr, relay: PeerId): boolean {
+	const components = addr.getComponents();
+	return components.some((component, i) => component.name === 'p2p-circuit' && namesPeer(components[i - 1], relay));
+}
+
+/**
+ * Whether `component` is a `p2p` component naming `peer`. Compared as canonical
+ * strings because a multiaddr keeps a peer id in whichever form it was written
+ * (base58 or CIDv1). `PeerId.equals` is avoided because test doubles supply the
+ * dialer's `peerId` with `toString` only.
+ */
+function namesPeer(component: Component | undefined, peer: PeerId): boolean {
+	if (component?.name !== 'p2p' || component.value === undefined) {
+		return false;
+	}
+	const expected = peer.toString();
+	try {
+		return peerIdFromString(component.value).toString() === expected;
+	} catch (err) {
+		log('cannot read %s as a peer id; treating it as not this node: %o', component.value, err);
+		return false;
+	}
+}
+
 function allAttemptsFailed(label: string, failures: AddrAttemptFailure[]): Error {
 	if (failures.length === 0) {
 		return new Error(`${label}: no candidate addresses`);

package/src/peer-join-backfill.ts

@@ -1,17 +1,28 @@
 import debug from 'debug';
-import type { Connection, Libp2p, PeerId } from '@libp2p/interface';
+import type { IdentifyResult, Libp2p, PeerId } from '@libp2p/interface';
 import type { ActionId, IPeerNetwork } from '@optimystic/db-core';
-import { BlockTransferClient, type BlockCommitProof, type IRawStorage } from '@optimystic/db-p2p';
+import { BlockTransferClient, buildBlockTransferProtocol, type BlockCommitProof, type IRawStorage } from '@optimystic/db-p2p';
 import { peerJoinPushBudget } from './link-budget.js';
 
 // Peer-join whole-store block catch-up, shared by the STRAND networks and the CONTROL
-// network. On `connection:open` (debounced) it pushes every committed, materialized block
-// in the local raw store to the new peer, so a machine that joined after blocks were
+// network. On a new peer's `peer:identify` result — libp2p's identify protocol runs once per
+// connection and reports the protocols the remote supports — naming this network's own
+// block-transfer protocol, it schedules a debounced push of every committed, materialized
+// block in the local raw store to that peer, so a machine that joined after blocks were
 // committed still ends up physically holding them. Optimystic has no cohort-join catch-up
 // of its own; a block committed while its writer was alone has exactly one holder forever
 // without this (named collection-header blocks are written once, at collection creation,
 // and their revision never moves again — so no later commit ever carries them anywhere).
 //
+// A peer whose identify does not name the protocol — a bare circuit relay, a bootstrap node,
+// or (on the control network) a stranger the inbound gate admits without membership — is
+// never scheduled at all: it cannot receive anything, since the protocol id is namespaced per
+// network and the dial would simply fail. Before this filter existed, such a peer WAS
+// scheduled, failed every dial, and after `PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES` produced a
+// `console.warn` naming it — gotchoices/sereus#18 is two relay-only parties restarting and
+// printing exactly that warning about their own relay, forever, on every reconnect. See
+// {@link speaksBlockTransfer}.
+//
 // NOTE: this copies the WHOLE local store to every newly connected peer, which is right
 // while a network is one party's handful of machines (see docs/architecture.md →
 // Replication cluster size — the control network replicates to the whole party by intent,
@@ -26,12 +37,10 @@ import { peerJoinPushBudget } from './link-budget.js';
 // Membership — the one place the two networks differ, expressed as the optional
 // `authorizePeer` dep:
 //
-// - STRAND networks pass none. Anything connected on a strand's own libp2p network already
-//   receives cohort replicas of new commits, so pushing older blocks to it exposes nothing
-//   new; adding a gate would diverge from what ordinary replication already does there. A
-//   peer that does NOT speak the strand's block-transfer protocol (a bare circuit relay or
-//   bootstrap node the strand node also connects to) cannot receive anything: the protocol
-//   id is namespaced per strand, so the dial fails and the push is dropped.
+// - STRAND networks pass none. Anything that speaks the strand's own block-transfer protocol
+//   already receives cohort replicas of new commits, so pushing older blocks to it exposes
+//   nothing new; adding a gate would diverge from what ordinary replication already does
+//   there.
 // - The CONTROL network MUST pass one, because that argument does not carry over: its
 //   inbound connection gate deliberately admits non-members in several states (an
 //   un-enrolled node taking its seed, an open enrollment window, an outstanding
@@ -40,8 +49,8 @@ import { peerJoinPushBudget } from './link-budget.js';
 //   peer would hand a stranger the party's entire membership, addresses and strand list.
 //   `CadreNode` passes `isAuthorizedMember`; the gate is consulted at PUSH time, not at
 //   schedule time, and fails closed on a thrown check. A denied run is not memoized, so
-//   the peer is retried on its next `connection:open` — or sooner, via
-//   `scheduleConnectedPeers()` on a membership change (the production join order is
+//   the peer is retried on its next `peer:identify` (a reconnect re-runs identify) — or
+//   sooner, via `scheduleConnectedPeers()` on a membership change (the production join order is
 //   connect-then-authorize, so the denial at dial time is the expected first pass).
 //
 // Both per-push deadlines are DERIVED from the declared link round trip
@@ -54,22 +63,23 @@ import { peerJoinPushBudget } from './link-budget.js';
 // `packages/integration-tests/src/scenarios/relayed-dial-cost-by-latency.integration.ts`.
 //
 // It does NOT work at every speed. Above the declared link, libp2p's own dial and
-// inbound-upgrade limits — derived from the same declaration — abandon the connection before
-// any deadline here is consulted, and the listener's one makes that failure look like an absent
-// peer rather than a timeout. That is also what happens when the machine being caught up
-// declared a FASTER link than this one, since its limit is the listener's. See
-// `link-budget.ts` ("libp2p's own two limits", "What still fails at the supported link").
+// inbound-upgrade limits — which Optimystic derives from the same declaration — abandon the
+// connection before any deadline here is consulted, and the listener's one makes that failure
+// look like an absent peer rather than a timeout. That is also what happens when the machine
+// being caught up declared a FASTER link than this one, since its limit is the listener's. See
+// `link-budget.ts` ("Optimystic's deadlines, from the same declaration", "What still fails at
+// the supported link").
 //
 // RETRY, and why it backs off. A run whose PUSH FAILED — the transport threw, which is what
 // a dial or response deadline expiring looks like here — re-arms on a doubling backoff
-// (`retryBackoffMs` to `maxRetryBackoffMs`), and a `connection:open` arriving while that wait
+// (`retryBackoffMs` to `maxRetryBackoffMs`), and a `peer:identify` arriving while that wait
 // is outstanding is DROPPED rather than collapsing it back to the debounce. Both halves are
 // load-bearing:
 //
 // - Without the re-arm, a transient push failure over a stable connection left the peer
 //   partially copied until its next reconnect (read repair still covered reads meanwhile).
 // - Without dropping churn inside the wait, a peer that cannot be reached at all is
-//   re-dialled on every `connection:open` forever. That is not hypothetical: the 2026-09-26
+//   re-dialled on every `peer:identify` forever. That is not hypothetical: the 2026-09-26
 //   relayed reproduction shows one peer re-opening a connection about every 14.5 s for a
 //   200-second run, each event starting a catch-up whose dial could not possibly finish.
 //   The connection kept re-appearing because Optimystic's own block-transfer push path
@@ -87,13 +97,13 @@ import { peerJoinPushBudget } from './link-budget.js';
 // {@link Chunk.proofs}). Re-arming on those would re-push the WHOLE store to that peer every
 // `maxRetryBackoffMs` for as long as the node runs, and report the failure below as a link
 // budget problem when nothing about the link is wrong. All three still leave the peer
-// un-memoized, so its next `connection:open` retries — the behaviour that predates the
+// un-memoized, so its next `peer:identify` retries — the behaviour that predates the
 // backoff, and the right one for a verdict rather than a timeout. Denial in particular is
 // re-driven on purpose by `scheduleConnectedPeers()` the moment the membership commit lands,
 // because the control network's join order is connect-then-authorize.
 //
 // A re-arm is also skipped when the peer is no longer CONNECTED. This module's trigger is
-// `connection:open`, so a peer that went away already has one: re-arming instead would leave
+// `peer:identify`, so a peer that went away already has one: re-arming instead would leave
 // a machine dialing a peer it cannot see once a minute for the rest of its uptime.
 //
 // After `PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES` consecutive failures one `console.warn`
@@ -101,16 +111,25 @@ import { peerJoinPushBudget } from './link-budget.js';
 // nothing at all: the connection simply never appears and only a DEBUG log mentions a dial
 // timeout.
 //
-// NOTE: a failing dial to a non-speaking peer costs one dial timeout per attempt, and is
-// never memoized (only clean runs are). Bounded by the backoff above plus the
-// unreachable-peer bail in `runCatchUp` — one dial per attempt, not one per chunk. If a node
-// ever holds many such connections, or the enumeration ahead of the first chunk gets
-// expensive, pre-check `libp2p.peerStore` for this network's block-transfer protocol before
-// enumerating.
+// NOTE: the protocol check happens once — either when a connection's `peer:identify` fires,
+// or, for a peer already connected when this instance starts, when `scheduleConnectedPeers()`
+// reads its protocols back from the peer store — and is never repeated once a peer is
+// scheduled. A peer that stops speaking the protocol after being scheduled (should that ever
+// happen) is not de-scheduled; `runCatchUp`'s own unreachable-peer bail is what would catch
+// that case instead. `peer:identify` also fires on every identify-push from a connected peer
+// (address or protocol changes), which only re-enters the debounce — cheap, and dropped
+// outright for caught-up peers and peers inside a backoff wait.
+//
+// NOTE: a same-network peer whose identify never completes on a connection (the identify
+// stream times out over a slow relayed link, say) is not caught up until a later identify
+// succeeds — a reconnect, an identify-push, or on the control network a membership-change
+// re-drive. Accepted: every db-p2p node runs identify, and read repair still covers reads
+// meanwhile; if relayed links ever routinely outlast identify's timeout, raise that timeout
+// in the node builder rather than scheduling unidentified peers here.
 //
 // NOTE: a peer that disconnects INSIDE a backoff wait still costs the one attempt that wait
 // was already armed for — the connectivity check is made when the re-arm is decided, not when
-// the timer fires, and this module subscribes to `connection:open` only. One dial, not a
+// the timer fires, and this module subscribes to `peer:identify` only. One dial, not a
 // recurring one; if a node ever holds many transient peers, subscribe to `connection:close`
 // and clear the pending timer there.
 
@@ -124,6 +143,18 @@ const log = debug('sereus:cadre:peer-join-backfill');
  */
 export const MAX_BLOCK_MESSAGE_BYTES = 8 * 1024 * 1024;
 
+/**
+ * Whether an identified peer's protocol list names this network's own block-transfer
+ * protocol — the one gate that decides whether {@link PeerJoinBackfill} schedules a peer at
+ * all. A peer that lacks it (a bare circuit relay, a bootstrap node, a stranger the control
+ * network's inbound gate admitted without membership) cannot receive a push no matter how
+ * long it is dialed, since the protocol id is namespaced per network. Exported because a
+ * later strand peer-address ticket's identify-driven observation needs the identical test.
+ */
+export function speaksBlockTransfer(protocols: readonly string[], protocolPrefix: string): boolean {
+  return protocols.includes(buildBlockTransferProtocol(protocolPrefix));
+}
+
 /**
  * Consecutive failed catch-up runs against ONE peer before the module says so on
  * `console.warn` rather than only in its DEBUG log. At the default backoff that is reached
@@ -146,7 +177,8 @@ export interface PeerJoinBackfillConfig {
   maxChunkBlocks?: number;
   /**
    * Per-push dial deadline, ms. Default {@link peerJoinPushBudget}'s `dialTimeoutMs` — four link
-   * round trips at the declared link, 14 000 ms as shipped. NOT a fixed number: a relayed dial
+   * round trips at the declared link plus the called machine's admission decision, 16 000 ms as
+   * shipped. NOT a fixed number: a relayed dial
    * costs a fixed number of exchanges, so a host on a slower link moves this (and every other
    * cadre dial budget) by declaring `NetworkConfig.linkRoundTripMs`. Naming it here still wins
    * over the derived value — `link-budget.ts` has the counts and the measurement.
@@ -277,7 +309,7 @@ function base64WireBytes(rawBytes: number): number {
  * Best-effort throughout: nothing here throws into a libp2p event handler or into a
  * runtime bring-up; a failed chunk is logged and the run continues. A peer is marked
  * fully caught up ONLY after a run with no thrown chunk and an empty `missing` list, so
- * the next `connection:open` from a peer whose catch-up failed retries it.
+ * the next `peer:identify` from a peer whose catch-up failed retries it.
  */
 export class PeerJoinBackfill {
   private readonly config: Required<PeerJoinBackfillConfig>;
@@ -303,31 +335,43 @@ export class PeerJoinBackfill {
   private readonly failures = new Map<string, number>();
   /**
    * Epoch ms before which a peer's catch-up must not be re-run, set alongside a backoff timer
-   * that will run it. Its presence is what makes `connection:open` churn free: a schedule
+   * that will run it. Its presence is what makes `peer:identify` churn free: a schedule
    * arriving inside the wait is dropped, rather than collapsing the backoff to the debounce.
    */
   private readonly retryAfter = new Map<string, number>();
   /** Peers already reported on `console.warn`; reset when a run finally lands cleanly. */
   private readonly warned = new Set<string>();
-  private readonly onConnectionOpen: (evt: CustomEvent<Connection>) => void;
+  private readonly onPeerIdentify: (evt: CustomEvent<IdentifyResult>) => void;
   private loggedNoListBlockIds = false;
 
   constructor(private readonly deps: PeerJoinBackfillDeps, config?: PeerJoinBackfillConfig) {
     this.config = { ...DEFAULT_PEER_JOIN_BACKFILL, ...config };
     this.createPushClient = deps.createPushClient
       ?? ((peerId) => new BlockTransferClient(peerId, deps.peerNetwork, deps.protocolPrefix));
-    this.onConnectionOpen = (evt) => this.schedulePeer(evt.detail.remotePeer);
+    this.onPeerIdentify = (evt) => {
+      const { peerId, protocols } = evt.detail;
+      if (speaksBlockTransfer(protocols, this.deps.protocolPrefix)) {
+        this.schedulePeer(peerId);
+      }
+    };
   }
 
-  /** Subscribe to connection:open AND schedule a catch-up for peers already connected. */
+  /**
+   * Subscribe to `peer:identify` AND schedule a catch-up for already-connected peers whose
+   * stored protocols already name this network's block-transfer protocol — a peer that does
+   * not speak it (a bare circuit relay, a bootstrap node) is never scheduled at all. See
+   * {@link speaksBlockTransfer} and the module comment.
+   */
   start(): void {
     if (this.started || this.stopped || !this.config.enabled) return;
     this.started = true;
-    this.deps.libp2p.addEventListener('connection:open', this.onConnectionOpen);
-    // A runtime rebuilt over live connections (resumeStrand) never sees their
-    // connection:open, so walk what is already connected once.
-    const scheduled = this.scheduleConnectedPeers();
-    log('[%s] started (%d peer(s) already connected)', this.deps.label, scheduled);
+    this.deps.libp2p.addEventListener('peer:identify', this.onPeerIdentify);
+    // A runtime rebuilt over live connections (resumeStrand) never sees their peer:identify —
+    // it already fired before this instance existed, but its result is persisted in the peer
+    // store — so walk what is already connected once.
+    void this.scheduleConnectedPeers().then((scheduled) => {
+      log('[%s] started (%d peer(s) already connected)', this.deps.label, scheduled);
+    });
   }
 
   /** Unsubscribe, clear timers; in-flight runs observe the stopped flag and bail. */
@@ -335,7 +379,7 @@ export class PeerJoinBackfill {
     if (this.stopped) return;
     this.stopped = true;
     if (this.started) {
-      this.deps.libp2p.removeEventListener('connection:open', this.onConnectionOpen);
+      this.deps.libp2p.removeEventListener('peer:identify', this.onPeerIdentify);
     }
     for (const timer of this.timers.values()) {
       clearTimeout(timer);
@@ -347,27 +391,46 @@ export class PeerJoinBackfill {
   }
 
   /**
-   * (Re-)schedule a debounced catch-up for every currently-connected peer not yet caught
-   * up. Idempotent and cheap (caught-up peers are skipped before any timer is set, and a
-   * peer whose run is in flight is deferred to the end of that run rather than dropped).
-   * Driven by {@link start}, and — on a gated network — by the embedder whenever
-   * membership changes, so a peer whose first pass was denied (connected before it was
-   * authorized: the production join order) is retried without waiting for a reconnect.
-   * Returns how many distinct peers were considered (for the start() log) — a peer holding
-   * several connections is one peer, and is scheduled once.
+   * (Re-)schedule a debounced catch-up for every currently-connected peer whose protocols, as
+   * already stored in the libp2p peer store, name this network's block-transfer protocol. A
+   * peer not yet in the peer store — its identify has not finished — is left to the
+   * `peer:identify` handler rather than dialed blind; one whose stored protocols are known
+   * and lack ours is skipped outright. Idempotent and cheap otherwise (caught-up peers are
+   * skipped before any timer is set, and a peer whose run is in flight is deferred to the end
+   * of that run rather than dropped). Driven by {@link start}, and — on a gated network — by
+   * the embedder whenever membership changes, so a peer whose first pass was denied (connected
+   * before it was authorized: the production join order) is retried without waiting for a
+   * reconnect. Returns how many distinct peers were considered (for the start() log) — a peer
+   * holding several connections is one peer, and is scheduled once.
    */
-  scheduleConnectedPeers(): number {
+  async scheduleConnectedPeers(): Promise<number> {
     if (this.stopped) return 0;
-    const peers = new Set<string>();
+    const peers = new Map<string, PeerId>();
     for (const connection of this.deps.libp2p.getConnections()) {
-      const key = connection.remotePeer.toString();
-      if (peers.has(key)) continue;
-      peers.add(key);
-      this.schedulePeer(connection.remotePeer);
+      peers.set(connection.remotePeer.toString(), connection.remotePeer);
     }
+    await Promise.all([...peers.values()].map((peerId) => this.scheduleIfKnownToSpeak(peerId)));
     return peers.size;
   }
 
+  /** Schedules `peerId` only if the peer store already knows it speaks this network's protocol. */
+  private async scheduleIfKnownToSpeak(peerId: PeerId): Promise<void> {
+    let protocols: string[];
+    try {
+      ({ protocols } = await this.deps.libp2p.peerStore.get(peerId));
+    } catch (error) {
+      // NotFoundError: identify has not finished. Leave it to the `peer:identify` handler
+      // rather than dialing blind. Anything else is unexpected — log it and skip the peer.
+      if ((error as Error).name !== 'NotFoundError') {
+        log('[%s] peer store read for %s failed — not scheduling: %o', this.deps.label, peerId.toString(), error);
+      }
+      return;
+    }
+    if (speaksBlockTransfer(protocols, this.deps.protocolPrefix)) {
+      this.schedulePeer(peerId);
+    }
+  }
+
   /** Debounced entry point for connection churn: one run per peer per settle window. */
   private schedulePeer(peerId: PeerId): void {
     const key = peerId.toString();
@@ -380,7 +443,7 @@ export class PeerJoinBackfill {
     }
     // A peer whose last run failed is already re-armed on a backoff timer that will run it, so
     // DROP this schedule instead of shortening the wait — otherwise a peer that cannot be
-    // reached is re-dialled on every connection:open forever (see the module comment's retry
+    // reached is re-dialled on every peer:identify forever (see the module comment's retry
     // paragraph). A denied run never gets here: it does not set a backoff.
     const retryAt = this.retryAfter.get(key);
     if (retryAt !== undefined && Date.now() < retryAt) return;
@@ -420,7 +483,7 @@ export class PeerJoinBackfill {
         // rejection are all verdicts a retry cannot change, and re-arming on them would
         // re-push the whole store to that peer forever. See the module comment.
         //
-        // Gated on `started` too: the re-arm exists to REPLACE a connection:open-driven retry,
+        // Gated on `started` too: the re-arm exists to REPLACE a peer:identify-driven retry,
         // so a caller driving `catchUpPeer` by hand against a backfill that was never started
         // owns its own retry policy and must not be left holding a background timer.
         this.scheduleRetryWithBackoff(peerId);
@@ -452,7 +515,7 @@ export class PeerJoinBackfill {
   /**
    * Re-arm one peer's catch-up after a run whose push failed, on a wait that doubles
    * per consecutive failure up to `maxRetryBackoffMs`. Sets {@link retryAfter} alongside the
-   * timer, which is what makes `connection:open` churn inside the wait free.
+   * timer, which is what makes `peer:identify` churn inside the wait free.
    */
   private scheduleRetryWithBackoff(peerId: PeerId): void {
     const key = peerId.toString();

package/src/push-fanout.ts

@@ -198,6 +198,12 @@ export class PushFanoutService {
    * double-wake). Only a dial/transport REJECTION means the phone is suspended
    * and unreachable over the control network, which is the one case that falls
    * through to FCM/APNs.
+   *
+   * NOTE: the platform push waits for the whole direct dial to fail, up to
+   * `DEFAULT_WAKE_DIAL_BUDGET_MS` (46 s at the default declared link). A suspended
+   * phone typically fails its relay address fast and spends the rest on its direct
+   * one. If that delay shows up, start the platform push in parallel with the dial,
+   * or after its first attempt.
    */
   private async wakePeer(peerId: string, strandId: string, reason: string): Promise<void> {
     // A wake of either kind is now being attempted → arm the cooldown up front.

package/src/relay-reservation.ts

@@ -143,7 +143,9 @@ export interface RelayReservationState {
 /**
  * How long {@link driveRelayReservation} waits for a reservation to appear, at the DEFAULT
  * declared link round trip: `RELAY_RESERVATION_ROUND_TRIPS` (4) x `DECLARED_LINK_ROUND_TRIP_MS`
- * (3500 ms) = 14 000 ms, where it was a fixed 10_000 before it was derived.
+ * (3500 ms), plus 2 x `ADMISSION_DECISION_TIMEOUT_MS` (2000 ms) for a party-run relay's
+ * connection and reservation decisions, = 18 000 ms (`relayReservationBudgetMs`), where it was a
+ * fixed 10_000 before it was derived.
  *
  * Counted rather than chosen because this one deadline bounds the whole drive — dial the relay,
  * request the reservation, wait — and each of those costs a fixed number of exchanges, not a

package/src/relay-server.ts

@@ -0,0 +1,98 @@
+/**
+ * The circuit-relay SERVER a party-run node runs — whether it runs one, and with which
+ * `@libp2p/circuit-relay-v2` init — resolved once from `NetworkConfig` for both node
+ * kinds: the control node (`cadre-node.ts` → `buildControlNodeOptions`) and every strand
+ * node (`strand-instance-manager.ts` → `buildStrandRuntime`). One function decides both
+ * answers so the two build sites cannot drift apart.
+ *
+ * WHY cadre sets an init at all. libp2p's server defaults `applyDefaultLimit` to true,
+ * which stamps every reservation with `Limit { data: 128 KiB, duration: 2 min }`; libp2p
+ * marks each connection relayed under it "limited" and resets it once either cap is
+ * reached, and db-p2p's database protocols refuse a limited connection outright (they do
+ * not set `runOnLimitedConnection`). A party-run relay exists to carry that party's own
+ * database traffic, so the cap cut off every sync and chat history forwarded through it
+ * (gotchoices/sereus#19). The dedicated relays (`ops/docker/libp2p-infra`, and the
+ * `startDedicatedRelay` test fixture that stands in for it) already turn the limit off;
+ * this is the same policy for the party-run kind.
+ */
+
+import type { CircuitRelayServerInit, ServerReservationStoreInit } from '@libp2p/circuit-relay-v2';
+import type { NetworkConfig, NodeProfile } from './types.js';
+
+/**
+ * Default size of a party-run relay's reservation store, raised from libp2p's 15.
+ *
+ * A NAT'd machine reserves one slot for its control node and one for each strand it
+ * serves, all on the same relay (`strand-network-config.ts` hands strand nodes the
+ * control node's `network.relayAddrs`), so the store needs
+ * `NAT'd machines × (1 + strands each)` slots. At libp2p's 15, three phones serving four
+ * strands each already fill it. 128 covers, for example, ten NAT'd machines serving eleven
+ * strands each with the unauthorized-reservation budget's 8 slots
+ * (`MAX_UNAUTHORIZED_RELAY_RESERVATIONS`) still free on top — one party's worth, where the
+ * dedicated relay's 500 is sized for many parties. A reservation costs the server a map
+ * entry and a timer, not a connection's worth of state, so the headroom is cheap.
+ */
+export const PARTY_RELAY_MAX_RESERVATIONS = 128;
+
+/**
+ * How long a party-run relay holds a reservation that is not refreshed: libp2p's own
+ * default (2 h), set EXPLICITLY so that cadre, not a libp2p constant it cannot import,
+ * owns the value the unauthorized-reservation budget has to agree with (see
+ * {@link ResolvedRelayServer.init}).
+ */
+export const PARTY_RELAY_RESERVATION_TTL_MS = 2 * 60 * 60 * 1000;
+
+/**
+ * The reservation-store settings every party-run relay resolves unless the caller
+ * overrides them one key at a time through `network.relayServerInit.reservations`.
+ * `applyDefaultLimit: false` is the point of this module — see the module doc.
+ */
+const PARTY_RELAY_RESERVATION_DEFAULTS = {
+  applyDefaultLimit: false,
+  maxReservations: PARTY_RELAY_MAX_RESERVATIONS,
+  reservationTtl: PARTY_RELAY_RESERVATION_TTL_MS
+} as const satisfies ServerReservationStoreInit;
+
+/** Reservation settings with the three keys cadre always resolves made definite. */
+export type ResolvedRelayReservations = ServerReservationStoreInit
+  & Required<Pick<ServerReservationStoreInit, keyof typeof PARTY_RELAY_RESERVATION_DEFAULTS>>;
+
+/** What {@link resolveRelayServer} decides for one node. */
+export interface ResolvedRelayServer {
+  /** Does this node run the relay server? Passed as db-p2p's `relay`. */
+  enabled: boolean;
+  /**
+   * The server's init, passed as db-p2p's `relayServerInit` when {@link enabled}: the
+   * party-run defaults with the caller's `network.relayServerInit` merged over them.
+   * `reservations.reservationTtl` is always set, which is what lets the control node's
+   * unauthorized-reservation budget expire its entries on the server's own clock.
+   */
+  init: CircuitRelayServerInit & { reservations: ResolvedRelayReservations };
+}
+
+/**
+ * Resolve the relay server for a node built from `network` with `profile`.
+ *
+ * `enabled`: an explicit `network.enableRelay` wins; otherwise storage-profile nodes run
+ * the server (they are the machines with the connectivity and uptime to be a relay).
+ *
+ * `init`: MERGED, not replaced. `reservations` is merged key by key over the party-run
+ * defaults, so a caller who sets only `maxReservations` does not silently get the data
+ * limit back; every other top-level key is taken from the caller as given. A key set to
+ * `undefined` counts as unset, so the default beneath it holds.
+ */
+export function resolveRelayServer(network: NetworkConfig | undefined, profile: NodeProfile): ResolvedRelayServer {
+  const override = network?.relayServerInit;
+  return {
+    enabled: network?.enableRelay ?? (profile === 'storage'),
+    init: {
+      ...override,
+      reservations: { ...PARTY_RELAY_RESERVATION_DEFAULTS, ...definedEntries(override?.reservations) }
+    }
+  };
+}
+
+/** `obj` without its `undefined`-valued keys, so spreading it never erases a default. */
+function definedEntries<T extends object>(obj: T | undefined): Partial<T> {
+  return Object.fromEntries(Object.entries(obj ?? {}).filter(([, value]) => value !== undefined)) as Partial<T>;
+}