@serfab/cadre-core 1.6.0 → 1.7.0

package/src/peer-join-backfill.ts

@@ -1,17 +1,28 @@
 import debug from 'debug';
-import type { Connection, Libp2p, PeerId } from '@libp2p/interface';
+import type { IdentifyResult, Libp2p, PeerId } from '@libp2p/interface';
 import type { ActionId, IPeerNetwork } from '@optimystic/db-core';
-import { BlockTransferClient, type BlockCommitProof, type IRawStorage } from '@optimystic/db-p2p';
+import { BlockTransferClient, buildBlockTransferProtocol, type BlockCommitProof, type IRawStorage } from '@optimystic/db-p2p';
 import { peerJoinPushBudget } from './link-budget.js';
 
 // Peer-join whole-store block catch-up, shared by the STRAND networks and the CONTROL
-// network. On `connection:open` (debounced) it pushes every committed, materialized block
-// in the local raw store to the new peer, so a machine that joined after blocks were
+// network. On a new peer's `peer:identify` result — libp2p's identify protocol runs once per
+// connection and reports the protocols the remote supports — naming this network's own
+// block-transfer protocol, it schedules a debounced push of every committed, materialized
+// block in the local raw store to that peer, so a machine that joined after blocks were
 // committed still ends up physically holding them. Optimystic has no cohort-join catch-up
 // of its own; a block committed while its writer was alone has exactly one holder forever
 // without this (named collection-header blocks are written once, at collection creation,
 // and their revision never moves again — so no later commit ever carries them anywhere).
 //
+// A peer whose identify does not name the protocol — a bare circuit relay, a bootstrap node,
+// or (on the control network) a stranger the inbound gate admits without membership — is
+// never scheduled at all: it cannot receive anything, since the protocol id is namespaced per
+// network and the dial would simply fail. Before this filter existed, such a peer WAS
+// scheduled, failed every dial, and after `PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES` produced a
+// `console.warn` naming it — gotchoices/sereus#18 is two relay-only parties restarting and
+// printing exactly that warning about their own relay, forever, on every reconnect. See
+// {@link speaksBlockTransfer}.
+//
 // NOTE: this copies the WHOLE local store to every newly connected peer, which is right
 // while a network is one party's handful of machines (see docs/architecture.md →
 // Replication cluster size — the control network replicates to the whole party by intent,
@@ -26,12 +37,10 @@ import { peerJoinPushBudget } from './link-budget.js';
 // Membership — the one place the two networks differ, expressed as the optional
 // `authorizePeer` dep:
 //
-// - STRAND networks pass none. Anything connected on a strand's own libp2p network already
-//   receives cohort replicas of new commits, so pushing older blocks to it exposes nothing
-//   new; adding a gate would diverge from what ordinary replication already does there. A
-//   peer that does NOT speak the strand's block-transfer protocol (a bare circuit relay or
-//   bootstrap node the strand node also connects to) cannot receive anything: the protocol
-//   id is namespaced per strand, so the dial fails and the push is dropped.
+// - STRAND networks pass none. Anything that speaks the strand's own block-transfer protocol
+//   already receives cohort replicas of new commits, so pushing older blocks to it exposes
+//   nothing new; adding a gate would diverge from what ordinary replication already does
+//   there.
 // - The CONTROL network MUST pass one, because that argument does not carry over: its
 //   inbound connection gate deliberately admits non-members in several states (an
 //   un-enrolled node taking its seed, an open enrollment window, an outstanding
@@ -40,8 +49,8 @@ import { peerJoinPushBudget } from './link-budget.js';
 //   peer would hand a stranger the party's entire membership, addresses and strand list.
 //   `CadreNode` passes `isAuthorizedMember`; the gate is consulted at PUSH time, not at
 //   schedule time, and fails closed on a thrown check. A denied run is not memoized, so
