@serfab/cadre-core 1.8.0 → 1.10.0

package/dist/strand-formation-rejection.d.ts

@@ -0,0 +1,94 @@
+/**
+ * How a formation dial fails, as types a joining device can branch on without reading the
+ * human-facing wording: a responder's refusal carries a fixed {@link FormationRejectionCode}
+ * on the wire and surfaces as a {@link FormationRejectedError}; a dial that never got an
+ * answer surfaces as a {@link FormationUnreachableError}.
+ */
+/**
+ * Why a formation responder refused a join. Sent beside the free-text `reason` on every
+ * `approved: false` result frame (`FormationResultMessage.code`).
+ */
+export type FormationRejectionCode = 
+/**
+ * No invitation row for this token on THIS responder. Retryable: a sibling machine of the
+ * inviter may not have received the row yet. Leaks nothing — only a holder of the token can
+ * ask, and an unknown token means the same as one never minted.
+ */
+'token-unknown'
+/**
+ * The invitation expired, or every allowed use is recorded. The loser of a redemption race
+ * and a latecomer both get this code, so neither can tell the two apart.
+ */
+ | 'token-spent'
+/** The joiner's consent signature does not verify (or `partyId` does not embed `peerKey`). */
+ | 'consent-invalid'
+/** The responder's disclosure validator refused the disclosure. */
+ | 'disclosure-invalid' | 'disclosure-too-large'
+/** The invitation's outside approval hook answered no. */
+ | 'approval-refused'
+/** The invitation's outside approval hook could not be reached or did not answer in time. */
+ | 'approval-unavailable'
+/** The inviter's approval setup is wrong: a malformed answer, an unenrolled key, or a misconfigured hook. */
+ | 'approval-invalid'
+/**
+ * The host strand is not running (or not yet replicated) on this responder, or issuing the
+ * joiner's membership invitation into it failed.
+ */
+ | 'host-strand-unavailable'
+/** The host strand predates the per-party identity split and can never admit a joiner. */
+ | 'host-strand-must-be-recreated'
+/** The responder is at its cap on concurrent formation sessions. */
+ | 'busy'
+/** Provisioning outran the responder's budget; the invitation is left unspent. */
+ | 'provisioning-timeout'
+/** The consent write failed for a reason other than a spent invitation. */
+ | 'conflict'
+/** An unexpected responder-side failure. */
+ | 'internal';
+/**
+ * Which rejections are worth retrying — the single place that says so. A retry repeats the
+ * same redemption later (or against another of the inviter's machines); a final code means
+ * no retry of this invitation can succeed.
+ */
+export declare const FORMATION_REJECTION_RETRYABLE: Readonly<Record<FormationRejectionCode, boolean>>;
+/** Is `value` a code this build knows? Own keys only, so a peer's `'constructor'` does not pass. */
+export declare function isFormationRejectionCode(value: unknown): value is FormationRejectionCode;
+/**
+ * The responder answered and refused the join.
+ *
+ * `code` is `'unrecognized'` when the frame carried no code or one this build does not know
+ * — formation runs between two parties on different versions — and such a rejection counts
+ * as retryable: retrying an unknown answer until the invitation expires is safe, while giving
+ * up on one that would have succeeded is not.
+ */
+export declare class FormationRejectedError extends Error {
+    readonly code: FormationRejectionCode | 'unrecognized';
+    readonly reason: string;
+    readonly retryable: boolean;
+    /** Both arguments come straight off the wire, so neither is trusted to have its declared type. */
+    constructor(code: unknown, reason: unknown);
+}
+/**
+ * The dial ended before a result frame was read: no responder address parsed, every address
+ * failed to dial, a deadline passed, or the stream closed early. Always retryable. Keeps the
+ * underlying failure's message, and the failure itself as `cause`.
+ */
+export declare class FormationUnreachableError extends Error {
+    readonly retryable = true;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The responder approved the join, so the invitation's one-time token is spent, and then a
+ * step on the joining machine failed: persisting the party's membership identity, or
+ * remembering the join. Never retryable: the same invitation can only answer `token-spent`
+ * from now on, so recovery is fixing the local cause and redeeming a fresh invitation.
+ */
+export declare class FormationPostApprovalError extends Error {
+    readonly strandId: string;
+    readonly retryable = false;
+    constructor(strandId: string, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/strand-formation-rejection.js

@@ -0,0 +1,77 @@
+/**
+ * How a formation dial fails, as types a joining device can branch on without reading the
+ * human-facing wording: a responder's refusal carries a fixed {@link FormationRejectionCode}
+ * on the wire and surfaces as a {@link FormationRejectedError}; a dial that never got an
+ * answer surfaces as a {@link FormationUnreachableError}.
+ */
+/**
+ * Which rejections are worth retrying — the single place that says so. A retry repeats the
+ * same redemption later (or against another of the inviter's machines); a final code means
+ * no retry of this invitation can succeed.
+ */
+export const FORMATION_REJECTION_RETRYABLE = {
+    'token-unknown': true,
+    'token-spent': false,
+    'consent-invalid': false,
+    'disclosure-invalid': false,
+    'disclosure-too-large': false,
+    'approval-refused': false,
+    'approval-unavailable': true,
+    'approval-invalid': false,
+    'host-strand-unavailable': true,
+    'host-strand-must-be-recreated': false,
+    'busy': true,
+    'provisioning-timeout': true,
+    'conflict': true,
+    'internal': true
+};
+/** Is `value` a code this build knows? Own keys only, so a peer's `'constructor'` does not pass. */
+export function isFormationRejectionCode(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(FORMATION_REJECTION_RETRYABLE, value);
+}
+/**
+ * The responder answered and refused the join.
+ *
+ * `code` is `'unrecognized'` when the frame carried no code or one this build does not know
+ * — formation runs between two parties on different versions — and such a rejection counts
+ * as retryable: retrying an unknown answer until the invitation expires is safe, while giving
+ * up on one that would have succeeded is not.
+ */
+export class FormationRejectedError extends Error {
+    /** Both arguments come straight off the wire, so neither is trusted to have its declared type. */
+    constructor(code, reason) {
+        const text = typeof reason === 'string' ? reason : 'no reason provided';
+        super(`Formation rejected: ${text}`);
+        this.name = 'FormationRejectedError';
+        this.code = isFormationRejectionCode(code) ? code : 'unrecognized';
+        this.reason = text;
+        this.retryable = this.code === 'unrecognized' || FORMATION_REJECTION_RETRYABLE[this.code];
+    }
+}
+/**
+ * The dial ended before a result frame was read: no responder address parsed, every address
+ * failed to dial, a deadline passed, or the stream closed early. Always retryable. Keeps the
+ * underlying failure's message, and the failure itself as `cause`.
+ */
+export class FormationUnreachableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.retryable = true;
+        this.name = 'FormationUnreachableError';
+    }
+}
+/**
+ * The responder approved the join, so the invitation's one-time token is spent, and then a
+ * step on the joining machine failed: persisting the party's membership identity, or
+ * remembering the join. Never retryable: the same invitation can only answer `token-spent`
+ * from now on, so recovery is fixing the local cause and redeeming a fresh invitation.
+ */
+export class FormationPostApprovalError extends Error {
+    constructor(strandId, message, options) {
+        super(message, options);
+        this.strandId = strandId;
+        this.retryable = false;
+        this.name = 'FormationPostApprovalError';
+    }
+}
+//# sourceMappingURL=strand-formation-rejection.js.map

package/dist/strand-formation-rejection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strand-formation-rejection.js","sourceRoot":"","sources":["../src/strand-formation-rejection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6CH;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAsD;IAC9F,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,KAAK;IACpB,iBAAiB,EAAE,KAAK;IACxB,oBAAoB,EAAE,KAAK;IAC3B,sBAAsB,EAAE,KAAK;IAC7B,kBAAkB,EAAE,KAAK;IACzB,sBAAsB,EAAE,IAAI;IAC5B,kBAAkB,EAAE,KAAK;IACzB,yBAAyB,EAAE,IAAI;IAC/B,+BAA+B,EAAE,KAAK;IACtC,MAAM,EAAE,IAAI;IACZ,sBAAsB,EAAE,IAAI;IAC5B,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;CACjB,CAAC;AAEF,oGAAoG;AACpG,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;AACjH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAK/C,kGAAkG;IAClG,YAAY,IAAa,EAAE,MAAe;QACxC,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC;QACxE,KAAK,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC;QACnE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,KAAK,cAAc,IAAI,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5F,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAGlD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAHjB,cAAS,GAAG,IAAI,CAAC;QAIxB,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAGnD,YAAqB,QAAgB,EAAE,OAAe,EAAE,OAA6B;QACnF,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QADL,aAAQ,GAAR,QAAQ,CAAQ;QAF5B,cAAS,GAAG,KAAK,CAAC;QAIzB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}

