@serfab/cadre-core 1.4.0 → 1.6.0

package/dist/link-budget.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Dial and reservation budgets derived from ONE declared link round trip, instead of fixed
+ * millisecond numbers chosen on a fast local network.
+ *
+ * Reaching another machine through a relay costs a FIXED NUMBER OF EXCHANGES, not a fixed
+ * number of milliseconds. So every budget written as milliseconds has a link speed above which
+ * it can never open a connection at all — and the slower the link, the more of them fall over,
+ * silently, because an abandoned dial looks the same as a peer that is not there. Counting round
+ * trips instead is what stops that class of defect coming back: the next person to widen a
+ * budget changes ONE declaration, and the next person to add a dial writes down its round-trip
+ * count beside the arithmetic.
+ *
+ * ── The instrument ──
+ *
+ * Every count and every number below comes from
+ * `packages/integration-tests/src/scenarios/relayed-dial-cost-by-latency.integration.ts`, which
+ * is committed and opt-in (`RELAY_DIAL_COST=1`). **Its doc comment is the single home of the
+ * measurement**; this module holds only what the derivation needs. Re-run it before changing
+ * anything here.
+ *
+ * ── The unit ──
+ *
+ * ONE LINK ROUND TRIP is a message from one machine reaching the other and a reply coming
+ * back, over the path those two machines actually use — through the relay, when that is the
+ * only way they can reach each other. In the instrument, which injects a constant ONE-WAY
+ * frame delay `d`, one link round trip is `2d`.
+ *
+ * A leg between a node and the RELAY is half a link round trip, because it crosses one of the
+ * two hops rather than both. That is why the reservation drive's cost reads as "four
+ * node-to-relay round trips" in one telling and "two link round trips" in another: same
+ * quantity, different unit. This module uses the LINK round trip throughout, so there is one
+ * unit to reason in.
+ *
+ * ── The counts, and what they cost ──
+ *
+ * | operation                                            | link round trips | at the declared default |
+ * | ---------------------------------------------------- | ---------------- | ----------------------- |
+ * | open a relayed connection to another machine          | 4                | 14 000 ms               |
+ * | dial the relay itself                                 | 1                | 3 500 ms                |
+ * | request a reservation on an open relay connection     | 1                | 3 500 ms                |
+ * | negotiate a protocol over an established circuit      | 1                | 3 500 ms                |
+ *
+ * **Measured** 2026-09-26, one Windows machine, loopback dedicated relay: a relayed dial took
+ * 20-25 ms at no delay, **7 255-7 279 ms at 900 ms one-way**, and **12 066-12 094 ms at 1 500 ms
+ * one-way**. Four link round trips of pure delay would be 7 200 and 12 000, so the real cost
+ * sits about 60-95 ms ABOVE the arithmetic — the handshakes, which no delay figure contains.
+ * That residue is why {@link DECLARED_LINK_ROUND_TRIP_MS} carries headroom over the link sereus
+ * supports rather than matching it exactly: a declaration equal to the supported round trip
+ * would derive a budget marginally BELOW the dial it has to contain.
+ *
+ * ── libp2p's own two limits ──
+ *
+ * Two limits inside libp2p bound the same relayed dial as cadre's budgets do, and both were
+ * 10 000 ms until `@optimystic/db-p2p` 1.7.0 let an embedder set them: the DIALER's
+ * `connectionManager.dialTimeout`, which bounds every dial that carries no abort signal of its
+ * own, and the LISTENER's `connectionManager.inboundUpgradeTimeout`, which is how long the
+ * machine being called lets a half-built connection finish its handshakes. At 10 000 ms each,
+ * no relayed connection could be opened above about 1 250 ms one-way (a 2.5-second link round
+ * trip) whatever cadre declared. The listener's limit is the one that makes that failure
+ * silent: at 1 500 ms one-way the dialer's own 12 094 ms dial RESOLVED while the listener had
+ * already thrown the connection away at 10 s, so the first stream over it died with
+ * `Unexpected EOF - stream closed while reading 0/1 bytes` and the listener reported no peer at
+ * all. cadre now declares both from this module ({@link connectionManagerTimeouts}) on the
+ * control node and every strand node.
+ *
+ * ── What still fails at the supported link ──
+ *
+ * - **Optimystic's own request dials.** `@optimystic/db-p2p`'s RPC clients dial with fixed
+ *   3 000 ms deadlines of their own (`DEFAULT_DIAL_TIMEOUT_MS`, the `pushDialTimeoutMs`
+ *   defaults), which neither limit above reaches because a caller's signal replaces
+ *   `dialTimeout`. So an Optimystic request that has to OPEN a relayed connection fails above
+ *   375 ms one-way. A request over a connection that is already open does not dial, and the
+ *   connections cadre opens itself are budgeted here. Upstream:
+ *   `debt-rpc-dial-deadlines-cannot-open-a-slow-relayed-connection` in optimystic.
+ * - **Cadre deadlines still typed as milliseconds.** The strand wake, strand-address and seed
+ *   delivery deadlines, and the cohort read deadline, bound exchanges over the same link but do
+ *   not derive from it: `tickets/backlog/debt-three-more-dial-deadlines-ignore-the-declared-link`.
+ * - **A machine that declares a faster link than its peers.** Every machine is the listener
+ *   for the others, so its `inboundUpgradeTimeout` — derived from ITS declaration — bounds
+ *   connections other machines open to it. A peer declaring 3 500 ms dialing a machine that
+ *   declared 500 ms gets exactly the silent failure above. Declare the same link on every
+ *   machine of a party.
+ */
+import type { Libp2pConnectionTimeouts } from '@optimystic/db-p2p';
+/**
+ * The link round trip cadre assumes when a host declares none, in milliseconds. A deployment
+ * that knows its own link states it with `NetworkConfig.linkRoundTripMs` instead.
+ *
+ * **Why 3 500.** Sereus supports two machines that reach each other only through a relay up to
+ * a **3-second link round trip** (1 500 ms each way — a congested mobile or satellite link;
+ * `docs/architecture.md` → "Relay Integration"). The worst relayed dial measured at that link
+ * was 12 094 ms, above the 12 000 ms a declaration of exactly 3 000 would derive, so the
+ * declaration rounds the supported link up to the next half second. 3 500 derives 14 000 ms
+ * and leaves about 1.9 s over that dial: room for a phone's Noise handshake, which the
+ * loopback measurement on a desktop does not contain. (The previous 2 000 followed the same
+ * convention for the 1.8 s band sereus supported before, with about 720 ms to spare.)
+ *
+ * Two budgets outside this module were sized against the 1.8 s band and do NOT move with it:
+ * `COHORT_READ_DEADLINE_MS` (`quereus-plugin-sereus/src/cluster-size.ts`, 5 000 ms) and
+ * `DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS` (`strand-first-sync-gate.ts`). The module doc's
+ * "What still fails" list carries the first.
+ *
+ * What 3 500 costs, against 2 000: a peer that is genuinely gone holds each operation longer
+ * before it is abandoned and retried — a relayed dial or a reservation drive 14 s instead of
+ * 8 s, and a control-cohort dial of one peer across all its addresses 56 s instead of 32 s.
+ * Raise it further for a link slower still; lower it only on a deployment where EVERY machine
+ * of the party is that close, for the reason the "What still fails" list gives.
+ */
+export declare const DECLARED_LINK_ROUND_TRIP_MS = 3500;
+/**
+ * Link round trips one relayed connection setup costs: transport, encryption and multiplexer
+ * handshakes to the relay, the circuit open, then both handshakes again end to end through it.
+ * Measured at 8 one-way delays, which is 4 link round trips.
+ */
+export declare const RELAYED_DIAL_ROUND_TRIPS = 4;
+/**
+ * Link round trips one whole reservation drive is budgeted for
+ * (`relay-reservation.ts`'s `driveRelayReservation`, whose ONE deadline covers the dial, the
+ * reservation request and the wait together).
+ *
+ * The protocol work measured is 2 — dial the relay (1) plus request the reservation (1). It is
+ * budgeted at 4, the relayed-dial count, because the wait afterwards may instead be satisfied
+ * by libp2p's own relay discovery, which repeats both legs after identify has run; 4 is
+ * therefore the largest thing this one deadline can be asked to contain, and the poll interval
+ * (`DEFAULT_RELAY_RESERVE_POLL_MS`) rounds up on top of it.
+ */
+export declare const RELAY_RESERVATION_ROUND_TRIPS = 4;
+/**
+ * Link round trips one request-and-answer over an ALREADY-OPEN circuit costs: the protocol
+ * negotiation (1, measured at 2 one-way delays) plus the request and its response (1). It does
+ * not include a dial — a caller that may have to open the connection budgets
+ * {@link RELAYED_DIAL_ROUND_TRIPS} separately, which is exactly what the two-field shape of
+ * Optimystic's `dialTimeoutMs` / `responseTimeoutMs` pair is for.
+ */
+export declare const CIRCUIT_REQUEST_ROUND_TRIPS = 2;
+/**
+ * What a block-transfer push message's BYTES get to cross, on top of the latency
+ * {@link CIRCUIT_REQUEST_ROUND_TRIPS} covers, in milliseconds.
+ *
+ * This part is bandwidth, not latency, so it does not scale with the declared round trip: a
+ * chunk is capped at `PeerJoinBackfillConfig.maxChunkBytes` (1 MiB by default) and crossing it
+ * costs whatever the link's throughput costs.
+ *
+ * NOTE: 6 000 ms is not a measurement of any throughput — it is the residue of the 10 000 ms
+ * this deadline shipped as before it was split into a latency part and a transfer part, chosen
+ * so that at the declaration then in force (2 000 ms) the derived value stayed 10 000 and no
+ * fast link got slower. Nobody has measured how long 1 MiB takes to cross a relayed mobile
+ * link. If pushes ever time out with the transfer only part done, measure that and raise THIS,
+ * not the declared round trip.
+ */
+export declare const PUSH_TRANSFER_ALLOWANCE_MS = 6000;
+/**
+ * Resolve a host's declared link round trip, falling back to
+ * {@link DECLARED_LINK_ROUND_TRIP_MS}.
+ *
+ * Validated here rather than downstream because nothing downstream would: every consumer
+ * multiplies this value into a `setTimeout` deadline, where a zero silently turns a budget into
+ * "give up immediately" and a `NaN` turns it into "never time out".
+ *
+ * Both node bring-up paths call this EAGERLY — `CadreNode.start()`, and
+ * `StrandInstanceManager.buildStrandRuntime` behind `addStrand`/`resumeStrand` — so a bad
+ * declaration fails the same start that Optimystic's own check on `cohortQueryTimeoutMs` fails.
+ * The eager call is what makes that true: every budget derived here is behind a condition (a
+ * node with no control storage builds no catch-up, a node with no relay addrs drives no
+ * reservation), so waiting for a first consumer would let a broken declaration boot and then
+ * throw inside a best-effort path that logs and carries on.
+ */
+export declare function resolveLinkRoundTripMs(linkRoundTripMs?: number): number;
+/**
+ * Deadline for OPENING a connection to another machine that may only be reachable through a
+ * relay: {@link RELAYED_DIAL_ROUND_TRIPS} at the declared link round trip.
+ */
+export declare function relayedDialBudgetMs(linkRoundTripMs?: number): number;
+/**
+ * libp2p's two connection-manager limits for a node at the declared link, handed to
+ * `@optimystic/db-p2p`'s `NodeOptions.connectionManager` on the control node and every strand
+ * node.
+ *
+ * Both bound the same thing — opening a relayed connection, measured at 8 one-way link delays,
+ * which is {@link RELAYED_DIAL_ROUND_TRIPS} (4) link round trips — so both are
+ * {@link relayedDialBudgetMs}: 4 x 3 500 = 14 000 ms at the default declaration, covering the
+ * 12 094 ms measured at the supported 3-second link.
+ *
+ * The listener's limit is deliberately NOT smaller than the dialer's. The listener's clock
+ * starts only when the relay hands it the circuit, a few one-way delays after the dialer's
+ * started, and both sides finish the handshakes at about the same moment; so with equal limits
+ * the listener never discards a connection that the dialer's own dial would still accept. A
+ * listener limit below the dialer's is what produced the silent failure in the module doc.
+ *
+ * The cost of a longer `inboundUpgradeTimeout` is that a peer which opens a connection and then
+ * stalls its handshake holds that half-built connection 14 s instead of 10 s.
+ *
+ * NOTE: derived from the declaration alone, so a per-field override that raises a cadre dial
+ * budget above it (`controlCohort.perAddressDialTimeoutMs`, `strandBackfill.dialTimeoutMs`)
+ * does not raise these; a dial that outlasts the listener's limit gets the silent failure
+ * again. If such overrides start being used for slow links, raise the declaration instead or
+ * take the largest configured dial budget here.
+ */
+export declare function connectionManagerTimeouts(linkRoundTripMs?: number): Libp2pConnectionTimeouts;
+/**
+ * Deadline for one whole relay reservation drive: {@link RELAY_RESERVATION_ROUND_TRIPS} at the
+ * declared link round trip.
+ */
+export declare function relayReservationBudgetMs(linkRoundTripMs?: number): number;
+/**
+ * Deadline for one request and its answer over a circuit that is already open —
+ * {@link CIRCUIT_REQUEST_ROUND_TRIPS} at the declared link round trip, plus `transferAllowanceMs`
+ * for the payload's own bytes.
+ */
+export declare function circuitRequestBudgetMs(linkRoundTripMs?: number, transferAllowanceMs?: number): number;
+/** The two deadlines one peer-join catch-up push needs, both derived from the declared link. */
+export interface PeerJoinPushBudget {
+    /** Opening the connection to the peer being caught up — a relayed dial, in the worst case. */
+    dialTimeoutMs: number;
+    /** The push request and its answer over that connection, including the chunk's own bytes. */
+    responseTimeoutMs: number;
+}
+/**
+ * The dial and response deadlines a peer-join catch-up push needs at a declared link. One
+ * helper rather than two call-site expressions, because the two construction sites
+ * (`CadreNode`'s control catch-up and `StrandInstanceManager`'s per-strand one) and
+ * `DEFAULT_PEER_JOIN_BACKFILL` must not drift apart.
+ */
+export declare function peerJoinPushBudget(linkRoundTripMs?: number): PeerJoinPushBudget;

