@serfab/cadre-core 1.8.0 → 1.10.0

package/src/link-budget.ts

@@ -58,66 +58,87 @@
  *
  * ── 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                |
- * | one request and its answer over an open circuit       | 2                | 7 000 ms                |
- * | open a relayed connection, then negotiate one protocol| 5                | 17 500 ms               |
- * | open a relayed connection, then one request on it     | 6                | 21 000 ms               |
- * | one Optimystic commit over connections already open   | 20               | 70 000 ms               |
- *
- * The reservation-request row is {@link RELAY_RESERVE_REQUEST_ROUND_TRIPS}, which also sizes how long
+ * | operation                                                        | link round trips | at the declared default |
+ * | ---------------------------------------------------------------- | ---------------- | ----------------------- |
+ * | open a relayed connection over a relay connection already open    | 4                | 14 000 ms               |
+ * | dial the relay itself                                             | 1                | 3 500 ms                |
+ * | open a relayed connection, opening the relay connection first     | 5                | 17 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                |
+ * | one request and its answer over an open circuit                   | 2                | 7 000 ms                |
+ * | open a relayed connection, then negotiate one protocol            | 6                | 21 000 ms               |
+ * | open a relayed connection, then one request on it                 | 7                | 24 500 ms               |
+ * | one Optimystic commit over connections already open               | 20               | 70 000 ms               |
+ *
+ * Every row that opens a relayed connection counts opening the relay connection too
+ * ({@link RELAYED_DIAL_ROUND_TRIPS}), because a dialer cannot know beforehand whether it holds
+ * one, and a budget that is too short fails as silently as an absent peer. The
+ * reservation-request row is {@link RELAY_RESERVE_REQUEST_ROUND_TRIPS}, which also sizes how long
  * a party-run relay waits for a stranger's reservation ({@link relayAdmissionReserveDeadlineMs}).
  * The commit row is a measurement of a whole write, not a count of exchanges; its doc comment
  * ({@link COMMIT_ROUND_TRIPS}) holds the figures and says when to re-measure it.
  *
- * **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.
- *
- * ── The listener's admission decision ──
+ * **Measured** 2026-09-26, one Windows machine, loopback dedicated relay: a relayed dial over a
+ * relay connection the dialer already held 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. On 2026-10-01 (libp2p 3.3.11), a dialer holding no
+ * relay connection took **15 113 ms at 1 500 ms one-way**: ten one-way delays, five link round
+ * trips, 113 ms above the arithmetic. 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.
+ *
+ * NOTE: the instrument splits the delay evenly across both hops (each node's own dialed socket
+ * gets the same one-way figure). On a link whose whole round trip sits on one machine's hop to
+ * the relay (a phone on a congested mobile link), the exchanges that cross only that hop — the
+ * relay dial, the hop-stream negotiation and CONNECT — may cost up to twice their share of the
+ * count. Not measured. If relayed dials are seen failing near their budget on such a link,
+ * measure that split before raising any count or the declaration.
+ *
+ * ── Admission decisions ──
  *
  * The table is link time only. Every budget that OPENS a connection also adds
- * {@link ADMISSION_DECISION_TIMEOUT_MS} (2 000 ms) per admission decision the machine being
- * called may make on the way, because that machine's gate runs on the dialer's clock (the
- * constant's doc says why). So a relayed dial is budgeted at 14 000 + 2 000 = 16 000 ms at the
- * default declaration, a dial plus one request at 23 000 ms, and a reservation drive, which a
- * party-run relay decides twice, at 18 000 ms. The allowance is flat: it is local decision
- * time, not link time, so it does not scale with the declaration.
- *
- * The measurement above crossed no gate. The instrument is bare libp2p on both sides, with no
- * cadre connection gater, so the 12 094 ms contains no admission decision at all. The
- * allowance is therefore on top of the measured dial rather than already inside it.
- *
- * NOTE: the measured dial also reused a connection to the relay that the dialer already held
- * (the instrument dials the relay first). A relayed dial that has to open that connection itself
- * spends one more link round trip, plus the relay's own admission decision when the relay is a
- * party-run control node, and the count counts neither; at the supported link such a dial fits
- * only while the called machine decides in under about 0.9 s.
- * `bug-relayed-dial-budget-omits-opening-the-relay-connection`.
+ * {@link ADMISSION_DECISION_TIMEOUT_MS} (2 000 ms) once for each gate the open may pass, because
+ * each gate runs on the dialer's clock (the constant's doc says why). A relayed dial passes
+ * {@link DIAL_ADMISSION_DECISIONS}, two: a party-run relay's, on the dialer's connection to it,
+ * then the called machine's. So a relayed dial is budgeted at 17 500 + 2 x 2 000 = 21 500 ms at
+ * the default declaration, a dial plus one request at 28 500 ms, and a reservation drive, which
+ * a party-run relay decides twice, at 18 000 ms. The allowance is flat: it is local decision
+ * time, not link time, so it does not scale with the declaration. One allowance per gate, rather
+ * than slack in the count, is what keeps each budget valid at every declaration.
+ *
+ * The measurement above crossed no gate. The instrument is bare libp2p on every side, with no
+ * cadre connection gater, so the 15 113 ms contains no admission decision at all. The
+ * allowances are therefore on top of the measured dial rather than already inside it.
  *
  * ── Optimystic's deadlines, from the same declaration ──
  *
  * cadre states its declared link to Optimystic on the control node and every strand node