package/dist/strand-fret-addrs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Reading the signed address records a running strand node's FRET routing table holds,
+ * as per-peer addresses ready for that node's own address book (`peer-addr-book.ts`).
+ *
+ * Why a strand node needs this. libp2p's peerStore hides every address one hour after
+ * it was first observed (the `NOTE:` on `mergePeerAddrs`), and FRET does not re-apply
+ * the records it holds: it hands a record to the peerStore when a neighbour's snapshot
+ * delivers it or a saved table is imported, and the peerStore refuses a record whose
+ * sequence number it already has. So a strand node that has been up for more than an
+ * hour would have no address for a peer whose connection then drops, although FRET
+ * still holds that peer's record. `CadreNode.refreshStrandPeerAddrs` re-merges the
+ * records on every pass, which is what keeps another party's strand nodes dialable;
+ * own-party siblings are re-resolved separately, over the strand-addr RPC.
+ *
+ * How long a record is available here is FRET's rule, not this module's: while FRET
+ * holds the entry, and at most 14 days after the record was last confirmed (a peer
+ * connected at export time counts as confirmed then).
+ *
+ * Every record is opened and verified here rather than taken on FRET's word. A record
+ * is self-certifying, the table is reached through a structural type rather than an
+ * interface this package depends on, and the address book write is attributed from what
+ * the record proves, not from the id the table filed it under.
+ */
+import { type Multiaddr } from '@multiformats/multiaddr';
+/**
+ * The slice of a strand's libp2p node this module touches. Structurally satisfied by
+ * `Libp2p`; db-p2p registers FRET as `services.fret`.
+ */
+export interface FretAddrHost {
+    peerId: {
+        toString(): string;
+    };
+    services?: Record<string, unknown>;
+}
+/** What one read of a strand node's FRET table yields. */
+export interface FretPeerAddrs {
+    /** Peer id → the addresses its record lists, each bound to that peer. Table order. */
+    peers: Map<string, Multiaddr[]>;
+    /**
+     * Records left out because they did not decode, did not verify, or were not signed
+     * by and about the peer the table filed them under.
+     */
+    rejected: number;
+}
+/**
+ * The addresses of every peer `host`'s FRET table holds a usable signed record for,
+ * `host` itself excluded. A node with no FRET service (a db-p2p build without it, a
+ * test double) reads as an empty table. One bad record never costs the others: it is
+ * counted in `rejected` and skipped.
+ *
+ * Throws only what `exportTable()` throws, which a caller treats like any other
+ * failure of a pass over a node that may be mid-teardown.
+ */
+export declare function strandFretPeerAddrs(host: FretAddrHost): Promise<FretPeerAddrs>;

