@serfab/cadre-core 0.10.0 → 0.12.0

package/dist/cadre-node.d.ts

@@ -13,6 +13,18 @@ import { StrandSolicitationService, type StrandSolicitationServiceOptions } from
 import { type RelayReservationState, type RelayReservationSupervisorOptions } from './relay-reservation.js';
 import type { WakeAck } from './types.js';
 import { type ConnectionPathSummary } from './diagnostics/connection-path.js';
+/**
+ * How often a running strand re-resolves its siblings' strand-network addresses
+ * and re-merges them into its own libp2p address book
+ * ({@link CadreNode.refreshStrandPeerAddrs}). Overridable per node via
+ * `network.controlCohort.strandAddrRefreshMs`.
+ *
+ * Ten minutes sits comfortably inside the peerStore's one-hour address expiry
+ * (`MAX_ADDRESS_AGE`, see `peer-addr-book.ts`) with headroom for several missed
+ * passes, and far above the 15 s reconcile cadence the refresh rides on, so the
+ * strand-addr RPC fan-out stays cheap.
+ */
+export declare const STRAND_PEER_ADDR_REFRESH_MS: number;
 type EventHandler<T> = (data: T) => void;
 /**
  * CadreNode is the main entry point for a cadre member.
@@ -68,6 +80,14 @@ export declare class CadreNode implements SAppIdLookup {
     private pushFanoutService;
     /** Backing field for the {@link running} / {@link isRunning} getters. */
     private _running;
+    /**
+     * The control database's own raw storage (cache-wrapped), resolved once per
+     * `start()` and released in {@link cleanup}. Owning it is what keeps
+     * `config.storage.provider('control')` a once-per-runtime call: a `stop()` then
+     * `start()` cycle on this object re-resolves against a live cache, and never
+     * orphans the previous wrapper's registration in the shared cache pool.
+     */
+    private controlStorage;
     /**
      * In-flight {@link serviceWake} operations keyed by strandId. Coalesces
      * concurrent on-demand wakes for the same strand into one runtime build + one
@@ -83,10 +103,11 @@ export declare class CadreNode implements SAppIdLookup {
     private windowWaiters;
     private eventHandlers;
     /**
-     * Relay multiaddrs the caller asked {@link reserveRelays} to reserve through.
-     * Empty (the default) means nobody asked, so {@link getRelayReservationState}
-     * reports `none` — this whole surface is opt-in and dormant for the CLI/host
-     * nodes, which use the configured `network.relayAddrs` route instead.
+     * Relay multiaddrs the caller asked {@link reserveRelays} to reserve through —
+     * or, on a node that names `network.relayAddrs`, the ones
+     * {@link driveControlRelayReservation} asked for at the end of {@link start}.
+     * Empty (the default) means neither happened, so {@link getRelayReservationState}
+     * reports `none`.
      */
     private relayReserveAddrs;
     /**
@@ -101,6 +122,23 @@ export declare class CadreNode implements SAppIdLookup {
      * supervisor to hold one — i.e. the pre-start `control node unavailable` case.
      */
     private relayReserveError;
+    /**
+     * True from just before the control libp2p node is created until
+     * {@link ControlDatabase.initialize} has settled — the connection gate's
+     * BRING-UP QUIET PERIOD (`membership-connection-gater.ts`), during which this
+     * node refuses every control connection in both directions.
+     *
+     * The invariant: the control database is built while this node holds zero
+     * control connections. Every same-party sibling connected in that window joins
+     * the Optimystic cohort the bring-up's block probes consult, and a sibling that
+     * has not yet replicated this node's `CadrePeer` row refuses them all — which
+     * fails `start()` outright and cannot be retried into convergence (writing the
+     * row that would clear the refusal needs the database being built).
+     *
+     * Cleared on FAILURE as well as success ({@link cleanup} clears it), so
+     * teardown is never gated.
+     */
+    private controlBringUpInFlight;
     /** Map of strandId -> sAppConfig for sAppId filtering and management */
     private sAppConfigs;
     /**
@@ -161,12 +199,25 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * In-memory delegate admission grants (see `delegate-admission.ts`): the
      * strand-node transport peerIds this party's members have announced over the
-     * strand-addr RPC, admitted at the CONNECTION level so a member's NAT'd
-     * strand node can hold a circuit-relay reservation on this node. Consulted
-     * ONLY by {@link admitInboundControlConnection}; the fail-closed per-stream
-     * gate ({@link authorizeInboundControlStream}) never honors it.
+     * strand-addr RPC, admitted at the CONNECTION and RESERVATION levels so a
+     * member's NAT'd strand node can hold a circuit-relay reservation on this
+     * node (without spending the unauthorized-reservation budget). Consulted
+     * ONLY by {@link admitInboundControlConnection} and
+     * {@link admitControlRelayReservation}; the fail-closed per-stream gate
+     * ({@link authorizeInboundControlStream}) never honors it.
      */
     private readonly delegateAdmission;