package/dist/link-budget.js

@@ -0,0 +1,239 @@
+/**
+ * Dial and reservation budgets derived from ONE declared link round trip, instead of fixed
+ * millisecond numbers chosen on a fast local network.
+ *
+ * Reaching another machine through a relay costs a FIXED NUMBER OF EXCHANGES, not a fixed
+ * number of milliseconds. So every budget written as milliseconds has a link speed above which
+ * it can never open a connection at all — and the slower the link, the more of them fall over,
+ * silently, because an abandoned dial looks the same as a peer that is not there. Counting round
+ * trips instead is what stops that class of defect coming back: the next person to widen a
+ * budget changes ONE declaration, and the next person to add a dial writes down its round-trip
+ * count beside the arithmetic.
+ *
+ * ── The instrument ──
+ *
+ * Every count and every number below comes from
+ * `packages/integration-tests/src/scenarios/relayed-dial-cost-by-latency.integration.ts`, which
+ * is committed and opt-in (`RELAY_DIAL_COST=1`). **Its doc comment is the single home of the
+ * measurement**; this module holds only what the derivation needs. Re-run it before changing
+ * anything here.
+ *
+ * ── The unit ──
+ *
+ * ONE LINK ROUND TRIP is a message from one machine reaching the other and a reply coming
+ * back, over the path those two machines actually use — through the relay, when that is the
+ * only way they can reach each other. In the instrument, which injects a constant ONE-WAY
+ * frame delay `d`, one link round trip is `2d`.
+ *
+ * A leg between a node and the RELAY is half a link round trip, because it crosses one of the
+ * two hops rather than both. That is why the reservation drive's cost reads as "four
+ * node-to-relay round trips" in one telling and "two link round trips" in another: same
+ * quantity, different unit. This module uses the LINK round trip throughout, so there is one
+ * unit to reason in.
+ *
+ * ── The counts, and what they cost ──
+ *
+ * | operation                                            | link round trips | at the declared default |
+ * | ---------------------------------------------------- | ---------------- | ----------------------- |
+ * | open a relayed connection to another machine          | 4                | 14 000 ms               |
+ * | dial the relay itself                                 | 1                | 3 500 ms                |
+ * | request a reservation on an open relay connection     | 1                | 3 500 ms                |
+ * | negotiate a protocol over an established circuit      | 1                | 3 500 ms                |
+ *
+ * **Measured** 2026-09-26, one Windows machine, loopback dedicated relay: a relayed dial took
+ * 20-25 ms at no delay, **7 255-7 279 ms at 900 ms one-way**, and **12 066-12 094 ms at 1 500 ms
+ * one-way**. Four link round trips of pure delay would be 7 200 and 12 000, so the real cost
+ * sits about 60-95 ms ABOVE the arithmetic — the handshakes, which no delay figure contains.
+ * That residue is why {@link DECLARED_LINK_ROUND_TRIP_MS} carries headroom over the link sereus
+ * supports rather than matching it exactly: a declaration equal to the supported round trip
+ * would derive a budget marginally BELOW the dial it has to contain.
+ *
+ * ── libp2p's own two limits ──
+ *
+ * Two limits inside libp2p bound the same relayed dial as cadre's budgets do, and both were
+ * 10 000 ms until `@optimystic/db-p2p` 1.7.0 let an embedder set them: the DIALER's
+ * `connectionManager.dialTimeout`, which bounds every dial that carries no abort signal of its
+ * own, and the LISTENER's `connectionManager.inboundUpgradeTimeout`, which is how long the
+ * machine being called lets a half-built connection finish its handshakes. At 10 000 ms each,
+ * no relayed connection could be opened above about 1 250 ms one-way (a 2.5-second link round
+ * trip) whatever cadre declared. The listener's limit is the one that makes that failure
+ * silent: at 1 500 ms one-way the dialer's own 12 094 ms dial RESOLVED while the listener had
+ * already thrown the connection away at 10 s, so the first stream over it died with
+ * `Unexpected EOF - stream closed while reading 0/1 bytes` and the listener reported no peer at
+ * all. cadre now declares both from this module ({@link connectionManagerTimeouts}) on the
+ * control node and every strand node.
+ *
+ * ── What still fails at the supported link ──
+ *
+ * - **Optimystic's own request dials.** `@optimystic/db-p2p`'s RPC clients dial with fixed
+ *   3 000 ms deadlines of their own (`DEFAULT_DIAL_TIMEOUT_MS`, the `pushDialTimeoutMs`
+ *   defaults), which neither limit above reaches because a caller's signal replaces
+ *   `dialTimeout`. So an Optimystic request that has to OPEN a relayed connection fails above
+ *   375 ms one-way. A request over a connection that is already open does not dial, and the
+ *   connections cadre opens itself are budgeted here. Upstream:
+ *   `debt-rpc-dial-deadlines-cannot-open-a-slow-relayed-connection` in optimystic.
+ * - **Cadre deadlines still typed as milliseconds.** The strand wake, strand-address and seed
+ *   delivery deadlines, and the cohort read deadline, bound exchanges over the same link but do
+ *   not derive from it: `tickets/backlog/debt-three-more-dial-deadlines-ignore-the-declared-link`.
+ * - **A machine that declares a faster link than its peers.** Every machine is the listener
+ *   for the others, so its `inboundUpgradeTimeout` — derived from ITS declaration — bounds
+ *   connections other machines open to it. A peer declaring 3 500 ms dialing a machine that
+ *   declared 500 ms gets exactly the silent failure above. Declare the same link on every
+ *   machine of a party.
+ */
+/**
+ * The link round trip cadre assumes when a host declares none, in milliseconds. A deployment
+ * that knows its own link states it with `NetworkConfig.linkRoundTripMs` instead.
+ *
+ * **Why 3 500.** Sereus supports two machines that reach each other only through a relay up to
+ * a **3-second link round trip** (1 500 ms each way — a congested mobile or satellite link;
+ * `docs/architecture.md` → "Relay Integration"). The worst relayed dial measured at that link
+ * was 12 094 ms, above the 12 000 ms a declaration of exactly 3 000 would derive, so the
+ * declaration rounds the supported link up to the next half second. 3 500 derives 14 000 ms
+ * and leaves about 1.9 s over that dial: room for a phone's Noise handshake, which the
+ * loopback measurement on a desktop does not contain. (The previous 2 000 followed the same
+ * convention for the 1.8 s band sereus supported before, with about 720 ms to spare.)
+ *
+ * Two budgets outside this module were sized against the 1.8 s band and do NOT move with it:
+ * `COHORT_READ_DEADLINE_MS` (`quereus-plugin-sereus/src/cluster-size.ts`, 5 000 ms) and
+ * `DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS` (`strand-first-sync-gate.ts`). The module doc's
+ * "What still fails" list carries the first.
+ *
+ * What 3 500 costs, against 2 000: a peer that is genuinely gone holds each operation longer
+ * before it is abandoned and retried — a relayed dial or a reservation drive 14 s instead of
+ * 8 s, and a control-cohort dial of one peer across all its addresses 56 s instead of 32 s.
+ * Raise it further for a link slower still; lower it only on a deployment where EVERY machine
+ * of the party is that close, for the reason the "What still fails" list gives.
+ */
+export const DECLARED_LINK_ROUND_TRIP_MS = 3500;
+/**
+ * Link round trips one relayed connection setup costs: transport, encryption and multiplexer
+ * handshakes to the relay, the circuit open, then both handshakes again end to end through it.
+ * Measured at 8 one-way delays, which is 4 link round trips.
+ */
+export const RELAYED_DIAL_ROUND_TRIPS = 4;
+/**
+ * Link round trips one whole reservation drive is budgeted for
+ * (`relay-reservation.ts`'s `driveRelayReservation`, whose ONE deadline covers the dial, the
+ * reservation request and the wait together).
+ *
+ * The protocol work measured is 2 — dial the relay (1) plus request the reservation (1). It is
+ * budgeted at 4, the relayed-dial count, because the wait afterwards may instead be satisfied
+ * by libp2p's own relay discovery, which repeats both legs after identify has run; 4 is
+ * therefore the largest thing this one deadline can be asked to contain, and the poll interval
+ * (`DEFAULT_RELAY_RESERVE_POLL_MS`) rounds up on top of it.
+ */
+export const RELAY_RESERVATION_ROUND_TRIPS = 4;
+/**
+ * Link round trips one request-and-answer over an ALREADY-OPEN circuit costs: the protocol
+ * negotiation (1, measured at 2 one-way delays) plus the request and its response (1). It does
+ * not include a dial — a caller that may have to open the connection budgets
+ * {@link RELAYED_DIAL_ROUND_TRIPS} separately, which is exactly what the two-field shape of
+ * Optimystic's `dialTimeoutMs` / `responseTimeoutMs` pair is for.
+ */
+export const CIRCUIT_REQUEST_ROUND_TRIPS = 2;
+/**
+ * What a block-transfer push message's BYTES get to cross, on top of the latency
+ * {@link CIRCUIT_REQUEST_ROUND_TRIPS} covers, in milliseconds.
+ *
+ * This part is bandwidth, not latency, so it does not scale with the declared round trip: a
+ * chunk is capped at `PeerJoinBackfillConfig.maxChunkBytes` (1 MiB by default) and crossing it
+ * costs whatever the link's throughput costs.
+ *
+ * NOTE: 6 000 ms is not a measurement of any throughput — it is the residue of the 10 000 ms
+ * this deadline shipped as before it was split into a latency part and a transfer part, chosen
+ * so that at the declaration then in force (2 000 ms) the derived value stayed 10 000 and no
+ * fast link got slower. Nobody has measured how long 1 MiB takes to cross a relayed mobile
+ * link. If pushes ever time out with the transfer only part done, measure that and raise THIS,
+ * not the declared round trip.
+ */
+export const PUSH_TRANSFER_ALLOWANCE_MS = 6000;
+/**
+ * Resolve a host's declared link round trip, falling back to
+ * {@link DECLARED_LINK_ROUND_TRIP_MS}.
+ *
+ * Validated here rather than downstream because nothing downstream would: every consumer
+ * multiplies this value into a `setTimeout` deadline, where a zero silently turns a budget into
+ * "give up immediately" and a `NaN` turns it into "never time out".
+ *
+ * Both node bring-up paths call this EAGERLY — `CadreNode.start()`, and
+ * `StrandInstanceManager.buildStrandRuntime` behind `addStrand`/`resumeStrand` — so a bad
+ * declaration fails the same start that Optimystic's own check on `cohortQueryTimeoutMs` fails.
+ * The eager call is what makes that true: every budget derived here is behind a condition (a
+ * node with no control storage builds no catch-up, a node with no relay addrs drives no
+ * reservation), so waiting for a first consumer would let a broken declaration boot and then
+ * throw inside a best-effort path that logs and carries on.
+ */
+export function resolveLinkRoundTripMs(linkRoundTripMs) {
+    if (linkRoundTripMs === undefined) {
+        return DECLARED_LINK_ROUND_TRIP_MS;
+    }
+    if (!Number.isFinite(linkRoundTripMs) || linkRoundTripMs <= 0) {
+        throw new Error(`network.linkRoundTripMs must be a finite number of milliseconds above zero, not ${String(linkRoundTripMs)}`);
+    }
+    return linkRoundTripMs;
+}
+/**
+ * Deadline for OPENING a connection to another machine that may only be reachable through a
+ * relay: {@link RELAYED_DIAL_ROUND_TRIPS} at the declared link round trip.
+ */
+export function relayedDialBudgetMs(linkRoundTripMs) {
+    return RELAYED_DIAL_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs);
+}
+/**
+ * libp2p's two connection-manager limits for a node at the declared link, handed to
+ * `@optimystic/db-p2p`'s `NodeOptions.connectionManager` on the control node and every strand
+ * node.
+ *
+ * Both bound the same thing — opening a relayed connection, measured at 8 one-way link delays,
+ * which is {@link RELAYED_DIAL_ROUND_TRIPS} (4) link round trips — so both are
+ * {@link relayedDialBudgetMs}: 4 x 3 500 = 14 000 ms at the default declaration, covering the
+ * 12 094 ms measured at the supported 3-second link.
+ *
+ * The listener's limit is deliberately NOT smaller than the dialer's. The listener's clock
+ * starts only when the relay hands it the circuit, a few one-way delays after the dialer's
+ * started, and both sides finish the handshakes at about the same moment; so with equal limits
+ * the listener never discards a connection that the dialer's own dial would still accept. A
+ * listener limit below the dialer's is what produced the silent failure in the module doc.
+ *
+ * The cost of a longer `inboundUpgradeTimeout` is that a peer which opens a connection and then
+ * stalls its handshake holds that half-built connection 14 s instead of 10 s.
+ *
+ * NOTE: derived from the declaration alone, so a per-field override that raises a cadre dial
+ * budget above it (`controlCohort.perAddressDialTimeoutMs`, `strandBackfill.dialTimeoutMs`)
+ * does not raise these; a dial that outlasts the listener's limit gets the silent failure
+ * again. If such overrides start being used for slow links, raise the declaration instead or
+ * take the largest configured dial budget here.
+ */
+export function connectionManagerTimeouts(linkRoundTripMs) {
+    const budgetMs = relayedDialBudgetMs(linkRoundTripMs);
+    return { dialTimeout: budgetMs, inboundUpgradeTimeout: budgetMs };
+}
+/**
+ * Deadline for one whole relay reservation drive: {@link RELAY_RESERVATION_ROUND_TRIPS} at the
+ * declared link round trip.
+ */
+export function relayReservationBudgetMs(linkRoundTripMs) {
+    return RELAY_RESERVATION_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs);
+}
+/**
+ * Deadline for one request and its answer over a circuit that is already open —
+ * {@link CIRCUIT_REQUEST_ROUND_TRIPS} at the declared link round trip, plus `transferAllowanceMs`
+ * for the payload's own bytes.
+ */
+export function circuitRequestBudgetMs(linkRoundTripMs, transferAllowanceMs = PUSH_TRANSFER_ALLOWANCE_MS) {
+    return CIRCUIT_REQUEST_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs) + transferAllowanceMs;
+}
+/**
+ * The dial and response deadlines a peer-join catch-up push needs at a declared link. One
+ * helper rather than two call-site expressions, because the two construction sites
+ * (`CadreNode`'s control catch-up and `StrandInstanceManager`'s per-strand one) and
+ * `DEFAULT_PEER_JOIN_BACKFILL` must not drift apart.
+ */
+export function peerJoinPushBudget(linkRoundTripMs) {
+    return {
+        dialTimeoutMs: relayedDialBudgetMs(linkRoundTripMs),
+        responseTimeoutMs: circuitRequestBudgetMs(linkRoundTripMs)
+    };
+}
+//# sourceMappingURL=link-budget.js.map