package/dist/strand-fret-addrs.js

@@ -0,0 +1,108 @@
+/**
+ * Reading the signed address records a running strand node's FRET routing table holds,
+ * as per-peer addresses ready for that node's own address book (`peer-addr-book.ts`).
+ *
+ * Why a strand node needs this. libp2p's peerStore hides every address one hour after
+ * it was first observed (the `NOTE:` on `mergePeerAddrs`), and FRET does not re-apply
+ * the records it holds: it hands a record to the peerStore when a neighbour's snapshot
+ * delivers it or a saved table is imported, and the peerStore refuses a record whose
+ * sequence number it already has. So a strand node that has been up for more than an
+ * hour would have no address for a peer whose connection then drops, although FRET
+ * still holds that peer's record. `CadreNode.refreshStrandPeerAddrs` re-merges the
+ * records on every pass, which is what keeps another party's strand nodes dialable;
+ * own-party siblings are re-resolved separately, over the strand-addr RPC.
+ *
+ * How long a record is available here is FRET's rule, not this module's: while FRET
+ * holds the entry, and at most 14 days after the record was last confirmed (a peer
+ * connected at export time counts as confirmed then).
+ *
+ * Every record is opened and verified here rather than taken on FRET's word. A record
+ * is self-certifying, the table is reached through a structural type rather than an
+ * interface this package depends on, and the address book write is attributed from what
+ * the record proves, not from the id the table filed it under.
+ */
+import debug from 'debug';
+import { PeerRecord, RecordEnvelope } from '@libp2p/peer-record';
+import { peerIdFromPublicKey } from '@libp2p/peer-id';
+import { multiaddr } from '@multiformats/multiaddr';
+import { fromString as uint8ArrayFromString } from 'uint8arrays';
+import { withTrailingPeerId } from './peer-record.js';
+const log = debug('sereus:cadre:strand-fret-addrs');
+/**
+ * The addresses of every peer `host`'s FRET table holds a usable signed record for,
+ * `host` itself excluded. A node with no FRET service (a db-p2p build without it, a
+ * test double) reads as an empty table. One bad record never costs the others: it is
+ * counted in `rejected` and skipped.
+ *
+ * Throws only what `exportTable()` throws, which a caller treats like any other
+ * failure of a pass over a node that may be mid-teardown.
+ */
+export async function strandFretPeerAddrs(host) {
+    const result = { peers: new Map(), rejected: 0 };
+    const fret = host.services?.fret;
+    if (!isFretTableSource(fret)) {
+        return result;
+    }
+    const selfId = host.peerId.toString();
+    for (const entry of fret.exportTable().entries) {
+        if (entry.id === selfId || entry.addressRecord === undefined) {
+            continue;
+        }
+        const addrs = await verifiedRecordAddrs(entry.id, entry.addressRecord.envelope);
+        if (addrs === null) {
+            result.rejected++;
+        }
+        else if (addrs.length > 0) {
+            result.peers.set(entry.id, addrs);
+        }
+    }
+    return result;
+}
+function isFretTableSource(service) {
+    return typeof service === 'object' && service !== null
+        && typeof service.exportTable === 'function';
+}
+/**
+ * The addresses one record lists, bound to `peerId`; null when the record must not be
+ * used. `openAndCertify` proves only that the envelope's own key signed it, so the
+ * signer and the peer the payload describes are each held against `peerId` here:
+ * without that, any peer could sign a record rewriting another peer's addresses.
+ */
+async function verifiedRecordAddrs(peerId, envelope) {
+    try {
+        const opened = await RecordEnvelope.openAndCertify(uint8ArrayFromString(envelope, 'base64url'), PeerRecord.DOMAIN);
+        const record = PeerRecord.createFromProtobuf(opened.payload);
+        const signer = peerIdFromPublicKey(opened.publicKey).toString();
+        const subject = record.peerId.toString();
+        if (signer !== peerId || subject !== peerId) {
+            log('skipping the address record filed under %s: signed by %s about %s', peerId, signer, subject);
+            return null;
+        }
+        return bindToPeer(record.multiaddrs.map((addr) => addr.toString()), peerId);
+    }
+    catch (error) {
+        log('skipping the address record filed under %s: %o', peerId, error);
+        return null;
+    }
+}
+/**
+ * A record names its peer once, in `peerId`, so its addresses carry no trailing
+ * `/p2p/<peerId>` and a relay-only peer's circuit address ends at the relay hop
+ * (`…/p2p/<relay>/p2p-circuit`). Each is given the suffix that makes it a complete
+ * dial target; one already terminating in a different peer id does not reach this peer
+ * and is dropped.
+ *
+ * Takes strings because `@libp2p/peer-record` carries its own `@multiformats/multiaddr`
+ * copy, a structurally different type from the one `withTrailingPeerId` takes.
+ */
+function bindToPeer(addrs, peerId) {
+    const bound = [];
+    for (const addr of addrs) {
+        const withPeer = withTrailingPeerId(multiaddr(addr), peerId);
+        if (withPeer !== null) {
+            bound.push(withPeer);
+        }
+    }
+    return bound;
+}
+//# sourceMappingURL=strand-fret-addrs.js.map

