@serfab/cadre-core 1.8.0 → 1.9.0

package/src/strand-network-state.ts

@@ -0,0 +1,243 @@
+/**
+ * Node-local, NON-replicated **strand network state**: for each strand this node
+ * runs, the last network state Optimystic's db-p2p saved for that strand's libp2p
+ * node — its FRET routing table (each peer entry carrying the peer's signed libp2p
+ * address record), the network-size high-water mark, and which of those peers were
+ * seen serving the strand. db-p2p reads it back once when the strand node is built
+ * and re-imports the table, which hands every record to the libp2p peerStore, so a
+ * restarted strand node already has addresses for the peers it was talking to
+ * (gotchoices/sereus#18).
+ *
+ * The payload is opaque here. db-p2p owns its version fence (a snapshot whose
+ * `version` it does not write is discarded whole) and FRET owns table validation
+ * (a structurally corrupt table is refused, a stale record dropped). This module
+ * checks only that an entry is a plain object with a numeric `version`, and never
+ * rewrites one.
+ *
+ * Three implementations mirroring `bootstrap-peer-store.ts` (same "must outlive the
+ * process, storage differs per platform" problem; both persistent forms share
+ * `node-local-snapshot.ts`):
+ *  - {@link MemoryStrandNetworkStateStore} (this module, cross-platform) — ephemeral;
+ *    the default when no store is injected via `CadreNodeConfig.strandNetworkState`.
+ *    A node using it restarts with an empty routing table.
+ *  - {@link PersistentStrandNetworkStateStore} (this module, cross-platform) —
+ *    durable over any `DurableSlot` the embedding app supplies.
+ *  - `FileStrandNetworkStateStore` — the above over a Node file in the node's state
+ *    directory; Node-only, behind the subpath
+ *    `@serfab/cadre-core/strand-network-state-file` so `node:fs` never lands in the
+ *    RN/browser graph.
+ *
+ * One store per NODE holding every strand, keyed by strand id, so the embedder
+ * wires one slot, like the other node-local stores.
+ *
+ * **Nothing here is trust-bearing.** A routing-table entry grants no authority:
+ * every address record is signed by the peer it names and verified by FRET at
+ * import, and the dialed peer authenticates by peer id at the handshake.
+ */
+import debug from 'debug';
+import type { NetworkStatePersistence, PersistedNetworkState } from '@optimystic/db-p2p';
+import { NodeLocalSnapshot, type DurableSlot, type NodeLocalSnapshotSpec } from './node-local-snapshot.js';
+
+const log = debug('sereus:cadre:strand-network-state');
+
+export interface StrandNetworkStateStore {
+	/** Party this store is scoped to. */
+	readonly partyId: string;
+
+	/**
+	 * The last state saved for `strandId`, or undefined. Synchronous: served from the
+	 * in-memory half of the store. The returned object is the stored one — callers
+	 * must not mutate it.
+	 */
+	load(strandId: string): PersistedNetworkState | undefined;
+
+	/**
+	 * Replace the strand's state. Implementations MUST reflect it in {@link load}
+	 * SYNCHRONOUSLY; the returned promise tracks durability only. The store keeps
+	 * `state` itself, so the caller must not mutate it afterwards (db-p2p builds a
+	 * fresh object per save).
+	 */
+	save(strandId: string, state: PersistedNetworkState): Promise<void>;
+
+	/**
+	 * Drop the strand's state — for a strand this node unpublished or left, whose
+	 * peers must not be re-imported by a later launch. A no-op for the stored state
+	 * when nothing is held, but {@link forgetGeneration} advances either way. Same
+	 * contract as {@link save}: reflected synchronously, the promise tracks durability.
+	 */
+	forget(strandId: string): Promise<void>;
+
+	/**
+	 * How many times `strandId` has been forgotten through this store instance.
+	 * {@link strandNetworkStatePersistence} compares it against the value it captured
+	 * to drop a save that arrives after the forget.
+	 */
+	forgetGeneration(strandId: string): number;
+}
+
+/** Per-strand forget counts; the in-process half of {@link StrandNetworkStateStore.forgetGeneration}. */
+class ForgetGenerations {
+	private readonly counts = new Map<string, number>();
+
+	of(strandId: string): number {
+		return this.counts.get(strandId) ?? 0;
+	}
+
+	advance(strandId: string): void {
+		this.counts.set(strandId, this.of(strandId) + 1);
+	}
+}
+
+/**
+ * Ephemeral in-memory store for nodes without durable storage (tests, and the
+ * default when nothing is injected). Same contract, no disk: a strand relaunched in
+ * the same process re-imports its table (a hibernation resume, a stop()→start()),
+ * and a restarted process starts with none.
+ */
+export class MemoryStrandNetworkStateStore implements StrandNetworkStateStore {
+	private readonly strands = new Map<string, PersistedNetworkState>();
+	private readonly generations = new ForgetGenerations();
+
+	constructor(readonly partyId: string) {}
+
+	load(strandId: string): PersistedNetworkState | undefined {
+		return this.strands.get(strandId);
+	}
+
+	async save(strandId: string, state: PersistedNetworkState): Promise<void> {
+		this.strands.set(strandId, state);
+	}
+
+	async forget(strandId: string): Promise<void> {
+		this.generations.advance(strandId);
+		if (this.strands.delete(strandId)) {
+			log('strand %s: network state forgotten (party=%s)', strandId, this.partyId);
+		}
+	}
+
+	forgetGeneration(strandId: string): number {
+		return this.generations.of(strandId);
+	}
+}
+
+/**
+ * What the store persists: `strands` maps strandId -> the state db-p2p saved. An
+ * entry that is not a plain object with a numeric `version` is dropped and its
+ * siblings kept (`drop-entry`): nothing here is trust-bearing, and one damaged
+ * strand must not cost every other strand its routing table. Everything past that
+ * structural check is db-p2p's and FRET's to judge at import.
+ */
+const STRAND_NETWORK_STATE_SNAPSHOT_SPEC: NodeLocalSnapshotSpec<PersistedNetworkState> = {
+	label: 'strand network state',
+	payloadKey: 'strands',
+	unusableEntry: 'drop-entry',
+	acceptEntry: (_strandId, raw) => {
+		if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return undefined;
+		if (typeof (raw as { version?: unknown }).version !== 'number') return undefined;
+		return raw as PersistedNetworkState;
+	}
+};
+
+/**
+ * Durable {@link StrandNetworkStateStore} over an app-supplied {@link DurableSlot} —
+ * the cross-platform half of every persistent backend (the Node
+ * `FileStrandNetworkStateStore` is this class over a file slot).
+ *
+ * Construct via {@link open}. Load and persist policy — what an absent, corrupt,
+ * foreign-party or unreadable slot does (the last one THROWS), and what a failed
+ * persist does — is documented once on `NodeLocalSnapshot`. Writes are serialised
+ * in-process by the snapshot's write chain, so several strand nodes saving at once
+ * cannot interleave partial snapshots.
+ *
+ * NOTE: an entry leaves only through {@link forget}, and nothing ages one out. A
+ * strand this machine detached because the strand watcher saw its control row gone
+ * (another machine of the party unpublished or left it), or one stopped and never
+ * relaunched, keeps its entry and it is rewritten with every save. The watcher path
+ * (`CadreNode.handleStrandRemoved`) does not forget because its removal is not proof
+ * the strand is gone: its query answers an empty list while the control database is
+ * absent. If snapshots grow on machines that host many short-lived strands, or a
+ * re-published strand id is seen importing its predecessor's table, drop entries at
+ * {@link open} that are older than FRET's own 14-day record age.
+ */
+export class PersistentStrandNetworkStateStore implements StrandNetworkStateStore {
+	private readonly generations = new ForgetGenerations();
+
+	private constructor(private readonly snapshot: NodeLocalSnapshot<PersistedNetworkState>) {}
+
+	/** Load (or cold-start) the party's strand network state from `slot`. */
+	static async open(slot: DurableSlot, partyId: string): Promise<PersistentStrandNetworkStateStore> {
+		return new PersistentStrandNetworkStateStore(
+			await NodeLocalSnapshot.open(slot, partyId, STRAND_NETWORK_STATE_SNAPSHOT_SPEC)
+		);
+	}
+
+	get partyId(): string {
+		return this.snapshot.partyId;
+	}
+
+	load(strandId: string): PersistedNetworkState | undefined {
+		return this.snapshot.get(strandId);
+	}
+
+	/**
+	 * Replace, visible via {@link load} synchronously, then the full snapshot is persisted.
+	 *
+	 * NOTE: every save rewrites the party's whole snapshot — every strand's table —
+	 * and db-p2p saves on every `connection:open`. Fine for a handful of strands; if
+	 * slot writes show up in profiles, move to one slot per strand or coalesce saves.
+	 */
+	save(strandId: string, state: PersistedNetworkState): Promise<void> {
+		return this.snapshot.put(strandId, state);
+	}
+
+	/** Forget, gone from {@link load} synchronously, then persisted — unless nothing was there. */
+	forget(strandId: string): Promise<void> {
+		this.generations.advance(strandId);
+		if (this.snapshot.has(strandId)) {
+			log('strand %s: network state forgotten (party=%s); persisting', strandId, this.partyId);
+		}
+		return this.snapshot.remove(strandId);
+	}
+
+	forgetGeneration(strandId: string): number {
+		return this.generations.of(strandId);
+	}
+}
+
+/**
+ * Adapts one strand's slice of the store to db-p2p's `NodeOptions.persistence`.
+ * Build one per strand runtime (`StrandInstanceManager.buildStrandRuntime` does).
+ *
+ * A save is dropped once the strand has been forgotten after this adapter was
+ * built: db-p2p saves fire-and-forget on connection events, so a node being torn
+ * down can still save after `forget(strandId)`, which would put the entry back.
+ * Saving resumes with the next runtime built for the strand (a relaunch or a
+ * hibernation resume), which builds a new adapter.
+ *
+ * NOTE: a strand that keeps running after its state was forgotten (self-revocation
+ * forgets but stops nothing) saves nothing more until its runtime is rebuilt. If a
+ * removed party is routinely re-admitted without a relaunch, re-arm saving at
+ * re-admission.
+ *
+ * NOTE: db-p2p saves on `connection:open` and on a changed serving verdict, not when
+ * a peer's addresses change. A peer whose address rotates during a long connection
+ * (a relay reservation moving) is saved with its old record until the next save,
+ * which matters only to a restart in between. If restarts are seen dialing rotated
+ * addresses, the fix is upstream: db-p2p saving when FRET's table changes.
+ */
+export function strandNetworkStatePersistence(
+	store: StrandNetworkStateStore,
+	strandId: string
+): NetworkStatePersistence {
+	const generation = store.forgetGeneration(strandId);
+	return {
+		load: async () => store.load(strandId),
+		save: async (state) => {
+			if (store.forgetGeneration(strandId) !== generation) {
+				log('strand %s: dropping a network-state save that arrived after the strand was forgotten', strandId);
+				return;
+			}
+			await store.save(strandId, state);
+		}
+	};
+}

