@serfab/cadre-core 1.6.0 → 1.7.0

package/dist/cadre-node.js

@@ -1,6 +1,7 @@
 import debug from 'debug';
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
 import { peerIdFromString, peerIdFromPrivateKey } from '@libp2p/peer-id';
+import { generateKeyPair } from '@libp2p/crypto/keys';
 import { createLibp2pNode } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { multiaddr } from '@multiformats/multiaddr';
@@ -16,7 +17,9 @@ import { DEFAULT_IDENTITY_KEY_ID } from './key-store.js';
 import { loadOrCreateIdentityKey } from './identity-key.js';
 import { MemoryTrustedOwnerStore } from './trusted-owner-store.js';
 import { MemoryBootstrapPeerStore } from './bootstrap-peer-store.js';
+import { MemoryStrandPeerBookStore } from './strand-peer-book.js';
 import { MemoryEnrolledMachineStore } from './enrolled-machine-store.js';
+import { JoinedStrandRows, KeyStoreJoinedStrandStore, MemoryJoinedStrandStore } from './joined-strand-store.js';
 import { mergePeerAddrs, groupAddrsByPeerId } from './peer-addr-book.js';
 import { verifyCadrePeerVoucher } from './peer-authorization.js';
 import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
@@ -34,7 +37,6 @@ import { HibernationManager } from './hibernation-manager.js';
 import { ControlDatabase, isStrandIdConflict } from './control-database.js';
 import { SeedBootstrapService } from './seed-bootstrap.js';
 import { StrandSolicitationService } from './strand-solicitation.js';
-import { MAX_STRAND_ADDRS } from './strand-formation-protocol.js';
 import { createMembershipConnectionGater, DEFAULT_ENROLLMENT_WINDOW_MS, UnauthorizedReservationBudget } from './membership-connection-gater.js';
 import { StrandWakeService, dialWake } from './strand-wake-protocol.js';
 import { StrandAddrService, collectStrandAddrs } from './strand-addr-protocol.js';