package/dist/strand-fret-addrs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strand-fret-addrs.js","sourceRoot":"","sources":["../src/strand-fret-addrs.ts"],"names":[],"mappings":"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"}

package/dist/strand-instance-manager.d.ts

@@ -1,7 +1,6 @@
 import type { PrivateKey } from '@libp2p/interface';
 import { type PeerJoinBackfillConfig } from './peer-join-backfill.js';
-import { type StrandPeerObservation } from './strand-peer-observer.js';
-import type { StrandPeerBookStore } from './strand-peer-book.js';
+import { type StrandNetworkStateStore } from './strand-network-state.js';
 import { type StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.js';
 import { type PendingMembershipInviteSource, type StrandMembershipReconciliationConfig } from './strand-membership-reconciler.js';
 import { type StrandFirstSyncConfig } from './strand-first-sync-gate.js';
@@ -210,25 +209,14 @@ export interface StartStrandConfig {
      */
     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;
+     * The node-local strand network state (`strand-network-state.ts`): this strand's
+     * slice of it is handed to db-p2p as `persistence`, so the strand node saves its
+     * FRET routing table (with each peer's signed address record) on every connection
+     * and re-imports it when it is next built. Absent ⇒ nothing is saved and the node
+     * starts with an empty table. `CadreNode` passes its store. Retained with the launch
+     * config, so a hibernation wake rebuilds the node over the same state.
+     */
+    networkState?: StrandNetworkStateStore;
 }
 /**
  * Volatile inputs re-resolved when resuming a quiesced strand — the ones that can
@@ -288,23 +276,6 @@ export declare class StrandInstanceManager {
      * missed writes).
      */
     private backfills;
-    /**
-     * 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;
-    /**
-     * 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;
     /**
      * The per-strand revoked-peer enforcer (closed strands only), keyed by strand
      * id. Same lifecycle rationale as {@link backfills}: created in

package/dist/strand-instance-manager.js

@@ -3,8 +3,7 @@ import { createLibp2pNode } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { StrandDatabase } from './strand-database.js';
 import { PeerJoinBackfill } from './peer-join-backfill.js';
-import { StrandPeerObserver } from './strand-peer-observer.js';
-import { StrandPeerBookSwap } from './strand-peer-book-swap.js';
+import { strandNetworkStatePersistence } from './strand-network-state.js';
 import { StrandRevocationEnforcer, createRevocationConnectionGater, readStrandRevocationRows } from './strand-revocation-enforcer.js';
 import { StrandMembershipReconciler } from './strand-membership-reconciler.js';
 import { removeMemberPeer } from './strand-membership-writer.js';
@@ -16,7 +15,7 @@ import { DEFAULT_CONNECTION_MONITOR, resolveStrandClusterSize, strandClusterPoli
 import { strandNodeAddrs } from './strand-network-config.js';
 import { resolveRelayServer } from './relay-server.js';
 import { superviseRelayReservation } from './relay-reservation.js';
-import { declaredCohortReadDeadlineMs, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
+import { declaredCohortReadDeadlineMs, optimysticDialLimits, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
 /**
@@ -140,23 +139,6 @@ export class StrandInstanceManager {
          * missed writes).
          */
         this.backfills = 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`.
-         */
-        this.peerObservers = 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`.
-         */
-        this.peerBookSwaps = new Map();
         /**
          * The per-strand revoked-peer enforcer (closed strands only), keyed by strand
          * id. Same lifecycle rationale as {@link backfills}: created in
@@ -505,6 +487,18 @@ export class StrandInstanceManager {
                     enableRingZulu: config.profile === 'storage'
                 },
                 ...(config.privateKey && { privateKey: config.privateKey }),
+                // Built per runtime, not per launch: the adapter stops saving once the strand's
+                // state is forgotten, and a rebuilt runtime is what starts it saving again.
+                //
+                // NOTE: the saved state also restores which peers db-p2p saw serving the strand,
+                // and it counts them in the cohort until FRET finds them unreachable. A node built
+                // while every other member is offline therefore fails its first writes ("Failed to
+                // get super-majority") — for 4-6 s on loopback, the window a running node already
+                // sees when a member drops. If apps report failed sends after relaunching alone on
+                // a slow relayed link, retry the write in the app or raise it upstream (db-p2p's
+                // remembered-serving fallback); dropping `persistence` brings back the split
+                // restart.
+                ...(config.networkState && { persistence: strandNetworkStatePersistence(config.networkState, strandId) }),
                 ...(config.network?.transports && { transports: config.network.transports }),
                 ...(config.network?.noiseCrypto && { noiseCrypto: config.network.noiseCrypto }),
                 // Unconditional, and the same default the control node takes: every node of
@@ -516,6 +510,9 @@ export class StrandInstanceManager {
                 // node is also the listener for every other member's strand node, and Optimystic
                 // derives that listener's limit from this (`link-budget.ts`).
                 linkRoundTripMs: resolveLinkRoundTripMs(config.network?.linkRoundTripMs),
+                // The same dial limits as the control node: a strand node dials the same machines,
+                // through the same relays and gates.
+                ...optimysticDialLimits(config.network?.linkRoundTripMs),
                 // Listen entries plus the WebSocket transport switch they imply — a strand node
                 // announces nothing the operator configured (`strand-network-config.ts`), and
                 // spreads AFTER `transports` above because the switch is a no-op whenever the
@@ -533,46 +530,6 @@ export class StrandInstanceManager {
             });
             timing('[buildStrandRuntime:%s] createLibp2pNode: %dms', strandId, Math.round(performance.now() - t0));
             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>/…`
@@ -781,20 +738,6 @@ 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);