package/dist/link-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-budget.js","sourceRoot":"","sources":["../src/link-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAIH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CAAC,eAAwB;IAC9D,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,2BAA2B,CAAC;IACpC,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,eAAe,IAAI,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CACd,mFAAmF,MAAM,CAAC,eAAe,CAAC,EAAE,CAC5G,CAAC;IACH,CAAC;IACD,OAAO,eAAe,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,eAAwB;IAC3D,OAAO,wBAAwB,GAAG,sBAAsB,CAAC,eAAe,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,yBAAyB,CAAC,eAAwB;IACjE,MAAM,QAAQ,GAAG,mBAAmB,CAAC,eAAe,CAAC,CAAC;IACtD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,qBAAqB,EAAE,QAAQ,EAAE,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,eAAwB;IAChE,OAAO,6BAA6B,GAAG,sBAAsB,CAAC,eAAe,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACrC,eAAwB,EACxB,mBAAmB,GAAG,0BAA0B;IAEhD,OAAO,2BAA2B,GAAG,sBAAsB,CAAC,eAAe,CAAC,GAAG,mBAAmB,CAAC;AACpG,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,eAAwB;IAC1D,OAAO;QACN,aAAa,EAAE,mBAAmB,CAAC,eAAe,CAAC;QACnD,iBAAiB,EAAE,sBAAsB,CAAC,eAAe,CAAC;KAC1D,CAAC;AACH,CAAC"}