-//   the peer is retried on its next `connection:open` — or sooner, via
-//   `scheduleConnectedPeers()` on a membership change (the production join order is
+//   the peer is retried on its next `peer:identify` (a reconnect re-runs identify) — or
+//   sooner, via `scheduleConnectedPeers()` on a membership change (the production join order is
 //   connect-then-authorize, so the denial at dial time is the expected first pass).
 //
 // Both per-push deadlines are DERIVED from the declared link round trip
@@ -62,14 +71,14 @@ import { peerJoinPushBudget } from './link-budget.js';
 //
 // RETRY, and why it backs off. A run whose PUSH FAILED — the transport threw, which is what
 // a dial or response deadline expiring looks like here — re-arms on a doubling backoff
-// (`retryBackoffMs` to `maxRetryBackoffMs`), and a `connection:open` arriving while that wait
+// (`retryBackoffMs` to `maxRetryBackoffMs`), and a `peer:identify` arriving while that wait
 // is outstanding is DROPPED rather than collapsing it back to the debounce. Both halves are
 // load-bearing:
 //
 // - Without the re-arm, a transient push failure over a stable connection left the peer
 //   partially copied until its next reconnect (read repair still covered reads meanwhile).
 // - Without dropping churn inside the wait, a peer that cannot be reached at all is
-//   re-dialled on every `connection:open` forever. That is not hypothetical: the 2026-09-26
+//   re-dialled on every `peer:identify` forever. That is not hypothetical: the 2026-09-26
 //   relayed reproduction shows one peer re-opening a connection about every 14.5 s for a
 //   200-second run, each event starting a catch-up whose dial could not possibly finish.
 //   The connection kept re-appearing because Optimystic's own block-transfer push path
@@ -87,13 +96,13 @@ import { peerJoinPushBudget } from './link-budget.js';
 // {@link Chunk.proofs}). Re-arming on those would re-push the WHOLE store to that peer every
 // `maxRetryBackoffMs` for as long as the node runs, and report the failure below as a link
 // budget problem when nothing about the link is wrong. All three still leave the peer
-// un-memoized, so its next `connection:open` retries — the behaviour that predates the
+// un-memoized, so its next `peer:identify` retries — the behaviour that predates the
 // backoff, and the right one for a verdict rather than a timeout. Denial in particular is
 // re-driven on purpose by `scheduleConnectedPeers()` the moment the membership commit lands,
 // because the control network's join order is connect-then-authorize.
 //
 // A re-arm is also skipped when the peer is no longer CONNECTED. This module's trigger is
-// `connection:open`, so a peer that went away already has one: re-arming instead would leave
+// `peer:identify`, so a peer that went away already has one: re-arming instead would leave
 // a machine dialing a peer it cannot see once a minute for the rest of its uptime.
 //
 // After `PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES` consecutive failures one `console.warn`
@@ -101,16 +110,25 @@ import { peerJoinPushBudget } from './link-budget.js';
 // nothing at all: the connection simply never appears and only a DEBUG log mentions a dial
 // timeout.
 //
-// NOTE: a failing dial to a non-speaking peer costs one dial timeout per attempt, and is
-// never memoized (only clean runs are). Bounded by the backoff above plus the
-// unreachable-peer bail in `runCatchUp` — one dial per attempt, not one per chunk. If a node
-// ever holds many such connections, or the enumeration ahead of the first chunk gets
-// expensive, pre-check `libp2p.peerStore` for this network's block-transfer protocol before
-// enumerating.
+// NOTE: the protocol check happens once — either when a connection's `peer:identify` fires,
+// or, for a peer already connected when this instance starts, when `scheduleConnectedPeers()`
+// reads its protocols back from the peer store — and is never repeated once a peer is
+// scheduled. A peer that stops speaking the protocol after being scheduled (should that ever
+// happen) is not de-scheduled; `runCatchUp`'s own unreachable-peer bail is what would catch
+// that case instead. `peer:identify` also fires on every identify-push from a connected peer
+// (address or protocol changes), which only re-enters the debounce — cheap, and dropped
+// outright for caught-up peers and peers inside a backoff wait.
+//
+// NOTE: a same-network peer whose identify never completes on a connection (the identify
+// stream times out over a slow relayed link, say) is not caught up until a later identify
+// succeeds — a reconnect, an identify-push, or on the control network a membership-change
+// re-drive. Accepted: every db-p2p node runs identify, and read repair still covers reads
+// meanwhile; if relayed links ever routinely outlast identify's timeout, raise that timeout
+// in the node builder rather than scheduling unidentified peers here.
 //
 // NOTE: a peer that disconnects INSIDE a backoff wait still costs the one attempt that wait
 // was already armed for — the connectivity check is made when the re-arm is decided, not when
