@serfab/cadre-core 1.8.0 → 1.10.0

package/dist/cadre-node.d.ts

@@ -1,10 +1,10 @@
 import type { Libp2p, PeerId } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
-import type { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStrandConfig, FoundStrandResult, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, OpenInvitation, FormStrandResult, StrandFormationDisclosure, StrandMembershipInvite, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, ResolveDeviceTokenOpts } from './types.js';
+import type { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStrandConfig, FoundStrandResult, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, OpenInvitation, FormStrandResult, StrandFormationDisclosure, StrandMembershipInvite, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, ResolveDeviceTokenOpts, PendingJoinStatus } from './types.js';
 import { type Ed25519KeyPair } from './ed25519-key.js';
 import { type TrustedOwnerStore, type TrustSource } from './trusted-owner-store.js';
 import { type BootstrapPeerStore } from './bootstrap-peer-store.js';
-import { type StrandPeerBookStore } from './strand-peer-book.js';
+import { type StrandNetworkStateStore } from './strand-network-state.js';
 import { type EnrolledMachineStore } from './enrolled-machine-store.js';
 import { type SAppIdLookup } from './strand-watcher.js';
 import { type ControlCohortReconcileResult } from './control-cohort.js';
@@ -84,6 +84,15 @@ export declare class CadreNode implements SAppIdLookup {
     private enrollmentService;
     private seedBootstrapService;
     private strandSolicitationService;
+    /**
+     * The service whose formation handler is registered on the control node. Trails
+     * {@link strandSolicitationService} while {@link initializeStrandSolicitation} swaps a new
+     * one in: the field is set at once so concurrent callers reuse it, the handler only when
+     * its queued swap runs.
+     */
+    private registeredSolicitation;
+    /** Tail of the queued formation-handler swaps ({@link swapFormationResponder}). */
+    private solicitationSwaps;
     private strandWakeService;
     /**
      * Control-network strand-address responder. Answers a co-cadre sibling's
@@ -304,36 +313,54 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private readonly strandAddrAskDueAt;
     /**
-     * Node-local strand peer book (see `strand-peer-book.ts`): per strand, the strand
-     * peers this node has met and their last-known strand-network addresses. Three
-     * writers: {@link recordFormationStrandPeers} files the responder's live strand
-     * addrs a formation result carried back (`FormationResultMessage.strandAddrs`),
-     * {@link observeStrandPeer} files every strand peer a running strand node
-     * identifies, and the per-strand book swap (`strand-peer-book-swap.ts`, handed the
-     * store as `StartStrandConfig.strandPeerBook`) files the node's own signed entry
-     * plus every signed entry a strand peer sends it — the only writer whose entries
-     * carry a signature, and the only one that can refresh a peer's addresses without
-     * meeting that peer. Read by {@link resolveCohortSeed} (launch + hibernation resume) and
-     * re-merged by every {@link refreshStrandPeerAddrs} pass, which is what keeps the
-     * entries alive past the peerStore's one-hour address expiry.
-     *
-     * This is the ONLY cross-party discovery input there is. The strand-addr RPC that
+     * The strand-network addresses a formation carried back
+     * (`FormationResultMessage.strandAddrs`), by strand id: the responder's live strand
+     * node addresses, kept so the strand's first attach has something to dial. Written by
+     * {@link recordFormationStrandAddrs}, read by {@link resolveCohortSeed} (launch and
+     * hibernation resume) and by every refresh pass for the peers the strand node's FRET
+     * table holds no record for yet ({@link remergeUnrecordedFormationAddrs}).
+     *
+     * This is the only cross-party input a FIRST attach has. The strand-addr RPC that
      * resolves a strand's addresses is membership-gated and answers own-party siblings
-     * only, so without the book a joiner's cohort seed for a two-party strand is empty
-     * and the mesh never forms — and, with an in-memory book, never RE-forms after a
-     * restart (gotchoices/sereus#18). A STORE rather than a map so an embedder can make
-     * it outlive the process; constructed (or adopted from `config.strandPeers.store`)
-     * by {@link initializeStrandPeerBookStore} during {@link start}, deliberately NOT
+     * only, so without it a joiner's seed for a two-party strand is empty and the mesh
+     * never forms. Every later launch has the strand node's saved network state as well
+     * ({@link strandNetworkStateStore}), which is what a restart re-finds the other party
+     * from (gotchoices/sereus#18).
+     *
+     * A re-formation replaces the strand's list. An entry survives a {@link stopStrand}
+     * and a stop()→start() of this node instance ({@link cleanup} leaves the map alone),
+     * and is dropped where the saved network state is: {@link unpublishStrand},
+     * {@link forgetJoinedStrand} and self-revocation.
+     *
+     * NOTE: accepted tradeoff — in memory only, so a process restart between `formStrand`
+     * and the strand's first launch loses the carried addresses, and the strand then
+     * launches with no cross-party seed until it is re-formed. Persisting the list on the
+     * joined-strand record was weighed and declined: it mixes address state into the join
+     * record, and needs an "only until the first run" rule to stop dead addresses being
+     * dialled on every launch. Every embedder launches straight after forming, and once
+     * the strand has run the saved network state covers every later restart. Revisit if an
+     * embedder forms and launches in separate sessions.
+     */
+    private readonly formationStrandAddrs;
+    /**
+     * Node-local strand network state (see `strand-network-state.ts`): per strand, the
+     * state db-p2p saves for the strand's libp2p node — its FRET routing table with each
+     * peer's signed address record. Handed to every strand launch as
+     * `StartStrandConfig.networkState`; the strand node saves into it on every connection
+     * and re-imports it when it is next built, which is what gives a restarted strand
+     * node addresses for the peers it was talking to.
+     *
+     * Constructed (or adopted from `config.strandNetworkState.store`) by
+     * {@link initializeStrandNetworkStateStore} during {@link start}, deliberately NOT
      * cleared by {@link cleanup}, so it survives a stop()→start() cycle of the same node
      * instance — same lifecycle as {@link bootstrapPeerStore}.
      *
-     * Entries survive a {@link stopStrand} (a stopped strand may be claimed again with
-     * {@link addStrand}, and is rediscovered on restart) and are forgotten by
-     * {@link unpublishStrand}, {@link forgetJoinedStrand} and self-revocation; the store
-     * ages the rest out after 14 days and caps each strand at 16 peers, so the book is
-     * bounded by time and by the strands this node runs rather than by its history.
+     * A strand's state survives a {@link stopStrand} and a hibernation quiesce, and is
+     * forgotten by {@link unpublishStrand}, {@link forgetJoinedStrand} and
+     * self-revocation. A strand detached because the watcher saw its row gone keeps its
+     * state (`NOTE:` on `PersistentStrandNetworkStateStore`).
      */
-    private strandPeerBookStore;
+    private strandNetworkStateStore;
     /**
      * PENDING strand membership invitations learned at formation, keyed by strandId — the
      * single-use `Strand.Invite` credential a closed-strand formation result carried back
@@ -361,9 +388,23 @@ export declare class CadreNode implements SAppIdLookup {
      * NOTE: entries live for the node's lifetime (one small pair per formed closed
      * strand); the number of keys is bounded only by the strands this node has ever
      * formed, not by time — if a node ever forms strands at scale, evict on
-     * `unpublishStrand` / `forgetJoinedStrand` as the strand peer book does.
+     * `unpublishStrand` / `forgetJoinedStrand` as {@link formationStrandAddrs} is.
      */
     private readonly pendingMembershipInvites;
+    /**
+     * Invite keys of the membership invitations this process has staged, by
+     * {@link adoptFormationMembershipInvite} or from a `joined` `PendingJoin` row
+     * ({@link stageMembershipInvitesFromPendingJoins}), so one the reconciler has settled is not
+     * staged again by the next pending-join pass. Same lifetime as
+     * {@link pendingMembershipInvites}: a restarted process stages each live one once more, and the
+     * reconciler settles it again (spent, or the party already seated).
+     */
+    private readonly stagedMembershipInviteKeys;
+    /**
+     * The pending-join retry loop (`pending-join-runner.ts`): built by {@link start}, stopped by
+     * {@link cleanup}. It acts only while this machine is an enrolled owner.
+     */
+    private pendingJoinRunner;
     /**
      * Founder launches refused because the strand was founded before the per-party
      * identity split (`PreSplitStrandIdentityError`), keyed by strandId. Read by
@@ -767,15 +808,15 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private initializeJoinedStrandStore;
     /**
-     * Construct (or adopt) the node-local strand peer book (see
-     * {@link strandPeerBookStore}). Synchronous for the reason
+     * Construct (or adopt) the node-local strand network state (see
+     * {@link strandNetworkStateStore}). Synchronous for the reason
      * {@link initializeBootstrapPeerStore} is: an injected store has already loaded its
      * persisted entries by the time it is handed in, and the in-memory fallback has
      * nothing to load. The instance is kept across stop()→start(). A store scoped to a
-     * different party is a configuration error, fail closed: another party's strand
-     * peers must never enter this node's dial loop.
+     * different party is a configuration error, fail closed: another party's routing
+     * tables must never be imported into this node's strands.
      */
-    private initializeStrandPeerBookStore;
+    private initializeStrandNetworkStateStore;
     /**
      * The node-local enrolled-machine store (null before {@link start}) — what this
      * node last knew about its party's size. Exposed for diagnostics and for a host
@@ -790,12 +831,12 @@ export declare class CadreNode implements SAppIdLookup {
      */
     getBootstrapPeerStore(): BootstrapPeerStore | null;
     /**
-     * The node-local strand peer book (null before {@link start}) — per strand, the
-     * strand peers this node dials first on launch, resume and refresh. Exposed for
-     * diagnostics and for a host that wants to show "whom would this strand re-find
-     * after a restart?".
+     * The node-local strand network state (null before {@link start}) — per strand, the
+     * state its strand node last saved and will re-import when next built. Exposed for
+     * diagnostics and for a host that wants to show "what routing table would this
+     * strand restart with?".
      */
-    getStrandPeerBookStore(): StrandPeerBookStore | null;
+    getStrandNetworkStateStore(): StrandNetworkStateStore | null;
     /**
      * The node-local trusted-owner anchor (null before {@link start}). This is
      * the set the authorized-membership predicate and seed-trust anchor consult —
@@ -948,11 +989,9 @@ export declare class CadreNode implements SAppIdLookup {
      *     `StrandSolicitationService.hasOutstandingInvitation`). A formation
      *     initiator is another party's peer by design and its token is only
      *     checkable inside the protocol, so the gate asks the coarser question
-     *     "does this node expect a stranger at all?". Merely REGISTERING the
-     *     responder ({@link initializeStrandSolicitation}) no longer suspends
-     *     stranger denial — eager registration (as `reference-app-rn` does at
-     *     bring-up) and `formStrand`'s lazy initialization both leave the gate
-     *     armed, because neither mints an invitation.
+     *     "does this node expect a stranger at all?". REGISTERING the responder
+     *     does not suspend stranger denial: every node registers one at
+     *     {@link start}, and registering mints no invitation.
      *
      * Ordering is semantically free (the checks are OR'd) but decides who pays:
      * checks 1-3 are in-memory, 4/5 share one control-DB read, and only a peer
@@ -984,6 +1023,11 @@ export declare class CadreNode implements SAppIdLookup {
      * 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: check 6 adds a second control read (`hasOutstandingFormationInvite`) for a
+     * stranger with no locally minted invitation in play, on every node now that every
+     * node runs the responder — a relay-enabled storage node included. If stranger
+     * connections to such a node ever arrive fast enough for that read to show, cache
+     * the answer for a few seconds.
      * 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
@@ -1326,6 +1370,12 @@ export declare class CadreNode implements SAppIdLookup {
      * handling, is what keeps a mixed list from taking a whole peer offline.
      */
     resolvePeerAddrs(peerId: string, opts?: ResolveOpts): Promise<Multiaddr[]>;
+    /**
+     * {@link resolvePeerAddrs} with the record's `UpdatedAt` kept beside the addresses, for a
+     * caller that ranks peers by how recently they published. `null` wherever that returns `[]`
+     * for a failed gate.
+     */
+    private resolvePeerRecord;
     /**
      * Guarantee every address handed to a control-network dial terminates in
      * `/p2p/<peerId>`, with no duplicates — the invariant every dial path
@@ -1519,15 +1569,18 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * The list may name transports this node cannot dial (a lent node reports TCP
      * and `/ws` addresses to a phone that dials WebSockets only). That needs no
-     * filtering here: libp2p's dial queue (`calculateMultiaddrs`, libp2p 3.1.3)
+     * filtering here: libp2p's dial queue (`calculateMultiaddrs`, libp2p 3.3.11)
      * rejects an address no transport can dial before touching the network, so
      * such an address costs a log line.
      *
      * The list is NOT handed to one `dial()`. libp2p tries a multi-address dial's
-     * addresses one after another under a single deadline, with no limit per
-     * address, and sorts loopback addresses last — so one or two addresses that
-     * never answer used up the whole deadline before the address that worked was
-     * tried. {@link dialPeerAddrs} dials each address on its own time limit instead.
+     * addresses one after another under a single deadline, and sorts loopback
+     * addresses last — so one or two addresses that never answer use up most of
+     * the deadline before the address that works is tried. libp2p 3.3's
+     * per-address `addressDialTimeout` does not prevent that: cadre sizes it for a
+     * cold relayed open through two admission decisions (`optimysticDialLimits`,
+     * 39 s at the default declared link).
+     * {@link dialPeerAddrs} dials each address on its own time limit instead.
      */
     private resolveControlDialAddrs;
     /**
@@ -2479,13 +2532,6 @@ export declare class CadreNode implements SAppIdLookup {
      * for a relay we are not yet connected to.
      */
     private resolveCohortSeed;
-    /**
-     * The strand peer book's contribution to a strand's seed: every live entry's
-     * addresses, freshest peer first, minus this node's own entry when `selfPeerId` is
-     * known (the book swap files one under the strand transport id; a node must never
-     * dial itself). Empty before {@link start} builds the store.
-     */
-    private strandPeerBookAddrs;
     /**
      * The own-party half of {@link resolveCohortSeed}: strand-network addresses resolved
      * from CONNECTED cohort siblings over the control-mesh strand-addr RPC, doubling as
@@ -2602,9 +2648,9 @@ export declare class CadreNode implements SAppIdLookup {
      * caller runs the drive regardless).
      *
      * NOTE: against a relay that is DOWN this hook costs up to two strand-addr
-     * timeouts (dial by peer id, then by addr; 23 s each at the default declared link round trip)
+     * timeouts (dial by peer id, then by addr; 28.5 s each at the default declared link round trip)
      * before the reservation drive even starts, so one failed re-drive holds the supervisor
-     * `driving` for those 46 s plus the drive's own deadline — 64 s at the default, and longer on
+     * `driving` for those 57 s plus the drive's own deadline — 75 s at the default, and longer on
      * a host that declared a slower one (`link-budget.ts`).
      * Bounded and harmless while the relay is unreachable anyway; if recovery
      * latency after a relay comes back ever matters, skip the announce when the
@@ -2615,18 +2661,19 @@ export declare class CadreNode implements SAppIdLookup {
     /** One strand's share of {@link refreshDelegateGrants}: announce to the relays whose grant is due. */
     private announceDelegateToDueRelays;
     /**
-     * Keep each running strand's own libp2p address book warm: re-merge its strand
-     * peer book on every pass, and re-ask each connected SIBLING for its strand
-     * addresses over the control mesh when that (sibling, strand) is due
+     * Keep each running strand's own libp2p address book warm: re-merge the address
+     * records its FRET routing table holds on every pass
+     * ({@link remergeStrandFretRecords}), and re-ask each connected SIBLING for its
+     * strand addresses over the control mesh when that (sibling, strand) is due
      * ({@link strandAddrAskDueAt}).
      *
-     * Without this, a strand's address book is written exactly once — the
+     * Without this, cadre-core writes a strand's address book 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
+     * loses its address for any peer 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`).
+     * re-resolved, and every address, another party's included, falls off at the
+     * peerStore's one-hour expiry (see `peer-addr-book.ts`).
      *
      * Due times are per (sibling, strand) and set from each sibling's own outcome, so
      * a sibling that connects late — a phone joining after the party's always-on
@@ -2670,17 +2717,59 @@ export declare class CadreNode implements SAppIdLookup {
     private strandAddrRefreshTargets;
     /**
      * One strand's share of {@link refreshStrandPeerAddrs}: RPC the siblings that are
-     * due, union their answers with this strand's peer-book addresses, and merge the
-     * lot into the strand's address book. Errors are logged and swallowed so one
-     * strand's failure never costs the others their refresh.
+     * due and merge their answers into the strand's address book, then re-merge the
+     * address records the strand node's FRET table holds. Errors are logged and
+     * swallowed so one strand's failure never costs the others their refresh.
      *
-     * The peer book merges on EVERY pass, whether or not any sibling is due or
-     * connected: nothing re-resolves another party's addresses, so this re-merge is the
-     * ONLY thing standing between them and the peerStore's one-hour expiry — and it is
-     * also how a re-formation's freshly carried addresses reach a running strand on the
-     * next tick. A strand with nobody due and no book entry does nothing.
+     * The sibling half runs first, so a failure reading the FRET table cannot cost a
+     * sibling answer its merge. The FRET half, and the formation-carried addresses of
+     * the peers it holds no record for, run on EVERY pass, whether or not any sibling is
+     * due or connected — see {@link remergeStrandFretRecords} and
+     * {@link remergeUnrecordedFormationAddrs} for why.
      */
     private refreshOneStrandPeerAddrs;
+    /**
+     * Is `strandNode` still the node `strandId` runs on? Asked again after every await
+     * in a refresh pass: a strand stopped mid-pass, or one already restarted onto a new
+     * node, must never have its store written to.
+     */
+    private isRunningStrandNode;
+    /**
+     * Re-merge, into a running strand node's address book, the addresses of every peer
+     * its FRET routing table holds a signed address record for (`strand-fret-addrs.ts`).
+     *
+     * This is what keeps ANOTHER PARTY's strand nodes dialable from a node that stays
+     * up. Nothing re-resolves their addresses — the strand-addr RPC answers own-party
+     * siblings only — and the peerStore hides an address one hour after it was first
+     * observed. FRET keeps each peer's record but hands it to the peerStore only when it
+     * arrives or is imported, so without this pass a connection to another party that
+     * drops after the first hour could not be redialed by either side.
+     *
+     * A record is held while FRET holds the peer's table entry, and at most 14 days after
+     * it was last confirmed, so that is also how long a wrong address can keep being
+     * re-merged. Each record is signed by the peer it names and verified before use, so
+     * the exposure is failed dials to an address that peer itself published.
+     *
+     * NOTE: every pass serialises the whole FRET table (`exportTable()`), verifies one
+     * signature per record and makes one `peerStore.merge` per peer, per running strand
+     * per 15 s tick. Fine at strand table sizes, and an unchanged address set writes
+     * nothing in libp2p's persistent peer store. If many strands or large tables make it
+     * show up, read only the entries whose address stamp is near the one-hour mark.
+     *
+     * @returns the ids of the peers the table holds a usable record for.
+     */
+    private remergeStrandFretRecords;
+    /**
+     * Re-merge the addresses this strand's formation carried ({@link formationStrandAddrs})
+     * for every peer the strand node's FRET table holds no record for (`recorded`).
+     *
+     * Until the first connection to the responder, the carried addresses are the only
+     * thing naming it, and the launch seed writes them once. FRET's `bootstraps` keep only
+     * the peer id, so if the responder stays unreachable past the peerStore's one-hour
+     * expiry, nothing could dial it when it returns. Once FRET holds the peer's own signed
+     * record, that record supersedes what the formation carried and this stops.
+     */
+    private remergeUnrecordedFormationAddrs;
     /**
      * RPC `due` siblings for `strandId` and set each one's next due time from its own
      * outcome: an answer, even an empty one, waits the full refresh interval; anything
@@ -2695,11 +2784,11 @@ export declare class CadreNode implements SAppIdLookup {
      * 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.
+     * `addrs` is a peer-agnostic list — the union the strand-addr RPC returns, or the
+     * addresses a formation carried — 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
@@ -2709,14 +2798,13 @@ export declare class CadreNode implements SAppIdLookup {
      * peerStore's one-hour expiry. No new gating here — cross-party strand trust is
      * `backlog/strand-network-nat-relay-reachability`.
      *
-     * NOTE: one input ages out on a slower clock — the strand peer book's entries
-     * ({@link strandPeerBookStore}). Nothing can re-resolve another party's addresses,
-     * so {@link refreshStrandPeerAddrs} re-merges the book every pass, which means a
-     * junk entry from a responder or a peer's identify survives until the book drops it
-     * (14 days unrefreshed, or the peer's next connection replacing the entry) rather
-     * than an hour. Bounded to 16 peers × 16 addrs per strand, forgotten on
-     * `unpublishStrand` / `forgetJoinedStrand`, and still authority-free — so the
-     * exposure is a handful of failed dials, not a trust hole.
+     * NOTE: one input outlives that hour — a formation's carried addresses
+     * ({@link formationStrandAddrs}) are in every launch and resume seed for as long as
+     * this process remembers the formation, and re-merged on every refresh pass until the
+     * strand node's FRET table holds the peer's own record, so a junk address from a
+     * responder that is never met keeps being re-merged. Bounded by `sanitizeStrandAddrs`,
+     * replaced by a re-formation, dropped on `unpublishStrand` / `forgetJoinedStrand`, and
+     * still authority-free — so the exposure is a handful of failed dials, not a trust hole.
      */
     private mergeStrandPeerAddrs;
     /**
@@ -2732,7 +2820,8 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Leave a strand joined from another party, for the whole party: remove its party-wide
      * `JoinedStrand` row (owner-signed, with a `Revocation` tombstone), then this machine's
-     * unpublished record, its strand peer book entries and any session-kept entry, then
+     * unpublished record, its formation-carried addresses, its saved network state and any
+     * session-kept entry, then
      * {@link stopStrand} it here. Every other machine's watcher then sees the row gone and
      * detaches the strand, a storage replica included; a machine offline at the time reaps the
      * row once the tombstone reaches it. The joiner's counterpart of {@link unpublishStrand},
@@ -2771,8 +2860,9 @@ export declare class CadreNode implements SAppIdLookup {
      * session here — the `strand:revoked` contract is that nothing is torn down for the app —
      * and its party-wide row is queued for removal by the next connected owner reconcile pass
      * (`JoinedStrandSession.forgetAfterThisSession`). A no-op for this party's own strands,
-     * which have neither record; the strand peer book is forgotten either way, since a
-     * removed party must not keep dialing the strand's peers.
+     * which have neither record; the formation-carried addresses and the saved network
+     * state are forgotten either way, since a removed party must not keep dialing the
+     * strand's peers.
      *
      * NOTE: accepted tradeoff — a sibling machine that has not raised `strand:revoked` itself
      * detaches the strand (`strand:stopped`) when the party-wide removal reaches it, instead
@@ -2790,25 +2880,13 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private forgetRevokedJoin;
     /**
-     * Forget a strand's entries in the peer book (see {@link strandPeerBookStore}):
-     * fire-and-log, like every book write — the removal is visible synchronously by the
-     * store's contract, and a failed persist costs restart survival only.
+     * Forget what this node holds about a strand's peers: the addresses its formation
+     * carried (see {@link formationStrandAddrs}) and its saved network state (see
+     * {@link strandNetworkStateStore}). The store write is fire-and-log — the removal is
+     * visible synchronously by the store's contract, and a failed persist only leaves the
+     * entry on disk for the next start.
      */
     private forgetStrandPeers;
-    /**
-     * The strand peer book's observation writer (`StartStrandConfig.onStrandPeerIdentified`):
-     * a strand node identified a strand peer at `observation.addrs`, so remember it as an
-     * unsigned entry seen just now. The observer never reports self, and the store binds
-     * every address to the peer id before filing it.
-     */
-    private observeStrandPeer;
-    /**
-     * Merge one entry into the peer book. Fire-and-log: the entry is visible
-     * synchronously by the store's contract, and the promise tracks durability only. A
-     * persist failure costs restart survival, never this session's seed — the same trade
-     * {@link retainDialTarget} makes.
-     */
-    private rememberStrandPeer;
     /**
      * Stop a strand on THIS node only: untrack it from hibernation, drop its sApp config,
      * stop the local instance, and emit `strand:stopped`. The shared `Strand` row is left
@@ -3392,32 +3470,128 @@ export declare class CadreNode implements SAppIdLookup {
      */
     dialInvite(invite: CadreInvite): Promise<void>;
     /**
-     * Initialize the strand solicitation service.
-     * This enables forming strands with other parties via open invitations.
+     * Replace this node's strand solicitation service — the formation responder every node
+     * installs at {@link start}, and the initiator side of {@link formStrand}. Optional: call it
+     * only to customize the responder (an approver, a provisioner, formation deadlines). The
+     * new service's handler replaces the previous one's on the control node, and invitations
+     * the previous service minted stay outstanding.
+     *
+     * Without `options.formationUsageRecorder`, tokens are checked against this party's
+     * replicated `FormationInvite`/`FormationUsage` rows ({@link ControlFormationUsageRecorder}).
+     * A responder that accepts every token is reachable only by constructing
+     * {@link StrandSolicitationService} directly.
      *
      * @param options - Configuration for the solicitation service
      */
     initializeStrandSolicitation(options?: StrandSolicitationServiceOptions): Promise<void>;
     /**
-     * Get the strand solicitation service (for advanced use)
+     * Answer formation from start. Log-and-continue: a node that cannot is still useful, and
+     * {@link createOpenInvitation} / {@link formStrand} install the responder when it is missing.
+     */
+    private installDefaultFormationResponder;
+    /**
+     * Move the control node's formation handler from the registered service to `service`.
+     * Queued by {@link initializeStrandSolicitation} so swaps run one at a time: libp2p allows
+     * one handler per protocol id, and two overlapping swaps would each find the other's
+     * handler in the way. A failed swap registers the previous service again, points
+     * {@link strandSolicitationService} back at it unless a later call has replaced it, and
+     * rethrows.
+     *
+     * NOTE: same stray-handler caveat as {@link installSeedBootstrapService} — a failed
+     * peer-store merge leaves the formation handler registered, so the restore below (and a
+     * retry) rejects as a duplicate.
+     */
+    private swapFormationResponder;
+    /**
+     * Get the strand solicitation service (for advanced use). Non-null on a started node unless
+     * the install at {@link start} failed.
      */
     getStrandSolicitationService(): StrandSolicitationService | null;
     /**
      * Create an open invitation for others to form strands with this party.
      *
+     * The invitation's bootstrap list names this machine first (it is the one most likely to
+     * run the host strand), then a few of the party's other machines
+     * ({@link siblingInvitationAddrs}), so a joiner can still form while this one is offline.
+     *
      * @param sAppId - The sApp to use for formed strands
      * @param expirationMs - How long the invitation is valid (ms from now)
      * @returns The open invitation to share out-of-band
+     * @throws when neither this machine nor any other machine of the party has an address
      */
     createOpenInvitation(sAppId: string, expirationMs?: number): Promise<OpenInvitation>;
     /**
-     * Form a strand with a responder via an open invitation.
+     * Addresses of the party's other machines for an invitation's bootstrap list
+     * ({@link selectInvitationSiblingAddrs} picks which). The source is each authorized
+     * member's signed `CadrePeer` record ({@link resolvePeerRecord}), so a machine whose record
+     * is missing, stale or untrusted is left out; live connections only order them.
+     *
+     * Best-effort: a failed read leaves the invitation naming this machine alone, which is what
+     * it named before siblings were added.
+     */
+    private siblingInvitationAddrs;
+    /**
+     * Form a strand with a responder via an open invitation: one attempt, from this machine, with
+     * nothing recorded party-wide. {@link requestJoin} is the path that keeps trying.
      *
      * @param invitation - The open invitation received out-of-band
      * @param disclosure - Identity/context information to share with the responder
      * @returns The member key and strand info if successful
+     * @throws `FormationRejectedError` or `FormationUnreachableError` when the formation fails, and
+     *   `FormationPostApprovalError` when it was approved and a step on this machine then failed
      */
     formStrand(invitation: OpenInvitation, disclosure?: StrandFormationDisclosure): Promise<FormStrandResult>;
+    /**
+     * Ask to join through `invitation` and have the party keep trying until the join works, the
+     * invitation is used up or expires, or the request is dismissed: across restarts, and from
+     * any owner machine of the party (`docs/strands.md` → "Joining while the inviter is
+     * offline"). Records a party-wide `PendingJoin` row, runs one attempt on this machine at
+     * once, and returns the status after it: `'joined'` when the inviter answered yes, `'waiting'`
+     * when it was unreachable or not ready, `'failed'` when it refused for good.
+     *
+     * Asking again for an invitation whose request is still pending adopts that request as it
+     * is; asking again after it finished starts a fresh one. Later changes arrive as
+     * `pendingJoin:changed`. A joined strand is offered through `strand:discovered` like any
+     * {@link formStrand} join. Do not also call {@link formStrand} with the same invitation:
+     * nothing coordinates the two, and one of them gets `token-spent`.
+     *
+     * @throws on a machine that is not an enrolled owner (the row is owner-signed), and on an
+     *   invitation already past its expiration
+     */
+    requestJoin(invitation: OpenInvitation, disclosure?: StrandFormationDisclosure): Promise<PendingJoinStatus>;
+    /**
+     * Every join asked for with {@link requestJoin} and not dismissed, pending or finished, as this
+     * machine sees it (see `PendingJoinStatus` for which states are machine-local).
+     */
+    listPendingJoins(): Promise<PendingJoinStatus[]>;
+    /**
+     * Remove a join request party-wide. On a pending request this cancels it: every owner machine
+     * stops at its next read, and an attempt already running does not record its outcome (a join
+     * it made stays on that machine, as any {@link formStrand} join does). Owner machines only.
+     * Resolves `false` when there was no such request.
+     */
+    dismissPendingJoin(id: string): Promise<boolean>;
+    private requirePendingJoins;
+    /** This machine's owner key and signer for an owner-signed control write, or a throw carrying `refusal`. */
+    private requireOwnerSigner;
+    /**
+     * Write a join request's row, or adopt the party's existing row for the same invitation: a
+     * pending one as it is, a finished one replaced by `requested` (the user asked again).
+     */
+    private recordJoinRequest;
+    /** Build and start the pending-join retry loop over this node (see {@link pendingJoinRunner}). */
+    private startPendingJoinRunner;
+    /** The invitation a `PendingJoin` row stores. A failure names the row, never the invitation, which is a bearer credential. */
+    private pendingJoinInvitation;
+    private pendingJoinSAppId;
+    /**
+     * Stage the membership invitation of each `joined` row this process has not staged yet, so a
+     * closed strand joined on another owner machine is seated by whichever machine launches it
+     * first; the party key it admits is the replicated `StrandPartyKey` row the finishing machine
+     * seated. A strand that already has an invitation staged keeps it, for the reconciler to
+     * settle first.
+     */
+    private stageMembershipInvitesFromPendingJoins;
     /**
      * Remember the strand a formation just joined (see {@link joinedStrandStore}), so it
      * is re-offered after a restart even when the app is killed before its `addStrand`, and
@@ -3550,21 +3724,27 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private wakeHostStrandForFormation;
     /**
-     * Remember the responder's strand-network addresses for a strand this node just
-     * formed in the strand peer book (see {@link strandPeerBookStore}), so the strand's
-     * discovery seed has something to work with when the app launches it — and again
-     * after every restart.
+     * Keep the responder's strand-network addresses for a strand this node just formed
+     * (see {@link formationStrandAddrs}), so the strand's discovery seed has something to
+     * dial when the app launches it.
      *
      * The carried list is peer-agnostic (`sanitizeStrandAddrs` bounds and parses it,
      * nothing more), so it is attributed per peer here (`groupAddrsByPeerId`, the same
-     * rule the address-book merge applies) and each peer becomes one unsigned entry seen
-     * just now: the responder disclosed the addresses live a moment ago. An entry naming
-     * no destination peer is dropped there. Scoped strictly to `strandId`: these
-     * addresses reach ONE strand node of ONE other party and must never seed another
-     * strand's mesh or the control peerStore. An empty list records nothing, so a later
-     * formation against the same strand that DOES disclose addresses is not shadowed.
-     */
-    private recordFormationStrandPeers;
+     * rule the address-book merge applies) and kept grouped by peer; an entry naming no
+     * destination peer is dropped there. Scoped strictly to `strandId`: these addresses
+     * reach ONE strand node of ONE other party and must never seed another strand's mesh
+     * or the control peerStore.
+     *
+     * A list that names a peer REPLACES the strand's earlier one: the responder
+     * disclosed its current addresses, so the older list is stale. An empty list, or one
+     * naming no peer, records nothing, so it cannot wipe an earlier disclosure.
+     *
+     * A strand already running when this lands (a re-formation, which is the recovery
+     * path for a dead address) gets the new addresses merged into its address book now.
+     * Nothing else would deliver them: the seed is read only at launch and resume, and the
+     * refresh pass skips a peer FRET already holds a record for — the stale one, here.
+     */
+    private recordFormationStrandAddrs;
     /**
      * Encode an open invitation for out-of-band delivery (QR, link, etc.).
      */