@serfab/cadre-core 1.5.0 → 1.7.0

package/dist/cadre-node.d.ts

@@ -4,6 +4,7 @@ import type { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStr
 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 EnrolledMachineStore } from './enrolled-machine-store.js';
 import { type SAppIdLookup } from './strand-watcher.js';
 import { type ControlCohortReconcileResult } from './control-cohort.js';
@@ -257,37 +258,36 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private readonly strandPeerAddrRefreshAt;
     /**
-     * CROSS-PARTY strand-network addresses learned at formation, keyed by strandId — the
-     * responder's live strand addrs, carried back on the formation result
-     * (`FormationResultMessage.strandAddrs`) and recorded by {@link formStrand}.
+     * 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
      * resolves a strand's addresses is membership-gated and answers own-party siblings
-     * only, so without this map a joiner's cohort seed for a two-party strand is empty and
-     * the mesh never forms.
-     *
-     * Read by {@link resolveCohortSeed} (launch + hibernation resume) and re-merged by
-     * every {@link refreshStrandPeerAddrs} pass — the re-merge is what keeps the entries
-     * alive past the peerStore's one-hour address expiry, since nothing can re-resolve
-     * them.
-     *
-     * IN-MEMORY and ONE-SHOT, deliberately (see `docs/strands.md`): the addresses die with
-     * the process, and a restarted initiator with no sibling running the strand is back to
-     * an empty seed until the durability work lands
-     * (`backlog/feat-cross-party-strand-addr-durability`). They are also never refreshed,
-     * so a responder whose relay reservation rotates before the initiator dials leaves a
-     * dead entry behind; recovery today is a fresh invitation.
-     *
-     * NOTE: entries are kept for the node's lifetime, including across a
-     * {@link stopStrand} — a stopped strand may be claimed again with {@link addStrand}
-     * (the watcher itself will not re-offer it: the stop suppresses the id for the rest of
-     * the session) and must still get its seed. Each strand's list is capped at
-     * `MAX_STRAND_ADDRS`, but the
-     * number of KEYS is bounded only by the strands this node has ever formed as an
-     * initiator (not by time); if a node ever forms strands at scale, evict on
-     * `unpublishStrand` or cap the map.
-     */
-    private readonly crossPartyStrandAddrs;
+     * 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
+     * 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.
+     */
+    private strandPeerBookStore;
     /**
      * PENDING strand membership invitations learned at formation, keyed by strandId — the
      * single-use `Strand.Invite` credential a closed-strand formation result carried back
@@ -295,10 +295,9 @@ export declare class CadreNode implements SAppIdLookup {
      * to redeem (`consumeInvite` seats the `Strand.Member` row under this party's own key
      * — the `strand-node-binds-member-peer` half of the party-identity chain).
      *
-     * IN-MEMORY, deliberately, like {@link crossPartyStrandAddrs}: a restarted joiner
-     * re-forms from scratch anyway (durability is
-     * `backlog/feat-cross-party-strand-addr-durability`'s problem), and re-forming issues
-     * a fresh invitation. A re-formation against the same strand REPLACES the entry — the
+     * IN-MEMORY, deliberately: an invitation is single-use and short-lived, a restarted
+     * joiner that never redeemed it re-forms from scratch, and re-forming issues a fresh
+     * one. A re-formation against the same strand REPLACES the entry — the
      * fresh invitation supersedes one that may have expired. The party key the invitation
      * admits, by contrast, IS persisted (`StrandPartyKey`, seated by
      * {@link adoptFormationMembershipInvite} before the entry lands here), so a lost
@@ -314,8 +313,9 @@ export declare class CadreNode implements SAppIdLookup {
      * just waits; once launched, staging notifies the manager, which re-arms a finished loop.
      *
      * NOTE: entries live for the node's lifetime (one small pair per formed closed
-     * strand), the same unbounded-keys tripwire {@link crossPartyStrandAddrs} documents —
-     * if a node ever forms strands at scale, evict alongside that map.
+     * 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.
      */
     private readonly pendingMembershipInvites;
     /**
@@ -386,6 +386,23 @@ export declare class CadreNode implements SAppIdLookup {
      * so it survives a stop()→start() cycle of the same node instance.
      */
     private enrolledMachineStore;
