@serfab/cadre-core 1.5.0 → 1.7.0

package/src/index.ts

@@ -117,6 +117,73 @@ export {
   type EnrolledMachineStore
 } from './enrolled-machine-store.js';
 
+// Node-local record of the strands this node joined from ANOTHER party, re-offered on
+// every start as `strand:discovered`. Cross-platform: its durable form rides the
+// KeyStore seam above (the record carries a closed strand's read secret), so there is
+// no file-backed subpath.
+export {
+  MemoryJoinedStrandStore,
+  KeyStoreJoinedStrandStore,
+  type JoinedStrandStore,
+  type JoinedStrandRecord
+} from './joined-strand-store.js';
+
+// Node-local strand peer book: per strand, the strand peers this node has met and
+// their last-known addresses, dialed first on every launch so a restarted machine
+// re-finds the other parties. Same cross-platform split as the bootstrap-peer store
+// above — interface + in-memory + slot-backed stores here, Node-only file backend
+// behind the subpath '@serfab/cadre-core/strand-peer-book-file'.
+export {
+  MemoryStrandPeerBookStore,
+  PersistentStrandPeerBookStore,
+  mergeStrandPeerEntry,
+  sanitizeStrandPeerEntry,
+  strandPeerFreshness,
+  MAX_STRAND_PEERS,
+  STRAND_PEER_MAX_AGE_MS,
+  type StrandPeerBookStore,
+  type StrandPeerBookOptions,
+  type StrandPeerEntry
+} from './strand-peer-book.js';
+export {
+  StrandPeerObserver,
+  dialableAddrs,
+  connectedIdentifiedPeers,
+  STRAND_PEER_OBSERVE_THROTTLE_MS,
+  type StrandPeerObservation,
+  type StrandPeerObserverDeps,
+  type StrandPeerObserverOptions,
+  type ConnectedIdentifiedPeer
+} from './strand-peer-observer.js';
+// The signed book SWAP between strand peers (`/sereus/strand-peers/1.0.0`): the wire
+// protocol, signing and verification, and the per-strand driver that arms it.
+export {
+  STRAND_PEER_BOOK_PROTOCOL,
+  SIGNED_STRAND_PEER_ENTRY_VERSION,
+  STRAND_PEER_ISSUED_AT_SKEW_MS,
+  MAX_BOOK_FRAME_SIZE,
+  StrandPeerBookService,
+  exchangeStrandPeerBook,
+  signStrandPeerEntry,
+  signedStrandPeerEntryPayload,
+  verifySignedStrandPeerEntry,
+  verifyStrandPeerBookFrame,
+  trimBookFrameToFit,
+  assertBookFrameFits,
+  type SignedStrandPeerEntry,
+  type StrandPeerBookFrame,
+  type StrandPeerEntryVerdict,
+  type StrandPeerBookServiceDeps,
+  type ExchangeStrandPeerBookOptions
+} from './strand-peer-book-protocol.js';
+export {
+  StrandPeerBookSwap,
+  STRAND_PEER_BOOK_SWAP_THROTTLE_MS,
+  OWN_ENTRY_RESIGN_DEBOUNCE_MS,
+  type StrandPeerBookSwapDeps,
+  type StrandPeerBookSwapOptions
+} from './strand-peer-book-swap.js';
+
 // Storage scope keys — what `CadreNodeConfig.storage.provider` is called with. A
 // strand's key is its strand id; the control database's key carries the party id,
 // so two parties on one device never share a control store. Every key stays within
@@ -457,6 +524,7 @@ export {
   PUSH_TRANSFER_ALLOWANCE_MS,
   resolveLinkRoundTripMs,
   relayedDialBudgetMs,
+  connectionManagerTimeouts,
   relayReservationBudgetMs,
   circuitRequestBudgetMs,
   peerJoinPushBudget,

package/src/joined-strand-store.ts

@@ -0,0 +1,308 @@
+/**
+ * Node-local record of the strands this node joined from ANOTHER party.
+ *
+ * A party's own strands come back after a restart through its control database: the
+ * `Strand` table holds their rows, the strand watcher polls it, and each row no sApp
+ * config claims is offered as `strand:discovered`. A strand joined through formation with
+ * another party (`CadreNode.formStrand`) has no row there — the other party's control
+ * database holds it — so nothing re-offered it after a restart, and every embedding app
+ * kept its own list of joins, read secret included (gotchoices/sereus#18).
+ *
+ * `CadreNode` records each such join here, hands the records to its strand watcher beside
+ * the control rows ({@link JoinedStrandRows}), and forgets one on `forgetJoinedStrand` or
+ * when this party is removed from the strand.
+ *
+ * Two implementations:
+ *  - {@link MemoryJoinedStrandStore} — joins die with the process. The default only for a
+ *    node configured with no `keyStore`.
+ *  - {@link KeyStoreJoinedStrandStore} — one {@link KeyStore} slot per join. A record holds
+ *    the closed strand's shared read secret, and the KeyStore is the one seam every
+ *    platform already routes secrets through (the platform enclave on React Native, the
+ *    state directory for `FileKeyStore`), so the record goes there rather than into a
+ *    `DurableSlot` like the bootstrap-peer store.
+ *
+ * Party-scoped like every other node-local store, because one KeyStore can serve several
+ * parties: the React Native app keeps one per device and lets the user switch party. A
+ * join made for one party must never be offered to a node started for another.
+ *
+ * Dependency-free beyond the KeyStore seam, so safe in every entry graph.
+ */
+import debug from 'debug';
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import type { KeyId, KeyStore } from './key-store.js';
+import { assertStrandScopeKey, isValidStrandScopeKey } from './storage-scope.js';
+import type { StrandRow } from './types.js';
+
+const log = debug('sereus:cadre:joined-strand-store');
+
+/** One strand this node joined from ANOTHER party — nothing in this party's control DB names it. */
+export interface JoinedStrandRecord {
+	/** The strand id (a valid scope key, see storage-scope.ts). */
+	Id: string;
+	Type: 'o' | 'c';
+	/** The closed strand's shared read secret the formation delivered; null for an open strand. */
+	MemberPrivateKey: string | null;
+	/** Wall-clock ms this node first recorded the join. Diagnostics only. */
+	joinedAt: number;
+}
+
+export interface JoinedStrandStore {
+	/** Party this store is scoped to. */
+	readonly partyId: string;
+
+	/** Every remembered join. A call reflects every {@link record}/{@link forget} that resolved before it was made. */
+	list(): Promise<JoinedStrandRecord[]>;
+
+	/** Remember a join, REPLACING any record with the same `Id`. */
+	record(record: JoinedStrandRecord): Promise<void>;
+
+	/** Forget a join. A no-op when there is no record for `strandId`. */
+	forget(strandId: string): Promise<void>;
+}
+
+/**
+ * The {@link StrandRow} a record stands for — the shape `addStrand` and `strand:discovered`
+ * carry. `FounderOwnerKey` is null because a joiner never founds; `CadreNode.launchStrand`
+ * reads null as "not mine" and joins.
+ */
+export function joinedStrandRow(record: JoinedStrandRecord): StrandRow {
+	return { Id: record.Id, Type: record.Type, MemberPrivateKey: record.MemberPrivateKey, FounderOwnerKey: null };
+}
+
+/**
+ * Ephemeral store for a node without a `keyStore`. Warns once, at the first join it is
+ * asked to remember, because a join held only here is not re-offered after a restart —
+ * exactly the gotchoices/sereus#18 shape, and it should show in a log rather than pass
+ * silently.
+ */
+export class MemoryJoinedStrandStore implements JoinedStrandStore {
+	private readonly records = new Map<string, JoinedStrandRecord>();
+	private warned = false;
+
+	constructor(readonly partyId: string) {}
+
+	async list(): Promise<JoinedStrandRecord[]> {
+		return [...this.records.values()];
+	}
+
+	async record(record: JoinedStrandRecord): Promise<void> {
+		this.warnOnce();
+		this.records.set(record.Id, { ...record });
+	}
+
+	async forget(strandId: string): Promise<void> {
+		this.records.delete(strandId);
+	}
+
+	private warnOnce(): void {
+		if (this.warned) {
+			return;
+		}
+		this.warned = true;
+		console.warn(
+			'CadreNode has no keyStore and no joinedStrands.store, so strands joined from another party ' +
+			'are remembered in memory only and will NOT be re-offered after a restart. Configure a keyStore, ' +
+			'or inject joinedStrands: { store: new KeyStoreJoinedStrandStore(<a durable KeyStore>, partyId) }.'
+		);
+	}
+}
+
+/** Slot id prefix for every joined-strand record; the party segment and the strand id follow. */
+const SLOT_PREFIX = 'cadre/joined-strand/';
+
+/**
+ * Durable store over a {@link KeyStore}: one slot per join, id
+ * `cadre/joined-strand/<base64url party id>/<strand id>`, holding the record's UTF-8 JSON.
+ * The party segment is base64url for the reason `controlStorageScope` gives: a party id is
+ * arbitrary text, and base64url never contains the `/` that ends the segment.
+ *
+ * Loads every slot once, at the first {@link list}, then answers from memory and writes
+ * through, so the strand watcher's five-second poll does not read the enclave on every
+ * pass. A load that fails — `KeyStoreAccessError` from a refused unlock prompt, say —
+ * is rethrown rather than read as "no joins" and retried at the next call, exactly as
+ * `loadOrCreateIdentityKey` treats the identity slot. A slot that does not parse as a
+ * record for its own id is dropped with a log and its siblings kept: refusing to start
+ * repairs nothing, and the other joins are still good.
+ */
+export class KeyStoreJoinedStrandStore implements JoinedStrandStore {
+	private readonly slotPrefix: string;
+	/** The loaded records; null until a load succeeds. */
+	private records: Map<string, JoinedStrandRecord> | null = null;
+	/** Runs every KeyStore access in call order, so a load never interleaves with a write. */
+	private queue: Promise<unknown> = Promise.resolve();
+
+	constructor(private readonly keyStore: KeyStore, readonly partyId: string) {
+		this.slotPrefix = SLOT_PREFIX + uint8ArrayToString(uint8ArrayFromString(partyId, 'utf8'), 'base64url') + '/';
+	}
+
+	list(): Promise<JoinedStrandRecord[]> {
+		return this.inOrder(async () => [...(await this.loaded()).values()]);
+	}
+
+	/** Throws `InvalidStrandIdError` for an id that could never load back, before anything is written. */
+	record(record: JoinedStrandRecord): Promise<void> {
+		assertStrandScopeKey(record.Id);
+		const stored: JoinedStrandRecord = { ...record };
+		return this.inOrder(async () => {
+			await this.keyStore.set(this.slotId(record.Id), uint8ArrayFromString(JSON.stringify(stored), 'utf8'));
+			this.records?.set(record.Id, stored);
+			log('joined strand remembered (party=%s, strand=%s, type=%s)', this.partyId, record.Id, record.Type);
+		});
+	}
+
+	forget(strandId: string): Promise<void> {
+		return this.inOrder(async () => {
+			await this.keyStore.delete(this.slotId(strandId));
+			this.records?.delete(strandId);
+			log('joined strand forgotten (party=%s, strand=%s)', this.partyId, strandId);
+		});
+	}
+
+	private slotId(strandId: string): KeyId {
+		return this.slotPrefix + strandId;
+	}
+
+	private inOrder<T>(op: () => Promise<T>): Promise<T> {
+		const result = this.queue.then(op);
+		// The caller receives `result`, rejection included; the queue only needs to know it settled.
+		this.queue = result.catch(() => undefined);
+		return result;
+	}
+
+	// NOTE: a failed load is retried at the next list(), which is every strand-watcher poll;
+	// over a backend that gates reads behind an unlock prompt the user keeps declining, that
+	// is a prompt every five seconds. Every KeyStore shipped today is ungated for this reason
+	// (see `SecureStoreKeyStoreOptions.requireAuthentication`); if one is ever gated, back
+	// off the retry here.
+	private async loaded(): Promise<Map<string, JoinedStrandRecord>> {
+		if (this.records) {
+			return this.records;
+		}
+		const records = new Map<string, JoinedStrandRecord>();
+		for (const slot of await this.keyStore.list()) {
+			if (!slot.startsWith(this.slotPrefix)) {
+				continue;
+			}
+			const strandId = slot.slice(this.slotPrefix.length);
+			const bytes = await this.keyStore.get(slot);
+			if (!bytes) {
+				continue;
+			}
+			const record = parseRecord(strandId, bytes);
+			if (record) {
+				records.set(strandId, record);
+			}
+		}
+		this.records = records;
+		log('joined strands loaded (party=%s, count=%d)', this.partyId, records.size);
+		return records;
+	}
+}
+
+/** The record a slot holds, or undefined (logged) when it is not one for `strandId`. */
+function parseRecord(strandId: string, bytes: Uint8Array): JoinedStrandRecord | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(uint8ArrayToString(bytes, 'utf8'));
+	} catch (error) {
+		log('dropping joined-strand slot for %s: not JSON (%o)', strandId, error);
+		return undefined;
+	}
+	const { Id, Type, MemberPrivateKey, joinedAt } = (typeof parsed === 'object' && parsed !== null ? parsed : {}) as Record<string, unknown>;
+	const valid = Id === strandId
+		&& isValidStrandScopeKey(strandId)
+		&& (Type === 'o' || Type === 'c')
+		&& (MemberPrivateKey === null || typeof MemberPrivateKey === 'string')
+		&& typeof joinedAt === 'number';
+	if (!valid) {
+		log('dropping joined-strand slot for %s: not a joined-strand record for that id', strandId);
+		return undefined;
+	}
+	return { Id: strandId, Type: Type as 'o' | 'c', MemberPrivateKey: MemberPrivateKey as string | null, joinedAt: joinedAt as number };
+}
+
+/**
+ * What the strand watcher sees of the joined-strand store: the control rows plus one row per
+ * remembered join, which is how a join comes back as `strand:discovered` (or auto-launches)
+ * after a restart with no second offer path. One instance per node session.
+ *
+ * Holds the two pieces of state a plain union would get wrong, both of which would otherwise
+ * make the watcher detach running strands, since a joined row missing from a poll reads to it
+ * as a removal:
+ *  - the last list the store answered, reused when a later list fails, so a read failure is
+ *    not "every join was forgotten";
+ *  - joins forgotten because this party was removed from the strand
+ *    ({@link forgetAfterThisSession}): gone from the store, so the next start does not
+ *    re-attach them, but still offered until this session ends, because `strand:revoked`
+ *    promises that nothing is torn down for the app.
+ */
+export class JoinedStrandRows {
+	private lastListed: JoinedStrandRecord[] = [];
+	private readonly keptForSession = new Map<string, JoinedStrandRecord>();
+
+	constructor(private readonly store: JoinedStrandStore) {}
+
+	/**
+	 * `control` plus a row for every remembered join. A control row wins an id collision: the
+	 * strand is this party's own now (its founding party enrolled this machine, say), the
+	 * control database remembers it, and the record is stale — so it is forgotten here.
+	 */
+	async withControlRows(control: readonly StrandRow[]): Promise<StrandRow[]> {
+		const controlIds = new Set(control.map((row) => row.Id));
+		const joined = new Map<string, JoinedStrandRecord>(this.keptForSession);
+		for (const record of await this.listed()) {
+			joined.set(record.Id, record);
+		}
+		const rows = [...control];
+		for (const record of joined.values()) {
+			if (controlIds.has(record.Id)) {
+				await this.forgetSuperseded(record.Id);
+			} else {
+				rows.push(joinedStrandRow(record));
+			}
+		}
+		return rows;
+	}
+
+	/** Forget a join for good: the app is leaving the strand. */
+	async forget(strandId: string): Promise<void> {
+		this.keptForSession.delete(strandId);
+		await this.store.forget(strandId);
+	}
+
+	/**
+	 * Forget a join durably, but keep offering it until this session ends. For a strand this
+	 * party was removed from: it must not re-attach on every launch, and it must not be torn
+	 * down underneath the app either. A no-op for a strand with no record.
+	 */
+	async forgetAfterThisSession(strandId: string): Promise<void> {
+		const record = (await this.listed()).find((listed) => listed.Id === strandId);
+		if (!record) {
+			return;
+		}
+		// Kept BEFORE the store forgets, so no poll can list the store without it and union
+		// without the kept copy.
+		this.keptForSession.set(strandId, record);
+		await this.store.forget(strandId);
+	}
+
+	private async listed(): Promise<JoinedStrandRecord[]> {
+		try {
+			this.lastListed = await this.store.list();
+		} catch (error) {
+			log('joined-strand store list failed; offering the last list it answered (%d join(s)): %o',
+				this.lastListed.length, error);
+		}
+		return this.lastListed;
+	}
+
+	private async forgetSuperseded(strandId: string): Promise<void> {
+		this.keptForSession.delete(strandId);
+		try {
+			await this.store.forget(strandId);
+			log('joined strand %s now has a control row — record forgotten', strandId);
+		} catch (error) {
+			log('forgetting superseded joined strand %s failed; the next poll retries: %o', strandId, error);
+		}
+	}
+}

package/src/key-store.ts

@@ -32,6 +32,12 @@ export const DEFAULT_IDENTITY_KEY_ID: KeyId = 'cadre/identity';
  * Key material is raw bytes (e.g. libp2p protobuf-serialized private keys).
  * Text-only backends encode/decode (base64) internally; byte-native backends
  * (LevelDB) store as-is.
+ *
+ * Not only keys: `KeyStoreJoinedStrandStore` keeps one small UTF-8 JSON record
+ * (about 200 bytes, a closed strand's read secret among its fields) per strand
+ * this node joined from another party, under ids beginning
+ * `cadre/joined-strand/`. {@link list} therefore returns those ids too, and a
+ * backend must accept `/` in an id and values of that size.
  */
 export interface KeyStore {
 	/** Resolves to the stored material, or undefined if the slot is empty. */

package/src/link-budget.ts

@@ -35,63 +35,80 @@
  *
  * | operation                                            | link round trips | at the declared default |
  * | ---------------------------------------------------- | ---------------- | ----------------------- |
- * | open a relayed connection to another machine          | 4                | 8 000 ms                |
- * | dial the relay itself                                 | 1                | 2 000 ms                |
- * | request a reservation on an open relay connection     | 1                | 2 000 ms                |
- * | negotiate a protocol over an established circuit      | 1                | 2 000 ms                |
- *
- * **Measured** 2026-09-26, one Windows machine, loopback dedicated relay, re-run for this
- * change: 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 and a
- * phone's pure-JS crypto, which no delay figure contains. That residue is small but it is why
- * {@link DECLARED_LINK_ROUND_TRIP_MS} carries headroom over the band sereus supports rather
- * than matching it exactly: a declaration equal to the measured round trip would derive a
- * budget marginally BELOW the dial it has to contain.
- *
- * ── The ceiling this does NOT lift ──
- *
- * Above roughly 1 250 ms one-way — a 2.5-second link round trip — no relayed connection can be
- * established by this stack whatever cadre declares here. Two budgets of 10 000 ms each inside
- * libp2p bound the same dial and cannot be reached from sereus at all:
- * `connectionManager.dialTimeout` (libp2p's own default, which `@optimystic/db-p2p`'s
- * `libp2p-node-base.ts` neither sets nor exposes) and `connectionManager.inboundUpgradeTimeout`
- * (which it sets to 10 000). Both appear in the same re-run: at 1 500 ms one-way the dial under
- * libp2p's default failed with `The operation was aborted due to timeout`, and with the shipped
- * inbound-upgrade budget the DIALER's own 12 094 ms dial resolved while the LISTENER had
- * already thrown the half-built connection away — so the first stream over it died with
+ * | 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. That is why a too-slow link produces silence rather than an error.
- *
- * Two consequences for a reader choosing a declaration. Below that ceiling, the DEFAULT
- * declaration of 2 000 ms does not reach it: four round trips of 2 000 ms is 8 000 ms, which
- * covers a one-way delay up to 1 000 ms, so a deployment somewhere between 1 000 and 1 250 ms
- * one-way has to declare its own (about 2 200-2 500) to use the band libp2p still allows. And
- * declaring much ABOVE 2 500 buys nothing: the budgets here grow, and
- * the connection still fails inside libp2p. Lifting that needs an upstream change and a
- * decision about how slow a link sereus intends to carry —
- * `tickets/blocked/how-slow-a-relayed-link-does-sereus-carry`. A reader who raised these
- * numbers and still cannot connect at 1 500 ms one-way has met that ceiling, not this module.
+ * 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 2 000.** It states the slowest link sereus already claims to support, and two other
- * budgets fix that claim independently: `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`, 120 000 ms) were both
- * sized against two parties reaching each other only through a public relay at a round trip
- * near 1.8 s. Declaring 2 000 rounds that band up and leaves about 720 ms over the worst
- * relayed dial measured at it (7 279 ms against a derived 8 000 ms).
- *
- * Raising it is how a deployment that KNOWS its link is slower moves every derived budget at
- * once. The cost is the ordinary cost of a longer deadline: a peer that is genuinely gone holds
- * the operation for that much longer before it is abandoned and retried. Above about 2 500 it
- * buys nothing — see the module doc's ceiling paragraph.
+ * **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 = 2000;
+export const DECLARED_LINK_ROUND_TRIP_MS = 3500;
 
 /**
  * Link round trips one relayed connection setup costs: transport, encryption and multiplexer
@@ -132,10 +149,10 @@ export const CIRCUIT_REQUEST_ROUND_TRIPS = 2;
  *
  * 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 default declaration the derived value is the same 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.
+ * 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;
 
@@ -175,6 +192,36 @@ export function relayedDialBudgetMs(linkRoundTripMs?: number): number {
 	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?: number): Libp2pConnectionTimeouts {
+	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.