- * (`@optimystic/db-p2p`'s `NodeOptions.linkRoundTripMs`, from 1.8.0), and Optimystic derives
- * its network deadlines from it (`resolveLinkDeadlines` in its `rpc-deadline.ts`), each never
- * below the LAN value it replaced. At the default declaration:
- *
- * | Optimystic deadline                                  | link round trips | at the default | undeclared |
- * | ---------------------------------------------------- | ---------------- | -------------- | ---------- |
- * | libp2p `dialTimeout` and `inboundUpgradeTimeout`     | 5                | 17 500 ms      | 10 000 ms  |
- * | one request's dial, stream negotiation included      | 6                | 21 000 ms      | 3 000 ms   |
- * | one request's response                               | 3                | 10 500 ms      | 10 000 ms  |
- * | a rebalance transfer's dial, and again its reply     | 6, floor 30 000  | 30 000 ms      | 30 000 ms  |
- *
- * Its churn and under-replication pushes take the request rows' values. The undeclared column
+ * (`@optimystic/db-p2p`'s `NodeOptions.linkRoundTripMs`), and Optimystic derives its network
+ * deadlines from it (`resolveLinkDeadlines` in its `rpc-deadline.ts`), each never below the LAN
+ * value it replaced. Optimystic's derivation is link time only, so cadre states the three limits
+ * that cover opening a connection itself ({@link optimysticDialLimits}): Optimystic's value plus
+ * {@link DIAL_ADMISSION_DECISIONS} admission decisions. At the default declaration:
+ *
+ * | deadline                                                | link round trips       | at the default | undeclared |
+ * | ------------------------------------------------------- | ---------------------- | -------------- | ---------- |
+ * | libp2p `addressDialTimeout`, one address of a dial      | 10, + 2 decisions      | 39 000 ms      | 6 000 ms   |
+ * | libp2p `dialTimeout`, a dial that carries no signal     | 10, + 2 decisions      | 39 000 ms      | 10 000 ms  |
+ * | libp2p `inboundUpgradeTimeout`, the listener's side     | 5                      | 17 500 ms      | 10 000 ms  |
+ * | one request's dial, stream negotiation included         | 11, + 2 decisions      | 42 500 ms      | 3 000 ms   |
+ * | one request's response                                  | 3                      | 10 500 ms      | 10 000 ms  |
+ * | a rebalance transfer's dial, and again its reply        | request dial, ≥ 30 000 | 42 500 ms      | 30 000 ms  |
+ *
+ * Ten round trips is Optimystic's count for opening a relayed connection through a relay the
+ * dialer is not yet connected to, which opens that connection first (about 8.6 round trips over
+ * WebSocket, 9.6 over `wss`), with a margin. The two decisions are the gates that open runs
+ * through on the dialer's clock: a party-run relay's, on the dialer's connection to it, then the
+ * called machine's. Each may take {@link ADMISSION_DECISION_TIMEOUT_MS}.
+ *
+ * Its churn and under-replication pushes take the request rows' values, and the Quereus plugin
+ * derives a write's budgets from the request dial: four of them for the transaction (170 000 ms)
+ * and one for cancelling it (42 500 ms). The undeclared column
  * is why cadre always states the value, default included. A fixed 3 000 ms request dial cannot
  * open a relayed connection above 375 ms one-way, and it also bounded the protocol negotiation
  * on a connection that was already open, which is one link round trip: at the supported link
@@ -128,29 +149,38 @@
  * ({@link cohortReadDeadlineMs} says why).
  *
  * NOTE: the longer deadlines are paid against a machine that is gone. An Optimystic request
- * to a peer that never completes a connection now waits up to the 21 000 ms dial deadline where
- * it waited 3 000, and one that connects and never answers waits 10 500 where it waited 10 000.
- * Measured 2026-09-30 (`control-write-degraded-cohort-member.integration.ts`): a control write
- * against a connected, silent member failed at 42.2 s, against 40.2 s with no link declared.
- * The dial case was not measured. cadre's cut-off budgets (`CONTROL_WRITE_RETRY_BUDGET_MS`,
- * `CONTROL_READ_RETRY_BUDGET_MS`) are checked between attempts, so one attempt can outlast
- * them by that much. If writes on a fast link are seen waiting out the dial deadline against an
- * unreachable machine, declare that deployment's real round trip instead of the default.
- *
- * libp2p's two limits bound the same relayed dial as cadre's budgets do: the DIALER's
- * `dialTimeout`, which bounds every dial that carries no abort signal of its own, and the
- * LISTENER's `inboundUpgradeTimeout`, which is how long the machine being called lets a
- * half-built connection finish its handshakes. At libp2p's 10 000 ms, no relayed connection
- * could be opened above about 1 250 ms one-way (a 2.5-second link round trip) whatever cadre
- * declared, and 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. Optimystic's
- * derivation contains {@link relayedDialBudgetMs} at every declaration: five round trips are at
- * least four plus the {@link ADMISSION_DECISION_TIMEOUT_MS} allowance once the round trip
- * reaches 2 000 ms, and the 10 000 ms floor covers every shorter one. `link-budget.spec.ts` pins
- * that against Optimystic's own derivation, so a change on either side that breaks it fails
- * there rather than silently on a slow link.
+ * to a peer that never completes a connection waits up to the 42 500 ms dial deadline, each of
+ * that peer's addresses up to 39 000 ms inside it, and one that connects and never answers
+ * waits 10 500. A control write against a connected, silent member fails after about 84 s
+ * (one pend round and three cancel rounds; `docs/cadre-consistency.md` → "Deadlines Over
+ * Optimystic's Reads and Commits"). The dial case was not measured. cadre's cut-off budgets
+ * (`CONTROL_WRITE_RETRY_BUDGET_MS`, `CONTROL_READ_RETRY_BUDGET_MS`) are checked between
+ * attempts, so one attempt can outlast them by that much. If writes on a fast link are seen
+ * waiting out the dial deadline against an unreachable machine, declare that deployment's real
+ * round trip instead of the default.
+ *
+ * The LISTENER's `inboundUpgradeTimeout` is how long the machine being called lets a half-built
+ * connection finish its handshakes, and it is the limit that makes a dial outlasting it silent:
+ * at libp2p's 10 000 ms and 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 leaves it to Optimystic, with no decisions added: its timer starts when the
+ * relay hands the listener the inbound circuit, so it runs over the listener's own upgrade and
+ * the listener's own decision, never over the dialer's connection to the relay or the relay's
+ * decision. So it has to contain the part of {@link relayedDialBudgetMs} its clock covers, not
+ * the whole budget: at most the circuit leg ({@link CIRCUIT_DIAL_ROUND_TRIPS}) plus one
+ * {@link ADMISSION_DECISION_TIMEOUT_MS}. Optimystic's derivation does at every declaration: five
+ * round trips are at least four plus the allowance once the round trip reaches 2 000 ms, and the
+ * 10 000 ms floor covers every shorter one. `link-budget.spec.ts` pins that against Optimystic's
+ * own derivation, so a change on either side that breaks it fails there rather than silently on
+ * a slow link.
+ *
+ * NOTE: the whole {@link relayedDialBudgetMs} is longer than the listener's limit (21 500 ms
+ * against 17 500 ms at the default), so on a link SLOWER than the one declared, a dial over a
+ * relay connection the dialer already holds can outlast the listener while its own budget still
+ * runs (at the default, between about a 4.4 s and a 5.4 s round trip), and fails silently
+ * instead of with a timeout. At or below the declared link it cannot. If streams dying with
+ * `Unexpected EOF` are seen on such a link, declare that link's real round trip.
  *
  * NOTE: derived from the declaration alone, so a per-field override that raises a cadre dial
  * budget above it (`controlCohort.perAddressDialTimeoutMs`, `strandBackfill.dialTimeoutMs`)
@@ -174,20 +204,21 @@
  *   arrives.
  */
 
+import { resolveLinkDeadlines, type Libp2pConnectionTimeouts, type RpcDeadlineDefaults } 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
- * of link time 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 listener's admission
- * decision is not in that 1.9 s; it has its own allowance on top (the module doc's "The
- * listener's admission decision"). (The previous 2 000 followed the same convention for the
- * 1.8 s band sereus supported before, with about 720 ms to spare.)
+ * `docs/architecture.md` → "Relay Integration"). The worst relayed dial measured at that link,
+ * opening the relay connection first, was 15 113 ms, above the 15 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 17 500 ms of link time and leaves about 2.4 s over that dial: room for a
+ * phone's Noise handshakes, which the loopback measurement on a desktop does not contain. The
+ * admission decisions are not in that 2.4 s; they have their own allowance on top (the module
+ * doc's "Admission decisions").
  *
  * One budget outside this module does NOT move with it: `DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`
  * (`strand-first-sync-gate.ts`) bounds a whole first sync, which has no round-trip count, so it
@@ -196,33 +227,38 @@
  * ({@link cohortReadDeadlineMs}).
  *
  * What 3 500 costs, against 2 000: a peer that is genuinely gone holds each operation longer
- * before it is abandoned and retried — the link part of a relayed dial or a reservation drive
- * 14 s instead of 8 s, and of a control-cohort dial of one peer across all its addresses 56 s
- * instead of 32 s. The admission allowance adds to both (see {@link relayedDialBudgetMs}).
+ * before it is abandoned and retried — the link part of a relayed dial 17.5 s instead of 10 s,
+ * of a reservation drive 14 s instead of 8 s, and of a control-cohort dial of one peer across
+ * all its addresses 70 s instead of 40 s. The admission allowances add to each (see
+ * {@link relayedDialBudgetMs}).
  * 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.
+ * Link round trips opening a relayed connection costs over a relay connection the dialer
+ * ALREADY holds: the circuit open through the relay (hop-stream negotiation and CONNECT, then
+ * the relay's stop stream to the called machine), then the encryption and multiplexer
+ * handshakes end to end through it. Measured at 8 one-way delays.
  */
-export const RELAYED_DIAL_ROUND_TRIPS = 4;
+export const CIRCUIT_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.
+ * Link round trips the dialer spends opening its own connection to the relay: transport,
+ * encryption and multiplexer handshakes on its one hop. Measured at 2 one-way delays. libp2p's
+ * circuit transport opens it inside the relayed dial, under the caller's signal, whenever no
+ * relay connection is open yet.
+ */
+export const RELAY_DIAL_ROUND_TRIPS = 1;
+
+/**
+ * Link round trips a relayed dial is budgeted for: opening the relay connection
+ * ({@link RELAY_DIAL_ROUND_TRIPS}) and then the circuit over it ({@link CIRCUIT_DIAL_ROUND_TRIPS}).
+ * Measured at 10 one-way delays from a dialer holding no relay connection. Counted for every
+ * relayed dial, because a dialer cannot know beforehand whether that connection is open.
  */
-export const RELAY_RESERVATION_ROUND_TRIPS = 4;
+export const RELAYED_DIAL_ROUND_TRIPS = RELAY_DIAL_ROUND_TRIPS + CIRCUIT_DIAL_ROUND_TRIPS;
 
 /**
  * Link round trips from the moment a party-run relay admits a stranger's connection for relay
@@ -242,6 +278,20 @@ export const RELAY_RESERVATION_ROUND_TRIPS = 4;
  */
 export const RELAY_RESERVE_REQUEST_ROUND_TRIPS = 1;
 
+/**
+ * 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 ({@link RELAY_DIAL_ROUND_TRIPS}) plus request
+ * the reservation ({@link RELAY_RESERVE_REQUEST_ROUND_TRIPS}). It is budgeted at twice that,
+ * 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 = 2 * (RELAY_DIAL_ROUND_TRIPS + RELAY_RESERVE_REQUEST_ROUND_TRIPS);
+
 /**
  * Link round trips negotiating one protocol over an ALREADY-OPEN connection costs: the
  * multistream-select exchange that `dialProtocol` / `newStream` runs before the stream is
@@ -290,7 +340,7 @@ export const COMMIT_ROUND_TRIPS = 20;
  * possibly through a relay: {@link RELAYED_DIAL_ROUND_TRIPS} + {@link CIRCUIT_REQUEST_ROUND_TRIPS}.
  * The shape of cadre's own one-frame control protocols (strand wake, strand address, seed
  * delivery), each of which bounds the dial and the exchange with ONE deadline. Link time only:
- * {@link relayedRequestBudgetMs} adds the listener's admission allowance on top.
+ * {@link relayedRequestBudgetMs} adds the dial's admission allowances on top.
  */
 export const RELAYED_REQUEST_ROUND_TRIPS = RELAYED_DIAL_ROUND_TRIPS + CIRCUIT_REQUEST_ROUND_TRIPS;
 
@@ -350,11 +400,13 @@ export const PUSH_TRANSFER_ALLOWANCE_MS = 6000;
  * - **The decision is spent on the dialing machine's clock.** libp2p's listener
  *   runs this gate before it answers the multiplexer negotiation the dialer is
  *   waiting on (`libp2p/dist/src/upgrader.js`), and the listener's own
- *   `inboundUpgradeTimeout` is already running while it does. So
- *   {@link relayedDialBudgetMs}, and every budget built on it, adds this
- *   deadline once per decision the called machine may make, and the two libp2p
- *   limits Optimystic derives from the same declaration contain it (the module
- *   doc's "Optimystic's deadlines, from the same declaration").
+ *   `inboundUpgradeTimeout` is already running while it does; a party-run
+ *   relay runs the same gate on the dialer's connection to it. So
+ *   {@link relayedDialBudgetMs}, every budget built on it, and the dial limits
+ *   cadre states to Optimystic ({@link optimysticDialLimits}) add this deadline
+ *   once for each of the {@link DIAL_ADMISSION_DECISIONS} gates a dial passes,
+ *   and the listener's limit Optimystic derives contains the called machine's
+ *   (the module doc's "Optimystic's deadlines, from the same declaration").
  *   Raising it therefore lengthens every dial budget with it: a slow decision
  *   still fits, and a dial to a peer that is gone takes that much longer to
  *   give up.
@@ -393,31 +445,39 @@ export function resolveLinkRoundTripMs(linkRoundTripMs?: number): number {
 	return linkRoundTripMs;
 }
 
+/**
+ * Admission decisions a relayed dial may wait on, each on the dialer's clock: a party-run relay's,
+ * on the dialer's connection to it (`denyInboundEncryptedConnection`), then the called machine's.
+ */
+export const DIAL_ADMISSION_DECISIONS = 2;
+
 /**
  * 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, plus one
- * {@link ADMISSION_DECISION_TIMEOUT_MS} for the called machine's inbound gate, which runs on
- * this dial's clock. 4 x 3 500 + 2 000 = 16 000 ms at the default declaration.
- *
- * What the allowance costs: a peer that is truly gone holds each dial 2 s longer before it is
- * abandoned — a per-address dial 16 s instead of 14 s, a control-cohort dial of one peer across
- * its 4 addresses 64 s instead of 56 s, and a wake call's two attempts 46 s instead of 42 s. A
- * machine that runs no gate (the dedicated relay container, an open-strand node) gets the same
- * budget; the extra 2 s only lengthens a failure there, never a success.
+ * relay: {@link RELAYED_DIAL_ROUND_TRIPS} at the declared link round trip, which includes opening
+ * the dialer's own connection to the relay, plus one {@link ADMISSION_DECISION_TIMEOUT_MS} for
+ * each of the {@link DIAL_ADMISSION_DECISIONS} gates that run on this dial's clock.
+ * 5 x 3 500 + 2 x 2 000 = 21 500 ms at the default declaration.
+ *
+ * What it costs: a peer that is truly gone holds each dial this long before it is abandoned — a
+ * per-address dial 21.5 s, a control-cohort dial of one peer across its 4 addresses 86 s, and a
+ * wake call's two attempts 57 s — of which the relay leg and the relay's decision are 5.5 s per
+ * dial. A dial over a relay connection already open, or to a machine that runs no gate (the
+ * dedicated relay container, an open-strand node), gets the same budget; the unused part only
+ * lengthens a failure there, never a success.
  *
  * A per-field override of a deadline derived from this one
  * (`network.controlCohort.perAddressDialTimeoutMs`, `strandBackfill.dialTimeoutMs`,
- * `DialWakeOptions.timeoutMs`, …) replaces the whole derived value, allowance included.
+ * `DialWakeOptions.timeoutMs`, …) replaces the whole derived value, allowances included.
  */
 export function relayedDialBudgetMs(linkRoundTripMs?: number): number {
-	return RELAYED_DIAL_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs) + ADMISSION_DECISION_TIMEOUT_MS;
+	return RELAYED_DIAL_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs) + DIAL_ADMISSION_DECISIONS * ADMISSION_DECISION_TIMEOUT_MS;
 }
 
 /**
  * Deadline for what `dialProtocol` does end to end: OPEN a possibly relayed connection
- * ({@link relayedDialBudgetMs}, admission allowance included) and then NEGOTIATE one protocol
- * on it ({@link PROTOCOL_NEGOTIATION_ROUND_TRIPS} at the declared link round trip). 16 000 +
- * 3 500 = 19 500 ms at the default declaration. The strand formation dial is bounded by this;
+ * ({@link relayedDialBudgetMs}, admission allowances included) and then NEGOTIATE one protocol
+ * on it ({@link PROTOCOL_NEGOTIATION_ROUND_TRIPS} at the declared link round trip). 21 500 +
+ * 3 500 = 25 000 ms at the default declaration. The strand formation dial is bounded by this;
  * the one-frame control exchanges bound the negotiation together with their request instead
  * ({@link relayedRequestBudgetMs}).
  */
@@ -482,9 +542,9 @@ export function circuitRequestBudgetMs(
 
 /**
  * Deadline for opening a (possibly relayed) connection and completing one small request on it:
- * {@link relayedDialBudgetMs}, admission allowance included, plus
+ * {@link relayedDialBudgetMs}, admission allowances included, plus
  * {@link CIRCUIT_REQUEST_ROUND_TRIPS} at the declared link round trip — so
- * {@link RELAYED_REQUEST_ROUND_TRIPS} of link time in all. 16 000 + 2 x 3 500 = 23 000 ms at the
+ * {@link RELAYED_REQUEST_ROUND_TRIPS} of link time in all. 21 500 + 2 x 3 500 = 28 500 ms at the
  * default declaration.
  *
  * No transfer allowance, unlike {@link circuitRequestBudgetMs}: the requests this bounds are a few
@@ -581,3 +641,44 @@ export function peerJoinPushBudget(linkRoundTripMs?: number): PeerJoinPushBudget
 		responseTimeoutMs: circuitRequestBudgetMs(linkRoundTripMs)
 	};
 }
+
+/** The connection limits cadre states to Optimystic on every node it builds, beside the declared link. */
+export interface OptimysticDialLimits {
+	/** `NodeOptions.connectionManager`: libp2p's limit on one address of a dial, and on a dial that carries no signal. */
+	connectionManager: Required<Pick<Libp2pConnectionTimeouts, 'addressDialTimeout' | 'dialTimeout'>>;
+	/** `NodeOptions.rpcDeadlines`: the dial deadline of every Optimystic request. */
+	rpcDeadlines: Pick<RpcDeadlineDefaults, 'dialTimeoutMs'>;
+}
+
+/**
+ * The three limits that cover opening a connection, as cadre states them to Optimystic on the
+ * control node and every strand node: Optimystic's own derivation from the declared link
+ * (`resolveLinkDeadlines`), which is link time only, plus one {@link ADMISSION_DECISION_TIMEOUT_MS}
+ * for each of the {@link DIAL_ADMISSION_DECISIONS} gates the open runs through. 39 000 ms per
+ * address, 39 000 ms per dial and a 42 500 ms request dial at the default declaration.
+ *
+ * Built on Optimystic's derivation rather than restating its round-trip counts, so a change to
+ * them reaches every node without an edit here. `dialTimeout` stays at least `addressDialTimeout`,
+ * as Optimystic's derivation has it, because both take the same addition. The request dial stays
+ * one round trip longer than `addressDialTimeout`, also as Optimystic derives them, although
+ * Optimystic's `rpcDeadlines` doc asks for it to be no longer: that round trip is the stream
+ * negotiation after the connection opens, which the per-address limit does not cover.
+ *
+ * The listener's `inboundUpgradeTimeout` and the request response deadline are left to Optimystic:
+ * the listener's timer runs over its own upgrade and its own decision only (the module doc's
+ * "Optimystic's deadlines, from the same declaration"), and a response waits on no gate.
+ *
+ * The declaration is resolved first, so an invalid one fails with cadre's message. A round trip
+ * above Optimystic's `MAX_LINK_ROUND_TRIP_MS` throws from Optimystic, here.
+ */
+export function optimysticDialLimits(linkRoundTripMs?: number): OptimysticDialLimits {
+	const derived = resolveLinkDeadlines(resolveLinkRoundTripMs(linkRoundTripMs));
+	const decisionsMs = DIAL_ADMISSION_DECISIONS * ADMISSION_DECISION_TIMEOUT_MS;
+	return {
+		connectionManager: {
+			addressDialTimeout: derived.addressDialTimeoutMs + decisionsMs,
+			dialTimeout: derived.libp2pDialTimeoutMs + decisionsMs
+		},
+		rpcDeadlines: { dialTimeoutMs: derived.dialTimeoutMs + decisionsMs }
+	};
+}

package/src/membership-connection-gater.ts

@@ -36,9 +36,9 @@
  *    node has at least one UNEXPIRED, NOT-FULLY-CONSUMED open invitation
  *    outstanding (`StrandSolicitationService.hasOutstandingInvitation` — the
  *    tokens this process minted or published, plus any still-redeemable
- *    `FormationInvite` row the usage recorder can see). Merely registering the
- *    responder (`CadreNode.initializeStrandSolicitation`) does NOT suspend it,
- *    so an app that registers eagerly at node bring-up keeps a live gate. The
+ *    `FormationInvite` row the usage recorder can see). Registering the
+ *    responder does NOT suspend it, so every node — each registers one at
+ *    `CadreNode.start` — keeps a live gate. The
  *    handler's own trust decision remains the per-token check, which is
  *    strictly finer than this one: a peer admitted here can still be rejected
  *    in-protocol for a bogus or spent token.

package/src/node-local-snapshot.ts

@@ -5,9 +5,9 @@
  *
  *  - the trusted-owner anchor (`trusted-owner-store.ts`),
  *  - the cold-start bootstrap-peer store (`bootstrap-peer-store.ts`),
- *  - the strand peer book (`strand-peer-book.ts`), whose entries are one map per
- *    strand rather than one value per key — the validation hook below is what
- *    lets it drop a single junk peer without dropping the strand.
+ *  - the strand network state (`strand-network-state.ts`): per strand, the state
+ *    Optimystic's db-p2p saved for the strand node, opaque here past a structural
+ *    check.
  *
  * ANOTHER node-local record — the enrolled-machine count
  * (`enrolled-machine-store.ts`) — reuses {@link DurableSlot} but deliberately
@@ -72,10 +72,10 @@ const ENVELOPE_VERSION = 1;
  *    in full is not an anchor. Trusting a *subset* of the keys a file claims is
  *    a silent, security-relevant downgrade, so the whole record is discarded
  *    and the node trusts no one until re-seeded out of band.
- *  - `'drop-entry'` (the bootstrap-peer store and the strand peer book): the
- *    record is a best-effort dial list and nothing in it is trust-bearing, so one
- *    junk entry must not discard a stranded node's only remaining way back to
- *    its party or its strand's peers.
+ *  - `'drop-entry'` (the bootstrap-peer store and the strand network state):
+ *    the record is a best-effort dial list and nothing in
+ *    it is trust-bearing, so one junk entry must not discard a stranded node's
+ *    only remaining way back to its party or its strand's peers.
  */
 export type UnusableEntryPolicy = 'discard-all' | 'drop-entry';
 
@@ -149,6 +149,11 @@ export class NodeLocalSnapshot<E> {
 		return this.entries.has(key);
 	}
 
+	/** The entry held for `key`, if any. Needs no copy: {@link put} replaces an entry, never mutates it. */
+	get(key: string): E | undefined {
+		return this.entries.get(key);
+	}
+
 	/** Fresh copy of the keys — a snapshot decoupled from later {@link put} / {@link remove} calls. */
 	keySnapshot(): Set<string> {
 		return new Set(this.entries.keys());

package/src/peer-dial.ts

@@ -2,12 +2,15 @@
  * Dialing one peer from a list of candidate addresses, so that an address that
  * never answers cannot use up the time the others needed.
  *
- * libp2p's own multi-address dial (`libp2p.dial(addrs)`, libp2p 3.1.3's
- * `DialQueue.dialPeer`) tries the addresses ONE AT A TIME under ONE signal, with
- * no time limit per address. An address whose connection attempt is silently
- * dropped — a firewall, a subnet the dialer cannot route to, a virtual adapter's
- * address a Windows host reports alongside its real ones — holds that dial until
- * the whole signal expires, and every address sorted after it is never tried. It
+ * libp2p's own multi-address dial (`libp2p.dial(addrs)`, `DialQueue.dialPeer`)
+ * tries the addresses ONE AT A TIME under ONE signal. Its only per-address limit
+ * is the connection manager's `addressDialTimeout` (libp2p 3.3+), which cadre
+ * sizes for a cold relayed open through two admission decisions
+ * (`optimysticDialLimits` in `link-budget.ts`: 39 s at the default declared
+ * link). An address whose connection attempt is silently dropped — a firewall, a
+ * subnet the dialer cannot route to, a virtual adapter's address a Windows host
+ * reports alongside its real ones — holds that dial for that long or until the
+ * whole signal expires, and the addresses sorted after it get what is left. It
  * also sorts the list itself (`defaultAddressSorter`), putting loopback addresses
  * last, behind exactly the LAN addresses most likely to be dropped. A phone
  * borrowing a node from a cadre-host whose only reachable address was the
@@ -34,17 +37,17 @@ 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) 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.
+ * `RELAYED_DIAL_ROUND_TRIPS` (5) x `DECLARED_LINK_ROUND_TRIP_MS` (3500 ms) plus
+ * `DIAL_ADMISSION_DECISIONS` (2) x `ADMISSION_DECISION_TIMEOUT_MS` (2000 ms) = 21 500 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
  * 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. `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
+ * reasoning is now a measured count instead of an estimate — five link round trips, measured at
+ * 15 113 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.
@@ -200,9 +203,10 @@ export async function dialPeerAddrs(
  * one address and immediately dialing the next for the same peer therefore
  * joins the dying job, which rejects the new dial with `AbortError` before it
  * touches the network — the next address is never tried. Seen against libp2p
- * 3.1.3; `test/peer-dial.spec.ts` dials real nodes so an upgrade that changes it
- * shows up there. All of the queue's cleanup runs as microtasks, so it has
- * finished by the time a macrotask runs.
+ * 3.1.3, and the queue's join is unchanged in 3.3.11; `test/peer-dial.spec.ts`
+ * dials real nodes so an upgrade that changes it shows up there. All of the
+ * queue's cleanup runs as microtasks, so it has finished by the time a
+ * macrotask runs.
  */
 export async function tryAddrsInTurn<T>(
 	addrs: readonly Multiaddr[],

package/src/peer-join-backfill.ts

@@ -148,10 +148,9 @@ export const MAX_BLOCK_MESSAGE_BYTES = 8 * 1024 * 1024;
  * 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.
+ * long it is dialed, since the protocol id is namespaced per network.
  */
-export function speaksBlockTransfer(protocols: readonly string[], protocolPrefix: string): boolean {
+function speaksBlockTransfer(protocols: readonly string[], protocolPrefix: string): boolean {
   return protocols.includes(buildBlockTransferProtocol(protocolPrefix));
 }
 
@@ -176,9 +175,9 @@ export interface PeerJoinBackfillConfig {
   /** Max blocks per push message. Default 64. */
   maxChunkBlocks?: number;
   /**
-   * Per-push dial deadline, ms. Default {@link peerJoinPushBudget}'s `dialTimeoutMs` — four link
-   * 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
+   * Per-push dial deadline, ms. Default {@link peerJoinPushBudget}'s `dialTimeoutMs` — five link
+   * round trips at the declared link plus two admission decisions (a party-run relay's and the
+   * called machine's), 21 500 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.