+    /**
+     * Node-local record of the strands this node joined from ANOTHER party (see
+     * `joined-strand-store.ts`) — the only thing that names them after a restart, since
+     * this party's control database holds no row for them. Written by {@link formStrand}
+     * and by an {@link addStrand} of a foreign row; forgotten by {@link forgetJoinedStrand}
+     * and on self-revocation. Adopted from `config.joinedStrands.store`, else built over
+     * `config.keyStore`, else in-memory, by {@link initializeJoinedStrandStore}. Like
+     * {@link bootstrapPeerStore} it is deliberately NOT cleared by {@link cleanup}.
+     */
+    private joinedStrandStore;
+    /**
+     * The strand watcher's view of {@link joinedStrandStore}: its records unioned with the
+     * control rows each poll. Per SESSION, unlike the store — rebuilt at every
+     * {@link start}, which is what ends a revoked join's "keep offering until this session
+     * ends" (see `JoinedStrandRows.forgetAfterThisSession`).
+     */
+    private joinedStrandRows;
     /**
      * The enrolled-machine count this node's CONTROL libp2p node was (or will be)
      * built with — read out of {@link enrolledMachineStore} during {@link start},
@@ -693,6 +710,25 @@ export declare class CadreNode implements SAppIdLookup {
      * number nobody chose, and the mismatch always means a miswired embedder.
      */
     private initializeEnrolledMachineStore;
+    /**
+     * Construct (or adopt) the node-local joined-strand store (see
+     * {@link joinedStrandStore}) and this session's watcher view over it.
+     *
+     * The store instance is kept across stop()→start(); the view is rebuilt. A store
+     * scoped to a different party is a configuration error, fail closed: its joins
+     * would be offered to this party's app as if this party had made them.
+     */
+    private initializeJoinedStrandStore;
+    /**
+     * Construct (or adopt) the node-local strand peer book (see
+     * {@link strandPeerBookStore}). 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.
+     */
+    private initializeStrandPeerBookStore;
     /**
      * 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
@@ -706,6 +742,13 @@ export declare class CadreNode implements SAppIdLookup {
      * node dial if it is stranded?".
      */
     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?".
+     */
+    getStrandPeerBookStore(): StrandPeerBookStore | null;
     /**
      * The node-local trusted-owner anchor (null before {@link start}). This is
      * the set the authorized-membership predicate and seed-trust anchor consult —
@@ -765,10 +808,10 @@ export declare class CadreNode implements SAppIdLookup {
      * needs no work of its own: `createLibp2pNode` registers the block-transfer
      * handler on every node it builds, control node included, and this node's
      * per-stream gate (`authorizeInboundControlStream`) covers the inbound
-     * direction. A denied peer is retried on its next `connection:open`, and —
-     * because the production join order is connect-then-authorize — on every
-     * committed membership change via {@link refreshAuthorizedControlPeers}'s
-     * `scheduleConnectedPeers()` call.
+     * direction. A denied peer is retried on its next `peer:identify` (a
+     * reconnect re-runs identify), and — because the production join order is
+     * connect-then-authorize — on every committed membership change via
+     * {@link refreshAuthorizedControlPeers}'s `scheduleConnectedPeers()` call.
      *
      * No-ops (logged) when the embedder configured no control storage or the
      * node exposes no key network — the backfill would have nothing to read or
@@ -1045,6 +1088,11 @@ export declare class CadreNode implements SAppIdLookup {
      * address without a `/p2p/<id>` component contributes nothing.
      */
     private getBootstrapPeerIds;