-// the timer fires, and this module subscribes to `connection:open` only. One dial, not a
+// the timer fires, and this module subscribes to `peer:identify` only. One dial, not a
 // recurring one; if a node ever holds many transient peers, subscribe to `connection:close`
 // and clear the pending timer there.
 
@@ -124,6 +142,18 @@ const log = debug('sereus:cadre:peer-join-backfill');
  */
 export const MAX_BLOCK_MESSAGE_BYTES = 8 * 1024 * 1024;
 
+/**
+ * Whether an identified peer's protocol list names this network's own block-transfer
+ * protocol — the one gate that decides whether {@link PeerJoinBackfill} schedules a peer at
+ * all. A peer that lacks it (a bare circuit relay, a bootstrap node, a stranger the control
+ * network's inbound gate admitted without membership) cannot receive a push no matter how
+ * long it is dialed, since the protocol id is namespaced per network. Exported because a
+ * later strand peer-address ticket's identify-driven observation needs the identical test.
+ */
+export function speaksBlockTransfer(protocols: readonly string[], protocolPrefix: string): boolean {
+  return protocols.includes(buildBlockTransferProtocol(protocolPrefix));
+}
+
 /**
  * Consecutive failed catch-up runs against ONE peer before the module says so on
  * `console.warn` rather than only in its DEBUG log. At the default backoff that is reached
@@ -277,7 +307,7 @@ function base64WireBytes(rawBytes: number): number {
  * Best-effort throughout: nothing here throws into a libp2p event handler or into a
  * runtime bring-up; a failed chunk is logged and the run continues. A peer is marked
  * fully caught up ONLY after a run with no thrown chunk and an empty `missing` list, so
- * the next `connection:open` from a peer whose catch-up failed retries it.
+ * the next `peer:identify` from a peer whose catch-up failed retries it.
  */
 export class PeerJoinBackfill {
   private readonly config: Required<PeerJoinBackfillConfig>;
@@ -303,31 +333,43 @@ export class PeerJoinBackfill {
   private readonly failures = new Map<string, number>();
   /**
    * Epoch ms before which a peer's catch-up must not be re-run, set alongside a backoff timer
-   * that will run it. Its presence is what makes `connection:open` churn free: a schedule
+   * that will run it. Its presence is what makes `peer:identify` churn free: a schedule
    * arriving inside the wait is dropped, rather than collapsing the backoff to the debounce.
    */
   private readonly retryAfter = new Map<string, number>();
   /** Peers already reported on `console.warn`; reset when a run finally lands cleanly. */
   private readonly warned = new Set<string>();
-  private readonly onConnectionOpen: (evt: CustomEvent<Connection>) => void;
+  private readonly onPeerIdentify: (evt: CustomEvent<IdentifyResult>) => void;
   private loggedNoListBlockIds = false;
 
   constructor(private readonly deps: PeerJoinBackfillDeps, config?: PeerJoinBackfillConfig) {
     this.config = { ...DEFAULT_PEER_JOIN_BACKFILL, ...config };
     this.createPushClient = deps.createPushClient
       ?? ((peerId) => new BlockTransferClient(peerId, deps.peerNetwork, deps.protocolPrefix));
-    this.onConnectionOpen = (evt) => this.schedulePeer(evt.detail.remotePeer);
+    this.onPeerIdentify = (evt) => {
+      const { peerId, protocols } = evt.detail;
+      if (speaksBlockTransfer(protocols, this.deps.protocolPrefix)) {
+        this.schedulePeer(peerId);
+      }
+    };
   }
 
-  /** Subscribe to connection:open AND schedule a catch-up for peers already connected. */
+  /**
+   * Subscribe to `peer:identify` AND schedule a catch-up for already-connected peers whose
+   * stored protocols already name this network's block-transfer protocol — a peer that does
+   * not speak it (a bare circuit relay, a bootstrap node) is never scheduled at all. See
+   * {@link speaksBlockTransfer} and the module comment.
+   */
   start(): void {
     if (this.started || this.stopped || !this.config.enabled) return;
     this.started = true;
-    this.deps.libp2p.addEventListener('connection:open', this.onConnectionOpen);
-    // A runtime rebuilt over live connections (resumeStrand) never sees their
-    // connection:open, so walk what is already connected once.
-    const scheduled = this.scheduleConnectedPeers();
-    log('[%s] started (%d peer(s) already connected)', this.deps.label, scheduled);
+    this.deps.libp2p.addEventListener('peer:identify', this.onPeerIdentify);
+    // A runtime rebuilt over live connections (resumeStrand) never sees their peer:identify —
+    // it already fired before this instance existed, but its result is persisted in the peer
+    // store — so walk what is already connected once.
+    void this.scheduleConnectedPeers().then((scheduled) => {
+      log('[%s] started (%d peer(s) already connected)', this.deps.label, scheduled);
+    });
   }
 
   /** Unsubscribe, clear timers; in-flight runs observe the stopped flag and bail. */
@@ -335,7 +377,7 @@ export class PeerJoinBackfill {
     if (this.stopped) return;
     this.stopped = true;
     if (this.started) {
-      this.deps.libp2p.removeEventListener('connection:open', this.onConnectionOpen);
+      this.deps.libp2p.removeEventListener('peer:identify', this.onPeerIdentify);
     }
     for (const timer of this.timers.values()) {
       clearTimeout(timer);
@@ -347,27 +389,46 @@ export class PeerJoinBackfill {
   }
 
   /**
-   * (Re-)schedule a debounced catch-up for every currently-connected peer not yet caught
-   * up. Idempotent and cheap (caught-up peers are skipped before any timer is set, and a
-   * peer whose run is in flight is deferred to the end of that run rather than dropped).
-   * Driven by {@link start}, and — on a gated network — by the embedder whenever
-   * membership changes, so a peer whose first pass was denied (connected before it was
-   * authorized: the production join order) is retried without waiting for a reconnect.
-   * Returns how many distinct peers were considered (for the start() log) — a peer holding
-   * several connections is one peer, and is scheduled once.
+   * (Re-)schedule a debounced catch-up for every currently-connected peer whose protocols, as
+   * already stored in the libp2p peer store, name this network's block-transfer protocol. A
+   * peer not yet in the peer store — its identify has not finished — is left to the
+   * `peer:identify` handler rather than dialed blind; one whose stored protocols are known
+   * and lack ours is skipped outright. Idempotent and cheap otherwise (caught-up peers are
+   * skipped before any timer is set, and a peer whose run is in flight is deferred to the end
+   * of that run rather than dropped). Driven by {@link start}, and — on a gated network — by
+   * the embedder whenever membership changes, so a peer whose first pass was denied (connected
+   * before it was authorized: the production join order) is retried without waiting for a
+   * reconnect. Returns how many distinct peers were considered (for the start() log) — a peer
+   * holding several connections is one peer, and is scheduled once.
    */
-  scheduleConnectedPeers(): number {
+  async scheduleConnectedPeers(): Promise<number> {
     if (this.stopped) return 0;
-    const peers = new Set<string>();
+    const peers = new Map<string, PeerId>();
     for (const connection of this.deps.libp2p.getConnections()) {
-      const key = connection.remotePeer.toString();
-      if (peers.has(key)) continue;
-      peers.add(key);
-      this.schedulePeer(connection.remotePeer);
+      peers.set(connection.remotePeer.toString(), connection.remotePeer);
     }
+    await Promise.all([...peers.values()].map((peerId) => this.scheduleIfKnownToSpeak(peerId)));
     return peers.size;
   }
 
+  /** Schedules `peerId` only if the peer store already knows it speaks this network's protocol. */
+  private async scheduleIfKnownToSpeak(peerId: PeerId): Promise<void> {
+    let protocols: string[];
+    try {
+      ({ protocols } = await this.deps.libp2p.peerStore.get(peerId));
+    } catch (error) {
+      // NotFoundError: identify has not finished. Leave it to the `peer:identify` handler
+      // rather than dialing blind. Anything else is unexpected — log it and skip the peer.
+      if ((error as Error).name !== 'NotFoundError') {
+        log('[%s] peer store read for %s failed — not scheduling: %o', this.deps.label, peerId.toString(), error);
+      }
+      return;
+    }
+    if (speaksBlockTransfer(protocols, this.deps.protocolPrefix)) {
+      this.schedulePeer(peerId);
+    }
+  }
+
   /** Debounced entry point for connection churn: one run per peer per settle window. */
   private schedulePeer(peerId: PeerId): void {
     const key = peerId.toString();
@@ -380,7 +441,7 @@ export class PeerJoinBackfill {
     }
     // A peer whose last run failed is already re-armed on a backoff timer that will run it, so
     // DROP this schedule instead of shortening the wait — otherwise a peer that cannot be
-    // reached is re-dialled on every connection:open forever (see the module comment's retry
+    // reached is re-dialled on every peer:identify forever (see the module comment's retry
     // paragraph). A denied run never gets here: it does not set a backoff.
     const retryAt = this.retryAfter.get(key);
     if (retryAt !== undefined && Date.now() < retryAt) return;
@@ -420,7 +481,7 @@ export class PeerJoinBackfill {
         // rejection are all verdicts a retry cannot change, and re-arming on them would
         // re-push the whole store to that peer forever. See the module comment.
         //
-        // Gated on `started` too: the re-arm exists to REPLACE a connection:open-driven retry,
+        // Gated on `started` too: the re-arm exists to REPLACE a peer:identify-driven retry,
         // so a caller driving `catchUpPeer` by hand against a backfill that was never started
         // owns its own retry policy and must not be left holding a background timer.
         this.scheduleRetryWithBackoff(peerId);
@@ -452,7 +513,7 @@ export class PeerJoinBackfill {
   /**
    * Re-arm one peer's catch-up after a run whose push failed, on a wait that doubles
    * per consecutive failure up to `maxRetryBackoffMs`. Sets {@link retryAfter} alongside the
-   * timer, which is what makes `connection:open` churn inside the wait free.
+   * timer, which is what makes `peer:identify` churn inside the wait free.
    */
   private scheduleRetryWithBackoff(peerId: PeerId): void {
     const key = peerId.toString();

package/src/strand-instance-manager.ts

@@ -4,6 +4,9 @@ import { createLibp2pNode, type IRawStorage } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { StrandDatabase } from './strand-database.js';
 import { PeerJoinBackfill, type PeerJoinBackfillConfig } from './peer-join-backfill.js';
+import { StrandPeerObserver, type StrandPeerObservation } from './strand-peer-observer.js';
+import { StrandPeerBookSwap } from './strand-peer-book-swap.js';
+import type { StrandPeerBookStore } from './strand-peer-book.js';
 import {
   StrandRevocationEnforcer,
   createRevocationConnectionGater,
@@ -261,6 +264,28 @@ export interface StartStrandConfig {
    * hibernation wake's rebuilt supervisors carry it too.
    */
   announceDelegateToRelay?: (strandId: string, relayAddr: string, delegatePeerId: string) => Promise<void>;
+
+  /**
+   * Called when the strand's libp2p node identifies a STRAND peer — one whose
+   * identify result names this strand's block-transfer protocol, so never the
+   * circuit relay or a bootstrap node — with the addresses it is dialable at
+   * (`strand-peer-observer.ts`). Throttled per peer; must not throw. `CadreNode`
+   * wires it to the node-local strand peer book, which is what lets a restarted
+   * machine dial the peers it was talking to. Absent ⇒ nothing is observed.
+   * Retained with the launch config, so a hibernation wake re-arms it on the
+   * rebuilt node.
+   */
+  onStrandPeerIdentified?: (strandId: string, observation: StrandPeerObservation) => void;
+
+  /**
+   * The node-local strand peer book the book SWAP reads and writes
+   * (`strand-peer-book-swap.ts`): the strand node signs its own addresses with
+   * {@link privateKey}, exchanges signed entries with every strand peer it identifies,
+   * and files what verifies. Absent ⇒ no swap runs — a peer that dials this node's
+   * swap handler gets no answer. `CadreNode` passes its book store. Retained with the
+   * launch config, so a hibernation wake re-arms the swap on the rebuilt node.
+   */
+  strandPeerBook?: StrandPeerBookStore;
 }
 
 /**
@@ -370,6 +395,24 @@ export class StrandInstanceManager {
    * missed writes).
    */
   private backfills: Map<string, PeerJoinBackfill> = new Map();
+  /**
+   * The per-strand peer-book observation writer (`strand-peer-observer.ts`), keyed
+   * by strand id. Same lifecycle rationale as {@link backfills}: started in
+   * `buildStrandRuntime` right after the libp2p node exists, stopped and dropped in
+   * `releaseRuntime`, so quiesce → resume re-arms it on the rebuilt node. Only
+   * present when the launch config supplied `onStrandPeerIdentified`.
+   */
+  private peerObservers: Map<string, StrandPeerObserver> = new Map();
+
+  /**
+   * Per-strand strand peer book SWAP driver ({@link StrandPeerBookSwap}) — the signed
+   * exchange of book entries between strand peers. Same lifetime as the peer-book
+   * observer above: armed in `buildStrandRuntime` right after the libp2p node exists
+   * (its protocol handler must be registered before an early peer dials it), stopped
+   * and dropped in `releaseRuntime`. Only present when the launch config supplied
+   * `strandPeerBook`.
+   */
+  private peerBookSwaps: Map<string, StrandPeerBookSwap> = new Map();
   /**
    * The per-strand revoked-peer enforcer (closed strands only), keyed by strand
    * id. Same lifecycle rationale as {@link backfills}: created in
@@ -734,6 +777,48 @@ export class StrandInstanceManager {
 
       instance.libp2pNode = node;
 
+      // The peer-book observation writer, armed BEFORE the database bring-up below
+      // (unlike the backfill) because the bootstrap dials that follow `libp2p.start()`
+      // land during that bring-up, and they are exactly the peers worth remembering:
+      // identify for an early peer may already have fired by the time anything after
+      // the database initializes runs. Registered in the map immediately so the
+      // failure rollback (releaseRuntime) stops it like every other runtime component.
+      const onStrandPeerIdentified = config.onStrandPeerIdentified;
+      if (onStrandPeerIdentified) {
+        const observer = new StrandPeerObserver({
+          label: strandId,
+          libp2p: node,
+          protocolPrefix,
+          onObserved: (observation) => onStrandPeerIdentified(strandId, observation)
+        });
+        this.peerObservers.set(strandId, observer);
+        observer.start();
+      }
+
+      // The strand peer book SWAP, armed at the same moment and for the same reason as
+      // the observer: a peer that dials this node's swap handler before it is registered
+      // fails its exchange and sits out a ten-minute throttle. The own entry is signed
+      // now and re-signed on every address change, which covers the relay reservation
+      // landing below (`self:peer:update` fires when the circuit addr is added), so no
+      // separate post-relay step is needed. Registered in the map immediately so the
+      // failure rollback (releaseRuntime) stops it like every other runtime component.
+      //
+      // NOTE: this is a third `peer:identify` listener per running strand, beside the
+      // observer's and the backfill's — see the backfill's NOTE below for when to fold
+      // them into one dispatcher.
+      if (config.strandPeerBook) {
+        const swap = new StrandPeerBookSwap({
+          strandId,
+          libp2p: node,
+          protocolPrefix,
+          store: config.strandPeerBook,
+          privateKey: config.privateKey,
+          linkRoundTripMs: config.network?.linkRoundTripMs
+        });
+        this.peerBookSwaps.set(strandId, swap);
+        swap.start();
+      }
+
       // One reservation supervisor PER RELAY, started now so the first attempts
       // overlap the database bring-up below (the relay is never in a strand's
       // Optimystic cohort — its protocol ids are namespaced `/optimystic/strand-<id>/…`
@@ -850,7 +935,7 @@ export class StrandInstanceManager {
       // peer-join-backfill.ts for the strand-side argument (and why the control
       // network, which DOES gate, is different).
       //
-      // NOTE: cost is one PeerJoinBackfill object + one `connection:open` listener
+      // NOTE: cost is one PeerJoinBackfill object + one `peer:identify` listener
       // per running strand — linear in strand count, negligible at the handful a
       // device or host runs today. If a node ever hosts strands by the hundred,
       // move to one shared listener that dispatches by strand id.
@@ -946,6 +1031,20 @@ export class StrandInstanceManager {
       backfill.stop();
       this.backfills.delete(instance.strandId);
     }
+    // The peer-book observer goes with the node it listened on; a resume re-arms
+    // one on the rebuilt node.
+    const peerObserver = this.peerObservers.get(instance.strandId);
+    if (peerObserver) {
+      peerObserver.stop();
+      this.peerObservers.delete(instance.strandId);
+    }
+    // The book swap likewise: unsubscribed and its handler unregistered while the node is
+    // still up; a resume re-arms one, which re-signs the own entry over the new addresses.
+    const peerBookSwap = this.peerBookSwaps.get(instance.strandId);
+    if (peerBookSwap) {
+      this.peerBookSwaps.delete(instance.strandId);
+      await peerBookSwap.stop();
+    }
     // The revoked-peer enforcer goes with the runtime it gated: a resume
     // rebuilds it with a fresh (initially empty, fail-open) snapshot.
     const revocationEnforcer = this.revocationEnforcers.get(instance.strandId);

package/src/strand-peer-book-file.ts

@@ -0,0 +1,39 @@
+/**
+ * Node-only file-backed {@link StrandPeerBookStore}: one JSON file per party under
+ * a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated strand
+ * peer book (the strand peers this node has met, with their last-known addresses).
+ *
+ * Nothing but the file itself lives here: the envelope, load policy, per-entry
+ * validation, the merge rule and the serialised snapshot writes are cross-platform
+ * in `PersistentStrandPeerBookStore` / `node-local-snapshot.ts`, and the file is a
+ * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of the
+ * package's cross-platform default entry (`./index.js`) — import it from the
+ * dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileStrandPeerBookStore } from '@serfab/cadre-core/strand-peer-book-file';
+ * ```
+ *
+ * Same isolation pattern as `bootstrap-peer-store-file.ts` / `key-store-file.ts`.
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentStrandPeerBookStore } from './strand-peer-book.js';
+import type { StrandPeerBookOptions, StrandPeerBookStore } from './strand-peer-book.js';
+
+/** Base name of the store file: `<dir>/strand-peers.<encoded partyId>.json`. */
+const SLOT_NAME = 'strand-peers';
+
+/**
+ * File-backed {@link StrandPeerBookStore}. Open via {@link open}, which loads the
+ * existing file and returns the cross-platform store over it; an absent, corrupt,
+ * or wrong-party file is a cold start (empty book) and structurally junk or
+ * aged-out entries are dropped, while a present-but-unreadable file throws. Those
+ * rules and their reasoning live on `NodeLocalSnapshot.open`.
+ */
+export const FileStrandPeerBookStore = {
+	/** Load (or cold-start) the party's strand peer book from a file in `dir`. */
+	async open(dir: string, partyId: string, options?: StrandPeerBookOptions): Promise<StrandPeerBookStore> {
+		return PersistentStrandPeerBookStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId, options);
+	}
+};