package/dist/peer-dial.d.ts

@@ -25,28 +25,41 @@
 import type { Connection } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
 /**
- * Default limit on ONE address's dial attempt, in ms.
+ * 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.
  *
  * 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
  * a mobile link: connect to the relay (transport, encryption and multiplexer
  * handshakes, when no relay connection is open yet), open the circuit, then run
- * both handshakes again end to end through the relay at roughly twice the
- * round-trip time. At a few hundred ms per round trip that is several seconds.
- * A direct dial that works is far quicker — a phone's WebSocket dial to a node
- * forwarded over `adb reverse` measured 1.6 s end to end. 8 s covers the relayed
- * case with some margin while still abandoning a silently dropped address
- * sooner than libp2p's own 10 s dial timeout would.
+ * both handshakes again end to end through the relay. `link-budget.ts` is where that
+ * reasoning is now a measured count instead of an estimate — four link round trips, measured at
+ * 12 094 ms on a link whose round trip is 3 s — so the value MOVES with a host's
+ * `NetworkConfig.linkRoundTripMs` rather than pinning the band this node can reach to whatever
+ * number was typed here. A direct dial that works is far quicker — a phone's WebSocket dial to
+ * a node forwarded over `adb reverse` measured 1.6 s end to end.
+ *
+ * Deriving it rather than leaving it fixed is deliberate: at 8000 ms fixed, the per-address
+ * limit — not libp2p's own 10 s dial timeout — was the first thing to cut a relayed dial off,
+ * from about 1000 ms of one-way link delay upward. Nothing said so, and a reader raising
+ * `DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS` below would not have found it.
  *
  * NOTE: a `/p2p-circuit/webrtc` address also negotiates a WebRTC session after
  * the relay leg. If such dials are ever seen failing at exactly this limit, raise
- * it (or `network.controlCohort.perAddressDialTimeoutMs` on the affected nodes)
- * rather than the per-peer limit, which cannot help an address that is itself
+ * the declared link round trip (or `network.controlCohort.perAddressDialTimeoutMs` on the
+ * affected nodes) rather than the per-peer limit, which cannot help an address that is itself
  * cut off.
  *
  * Override per node with `network.controlCohort.perAddressDialTimeoutMs`.
  */