+    /**
+     * Bounded budget of concurrent circuit-relay reservations granted to peers
+     * this node cannot (yet) place as members — the boot-ordering window where a
+     * genuine sibling reserves before its `CadrePeer` row has replicated here.
+     * Consulted only by {@link admitControlRelayReservation} (the gater's
+     * `denyInboundRelayReservation` policy); authorized members and announced
+     * delegates are admitted before it and never counted. Cap from
+     * `network.unauthorizedRelayReservationCap` (default
+     * `MAX_UNAUTHORIZED_RELAY_RESERVATIONS`).
+     */
+    private readonly unauthorizedRelayReservations;
     /**
      * When this node last ANNOUNCED a delegate, keyed `<targetPeerId>\n<strandId>`
      * (the peer announced TO, not the delegate). Throttles
@@ -176,6 +227,16 @@ export declare class CadreNode implements SAppIdLookup {
      * strand is no longer running are pruned on each reconcile pass.
      */
     private readonly delegateAnnounceAt;
+    /**
+     * When each running strand last had its siblings' strand addresses re-resolved
+     * into its own address book, keyed by strandId. Throttles
+     * {@link refreshStrandPeerAddrs} to once per {@link STRAND_PEER_ADDR_REFRESH_MS}
+     * per strand so the 15 s reconcile tick never becomes per-tick RPC chatter.
+     * Entries for strands that are no longer running are pruned on each pass, so a
+     * hibernated-then-resumed strand refreshes immediately rather than inheriting a
+     * stale stamp.
+     */
+    private readonly strandPeerAddrRefreshAt;
     /**
      * Cold-start bootstrap dial targets: the owner-flagged peers of every seed
      * this node has applied, keyed by peer id, valued by the seed's multiaddr
@@ -473,6 +534,46 @@ export declare class CadreNode implements SAppIdLookup {
      */
     trustOwnerKeys(keys: Iterable<string>, source: Exclude<TrustSource, 'genesis'>): Promise<void>;
     private createControlNode;
+    /**
+     * The control database's cache-wrapped raw storage, resolved from
+     * `config.storage.provider` on first use and then held in {@link controlStorage}
+     * for the rest of this runtime.
+     *
+     * Resolving once is the contract `RawStorageProvider` (types.ts) states: a provider is
+     * called once per scope per runtime lifetime. Re-entering it per call would mint a
+     * second store over one backend — a fresh, cold cache, with the previous wrapper's
+     * registration orphaned in the process-wide pool.
+     *
+     * Lazy rather than eager in `start()` so the pure-unit call path
+     * (`cadre-node-control-node-options.spec.ts` calls `buildControlNodeOptions` on a
+     * bare `new CadreNode`) still resolves — and, on that path too, only once.
+     *
+     * Wrapped in the write-through raw-storage cache (quereus-plugin-sereus's
+     * `cached-storage.ts`) because a control start's cost is its raw-storage
+     * operation count.
+     */
+    private resolveControlStorage;
+    /**
+     * Warn the operator when `network.announceAddrs` will silently cost this node the
+     * relay reachability it also configured.
+     *
+     * A non-empty announce set REPLACES everything libp2p advertises, so the
+     * `/p2p-circuit` address earned by a relay reservation is dropped from the node's
+     * advertised addresses even though the reservation itself is still held — peers
+     * behind NAT stop being able to reach it through that relay. Not an error: an
+     * operator whose relay slot is decorative may genuinely want only the announced
+     * address, so this reports and proceeds.
+     *
+     * Keyed off the RESOLVED listen addrs rather than `relayAddrs` alone, so a
+     * hand-written `/p2p-circuit` entry in `listenAddrs` — the same reservation by the
+     * longer route — is caught too.
+     *
+     * NOTE: the only direct `console.*` in this library — a boot-time operator warning, not a
+     * diagnostic trace (those use `debug`, which an operator never sees without `DEBUG=`). If a
+     * second such warning ever appears here, route both through a `CadreNodeEvents` entry the
+     * embedder surfaces instead of growing a console surface inside a library.
+     */
+    private warnIfAnnounceAddrsDiscardRelay;
     /**
      * Map this node's config onto the control network's libp2p node options.
      *
@@ -482,6 +583,15 @@ export declare class CadreNode implements SAppIdLookup {
      * only caller in production is `createControlNode`.
      */
     private buildControlNodeOptions;