+    /**
+     * What the strand watcher polls: this party's control rows plus a row per remembered
+     * cross-party join (see {@link joinedStrandRows}), so a joined strand is re-offered
+     * and relaunched on the same path as the party's own.
+     */
     private createStrandQueryable;
     /**
      * Schedule the node's initial self-record publish + ongoing refresh shortly
@@ -1875,6 +1923,10 @@ export declare class CadreNode implements SAppIdLookup {
      * published (e.g. re-attaching its own orphan after a restart) founds it, and attaching
      * anyone else's row joins, without the caller needing to know which it is.
      *
+     * A joined row (no `founder: true`) this party's control database does not hold — a
+     * strand joined from another party — is remembered in the node's joined-strand store, so it is re-offered as
+     * `strand:discovered` after a restart (see {@link forgetJoinedStrand}).
+     *
      * A rejected call leaves nothing running but DOES leave the sApp config
      * registered, deliberately: both an explicit retry and the {@link StrandWatcher}'s
      * automatic relaunch need it. A failed launch here hands the strand back to that
@@ -2273,6 +2325,13 @@ 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
@@ -2390,7 +2449,7 @@ export declare class CadreNode implements SAppIdLookup {
      * NOTE: against a relay that is DOWN this hook costs up to two strand-addr
      * timeouts (10 s each: dial by peer id, then by addr) before the reservation drive even
      * starts, so one failed re-drive holds the supervisor `driving` for those 20 s plus the
-     * drive's own deadline — 28 s at the default declared link round trip, and longer on a host
+     * drive's own deadline — 34 s at the default declared link round trip, 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
@@ -2427,17 +2486,17 @@ export declare class CadreNode implements SAppIdLookup {
     private refreshStrandPeerAddrs;
     /**
      * One strand's share of {@link refreshStrandPeerAddrs}: RPC the siblings, union their
-     * answers with this strand's cross-party contact 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.
+     * 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.
      *
      * `targets` may be EMPTY — a solo node, or one whose only control peers are strangers.
-     * The cross-party addresses still have to be re-merged in that case: they were learned
-     * at formation and can never be re-resolved, so this periodic re-merge is the ONLY
-     * thing standing between them and the peerStore's one-hour expiry. A strand with
-     * neither a sibling to ask nor a contact entry does nothing and leaves its throttle
-     * unstamped, so the next reconcile tick retries rather than sitting out the whole
-     * refresh interval having done nothing.
+     * The peer-book addresses still have to be re-merged in that case: nothing re-resolves
+     * another party's addresses, so this periodic re-merge is the ONLY thing standing
+     * between them and the peerStore's one-hour expiry. A strand with neither a sibling to
+     * ask nor a book entry does nothing and leaves its throttle unstamped, so the next
+     * reconcile tick retries rather than sitting out the whole refresh interval having
+     * done nothing.
      */
     private refreshOneStrandPeerAddrs;
     /**
@@ -2459,14 +2518,14 @@ 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 does NOT age out — the cross-party addresses a formation
-     * carried back ({@link crossPartyStrandAddrs}). Nothing can re-resolve them, so
-     * {@link refreshStrandPeerAddrs} re-merges the same stored list every pass, which
-     * also means a junk entry from a responder survives for the node's lifetime rather
-     * than an hour. Bounded to {@link MAX_STRAND_ADDRS} per strand, from a party this
-     * node deliberately formed a strand with, and still authority-free — so the
-     * exposure is a handful of failed dials, not a trust hole. Evict on
-     * `unpublishStrand` if that ever stops being an acceptable price.
+     * 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.
      */
     private mergeStrandPeerAddrs;
     /**
@@ -2479,6 +2538,69 @@ export declare class CadreNode implements SAppIdLookup {
      * live node, so it answers and a later sibling can dial in.
      */
     private getStrandMultiaddrs;