package/src/types.ts

@@ -11,7 +11,7 @@ import type { SeedTrustPolicy } from './seed-trust-policy.js';
 import type { KeyStore, KeyId } from './key-store.js';
 import type { TrustedOwnerStore, TrustSource } from './trusted-owner-store.js';
 import type { BootstrapPeerStore } from './bootstrap-peer-store.js';
-import type { StrandPeerBookStore } from './strand-peer-book.js';
+import type { StrandNetworkStateStore } from './strand-network-state.js';
 import type { EnrolledMachineStore } from './enrolled-machine-store.js';
 import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
@@ -1030,32 +1030,29 @@ export interface CadreNodeConfig {
   };
 
   /**
-   * Node-local strand peer book (see `strand-peer-book.ts`): per strand, the strand
-   * peers this node has met — the other parties' strand transport peers a formation
-   * carried back, and every strand peer observed on a live connection — with their
-   * last-known addresses. Read on every launch, hibernation resume and periodic
-   * address refresh, so a restarted machine dials the peers it was talking to before
-   * anything else, instead of coming back up alone (gotchoices/sereus#18). Sibling
-   * of {@link bootstrapPeers} — same NON-replicated, per-party, injected-backend
-   * shape — and, like it, nothing here is trust-bearing: dial hints only, each
-   * bound to its peer id. Entries age out after 14 days (`STRAND_PEER_MAX_AGE_MS`,
-   * overridable per store via `StrandPeerBookOptions.maxAgeMs`).
-   *
-   * Absent ⇒ an in-memory store is created at start() (ephemeral: the book dies
-   * with the process, and a cross-party strand whose only contact was the other
-   * party does not re-mesh after a restart until a fresh formation). Every
-   * reference embedder injects a durable backend over the same slot kind as its
-   * bootstrap-peer store. A new platform needs no new store class: supply a
-   * `DurableSlot` and inject `PersistentStrandPeerBookStore.open(slot, partyId)`.
-   */
-  strandPeers?: {
+   * Node-local strand network state (see `strand-network-state.ts`): per strand, the
+   * state Optimystic's db-p2p saves for the strand's libp2p node — its FRET routing
+   * table, each entry carrying the peer's signed address record. A strand node reads
+   * it back when it is built and re-imports the table, so a restarted machine already
+   * holds addresses for the strand peers it was talking to (gotchoices/sereus#18).
+   * Sibling of {@link bootstrapPeers} — same NON-replicated, per-party,
+   * injected-backend shape — and, like it, nothing here is trust-bearing: FRET
+   * verifies every record at import.
+   *
+   * Absent ⇒ an in-memory store is created at start() (ephemeral: a restarted process
+   * starts every strand with an empty routing table). Every reference embedder
+   * injects a durable backend over the same slot kind as its bootstrap-peer store. A
+   * new platform needs no new store class: supply a `DurableSlot` and inject
+   * `PersistentStrandNetworkStateStore.open(slot, partyId)`.
+   */
+  strandNetworkState?: {
     /**
-     * Injected store instance — e.g. a `FileStrandPeerBookStore` from the
-     * Node-only subpath `@serfab/cadre-core/strand-peer-book-file`, persisted in
+     * Injected store instance — e.g. a `FileStrandNetworkStateStore` from the
+     * Node-only subpath `@serfab/cadre-core/strand-network-state-file`, persisted in
      * the node's state directory. Its `partyId` must match
      * `controlNetwork.partyId`; start() fails closed on a mismatch.
      */
-    store?: StrandPeerBookStore;
+    store?: StrandNetworkStateStore;
   };
 
   /**

package/dist/strand-peer-book-file.d.ts

@@ -1,12 +0,0 @@
-import type { StrandPeerBookOptions, StrandPeerBookStore } from './strand-peer-book.js';
-/**
- * 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 declare const FileStrandPeerBookStore: {
-    /** Load (or cold-start) the party's strand peer book from a file in `dir`. */
-    open(dir: string, partyId: string, options?: StrandPeerBookOptions): Promise<StrandPeerBookStore>;
-};

package/dist/strand-peer-book-file.js

@@ -1,37 +0,0 @@
-/**
- * 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';
-/** 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, partyId, options) {
-        return PersistentStrandPeerBookStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId, options);
-    }
-};
-//# sourceMappingURL=strand-peer-book-file.js.map

package/dist/strand-peer-book-file.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"strand-peer-book-file.js","sourceRoot":"","sources":["../src/strand-peer-book-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAGtE,gFAAgF;AAChF,MAAM,SAAS,GAAG,cAAc,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,8EAA8E;IAC9E,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,OAAe,EAAE,OAA+B;QACvE,OAAO,6BAA6B,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3G,CAAC;CACD,CAAC"}

package/dist/strand-peer-book-protocol.d.ts

@@ -1,168 +0,0 @@
-import type { Connection, Libp2p, PrivateKey } from '@libp2p/interface';
-/** Protocol id of the strand peer book swap, registered on every running strand node. */
-export declare const STRAND_PEER_BOOK_PROTOCOL = "/sereus/strand-peers/1.0.0";
-/** Version tag inside every signed payload, so a later payload shape cannot verify as this one. */
-export declare const SIGNED_STRAND_PEER_ENTRY_VERSION = 1;
-/**
- * How far ahead of the receiver's clock a signed entry's `issuedAt` may be. Skew
- * between honest machines is seconds; a stamp further ahead than this is a broken
- * clock or an attempt to pin an entry, and is rejected rather than held.
- */
-export declare const STRAND_PEER_ISSUED_AT_SKEW_MS: number;
-/**
- * Cap on one frame's bytes. A typical full frame — {@link MAX_STRAND_PEERS} entries of
- * {@link MAX_STRAND_ADDRS} addresses at roughly 150 bytes each, plus a peer id and
- * signature per entry — is about 40 KiB, but nothing bounds a multiaddr's length (a
- * long DNS name can take one past 300 bytes), so a sender trims its forwarded
- * entries to fit ({@link trimBookFrameToFit}) rather than trusting the arithmetic;
- * {@link assertBookFrameFits} is then the invariant check.
- */
-export declare const MAX_BOOK_FRAME_SIZE: number;
-/**
- * One peer's own signed statement of where it is: a `StrandPeerEntry` without the
- * receiver-local `lastSeenAt`. `addrs` may be empty — a peer that lost its relay
- * reservation truthfully says "not reachable now", and that displaces a stale
- * reachable list at every receiver.
- */
-export interface SignedStrandPeerEntry {
-    /** The signer's strand transport peer id (Ed25519, so it embeds the verifying key). */
-    peerId: string;
-    /** Bound to `peerId`, signaling-first, at most `MAX_STRAND_ADDRS`. */
-    addrs: string[];
-    /** Signer's clock, ms. Greater wins between two statements by the same signer. */
-    issuedAt: number;
-    /** base64url Ed25519 signature over {@link signedStrandPeerEntryPayload}. */
-    sig: string;
-}
-/** Request and response of the swap: the sender's signed book for one strand. */
-export interface StrandPeerBookFrame {
-    /** Must name the strand whose network the frame arrived on; anything else is refused. */
-    strandId: string;
-    /** At most {@link MAX_STRAND_PEERS}. */
-    entries: SignedStrandPeerEntry[];
-}
-/** The bytes a signed entry's signature covers. */
-export declare function signedStrandPeerEntryPayload(strandId: string, entry: Pick<SignedStrandPeerEntry, 'peerId' | 'addrs' | 'issuedAt'>): Uint8Array;
-/**
- * Sign this node's own entry with its strand transport key. `addrs` must already be
- * bound to the key's peer id (`dialableAddrs` in `strand-peer-observer.ts` does that);
- * a receiver rejects an entry whose addresses do not all attribute to the signer.
- */
-export declare function signStrandPeerEntry(privateKey: PrivateKey, strandId: string, addrs: string[], issuedAt: number): Promise<SignedStrandPeerEntry>;
-/** Why a received entry was dropped — for logs and for the verification test. */
-export type StrandPeerEntryVerdict = {
-    ok: true;
-    entry: SignedStrandPeerEntry;
-} | {
-    ok: false;
-    reason: string;
-};
-/**
- * Verify one received entry: well-formed, an Ed25519 peer id, every address bound to
- * that peer id, `issuedAt` not further ahead of `now` than the skew ceiling, and a
- * valid self-signature. Never throws: junk from a peer is a verdict, not an error.
- */
-export declare function verifySignedStrandPeerEntry(strandId: string, raw: unknown, now: number): Promise<StrandPeerEntryVerdict>;
-/**
- * Verify a whole received frame. A frame-level violation — the wrong strand, entries
- * not a list, more entries than {@link MAX_STRAND_PEERS} — throws, and the caller
- * refuses the frame. An entry that fails {@link verifySignedStrandPeerEntry} is
- * dropped INDIVIDUALLY with a debug line; its siblings are kept. An entry naming
- * `selfPeerId` is dropped too: this node's own statement is authoritative locally
- * and a remote copy of it is at best redundant. One entry per peer id (the first).
- */
-export declare function verifyStrandPeerBookFrame(strandId: string, raw: unknown, selfPeerId: string, now: number): Promise<SignedStrandPeerEntry[]>;
-/**
- * The frame with its LAST entries dropped until it encodes within
- * {@link MAX_BOOK_FRAME_SIZE} and {@link MAX_STRAND_PEERS}. Callers list the entries
- * in the order they would rather keep them (the own entry first, then freshest
- * first), so what goes is the stalest forwarded statement, and a frame that fits is
- * returned as is. Dropping an entry is logged: a forwarded peer the recipient never
- * learns of is worth seeing in a trace.
- */
-export declare function trimBookFrameToFit(frame: StrandPeerBookFrame): StrandPeerBookFrame;
-/**
- * Refuse to send a frame the receiver would reject: over the entry cap, or over
- * {@link MAX_BOOK_FRAME_SIZE} once encoded. A caller that built its frame through
- * {@link trimBookFrameToFit} cannot trip this; it is the invariant check, not a
- * runtime condition to handle.
- */
-export declare function assertBookFrameFits(frame: StrandPeerBookFrame): void;
-/** What the {@link StrandPeerBookService} receiver needs from its host, injected so it is testable without a node. */
-export interface StrandPeerBookServiceDeps {
-    strandId: string;
-    /** This strand node's own peer id: a received entry naming it is never merged. */
-    selfPeerId: string;
-    /**
-     * The entries to answer `forPeerId` with — this node's own signed entry plus every
-     * signed entry it holds, minus `forPeerId`'s own (the asker knows where it is).
-     */
-    localEntries(forPeerId: string): SignedStrandPeerEntry[];
-    /** The asker's VERIFIED entries, for the host to merge. Must not throw. */
-    onEntries(entries: SignedStrandPeerEntry[], fromPeerId: string): void;
-    /** Clock, for tests. Default `Date.now`. */
-    now?: () => number;
-    /**
-     * How long the receiver waits for the inbound request frame (ms). Required for the same
-     * reason as {@link ExchangeStrandPeerBookOptions.timeoutMs}: the swap gives both sides one
-     * link-derived deadline.
-     */
-    readTimeoutMs: number;
-    /** Default {@link DEFAULT_MAX_CONCURRENT}. Over it, an empty frame is returned unread. */
-    maxConcurrent?: number;
-}
-/**
- * Receiver side: registers the protocol on a strand node and, per inbound frame,
- * verifies and hands over the asker's entries, then answers with the local book.
- * Registered through `node.handle`, so on a closed strand every inbound stream
- * passes the revocation gate first — a revoked machine cannot push addresses into
- * anyone's book.
- */
-export declare class StrandPeerBookService {
-    private readonly deps;
-    private readonly readTimeoutMs;
-    private readonly maxConcurrent;
-    private readonly now;
-    private node;
-    private activeStreams;
-    constructor(deps: StrandPeerBookServiceDeps);
-    /** In-flight inbound streams. */
-    get activeCount(): number;
-    /** Register the handler. Resolves once libp2p has recorded the protocol on the self record. */
-    initialize(node: Libp2p): Promise<void>;
-    /** Unregister the handler and release the node reference. */
-    shutdown(): Promise<void>;
-    /**
-     * Read the request, merge what verifies, answer with the local book. Every failure
-     * (cap, malformed or oversized frame, wrong strand, read timeout) answers an empty
-     * frame rather than hanging or dropping the stream, so the asker's exchange settles.
-     *
-     * NOTE: the concurrency cap bounds streams in flight, not frames per peer per unit
-     * time — the ten-minute throttle is the CLIENT's, so a connected peer can push a
-     * verified frame, and the persist it costs, as fast as it likes; see
-     * `backlog/debt-strand-peer-book-remote-write-bounds`.
-     */
-    private handleStream;
-    private reply;
-}
-/** Options for {@link exchangeStrandPeerBook}. */
-export interface ExchangeStrandPeerBookOptions {
-    /** This strand node's own peer id: a returned entry naming it is dropped. */
-    selfPeerId: string;
-    /**
-     * Whole-exchange deadline (ms). Required, with no fallback here: the exchange crosses the
-     * link, so its deadline derives from the declared link round trip (`link-budget.ts`), and
-     * the caller is the one that knows the declaration. A default in this module would be a
-     * second number free to drift from that derivation.
-     */
-    timeoutMs: number;
-    /** Clock, for tests. Default `Date.now`. */
-    now?: () => number;
-}
-/**
- * Client side: open one stream on `connection` — the live connection to the peer,
- * relayed or not — send `request`, and return the peer's VERIFIED entries. Throws on
- * any failure (the peer does not speak the protocol, a deadline, a refused frame);
- * the caller logs and moves on, never retrying before its throttle expires.
- */
-export declare function exchangeStrandPeerBook(connection: Connection, request: StrandPeerBookFrame, options: ExchangeStrandPeerBookOptions): Promise<SignedStrandPeerEntry[]>;