+    /**
+     * Does this node's CONTROL libp2p run the circuit-relay server? An explicit
+     * `network.enableRelay` wins; otherwise storage-profile nodes default to on
+     * (better connectivity/uptime). Shared by {@link buildControlNodeOptions}
+     * (which configures the server from it) and
+     * {@link admitInboundControlConnection} (whose deny/admit-for-relay branch
+     * must agree with whether a reservation is even servable here).
+     */
+    private relayServerEnabled;
     /**
      * Decide whether an inbound CONTROL-network connection from `remotePeerId`
      * should be admitted — the policy behind the connection gater wired in
@@ -491,7 +601,7 @@ export declare class CadreNode implements SAppIdLookup {
      * `membership-connection-gater.ts` for the layer's rationale and the
      * stranger-open protocol allowlist).
      *
-     * Admits when ANY of:
+     * Returns `'admit'` when ANY of:
      *  1. a shared-baseline check admits ({@link admitControlPeerUnconditionally}
      *     — not running / DB torn down, absent-or-empty trusted-owner anchor, or
      *     configured bootstrap/relay infrastructure);
@@ -528,17 +638,69 @@ export declare class CadreNode implements SAppIdLookup {
      *    this node yet is denied even though the formation handler would have
      *    accepted it, exactly like the unreplicated-membership-row case below.
      *
+     * When every check falls through, the verdict depends on whether this node
+     * runs the circuit-relay server ({@link relayServerEnabled}): without one,
+     * `'deny'`; with one, `'admit-for-relay'` — a circuit-relay reservation is
+     * established by the reserving peer DIALING the relay, so a connection deny
+     * here kills the reservation, and that deny is NOT self-healing: an outbound
+     * reconcile re-dial re-establishes a data link, but no outbound dial can
+     * grant the remote peer a reservation, and a relay-only peer has no address
+     * of its own to dial back — the reservation IS its address. The gater admits
+     * such a connection, decides the reservation via
+     * {@link admitControlRelayReservation}, and drops the connection if no
+     * reservation is admitted in time (see `membership-connection-gater.ts` →
+     * "The relay-reservation seam").
+     *
      * NOTE: check 4/5 runs a control-DB read per inbound connection
      * (`listAuthorizedMembers`); connections are rare and cadres small, and this
      * layer is fail-open behind `ADMISSION_DECISION_TIMEOUT_MS`, so the live
      * read is safe here — unlike the per-stream gate, which must consult the
      * materialized {@link authorizedControlPeers} snapshot instead.
-     * NOTE: a sibling whose membership row has not yet replicated to
-     * this node is denied until the row converges (typically via the owner);
-     * either side's next outbound reconcile dial (outbound is never gated)
-     * re-establishes the link — self-healing, but visible as a transient deny.
+     * NOTE: on a relay-DISABLED node, a sibling whose membership row has not yet
+     * replicated here is denied until the row converges (typically via the
+     * owner); either side's next outbound reconcile dial (outbound is never
+     * gated) re-establishes the DATA link — self-healing for data, visible as a
+     * transient deny. That self-healing story never covered a reservation, which
+     * is exactly why the relay-enabled path above exists.
      */
     private admitInboundControlConnection;
+    /**
+     * Should `remotePeerId` be granted a circuit-relay reservation slot on this
+     * node's relay server? The policy behind the gater's
+     * `denyInboundRelayReservation` hook (see `membership-connection-gater.ts` →
+     * "The relay-reservation seam"); the circuit-relay server consults it per
+     * RESERVE request, so it is never called on a node whose relay server is off.
+     *
+     * Admits when ANY of:
+     *  1. a shared-baseline check admits ({@link admitControlPeerUnconditionally}
+     *     — not running / DB torn down, absent-or-empty trusted-owner anchor, or
+     *     configured bootstrap/relay infrastructure);
+     *  2. the peer holds a live delegate admission grant — a member's strand
+     *     node reserving here (see `delegate-admission.ts`); never counted
+     *     against the unauthorized budget;
+     *  3. the authorized-member set is empty (cold start) or the peer IS an
+     *     authorized member — members are never counted against the budget; or
+     *  4. the peer takes (or already holds) a slot in the bounded
+     *     unauthorized-reservation budget — the boot-ordering window where a
+     *     genuine member reserves before its `CadrePeer` row replicates here.
+     *     Cap via `network.unauthorizedRelayReservationCap` (0 = refuse every
+     *     unauthorized reservation).
+     *
+     * Every uncounted admission also RELEASES the budget slot the peer may hold
+     * from an earlier reservation taken while it was still unplaceable — a member
+     * that boots, reserves, and only then has its row replicate here would
+     * otherwise keep that slot spent for the rest of the entry's TTL.
+     *
+     * The connection gate's stranger carve-outs (an open enrollment window, an
+     * outstanding formation invitation) deliberately do NOT extend here: they
+     * exist so a stranger's SEED or FORMATION stream can ride a connection, and
+     * neither needs relay capacity. A genuine invitee that does need a relay slot
+     * takes one from the budget like any other unplaced peer, so an open window
+     * never becomes an unbounded grant of this node's forwarding capacity.
+     */
+    private admitControlRelayReservation;
+    /** Admit a reservation on the peer's own merits, giving back any budget slot it still holds. */
+    private admitReservationUncounted;
     /**
      * Hold the control-network inbound gate open for not-yet-authorized peers
      * until `untilEpochMs` (extends, never shrinks, an already-open window).
@@ -550,7 +712,8 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Record (or refresh) a delegate admission grant: `delegatePeerId` is the
      * transport peerId of `announcerPeerId`'s strand-`strandId` node, admitted
-     * at the CONNECTION level (all a circuit-relay reservation needs) for
+     * at the CONNECTION and RESERVATION levels (all a circuit-relay reservation
+     * needs, without spending the unauthorized-reservation budget) for
      * `DELEGATE_GRANT_TTL_MS`. Called by the strand-addr responder after its
      * authorized-membership gate has passed; public so tests can drive the
      * admission policy without a full strand launch. A re-announce for the same
@@ -628,6 +791,12 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * The SOLE caller is {@link drainMembershipGate}, which serializes refreshes —
      * so two reads can no longer settle out of order.
+     *
+     * Reads WITHOUT the transient-failure retry, deliberately: `ControlDatabase` drives
+     * this listener with its write lock HELD (`notifyMembershipChanged`), so a retrying
+     * read here would sleep its backoff holding the lock and stall every other local
+     * writer. Nothing is lost — this refresh already keeps the previous snapshot on
+     * failure and is re-driven by the next membership write and by the timed reconcile.
      */
     private refreshAuthorizedControlPeers;
     /**
@@ -738,8 +907,44 @@ export declare class CadreNode implements SAppIdLookup {
      * Survivors are returned signaling (`/p2p-circuit`) first, filtered to
      * signaling-only when requested, as parsed `Multiaddr`s (unparsable addrs
      * dropped). Any gate failure yields an empty array rather than throwing.
+     *
+     * Every returned address is normalized to terminate in `/p2p/<peerId>` — see
+     * {@link normalizeDialAddrs} for why that invariant, not each dial site's own
+     * handling, is what keeps a mixed list from taking a whole peer offline.
      */
     resolvePeerAddrs(peerId: string, opts?: ResolveOpts): Promise<Multiaddr[]>;
