@serfab/cadre-core 1.9.0 → 1.10.0

package/src/control-write-retry.ts

@@ -77,11 +77,12 @@ export const SCHEMA_INIT_ATTEMPTS = 5;
  * This budget — not the attempt count — is what makes the policy safe to sit under every
  * control write. A transient failure (stream reset while a connection is still forming)
  * surfaces in well under a second, so it is retried and the loop adds at most ~2.2 s. A
- * genuinely silent cohort member fails at ~21 s per pend round (two `ClusterClient`
- * response-deadline attempts, 10.5 s each at the default declared link; a two-round write
- * measured 42.2 s in `control-write-degraded-cohort-member.integration.ts`), which
- * already exceeds this budget when attempt 1 returns — so that case is surfaced immediately
- * and retry adds ZERO latency to the case where it cannot help.
+ * genuinely silent cohort member costs ~21 s per consensus round (two `ClusterClient`
+ * response-deadline attempts, 10.5 s each at the default declared link): one pend round plus
+ * the cancel discharge's three rounds, about 84 s for one write in
+ * `control-write-degraded-cohort-member.integration.ts`, which already exceeds this budget
+ * when attempt 1 returns — so that case is surfaced immediately and retry adds ZERO latency
+ * to the case where it cannot help.
  *
  * It cuts the loop off by design, so it does not grow with the link: its job is to end the
  * retries of slow attempts, and the caller gets the last attempt's error unchanged. An attempt
@@ -92,16 +93,21 @@ export const SCHEMA_INIT_ATTEMPTS = 5;
  * (10.5 s at the default declared link) still gets none. See `docs/cadre-consistency.md` →
  * "Deadlines Over Optimystic's Reads and Commits".
  *
- * NOTE: a failed commit attempt now also pays a cancel discharge before its error returns
- * (optimystic `TransactorSource.transact`'s catch, added by upstream
- * `1-a-failed-attempt-must-discharge-its-own-pend`) — bounded by six rounds and
- * `abortOrCancelTimeoutMs`, which every collection this repo opens sets to 5 s
- * (`../optimystic/packages/quereus-plugin-optimystic/src/optimystic-adapter/collection-factory.ts`).
- * Two failed attempts whose cancels each run their full budget would consume this whole 10 s
- * ceiling and cut the three-attempt policy to two. Not observed — every measured round of the
- * transient-reset case committed on attempt 3 of 3 — so this is a condition to watch, not work
- * to do: if that case ever starts failing with `failed after 2/3 attempt(s)`, the cancel
- * discharge is where the time went.
+ * NOTE: a failed commit attempt also pays a cancel discharge before its error returns
+ * (optimystic `TransactorSource.transact`'s catch) — bounded by six rounds and
+ * `abortOrCancelTimeoutMs`, which every collection this repo opens sets to the larger of 5 s
+ * and the RPC dial deadline: 42.5 s at the default declared link (`optimysticDialLimits` in
+ * `link-budget.ts`;
+ * `../optimystic/packages/quereus-plugin-optimystic/src/optimystic-adapter/collection-factory.ts`).
+ * One cancel that runs its full budget therefore ends the retries on its own, cutting the
+ * three-attempt policy to however many attempts came before it. A cancel only runs that long
+ * when a peer stays silent, and that attempt has already spent its pend round past this
+ * budget, so the cut loses nothing there. After a transient fault the cancel is either
+ * answered or gives up after its six rounds against a dead transport, in about a second
+ * either way (optimystic `NetworkTransactor.MAX_CANCEL_ROUNDS`). Not observed — every
+ * measured round of the transient-reset case committed on attempt 3 of 3 — so this is a
+ * condition to watch, not work to do: if that case ever starts failing with
+ * `failed after 2/3 attempt(s)`, the cancel discharge is where the time went.
  */
 // eslint-disable-next-line no-restricted-syntax -- cuts off by design: it ends the retries of slow attempts rather than waiting them out; see docs/cadre-consistency.md → "Deadlines Over Optimystic's Reads and Commits"
 export const CONTROL_WRITE_RETRY_BUDGET_MS = 10_000;

package/src/index.ts

@@ -484,6 +484,8 @@ export {
 // one declared assumption about the link moves them all — see `NetworkConfig.linkRoundTripMs`.
 export {
   DECLARED_LINK_ROUND_TRIP_MS,
+  CIRCUIT_DIAL_ROUND_TRIPS,
+  RELAY_DIAL_ROUND_TRIPS,
   RELAYED_DIAL_ROUND_TRIPS,
   RELAY_RESERVATION_ROUND_TRIPS,
   CIRCUIT_REQUEST_ROUND_TRIPS,
@@ -496,7 +498,10 @@ export {
   circuitRequestBudgetMs,
   relayedRequestBudgetMs,
   peerJoinPushBudget,
-  type PeerJoinPushBudget
+  type PeerJoinPushBudget,
+  DIAL_ADMISSION_DECISIONS,
+  optimysticDialLimits,
+  type OptimysticDialLimits
 } from './link-budget.js';
 
 // Seed trust policy (trust anchor for incoming seeds)
@@ -521,6 +526,7 @@ export {
 export {
   FormationListener,
   dialFormation,
+  dialFormationByMachine,
   isValidResponderCreatesResult,
   isWellFormedMembershipInvite,
   sanitizeStrandAddrs,
@@ -534,9 +540,22 @@ export {
   type FormationListenerOptions,
   type FormationDialOptions,
   type FormationDialResult,
+  type FormationRejection,
+  type FormationTokenCheck,
   type ResponderProvisionOutcome
 } from './strand-formation-protocol.js';
+// How a formation dial fails: a typed refusal (with a fixed code) or no answer at all
+export {
+  FormationRejectedError,
+  FormationUnreachableError,
+  FormationPostApprovalError,
+  FORMATION_REJECTION_RETRYABLE,
+  isFormationRejectionCode,
+  type FormationRejectionCode
+} from './strand-formation-rejection.js';
 export { formationDeadlines, type FormationDeadlines } from './strand-formation-deadlines.js';
+// The pending-join retry loop behind CadreNode.requestJoin (PendingJoinStatus is in types.ts)
+export { PENDING_JOIN_POLL_MS, PENDING_JOIN_MAX_BACKOFF_MS, MAX_PENDING_JOIN_MS } from './pending-join-runner.js';
 
 // Strand Formation manager (drives the native transport)
 export {
@@ -545,6 +564,7 @@ export {
   MEMBERSHIP_INVITE_TTL_MS,
   MEMBERSHIP_INVITE_UNAVAILABLE_REASON,
   HOST_STRAND_MUST_BE_RECREATED_REASON,
+  type CadrePeerAddrsSource,
   type MembershipInviteIssuer,
   type StrandFormationManagerConfig,
   type StrandFormationManagerOptions

package/src/invitation-bootstrap.ts

@@ -0,0 +1,40 @@
+/**
+ * Which of the inviting party's other machines an open invitation names, so a joiner can still
+ * form while the machine that minted it is offline. The minting machine's own addresses go
+ * first and are not chosen here (`CadreNode.createOpenInvitation`).
+ */
+
+/**
+ * At most this many of the party's other machines are named, each with at most
+ * {@link INVITATION_ADDRS_PER_SIBLING} addresses: 12 extra addresses of roughly 100–200
+ * characters, base64url-encoded into an invitation shared as text.
+ *
+ * NOTE: if invitations are ever carried in a QR code, lower these caps or name the machines by
+ * peer id only.
+ * NOTE: the per-machine cap keeps the record's order (relay first, then direct addresses as the
+ * machine published them, loopback included). If a sibling with many interfaces is seen to have
+ * its reachable address cut, rank loopback and private addresses last before slicing.
+ */
+export const INVITATION_SIBLING_MACHINES = 3;
+export const INVITATION_ADDRS_PER_SIBLING = 4;
+
+/** One other machine of the party whose signed address record resolved. */
+export interface InvitationSibling {
+	peerId: string;
+	/** The record's `UpdatedAt`: when the machine last published its addresses. */
+	updatedAt: number;
+	/** Relay (signaling) addresses first, each ending in `/p2p/<peerId>`. */
+	addrs: string[];
+}
+
+/**
+ * The addresses of the siblings an invitation names. Machines this node is connected to right
+ * now come first, since a live connection is the best evidence that a machine is up; a record
+ * shows only that it was up within the freshness window. Within each half, newest record first.
+ */
+export function selectInvitationSiblingAddrs(siblings: InvitationSibling[], connected: ReadonlySet<string>): string[] {
+	return [...siblings]
+		.sort((a, b) => Number(connected.has(b.peerId)) - Number(connected.has(a.peerId)) || b.updatedAt - a.updatedAt)
+		.slice(0, INVITATION_SIBLING_MACHINES)
+		.flatMap((sibling) => sibling.addrs.slice(0, INVITATION_ADDRS_PER_SIBLING));
+}

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 }
+	};
+}