@serfab/cadre-core 0.10.0 → 0.11.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
@@ -176,6 +196,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 +503,25 @@ 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;
     /**
      * Map this node's config onto the control network's libp2p node options.
      *
@@ -759,23 +808,67 @@ 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.
      *
-     * 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.
+     * 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, 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;
     /**
@@ -1099,7 +1192,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 +1200,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 +1216,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 +1448,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 +1462,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,6 +1488,37 @@ 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
@@ -1437,6 +1561,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