+    /**
+     * Leave a strand joined from another party: forget its remembered join, so no later
+     * start re-offers it, then {@link stopStrand} it here. The "leave" a joiner has, since it
+     * cannot {@link unpublishStrand} a row its party's control database never held. For one
+     * of this party's own strands the forget is a no-op and this is just {@link stopStrand}.
+     *
+     * Touches nothing beyond this node — the other members are not told, and this party's
+     * membership row in the strand stays.
+     */
+    forgetJoinedStrand(strandId: string): Promise<void>;
+    /**
+     * Record `row` as a join from another party when this party's control database holds no
+     * row for it — the one case nothing else would re-offer after a restart. Skips the write
+     * when an identical record is already there (an app re-claiming a remembered join on
+     * every start), and keeps the first `joinedAt`.
+     *
+     * Best-effort, for {@link addStrand}: a failure costs the strand its re-offer after the
+     * next restart, not this attach, so it is reported and the attach goes on.
+     * {@link formStrand}, whose join nothing else would name, fails loudly instead.
+     *
+     * NOTE: "no control row" also describes a row the party has just unpublished. A claim
+     * of such a row the app kept from an earlier offer, made after the watcher already
+     * withdrew it, is remembered as a join and survives the removal on this machine until
+     * {@link forgetJoinedStrand}. Contrived today (a claim of a row the node itself is still
+     * offering skips this method); if it shows up, check the strand's `Revocation`
+     * tombstone here before recording.
+     */
+    private rememberForeignStrand;
+    /**
+     * Self-revocation arm of the joined-strand record: a party removed from a strand must
+     * not re-attach it on every launch. The strand keeps running this session — the
+     * `strand:revoked` contract is that nothing is torn down for the app — and is gone
+     * after the next start. The join record is a no-op for this party's own strands, which
+     * have none; the strand peer book is forgotten either way, since a removed party must
+     * not keep dialing the strand's peers.
+     *
+     * NOTE: a manager can re-admit a removed party directly (`addMemberByManager`), and the
+     * membership loop then finishes the join on its own — but the record is gone by then, so
+     * the next start does not re-attach the strand. Re-forming records it again. If direct
+     * re-admission becomes a routine flow, re-record the join when the revoked-peer gate
+     * clears for this node.
+     */
+    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.
+     */
+    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
@@ -2487,7 +2609,9 @@ export declare class CadreNode implements SAppIdLookup {
      * id in the watcher (`StrandWatcher.suppressStrand`) and drops it from
      * {@link getDiscoveredStrands}, so neither a later poll nor a drain can undo a
      * deliberate stop. Only an explicit {@link addStrand} does, which is the caller
-     * reversing its own decision. Party-wide removal is {@link unpublishStrand}.
+     * reversing its own decision. Party-wide removal is {@link unpublishStrand}. A strand
+     * joined from another party comes back the same way, from its remembered join;
+     * {@link forgetJoinedStrand} is how to leave one for good.
      */
     stopStrand(strandId: string): Promise<void>;
     /**
@@ -2613,7 +2737,7 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * BUDGET: the supervisor's first attempt is what `start()` waits on — deliberately the drive's
      * ordinary deadline rather than a boot-specific one. That deadline is now COUNTED, four link
-     * round trips at the declared `network.linkRoundTripMs` (8 s at its default, where it was a
+     * round trips at the declared `network.linkRoundTripMs` (14 s at its default, where it was a
      * fixed 10 s): a healthy dial-plus-reserve is sub-second even over a WAN, so this is slack for
      * a slow link, while 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. A host that declares
@@ -3059,6 +3183,16 @@ export declare class CadreNode implements SAppIdLookup {
      * @returns The member key and strand info if successful
      */
     formStrand(invitation: OpenInvitation, disclosure?: StrandFormationDisclosure): Promise<FormStrandResult>;
+    /**
+     * 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`.
+     * Last in {@link formStrand}, after the membership adoption, so a failure here leaves
+     * the party key and staged invitation in place for the re-formation it asks for.
+     *
+     * Throws on failure, like {@link adoptFormationMembershipInvite}: the formation's
+     * token is spent, and a join no store names would vanish at the next restart.
+     */
+    private rememberFormedStrand;
     /**
      * Adopt an approved closed-strand formation's membership half on the JOINER:
      *
@@ -3145,15 +3279,20 @@ export declare class CadreNode implements SAppIdLookup {
     private issueStrandMembershipInvite;
     /**
      * Remember the responder's strand-network addresses for a strand this node just
-     * formed, so the strand's discovery seed has something to work with when the app
-     * launches it (see {@link crossPartyStrandAddrs}).
-     *
-     * 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 is recorded as no entry at all rather than an empty one, so a later formation
-     * against the same strand that DOES disclose addresses is not shadowed.
-     */
-    private recordCrossPartyStrandAddrs;
+     * 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.
+     *
+     * 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;
     /**
      * Encode an open invitation for out-of-band delivery (QR, link, etc.).
      */