+    /**
+     * Guarantee every address handed to a control-network dial terminates in
+     * `/p2p/<peerId>`, with no duplicates — the invariant every dial path
+     * downstream relies on.
+     *
+     * `libp2p.dial(addrs)` requires that the addresses in ONE dial either all name
+     * a peer id or none do; a list mixing a circuit address (which ends in
+     * `/p2p/<target>`) with a bare direct one (which ends in `/tcp/…`) makes that
+     * call throw, and the whole peer is then silently skipped rather than one bad
+     * address.
+     *
+     * Applied by ALL THREE sources of control-dial candidates, so no call site
+     * invents its own rule and none can produce a mixed list: the signed record
+     * ({@link resolvePeerAddrs}), the libp2p address book
+     * ({@link peerStoreAddrs}), and a seed's retained owner addresses
+     * ({@link bootstrapDialAddrs}).
+     *
+     * An address naming a DIFFERENT trailing peer id is dropped: it does not reach
+     * `peerId`, so it does not belong in this peer's candidate list (libp2p's own
+     * dial queue filters the same shape out one layer lower).
+     */
+    private normalizeDialAddrs;
+    /**
+     * One address bound to `peerId`, or `null` when it cannot be — logged either
+     * way, never thrown, so every caller's list-shaping stays total.
+     *
+     * `withTrailingPeerId` encapsulates `/p2p/<peerId>`, which throws on a peer id
+     * that does not parse. Unreachable for a `CadrePeer` row (the binding gate
+     * above parsed it already), reachable for a seed-supplied one
+     * ({@link bootstrapDialAddrs}).
+     */
+    private bindAddrToPeer;
     /** Parse multiaddr strings, dropping (and logging) any that fail to parse. */
     private parseMultiaddrs;
     /**
@@ -759,29 +964,83 @@ export declare class CadreNode implements SAppIdLookup {
     /** Body of {@link reconcileControlCohort}; serialised by its single-flight guard. */
     private runReconcileControlCohort;
     /**
-     * Resolve one sibling's control-network dial addresses and dial it, best-effort.
-     * Returns whether a dial was attempted (false when no address resolves).
+     * Resolve every sibling's signed address record once and merge what resolves
+     * into the control node's libp2p **address book** (peerStore). Returns the
+     * resolved addresses per sibling so the dial loop reuses them rather than
+     * re-resolving — one `queryPeerRecord` per sibling per pass, not two.
+     *
+     * Deliberately every sibling, not the {@link selectControlCohortDials} subset,
+     * and deliberately including already-connected ones: everything below
+     * cadre-core dials by bare peer id (Optimystic's cluster/repo clients, FRET
+     * ping/announce), so the address book has to be warm BEFORE a live connection
+     * drops, and a sibling the out-degree cap declines to dial is still one those
+     * layers may need to reach.
+     *
+     * Only `resolvePeerAddrs` output is merged — never the cold-start
+     * `peerStoreAddrs` fallback, which came out of the address book to begin with
+     * and would restamp unverified seed addresses indefinitely. A sibling that
+     * resolves to nothing (revoked, stale, untrusted) is not written at all, so its
+     * existing entry ages out on its own.
+     *
+     * NOTE: this resolves EVERY sibling serially before the dial loop below runs,
+     * so it costs one record query per sibling per reconcile pass (~15s) and each
+     * one delays the pass's first dial. A cadre is a handful of devices, so today
+     * that is a few extra local reads; if cadres ever grow large, batch the records
+     * into one query, merge only on change, or move the warm pass after the dials.
+     */
+    private warmSiblingAddrBook;
+    /**
+     * {@link resolvePeerAddrs} for one sibling, best-effort: a control-DB read
+     * failure yields `[]` (and the cold-start fallback then gets its turn) rather
+     * than aborting the whole pass, like every other step here.
+     */
+    private resolveSiblingAddrs;
+    /**
+     * Budget for ONE proactive dial of the reconcile pass — steady-state sibling
+     * ({@link dialControlSibling}) and cold-start bootstrap peer
+     * ({@link dialBootstrapPeer}) alike, since both feed a whole address list to
+     * one `dial()` and both run in a sequential loop that the next entry waits on.
+     *
+     * See {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} for why the pass bounds
+     * this itself rather than inheriting each address's libp2p attempt timeout.
+     */
+    private controlDialTimeoutMs;
+    /**
+     * Dial one sibling from its already-resolved addresses, best-effort. Returns
+     * whether a dial was attempted (false when no address resolves).
      *
-     * A per-peer failure (NAT, offline, relay down, connection-gater denial) is
-     * logged and swallowed so one unreachable sibling never aborts the pass —
-     * exactly like {@link SeedBootstrapService.applySeed}'s owner-dial loop. A
-     * failed dial is simply retried on the next pass.
+     * A per-peer failure (NAT, offline, relay down, connection-gater denial, or
+     * the {@link controlDialTimeoutMs} budget expiring) is logged and swallowed so
+     * one unreachable sibling never aborts the pass — exactly like
+     * {@link SeedBootstrapService.applySeed}'s owner-dial loop. A failed dial is
+     * simply retried on the next pass.
      */
     private dialControlSibling;
     /**
-     * Resolve a sibling's control-network dial addresses for the reconcile pass.
+     * A sibling's control-network dial addresses for the reconcile pass.
      *
-     * Primary (steady state): the signed, fresh, trust-gated control addresses from
-     * the converged `CadrePeer` record via {@link resolvePeerAddrs}. Fallback (cold
-     * start): the libp2p peerStore entries `applySeed` populated, used only while the
-     * record is not yet resolvable. Returns `[]` (never throws) when neither yields
-     * an address — that sibling is skipped this pass.
+     * Primary (steady state): the signed, fresh, trust-gated control addresses
+     * `resolved` for it by {@link warmSiblingAddrBook} — passed in rather than
+     * re-resolved, so the pass makes one record query per sibling. Fallback (cold
+     * start): the libp2p peerStore entries `applySeed` populated, used only while
+     * the record is not yet resolvable. Returns `[]` (never throws) when neither
+     * yields an address — that sibling is skipped this pass.
      */
     private resolveControlDialAddrs;
     /**
      * Cold-start fallback: the libp2p peerStore multiaddrs for `peerId` (seeded by
      * {@link SeedBootstrapService.applySeed}). Returns `[]` on a missing entry or any
      * parse/lookup failure — never throws.
+     *
+     * Normalized through {@link normalizeDialAddrs} for the same reason
+     * {@link resolvePeerAddrs} is, and with more cause: the address book hands back
+     * a list that is inherently MIXED. `@libp2p/peer-store`'s
+     * `dedupeFilterAndSortAddresses` strips a trailing `/p2p/<peerId>` only when
+     * that id is the address's FIRST `/p2p/` component, so a direct address
+     * round-trips bare while a relayed one — whose first `/p2p/` names the relay —
+     * keeps its suffix (the same asymmetry `peer-addr-book.ts`'s `addrKey` exists
+     * to absorb). Feeding both to one `dial()` is exactly the
+     * `InvalidParametersError` that skipped the whole peer.
      */
     private peerStoreAddrs;
     /**
@@ -834,11 +1093,12 @@ export declare class CadreNode implements SAppIdLookup {
      * Bind a bootstrap peer's seed addresses to its peer id, so the dial
      * authenticates the peer it is aiming at rather than trusting whoever answers.
      *
-     * An address that already carries `/p2p/<id>` must carry THIS peer's id or it
-     * is dropped (a seed that disagrees with itself is not a dial target); one
-     * that carries none — an `addressOverrides`-published record, say — gets the
-     * id encapsulated. Unencapsulatable addresses are dropped rather than dialed
-     * bare.
+     * The same {@link normalizeDialAddrs} rule the resolved and address-book paths
+     * use, on the third and last source of control-dial candidates: an address that
+     * already terminates in `/p2p/<id>` must carry THIS peer's id or it is dropped
+     * (a seed that disagrees with itself is not a dial target); one that does not —
+     * a bare listen addr, or a relay hop with the destination missing — gets the id
+     * encapsulated; an unencapsulatable one is dropped rather than dialed bare.
      */
     private bootstrapDialAddrs;
     /** Dial one cold-start bootstrap peer, best-effort. Returns whether it connected. */