@@ -78,7 +80,7 @@ function relayStrandAddrPeer(relay) {
  * and order-preserving.
  *
  * Used wherever a strand's discovery seed unions two sources of address strings — the
- * freshly-RPC'd sibling answers and the cross-party addresses learned at formation. The
+ * freshly-RPC'd sibling answers and the strand peer book's last-known addresses. The
  * caller passes the FRESHER source as `primary`, so a stale entry can only ever be
  * appended, never promoted ahead of a current one, and each source keeps whatever
  * signaling-first ordering it arrived with.
@@ -373,37 +375,36 @@ export class CadreNode {
          */
         this.strandPeerAddrRefreshAt = new Map();
         /**
-         * 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.
+         * 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}.
          *
-         * 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.
+         * 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.
          */
-        this.crossPartyStrandAddrs = new Map();
+        this.strandPeerBookStore = null;
         /**
          * PENDING strand membership invitations learned at formation, keyed by strandId — the
          * single-use `Strand.Invite` credential a closed-strand formation result carried back
@@ -411,10 +412,9 @@ export class CadreNode {
          * 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
@@ -430,8 +430,9 @@ export class CadreNode {
          * 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.
          */
         this.pendingMembershipInvites = new Map();
         /**
@@ -502,6 +503,23 @@ export class CadreNode {
          * so it survives a stop()→start() cycle of the same node instance.
          */
         this.enrolledMachineStore = null;
+        /**
+         * 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}.
+         */
+        this.joinedStrandStore = null;
+        /**
+         * 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`).
+         */
+        this.joinedStrandRows = null;
         /** Initial self-registration timer (see {@link scheduleSelfRegistration}). */
         this.selfRegistrationTimer = null;
         /** TTL heartbeat that re-publishes the self record before it goes stale. */
@@ -788,6 +806,12 @@ export class CadreNode {
             // closed before any network bring-up, and the retained dial targets are
             // loaded before the first reconcile pass could consult them.
             this.initializeBootstrapPeerStore();
+            // The remembered cross-party joins, which the strand watcher built below polls
+            // beside the control rows. Before network bring-up, so a mis-scoped injected store
+            // fails closed like the two above.
+            this.initializeJoinedStrandStore();
+            // The strand peer book those joins are dialed from. Same placement, same reason.
+            this.initializeStrandPeerBookStore();
             // Read the party's enrolled-machine count out of its node-local record and
             // capture it for buildControlNodeOptions below. This MUST precede
             // createControlNode: Optimystic freezes the cluster policy when the node is
@@ -1135,6 +1159,48 @@ export class CadreNode {
         this.declaredEnrolledMachines = store.count();
         log('control repair yardstick will be declared from %o enrolled machine(s)', this.declaredEnrolledMachines);
     }
+    /**
+     * 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.
+     */
+    initializeJoinedStrandStore() {
+        const partyId = this.config.controlNetwork.partyId;
+        const { keyStore } = this.config;
+        const store = this.joinedStrandStore
+            ?? this.config.joinedStrands?.store
+            ?? (keyStore ? new KeyStoreJoinedStrandStore(keyStore, partyId) : new MemoryJoinedStrandStore(partyId));
+        if (store.partyId !== partyId) {
+            throw new Error(`CadreNodeConfig: joinedStrands.store is scoped to party ${store.partyId}, ` +
+                `but this node serves party ${partyId} — refusing to offer another party's joined strands`);
+        }
+        this.joinedStrandStore = store;
+        this.joinedStrandRows = new JoinedStrandRows(store);
+    }
+    /**
+     * 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.
+     */
+    initializeStrandPeerBookStore() {
+        const partyId = this.config.controlNetwork.partyId;
+        if (this.strandPeerBookStore) {
+            return;
+        }
+        const store = this.config.strandPeers?.store ?? new MemoryStrandPeerBookStore(partyId);
+        if (store.partyId !== partyId) {
+            throw new Error(`CadreNodeConfig: strandPeers.store is scoped to party ${store.partyId}, ` +
+                `but this node serves party ${partyId} — refusing to mix strand peer books`);
+        }
+        this.strandPeerBookStore = store;
+    }
     /**
      * 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
@@ -1152,6 +1218,15 @@ export class CadreNode {
     getBootstrapPeerStore() {
         return this.bootstrapPeerStore;
     }
+    /**
+     * 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() {
+        return this.strandPeerBookStore;
+    }
     /**
      * The node-local trusted-owner anchor (null before {@link start}). This is
      * the set the authorized-membership predicate and seed-trust anchor consult —
@@ -1225,10 +1300,10 @@ export class CadreNode {
      * 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
@@ -1823,7 +1898,7 @@ export class CadreNode {
             // ever holds many such connections, or refreshes get frequent, skip
             // re-arming peers whose last pass was denied under the SAME membership
             // snapshot instead of re-arming unconditionally.
-            this.controlBackfill?.scheduleConnectedPeers();
+            void this.controlBackfill?.scheduleConnectedPeers();
         }
         catch (error) {
             log('refreshAuthorizedControlPeers(%s) failed — keeping previous snapshot: %o', reason, error);
@@ -1859,6 +1934,11 @@ export class CadreNode {
         }
         return this.bootstrapPeerIds;
     }
+    /**
+     * 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.
+     */
     createStrandQueryable() {
         return {
             queryStrands: async () => {
@@ -1867,7 +1947,8 @@ export class CadreNode {
                     return [];
                 }
                 log('Querying strands from control database');
-                return await this.controlDatabase.queryStrands();
+                const control = await this.controlDatabase.queryStrands();
+                return this.joinedStrandRows ? await this.joinedStrandRows.withControlRows(control) : control;
             }
         };
     }
@@ -4149,6 +4230,10 @@ export class CadreNode {
      * 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
@@ -4179,6 +4264,12 @@ export class CadreNode {
                 `(Type 'c'), but this row is Type '${strandRow.Type}' — an open strand seats no ` +
                 'Member/Manager, so the key would be ignored.');
         }
+        // A row this node offered itself came from the control table or is already a
+        // remembered join, and a row this node founds is not a join, so only a joined row
+        // from elsewhere can be a new join to remember. A founded row recorded here would
+        // come back after a restart with `FounderOwnerKey: null` and relaunch as a joiner.
+        // Captured before the backlog delete below.
+        const rememberable = founder !== true && !this.discoveredStrands.has(strandRow.Id);
         // Store sApp config for this strand. The strand is claimed now, so it leaves the
         // unclaimed backlog — a later `getDiscoveredStrands()` drain must not re-offer it.
         this.sAppConfigs.set(strandRow.Id, sAppConfig);
@@ -4187,6 +4278,11 @@ export class CadreNode {
         // the strand again, or a party-wide removal would never stop it here.
         this.strandWatcher?.unsuppressStrand(strandRow.Id);
         log('Registered sAppConfig for strand %s (sApp: %s, founder: %s)', strandRow.Id, sAppConfig.id, founder ?? 'derived');
+        // Before the launch, so a foreign strand whose launch fails, or whose app is killed
+        // mid-launch, is still offered again: by the watcher's retry and by the next start.
+        if (rememberable) {
+            await this.rememberForeignStrand(strandRow);
+        }
         // An unset `founder` is DERIVED from the row inside launchStrand (this node founds
         // iff the row's FounderOwnerKey is its own owner key); an explicit flag wins — the
         // formation/responder flows pass one deliberately, since their consent-seated rows
@@ -4207,7 +4303,8 @@ export class CadreNode {
             // only delays the watcher's own first attempt by one poll interval, which is what
             // should happen right after an attempt that just failed.
             //
-            // NOTE: the retry relaunches from the CONTROL row plus the registered config, not
+            // NOTE: the retry relaunches from the CONTROL row (or, for a strand joined from
+            // another party, the remembered join) plus the registered config, not
             // from the row and arguments passed here — so a caller that enriched either (a
             // synthetic `MemberPrivateKey`, an explicit `founder` or `partyMemberPrivateKey`)
             // is retried with less than it asked for. Inert today: founder-ness re-derives from
@@ -4543,6 +4640,9 @@ export class CadreNode {
         // A refused pre-split launch left no tracked instance, so the stop below never
         // reaches detachStrand for it — clear the refusal here so a re-founded id starts clean.
         this.strandLaunchRefusals.delete(trimmed);
+        // A party-wide removal: the strand's peers must not stay dial targets for a strand
+        // that no longer exists (a re-published id is a fresh strand with fresh peers).
+        this.forgetStrandPeers(trimmed, 'unpublishStrand');
         // Clear THIS machine's own MemberPeer binding while the strand runtime — and the
         // retained party key — is still live: the delete above already destroyed the
         // party's StrandPartyKey row, so once this process forgets the key nothing can
@@ -4896,18 +4996,25 @@ export class CadreNode {
         // retained launch config carries this derived key, so hibernate → wake
         // (resumeStrand) reuses the same peerId.
         //
+        // Without an identity key (a node configured with neither `keyStore` nor
+        // `privateKey` — tests, and an embedder that opted out of a stable identity) the
+        // strand node still runs under a key CADRE-CORE HOLDS: a fresh random Ed25519 key,
+        // exactly what libp2p would generate internally if handed none, except that the
+        // book swap can sign this node's own entry with it (`strand-peer-book-swap.ts`) and
+        // the retained launch config keeps the same strand peer id across a hibernation
+        // resume. Stability across RESTARTS still needs an identity key.
+        //
         // NOTE: derivation requires an Ed25519 identity key, so a node configured
         // with some other key type now fails strand launch outright (surfaced as
         // `strand:error` / a rejected addStrand) where it previously started the
         // strand on that key. Ed25519 is already required for every control-DB
         // signing path, so nothing reachable today hits this; if a non-Ed25519
-        // identity is ever supported, fall back to `undefined` here — libp2p then
-        // generates a random per-strand key, which still avoids the collision but
-        // gives up peerId stability across restarts.
+        // identity is ever supported, take the random-key branch below for it — it
+        // still avoids the collision, and gives up only peerId stability across restarts.
         const identityKey = this.identityKey;
         const transportKey = identityKey
             ? await timed('strandTransportKey', () => strandTransportKey(identityKey, strand.Id))
-            : undefined;
+            : await generateKeyPair('Ed25519');
         // Derived BEFORE seed resolution so the seed pass doubles as the delegate
         // announcement and every grant is recorded before `startStrand` runs
         // `libp2p.start()` (the responder records the grant before replying; the
@@ -4935,7 +5042,19 @@ export class CadreNode {
             backfill: this.config.strandBackfill,
             revocationEnforcement: this.config.strandRevocationEnforcement,
             membershipReconciliation: this.config.strandMembershipReconciliation,
-            onSelfRevoked: (revokedStrandId) => this.emit('strand:revoked', { strandId: revokedStrandId }),
+            onSelfRevoked: (revokedStrandId) => {
+                this.forgetRevokedJoin(revokedStrandId);
+                this.emit('strand:revoked', { strandId: revokedStrandId });
+            },
+            // The strand peer book's observation writer: every strand peer the node
+            // identifies is remembered with its dialable addresses, so a restart re-finds
+            // it. Retained with the launch config, so a hibernation wake re-arms it.
+            onStrandPeerIdentified: (observedStrandId, observation) => this.observeStrandPeer(observedStrandId, observation),
+            // The book's third writer, the signed swap between strand peers: the strand node
+            // reads and writes the store directly (`strand-peer-book-swap.ts`). Retained with
+            // the launch config too. `?? undefined`: the field is `null` before start(), and a
+            // strand cannot launch before start(), so this is belt and braces.
+            strandPeerBook: this.strandPeerBookStore ?? undefined,
             onRejoinBlocked: (blockedStrandId) => this.emit('strand:rejoin-blocked', { strandId: blockedStrandId }),
             // The joiner's first-sync write gate (strand-first-sync-gate.ts): a launch that
             // comes up `'syncing'` announces the moment its database is published.
@@ -4998,11 +5117,31 @@ export class CadreNode {
      */
     async resolveCohortSeed(strandId, delegatePeerId) {
         const siblings = await this.resolveSiblingSeed(strandId, delegatePeerId);
-        // Sibling answers FIRST: they were resolved just now, while a contact-map entry is as
-        // old as the formation that produced it. `unionAddrs` appends only what the siblings
+        // Sibling answers FIRST: they were resolved just now, while a book entry is as old
+        // as the last connection to that peer. `unionAddrs` appends only what the siblings
         // did not already name, so a fresher answer is never displaced and each source keeps
-        // its own signaling-first ordering.
-        return unionAddrs(siblings, this.crossPartyStrandAddrs.get(strandId) ?? []);
+        // its own signaling-first ordering. `delegatePeerId` IS this strand node's own id.
+        return unionAddrs(siblings, this.strandPeerBookAddrs(strandId, delegatePeerId));
+    }
+    /**
+     * 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.
+     */
+    strandPeerBookAddrs(strandId, selfPeerId) {
+        const store = this.strandPeerBookStore;
+        if (!store) {
+            return [];
+        }
+        const addrs = [];
+        for (const entry of store.entries(strandId)) {
+            if (entry.peerId === selfPeerId) {
+                continue;
+            }
+            addrs.push(...entry.addrs);
+        }
+        return addrs;
     }
     /**
      * The own-party half of {@link resolveCohortSeed}: strand-network addresses resolved
@@ -5265,8 +5404,8 @@ export class CadreNode {
         // `connectedSiblingTargets`' membership read is unbounded, and with zero
         // connections its answer is empty whatever the table holds, so decide it from the
         // connection list instead of paying for the read once a tick. Note this only skips
-        // the RPC: a strand carrying cross-party contact addresses still refreshes below,
-        // because those never came from a sibling in the first place.
+        // the RPC: a strand with peer-book entries still refreshes below, because those
+        // never came from a sibling in the first place.
         //
         // NOTE: one strand-addr RPC per (due strand × connected sibling) per refresh
         // interval — each a tiny request/response on an already-open control
@@ -5286,17 +5425,17 @@ export class CadreNode {
     }
     /**
      * 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.
      */
     async refreshOneStrandPeerAddrs(strandId, targets, now) {
         const controlNode = this.controlNode;
@@ -5304,11 +5443,13 @@ export class CadreNode {
         if (!controlNode || !strandNode) {
             return;
         }
-        const contactAddrs = this.crossPartyStrandAddrs.get(strandId) ?? [];
-        if (targets.length === 0 && contactAddrs.length === 0) {
-            return;
-        }
         try {
+            // Inside the try: a strand node torn down mid-pass may throw on any read, and one
+            // strand's failure must never cost the others their refresh.
+            const contactAddrs = this.strandPeerBookAddrs(strandId, strandNode.peerId.toString());
+            if (targets.length === 0 && contactAddrs.length === 0) {
+                return;
+            }
             // The running strand node's own peerId is the delegate to announce — see
             // the relationship note on refreshStrandPeerAddrs.
             const siblingAddrs = targets.length === 0
@@ -5350,14 +5491,14 @@ export class CadreNode {
      * 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.
      */
     async mergeStrandPeerAddrs(strandNode, addrs, strandId) {
         const counts = { merged: 0, restamped: 0, skipped: 0, failed: 0 };
@@ -5423,6 +5564,128 @@ export class CadreNode {
         }
         return orderSignalingFirst(addrs);
     }
+    /**
+     * 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.
+     */
+    async forgetJoinedStrand(strandId) {
+        if (!this._running) {
+            throw new Error('CadreNode not running');
+        }
+        await this.joinedStrandRows.forget(strandId);
+        this.forgetStrandPeers(strandId, 'forgetJoinedStrand');
+        await this.stopStrand(strandId);
+    }
+    /**
+     * 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.
+     */
+    async rememberForeignStrand(row) {
+        const store = this.joinedStrandStore;
+        if (!store || !this.controlDatabase) {
+            return;
+        }
+        try {
+            if (await this.controlDatabase.queryStrand(row.Id)) {
+                return;
+            }
+            const existing = (await store.list()).find((record) => record.Id === row.Id);
+            if (existing?.Type === row.Type && existing.MemberPrivateKey === row.MemberPrivateKey) {
+                return;
+            }
+            await store.record({
+                Id: row.Id,
+                Type: row.Type,
+                MemberPrivateKey: row.MemberPrivateKey,
+                joinedAt: existing?.joinedAt ?? Date.now()
+            });
+        }
+        catch (error) {
+            console.warn(`addStrand(${row.Id}): could not remember this strand as joined from another party, ` +
+                'so it will not be re-offered after a restart:', error);
+        }
+    }
+    /**
+     * 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.
+     */
+    forgetRevokedJoin(strandId) {
+        void this.joinedStrandRows?.forgetAfterThisSession(strandId).catch((error) => {
+            log('forgetting revoked joined strand %s failed; it will be re-offered on the next start: %o', strandId, error);
+        });
+        // The strand's peers go with the join: a removed party must not keep dialing them.
+        this.forgetStrandPeers(strandId, 'self-revocation');
+    }
+    /**
+     * 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.
+     */
+    forgetStrandPeers(strandId, caller) {
+        void this.strandPeerBookStore?.forget(strandId).catch((error) => {
+            log('%s: forgetting strand %s peers failed (continuing): %o', caller, strandId, error);
+        });
+    }
+    /**
+     * 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.
+     */
+    observeStrandPeer(strandId, observation) {
+        this.rememberStrandPeer(strandId, {
+            peerId: observation.peerId,
+            addrs: observation.addrs,
+            issuedAt: 0,
+            lastSeenAt: Date.now()
+        }, '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.
+     */
+    rememberStrandPeer(strandId, entry, caller) {
+        const store = this.strandPeerBookStore;
+        if (!store) {
+            // Unreachable in production: start() builds the store before any strand can
+            // launch or form. Logged rather than thrown, for the same reason as retainDialTarget.
+            log('%s: no strand peer book yet — not remembering %s for strand %s', caller, entry.peerId, strandId);
+            return;
+        }
+        void store.merge(strandId, entry).catch((error) => {
+            log('%s: persisting strand %s peer %s failed (continuing): %o', caller, strandId, entry.peerId, error);
+        });
+    }
     /**
      * 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
@@ -5431,7 +5694,9 @@ export class CadreNode {
      * 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.
      */
     async stopStrand(strandId) {
         if (!this._running) {
@@ -6580,7 +6845,7 @@ export class CadreNode {
             this.initializeStrandSolicitation();
         }
         const result = await this.strandSolicitationService.formStrand(invitation, disclosure, this.controlNode);
-        this.recordCrossPartyStrandAddrs(result.strandId, result.strandAddrs);
+        this.recordFormationStrandPeers(result.strandId, result.strandAddrs);
         // A closed host strand's approval carries the joiner's own membership invitation —
         // persist this party's identity key and stage the invitation for bring-up to redeem.
         // Runs AFTER the addr recording so a persistence failure (which throws — see the
@@ -6588,8 +6853,34 @@ export class CadreNode {
         if (result.membershipInvite) {
             await this.adoptFormationMembershipInvite(result.strandId, result.membershipInvite);
         }
+        await this.rememberFormedStrand(result);
         return result;
     }
+    /**
+     * 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.
+     */
+    async rememberFormedStrand(result) {
+        try {
+            await this.joinedStrandStore.record({
+                Id: result.strandId,
+                Type: result.memberPrivateKey ? 'c' : 'o',
+                MemberPrivateKey: result.memberPrivateKey ?? null,
+                joinedAt: Date.now()
+            });
+        }
+        catch (error) {
+            throw new Error(`Formation for strand ${result.strandId} was approved (its one-time token is spent), but ` +
+                'remembering the join in this node\'s joined-strand store failed, so the strand would not ' +
+                'come back after a restart. Fix the store (usually the configured keyStore), then redeem a ' +
+                'fresh invitation.', { cause: error });
+        }
+    }
     /**
      * Adopt an approved closed-strand formation's membership half on the JOINER:
      *
@@ -6731,35 +7022,41 @@ export class CadreNode {
     }
     /**
      * 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.
-     */
-    recordCrossPartyStrandAddrs(strandId, strandAddrs) {
+     * 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.
+     */
+    recordFormationStrandPeers(strandId, strandAddrs) {
         if (strandAddrs.length === 0) {
             log('formStrand: responder disclosed no strand addrs for %s — cross-party seed stays empty', strandId);
             return;
         }
-        // Capped at the same `MAX_STRAND_ADDRS` one arriving list is, because this
-        // ACCUMULATES: re-forming against the same strand (the documented recovery for a
-        // responder whose relay reservation rotated) unions a fresh list onto the old one,
-        // and nothing here can tell a dead entry from a live one. Without the cap, the seed
-        // — and the peerStore rows every refresh pass re-merges from it — would grow by up
-        // to 16 entries per redemption for the node's lifetime. Oldest entries fall off the
-        // end, which is the right end to lose: `unionAddrs` keeps the freshest list first.
-        const merged = unionAddrs(strandAddrs, this.crossPartyStrandAddrs.get(strandId) ?? [])
-            .slice(0, MAX_STRAND_ADDRS);
-        this.crossPartyStrandAddrs.set(strandId, merged);
+        const now = Date.now();
+        let peers = 0;
+        for (const [peerId, addrs] of groupAddrsByPeerId([...strandAddrs])) {
+            this.rememberStrandPeer(strandId, {
+                peerId,
+                addrs: addrs.map((ma) => ma.toString()),
+                issuedAt: 0,
+                lastSeenAt: now
+            }, 'formStrand');
+            peers++;
+        }
         // A strand already running when this lands (a re-formation) would otherwise wait out
         // the rest of its ~10-minute refresh throttle before the new addresses reached its
         // address book. Clearing the stamp makes the next 15 s reconcile tick merge them,
         // which matters precisely because re-forming is the recovery path for a dead entry.
         this.strandPeerAddrRefreshAt.delete(strandId);
-        log('formStrand: recorded %d cross-party strand addr(s) for %s', merged.length, strandId);
+        log('formStrand: recorded %d cross-party strand addr(s) for %s under %d peer(s)', strandAddrs.length, strandId, peers);
     }
     /**
      * Encode an open invitation for out-of-band delivery (QR, link, etc.).