-export declare const DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS = 8000;
+export declare const DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS: number;
+/**
+ * How many whole per-address dial attempts {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS}
+ * budgets for: the address that works plus the three dead ones a lent cadre-host node is
+ * observed to report ahead of it (loopback and LAN WebSocket addresses, plus virtual adapters).
+ */
+export declare const CONTROL_COHORT_DIAL_ADDRESS_ATTEMPTS = 4;
 /**
  * Default limit on dialing ONE peer — every candidate address together — in ms.
  *
@@ -59,18 +72,24 @@ export declare const DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS = 8000;
  *
  * Sized to fit a typical list with dead addresses ahead of the one that works:
  * a lent cadre-host node reports two to four addresses a phone can dial
- * (loopback and LAN WebSocket addresses, plus any virtual adapters). Three
- * silently dropped addresses cost 3 × 8 s = 24 s, leaving 6 s for the working
- * address after them — well over the 1.6 s the phone measured. A peer whose
- * working address sits behind four or more dropped ones does not fit, and fails
- * each pass the same way; if that shows up, the remedy is ordering (try the
- * address that last connected first), not a larger number here.
+ * (loopback and LAN WebSocket addresses, plus any virtual adapters). So it is
+ * {@link CONTROL_COHORT_DIAL_ADDRESS_ATTEMPTS} whole per-address budgets — three silently
+ * dropped addresses, then the one that works, each getting the FULL per-address limit. A peer
+ * whose working address sits behind four or more dropped ones does not fit, and fails each pass
+ * the same way; if that shows up, the remedy is ordering (try the address that last connected
+ * first), not a larger number here.
+ *
+ * Counted as whole per-address budgets rather than the flat 30_000 it was before, because the
+ * old number left only 6 s after three dropped addresses — enough for the 1.6 s direct dial the
+ * phone measured, but NOT for the relayed dial the per-address limit is sized to cover. A peer
+ * whose only working address was a relayed one behind two dead ones therefore could not be
+ * dialled at all, and the arithmetic in this comment was what said otherwise.
  *
  * Override per node with `network.controlCohort.dialTimeoutMs` — tests that
  * drive dead addresses on purpose set it low so a pass's duration is a chosen
  * number rather than a transitive libp2p default stretched by machine load.
  */