@@ -1087,6 +1347,12 @@ export declare class CadreNode implements SAppIdLookup {
     expireDeviceToken(peerId: string): Promise<void>;
     private handleStrandAdded;
     private handleStrandRemoved;
+    /**
+     * Return this node to its pre-{@link start} state. The ONE teardown — `stop()` and
+     * a failed `start()` both come here, so anything a stopped node must not still be
+     * doing belongs in this method and not in `stop()`. `stop()` adds only the
+     * `control:disconnected` emit, which a never-connected start has no edge for.
+     */
     private cleanup;
     private handleStrandIdle;
     /**
@@ -1099,7 +1365,7 @@ export declare class CadreNode implements SAppIdLookup {
     private handleStrandHibernate;
     /**
      * Wake a strand. If it was hibernating (quiesced — no libp2p node), re-resolve
-     * the cohort discovery seed and mode exactly as `launchStrand` does and rebuild
+     * the cohort discovery seed exactly as `launchStrand` does and rebuild
      * its runtime via the strand manager. If it is still live (e.g. waking an idle
      * strand, which retains its resources), just flip the status. Overlapping wake
      * triggers are coalesced upstream by `HibernationManager`, so this runs once
@@ -1107,11 +1373,10 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private handleStrandWake;
     /**
-     * Rebuild a quiesced strand's runtime, re-resolving the volatile cohort inputs
-     * first: the discovery seed may have grown and cohort membership may have
-     * shifted the mode `bootstrap → networked` since the strand last ran. Shared by
+     * Rebuild a quiesced strand's runtime, re-resolving the volatile cohort input
+     * first: the discovery seed may have grown since the strand last ran. Shared by
      * the wake (`handleStrandWake`) and check-in (`handleStrandCheckIn`) paths so
-     * both apply the same fresh seed/mode resolution. `resumeStrand` is idempotent
+     * both apply the same fresh seed resolution. `resumeStrand` is idempotent
      * (returns the live instance unchanged) as a backstop against double-resume.
      */
     private resumeStrandRuntime;
@@ -1124,7 +1389,7 @@ export declare class CadreNode implements SAppIdLookup {
      * realized as a resume → bounded window → re-hibernate-if-idle cycle that
      * reuses the existing quiesce/resume primitives rather than a bespoke probe:
      *
-     *   1. Resume the strand (rebuild node + db, re-resolve cohort seed/mode) so
+     *   1. Resume the strand (rebuild node + db, re-resolve the cohort seed) so
      *      its strand network can reach cohort peers — exactly as a wake does.
      *   2. Hold it resumed for a bounded window, during which the app may drive
      *      reads (pull-on-read) and record activity.
@@ -1356,8 +1621,8 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Shared strand launch path for both the explicit (`addStrand`) and the
      * control-discovered (`handleStrandAdded`) entry points. Resolves the cohort
-     * seed, selects the mode, starts the strand, and registers it with the
-     * hibernation manager before emitting `strand:started`.
+     * seed, starts the strand, and registers it with the hibernation manager
+     * before emitting `strand:started`.
      *
      * Idempotent no-op when the strand manager already tracks `strand.Id` — the
      * ordinary founding sequence is `addStrand` (starts it locally) followed by
@@ -1370,18 +1635,19 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private launchStrand;
     /**
-     * Resolve a strand's discovery seed. Membership (and thus mode) comes from the
-     * control network's CadrePeer rows; the **strand-network** bootstrap addresses
-     * are resolved on demand over the control mesh via the strand-addr RPC —
-     * deliberately NOT from `CadrePeer.Multiaddr`, which carries *control*
-     * addresses that must not seed the strand mesh.
+     * Resolve a strand's discovery seed — the dialable strand-network multiaddr
+     * strings for cohort siblings. Membership comes from the control network's
+     * CadrePeer rows; the **strand-network** bootstrap addresses are resolved on
+     * demand over the control mesh via the strand-addr RPC — deliberately NOT
+     * from `CadrePeer.Multiaddr`, which carries *control* addresses that must not
+     * seed the strand mesh.
      *
      * Only siblings we already hold an open control connection to are RPC'd: they
      * are the ones that can answer right now, and dialing them by peerId reuses the
      * live connection. When no connected sibling yet runs the strand the seed is
-     * empty (`[]`) — mode still follows membership, and the empty seed self-heals
-     * on the next resume / check-in pass. Returns an empty seed when the control DB
-     * or node is absent (not yet started / torn down).
+     * empty (`[]`) — the empty seed self-heals on the next resume / check-in pass.
+     * Returns an empty seed when the control DB or node is absent (not yet
+     * started / torn down).
      *
      * When `delegatePeerId` is given (a strand launch/resume is imminent), the
      * pass doubles as the delegate ANNOUNCEMENT: our circuit relays are merged
@@ -1395,13 +1661,58 @@ export declare class CadreNode implements SAppIdLookup {
      * for a relay we are not yet connected to.
      */
     private resolveCohortSeed;
+    /**
+     * The co-cadre siblings worth sending a strand-addr RPC to right now: cohort
+     * members (self excluded) we already hold an open control connection to. They
+     * are the ones that can answer immediately, and dialing them by peerId reuses
+     * the live connection instead of opening a second one.
+     *
+     * Shared by {@link resolveCohortSeed} (launch/resume) and
+     * {@link refreshStrandPeerAddrs} (the periodic pass) so both ask the same set.
+     * Empty when the control DB or node is absent (not yet started / torn down).
+     *
+     * The read below is issued even when the node holds no control connection and
+     * the answer is therefore empty by construction. That is deliberate on the
+     * launch path: `control-database-solo-warm-start.spec.ts` exists to prove this
+     * exact read does not stall as an embedder's FIRST awaited control operation,
+     * on a warm cohort no one can reach. A caller that re-enters often enough for
+     * the read to matter should skip the call itself, as
+     * {@link refreshStrandPeerAddrs} does.
+     *
+     * NOTE: this read is UNBOUNDED and sits on the critical path an embedding app
+     * awaits during startup — `addStrand` cannot resolve until it does, and it is
+     * the first control operation an embedder's boot order issues (before genesis,
+     * before seed bootstrap). Measured fine today: the warm-start-alone shape a
+     * report pointed at — a `CadrePeer` list naming peers that are all gone, read
+     * off real files after a restart — completes in milliseconds, and
+     * `control-database-solo-warm-start.spec.ts` covers it under a deadline. If a
+     * control read ever CAN stall (a transactor change that consults the network
+     * for a local row, a storage backend with blocking I/O), give this one a
+     * timeout — and decide then whether the breach fails `addStrand` or degrades
+     * to an empty seed, because those promise callers different things.
+     */
+    private connectedSiblingTargets;
     /**
      * The circuit relays this node's strand nodes would reserve through: the
-     * union of the RESOLVED listen addrs' circuits — a hand-written
-     * `network.listenAddrs` circuit entry or a `network.relayAddrs` entry, which
-     * the strand node inherits verbatim either way — and the control node's own
-     * live `/p2p-circuit` multiaddrs (a reservation this node discovered rather
-     * than configured).
+     * union of CONFIGURED relays — `network.relayAddrs`, plus any hand-written
+     * `network.listenAddrs` circuit entry, both of which a strand node inherits
+     * verbatim — and the control node's own live `/p2p-circuit` multiaddrs (a
+     * reservation this node discovered rather than configured).
+     *
+     * The CONFIGURED half reads `network.relayAddrs` and `network.listenAddrs`
+     * directly rather than going through {@link resolveListenAddrs}: the control
+     * node's resolution takes the `'search'` route, whose bare `/p2p-circuit` entry
+     * names no relay, so a configured relay would be unannounceable here until this
+     * node's own reservation landed — and the announce must be in place BEFORE a
+     * strand node dials its reservation, since the relay's membership gate does not
+     * know the strand's derived peerId (see delegate-admission.ts). Configuration is
+     * authoritative; the live multiaddrs only ADD relays nobody configured.
+     *
+     * The `listenAddrs` half is now unreachable on a control node — `relay-addrs.ts`
+     * rejects a hand-written `<relay>/p2p-circuit` listen entry outright, because the
+     * bring-up quiet period denies the dial that listener makes from inside
+     * `libp2p.start()`. Kept because it costs one spread and this is the one place
+     * that would silently stop announcing if that rejection is ever relaxed.
      *
      * NOTE: a relay the STRAND node discovers on its own (autorelay — in neither
      * source) gets no announcement, and a membership-gated one will deny it; fine
@@ -1437,6 +1748,57 @@ export declare class CadreNode implements SAppIdLookup {
     private refreshDelegateGrants;
     /** One strand's share of {@link refreshDelegateGrants}: announce to the relays whose grant is due. */
     private announceDelegateToDueRelays;
+    /**
+     * Re-resolve each running strand's SIBLING addresses over the control mesh and
+     * merge them into that strand's own libp2p address book, throttled to once per
+     * {@link STRAND_PEER_ADDR_REFRESH_MS} per strand.
+     *
+     * Without this, a strand's address book is written exactly once — the
+     * launch/resume seed — and everything below cadre-core that dials a strand peer
+     * by bare peer id (Optimystic's cluster and repo clients, FRET ping/announce)
+     * loses its address for any sibling it is not currently connected to: a sibling
+     * that restarted its strand node or rotated its relay reservation is never
+     * re-resolved, and even the original seed addresses fall off at the peerStore's
+     * one-hour expiry (see `peer-addr-book.ts`).
+     *
+     * Distinct from {@link refreshDelegateGrants}, deliberately: that pass covers
+     * RELAYS on a `DELEGATE_GRANT_TTL_MS / 2` throttle to keep circuit-relay
+     * admission grants alive, this one covers SIBLINGS on an address-expiry
+     * throttle to keep the address book warm. They overlap only in that both carry
+     * `delegatePeerId`, so a sibling that also runs a relay gets its grant
+     * refreshed here as a side effect. Merging them would tie an admission-grant
+     * TTL to an address-expiry window that has nothing to do with it.
+     *
+     * Strands refresh CONCURRENTLY, like `refreshDelegateGrants`, so one
+     * unreachable sibling's dial timeout does not stack up per strand.
+     */
+    private refreshStrandPeerAddrs;
+    /**
+     * One strand's share of {@link refreshStrandPeerAddrs}: RPC the siblings, then
+     * merge their answers into this strand's address book. Errors are logged and
+     * swallowed so one strand's failure never costs the others their refresh.
+     */
+    private refreshOneStrandPeerAddrs;
+    /**
+     * Merge strand-network addresses into ONE strand node's libp2p address book,
+     * attributed per peer. Best-effort throughout: an address-book write must never
+     * fail a launch, a resume, or a reconcile pass.
+     *
+     * `addrs` is the peer-agnostic union the strand-addr RPC returns, so
+     * {@link groupAddrsByPeerId} attributes each entry to the **strand transport**
+     * peerId in its final `/p2p/` component — never the sibling's control peerId,
+     * which names a different libp2p node entirely. Entries that name no peer are
+     * dropped there and counted here, once per pass.
+     *
+     * NOTE: a member could answer with arbitrary multiaddrs bound to arbitrary peer
+     * ids and poison this address book. That is the same exposure the launch-time
+     * `bootstrapNodes` seeding already accepts, and the cost is bounded: an address
+     * grants no authority, the dialed peer authenticates by peer id at the
+     * handshake, and a bad entry costs one failed dial that ages out at the
+     * peerStore's one-hour expiry. No new gating here — cross-party strand trust is
+     * `backlog/strand-network-nat-relay-reachability`.
+     */
+    private mergeStrandPeerAddrs;
     /**
      * The local strand instance's dialable strand-network multiaddrs for the
      * strand-addr RPC, ordered signaling-first (reusing the control node's
@@ -1544,16 +1906,48 @@ export declare class CadreNode implements SAppIdLookup {
      * Get the control network node (for advanced use)
      */
     getControlNode(): Libp2p | null;
+    /**
+     * The boot-path half of {@link reserveRelays}: reserve through every
+     * `network.relayAddrs` entry, or fail `start()`.
+     *
+     * WHY IT RUNS HERE, AT THE END. `network.relayAddrs` used to resolve to a
+     * CONFIGURED circuit listener, which libp2p dials from inside `libp2p.start()`
+     * — so the relay was already a connected peer, and therefore already in this
+     * node's Optimystic cohort, before `ControlDatabase.initialize()` ran. Building
+     * that database is a long chain of cohort-consulting block probes (catalog
+     * hydration, then one per table, then the indexes), and a sibling that has not
+     * yet replicated this node's `CadrePeer` row correctly refuses every one of
+     * them, so bring-up died on `BlockUnavailableError` — deterministically, on
+     * every boot of a relay-only node. Retrying could not converge either: the
+     * condition that clears the refusal is this node's own row reaching the
+     * sibling, and writing that row needs the database the retry is building.
+     *
+     * So the invariant is ordering, not retrying: the control database is built
+     * while this node holds ZERO control connections (a cohort of one, entirely
+     * local), and only then does it reach out. Everything above in {@link start}
+     * has completed by the time this runs.
+     *
+     * BUDGET: the supervisor's first attempt — `relay-reservation.ts`'s
+     * `DEFAULT_RELAY_RESERVE_TIMEOUT_MS`, 10 s — is what `start()` waits on — deliberately the module default rather
+     * than a boot-specific one. A healthy dial-plus-reserve is sub-second even over
+     * a WAN, so 10 s is slack for a slow link; going much longer would make a dead
+     * relay indistinguishable from a hung start, and much shorter would fail nodes
+     * on links that were merely slow. The retries carry on in the background after
+     * this resolves, exactly as they do for a {@link reserveRelays} caller.
+     */
+    private driveControlRelayReservation;
     /**
      * Start keeping a relay reservation: dial the given relay(s) from the control
      * node, ask the first one that answers for a reservation slot, wait until the
      * resulting `/p2p-circuit` address makes this node dialable — and keep a
      * supervisor running that re-drives whenever the reservation is later lost.
      *
-     * For nodes that listen on the bare `/p2p-circuit` SEARCH addr (a browser tab)
-     * rather than a configured `network.relayAddrs` circuit listener — see
-     * `relay-reservation.ts` for why the two are alternatives and why configuring
-     * both is a regression. Opt-in: nothing calls this for the CLI/host nodes.
+     * The FAIL-SOFT entry point, for a caller that discovers its relay at runtime
+     * (a browser tab, a host UI). A node that names `network.relayAddrs` gets the
+     * same drive from {@link driveControlRelayReservation} at the end of
+     * {@link start}, which is fail-fast instead. Both fill the pending reservation
+     * the bare `/p2p-circuit` search listener registered; calling this afterwards
+     * simply replaces the supervisor with one over the new list.
      *
      * Resolves once the FIRST attempt has settled, exactly as it did when it drove
      * once; the retries continue in the background until {@link stop} or the next
@@ -1615,13 +2009,40 @@ export declare class CadreNode implements SAppIdLookup {
      * Push the multiaddrs that future invites should advertise. Pass `null` to
      * revert to the libp2p-reported addresses (the default). The host calls this
      * at spawn and on every NAT change.
+     *
+     * Entries need NOT carry a `/p2p/<peerId>` suffix — {@link resolveInviteAddresses}
+     * appends this node's own before anything publishes or dials them (see
+     * {@link normalizeSelfAddrs}). Passing them suffixed is equally fine.
      */
     setInviteAddresses(addresses: string[] | null): void;
     /**
      * Resolve the addresses to embed in invites. Prefers pushed addresses, then
-     * any config-supplied resolver, then the libp2p-observed multiaddrs.
+     * any config-supplied resolver, then the libp2p-observed multiaddrs. The two
+     * app-supplied sources are normalized onto `/p2p/<self>` (see
+     * {@link normalizeSelfAddrs}) so neither hook has to remember the suffix;
+     * libp2p's own addresses already carry it.
      */
     private resolveInviteAddresses;
+    /**
+     * Normalize addresses an app handed us for THIS node onto `/p2p/<self>`, the
+     * same invariant {@link normalizeDialAddrs} enforces on the way out.
+     *
+     * `setInviteAddresses` (the admin API `PUT /admin/invite-addresses`) and
+     * `network.inviteAddressResolver` both take arbitrary strings, and whatever
+     * they return ends up in this node's published `CadrePeer` record — so ONE
+     * unsuffixed entry from either hook is enough to give every sibling in the
+     * party a mixed candidate list for this peer. Establishing the suffix here,
+     * where those strings enter the system, means neither hook has to know the
+     * rule; `cadre-host`'s `buildInviteAddresses` already appends it, and
+     * re-normalizing an already-suffixed address is a no-op.
+     *
+     * Unparsable and other-peer-addressed entries are passed through untouched
+     * rather than dropped: publication is not the place to police an address's
+     * validity, and {@link resolvePeerAddrs} already drops both on the read side.
+     * Before `start()` resolves an identity there is no peer id to append, so the
+     * list is returned as given.
+     */
+    private normalizeSelfAddrs;
     /**
      * Enumerate the cadre's `CadrePeer` membership — the ADDRESSABLE surface (see
      * {@link isMember}). Rows whose stamp is retired in `CadreControl.Revocation`
@@ -1678,8 +2099,13 @@ export declare class CadreNode implements SAppIdLookup {
      * legit member goes un-authorized on readers that only pin the new key. Full
      * rotation handling (re-vouch on rotate) is the
      * `flip-strand-membership-rotation-known-gap` work, not this predicate's.
+     *
+     * @param retry - Whether the underlying membership read may retry a transient cluster
+     *   failure. Only {@link refreshAuthorizedControlPeers} passes `false`, because it runs
+     *   as the control database's membership listener with that database's write lock held;
+     *   see its comment.
      */
-    listAuthorizedMembers(): Promise<Array<{
+    listAuthorizedMembers(retry?: boolean): Promise<Array<{
         peerId: string;
         multiaddr: string | null;
     }>>;