-export declare const DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS = 30000;
+export declare const DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS: number;
 /** Time limits for dialing one peer from a list of candidate addresses. */
 export interface PeerDialBudget {
     /** Limit on one address's attempt, in ms. */

package/dist/peer-dial.js

@@ -24,30 +24,44 @@
  */
 import debug from 'debug';
 import { withDeadline } from './control-stream.js';
+import { relayedDialBudgetMs } from './link-budget.js';
 const log = debug('sereus:cadre:peer-dial');
 /**
- * Default limit on ONE address's dial attempt, in ms.
+ * 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.
  *
  * 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
  * a mobile link: connect to the relay (transport, encryption and multiplexer
  * handshakes, when no relay connection is open yet), open the circuit, then run
- * both handshakes again end to end through the relay at roughly twice the
- * round-trip time. At a few hundred ms per round trip that is several seconds.
- * A direct dial that works is far quicker — a phone's WebSocket dial to a node
- * forwarded over `adb reverse` measured 1.6 s end to end. 8 s covers the relayed
- * case with some margin while still abandoning a silently dropped address
- * sooner than libp2p's own 10 s dial timeout would.
+ * both handshakes again end to end through the relay. `link-budget.ts` is where that
+ * reasoning is now a measured count instead of an estimate — four link round trips, measured at
+ * 12 094 ms on a link whose round trip is 3 s — so the value MOVES with a host's
+ * `NetworkConfig.linkRoundTripMs` rather than pinning the band this node can reach to whatever
+ * number was typed here. A direct dial that works is far quicker — a phone's WebSocket dial to
+ * a node forwarded over `adb reverse` measured 1.6 s end to end.
+ *
+ * Deriving it rather than leaving it fixed is deliberate: at 8000 ms fixed, the per-address
+ * limit — not libp2p's own 10 s dial timeout — was the first thing to cut a relayed dial off,
+ * from about 1000 ms of one-way link delay upward. Nothing said so, and a reader raising
+ * `DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS` below would not have found it.
  *
  * NOTE: a `/p2p-circuit/webrtc` address also negotiates a WebRTC session after
  * the relay leg. If such dials are ever seen failing at exactly this limit, raise
- * it (or `network.controlCohort.perAddressDialTimeoutMs` on the affected nodes)
- * rather than the per-peer limit, which cannot help an address that is itself
+ * the declared link round trip (or `network.controlCohort.perAddressDialTimeoutMs` on the
+ * affected nodes) rather than the per-peer limit, which cannot help an address that is itself
  * cut off.
  *
  * Override per node with `network.controlCohort.perAddressDialTimeoutMs`.
  */
-export const DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS = 8000;
+export const DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS = relayedDialBudgetMs();
+/**
+ * How many whole per-address dial attempts {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS}
+ * budgets for: the address that works plus the three dead ones a lent cadre-host node is
+ * observed to report ahead of it (loopback and LAN WebSocket addresses, plus virtual adapters).
+ */
+export const CONTROL_COHORT_DIAL_ADDRESS_ATTEMPTS = 4;
 /**
  * Default limit on dialing ONE peer — every candidate address together — in ms.
  *
@@ -60,18 +74,24 @@ export const DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS = 8000;
  *
  * Sized to fit a typical list with dead addresses ahead of the one that works:
  * a lent cadre-host node reports two to four addresses a phone can dial
- * (loopback and LAN WebSocket addresses, plus any virtual adapters). Three
- * silently dropped addresses cost 3 × 8 s = 24 s, leaving 6 s for the working
- * address after them — well over the 1.6 s the phone measured. A peer whose
- * working address sits behind four or more dropped ones does not fit, and fails
- * each pass the same way; if that shows up, the remedy is ordering (try the
- * address that last connected first), not a larger number here.
+ * (loopback and LAN WebSocket addresses, plus any virtual adapters). So it is
+ * {@link CONTROL_COHORT_DIAL_ADDRESS_ATTEMPTS} whole per-address budgets — three silently
+ * dropped addresses, then the one that works, each getting the FULL per-address limit. A peer
+ * whose working address sits behind four or more dropped ones does not fit, and fails each pass
+ * the same way; if that shows up, the remedy is ordering (try the address that last connected
+ * first), not a larger number here.
+ *
+ * Counted as whole per-address budgets rather than the flat 30_000 it was before, because the
+ * old number left only 6 s after three dropped addresses — enough for the 1.6 s direct dial the
+ * phone measured, but NOT for the relayed dial the per-address limit is sized to cover. A peer
+ * whose only working address was a relayed one behind two dead ones therefore could not be
+ * dialled at all, and the arithmetic in this comment was what said otherwise.
  *
  * Override per node with `network.controlCohort.dialTimeoutMs` — tests that
  * drive dead addresses on purpose set it low so a pass's duration is a chosen
  * number rather than a transitive libp2p default stretched by machine load.
  */
-export const DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS = 30000;
+export const DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS = CONTROL_COHORT_DIAL_ADDRESS_ATTEMPTS * DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS;
 /** {@link PeerDialBudget} built from the two defaults above. */
 export const DEFAULT_PEER_DIAL_BUDGET = {
     perAddressMs: DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS,