@serfab/cadre-core 1.7.0 → 1.9.0

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
+import type { CircuitRelayServerInit } from '@libp2p/circuit-relay-v2';
 import type { IRawStorage, Libp2pConnectionMonitorInit, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
 import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
 import type { PeerJoinBackfillConfig } from './peer-join-backfill.js';
@@ -10,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';
@@ -123,10 +124,12 @@ export const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts> = {
  * Factory functions are useful for creating per-scope storage instances.
  *
  * **The argument is an opaque scope key.** Use it directly as a file name, directory
- * name or database name: every key stays within `[A-Za-z0-9._-]`, so no escaping is
- * needed and none should be assumed. Do not parse it; `controlStorageScope` /
- * `isControlStorageScope` (`storage-scope.ts`) are the supported way to mint and
- * recognize the control key. The control key holds the charset by base64url encoding;
+ * name or database name: every key stays within `[a-z0-9._-]`, so no escaping is
+ * needed and none should be assumed, and two different keys are two different names
+ * even on a filesystem that ignores case (Windows, macOS). Do not parse it;
+ * `controlStorageScope` / `isControlStorageScope` (`storage-scope.ts`) are the supported
+ * way to mint and recognize the control key. The control key holds the charset by
+ * lowercase hex encoding;
  * a strand's key — its strand id, which may have replicated in from another node in
  * the party — holds it because `StrandInstanceManager.startStrand` runs
  * `assertStrandScopeKey` on every launch and refuses a strand that fails it.
@@ -171,7 +174,7 @@ export interface StorageConfig {
    * the single-instance form cannot serve more than one party.
    *
    * The `scope` a factory receives is an opaque key already safe as a path or
-   * database-name segment (always within `[A-Za-z0-9._-]`), so each example below
+   * database-name segment (always within `[a-z0-9._-]`), so each example below
    * interpolates it directly.
    *
    * For Node.js environments, use FileRawStorage from @optimystic/db-p2p-storage-fs:
@@ -319,7 +322,8 @@ export interface NetworkConfig {
    * It buys a node that BOOTS, not a node that boots fast: `start()` still waits
    * out that first attempt, which costs the drive's whole timeout
    * (`DEFAULT_RELAY_RESERVE_TIMEOUT_MS`, four link round trips at
-   * {@link linkRoundTripMs} — 14 s at its default) against a relay that is unreachable
+   * {@link linkRoundTripMs} plus two admission decisions — 18 s at its default) against a relay
+   * that is unreachable
    * rather than merely refusing (`relay-reservation.ts` polls to the deadline, in
    * case libp2p's own discovery lands a reservation independently).
    *
@@ -342,6 +346,31 @@ export interface NetworkConfig {
    * better connectivity and uptime), false for transaction profile nodes.
    */
   enableRelay?: boolean;
+  /**
+   * Settings for this machine's circuit-relay SERVER, handed to `@libp2p/circuit-relay-v2`'s
+   * `circuitRelayServer(...)` (through db-p2p's `NodeOptions.relayServerInit`) on the control
+   * node and on every strand node. Only meaningful while {@link enableRelay} is on.
+   *
+   * Omitted, a party-run relay FORWARDS WITHOUT LIMIT: `reservations.applyDefaultLimit` is
+   * `false`, where libp2p's own default caps every relayed connection at 128 KiB or two
+   * minutes and resets it — which cut off any database sync or chat history forwarded
+   * through a party's own always-on machine. The store also holds
+   * `PARTY_RELAY_MAX_RESERVATIONS` (128) reservations instead of libp2p's 15, and each lives
+   * `PARTY_RELAY_RESERVATION_TTL_MS` (2 h) unrefreshed. See `relay-server.ts`.
+   *
+   * A value is MERGED over those defaults, not substituted for them: `reservations` key by
+   * key, every other top-level key as given. Setting only `reservations.maxReservations`
+   * keeps the limit off; `reservations: { applyDefaultLimit: true }` is how to turn libp2p's
+   * cap back on.
+   *
+   * The accepted tradeoff of the unlimited default: once a slot is granted, nothing caps what
+   * is forwarded through it, and a holder that keeps refreshing keeps it indefinitely — the
+   * 2 h lifetime only reclaims a slot whose holder went away. On the control node a peer it
+   * cannot place as a party member is bounded by COUNT ({@link unauthorizedRelayReservationCap}).
+   * A strand node's relay server has no such budget (its peers are cross-party by design), so
+   * any peer that reaches it is bounded only by `maxReservations`.
+   */
+  relayServerInit?: CircuitRelayServerInit;
   /**
    * Cap on concurrent circuit-relay reservations this node's relay server grants to
    * peers it cannot (yet) recognize as authorized members — the boot-ordering window
@@ -413,16 +442,21 @@ export interface NetworkConfig {
    * How long ONE cohort peer gets to answer ONE read-path request, in milliseconds, for the
    * control node and every strand node — as {@link connectionMonitor} is, and for the same
    * reason: the setting describes the LINK, and a phone's control node and its strand nodes
-   * ride the same one. Omitted takes {@link COHORT_READ_DEADLINE_MS} (5000 ms), chosen for two
-   * parties reaching each other only through a relay; Optimystic's own default is 1000 ms.
+   * ride the same one. Omitted, the deadline is DERIVED from {@link linkRoundTripMs}: one
+   * request and its answer over an open circuit costs two link round trips, so 7 000 ms at the
+   * default declaration (`cohortReadDeadlineMs` in `link-budget.ts`; the plugin's
+   * {@link COHORT_READ_DEADLINE_MS} is the same number). Optimystic's own default is 1000 ms.
    *
-   * Raise it for a link slower still, lower it for a deployment that is all LAN and wants a
-   * departed peer to stop holding up a read sooner. The cost of a larger value is that a peer
-   * which is truly gone holds a read of a block missing locally for that long before the read
-   * is declined and retried, and a joining machine's first sync runs several such consults —
-   * so a change here should be weighed against
-   * {@link CadreNodeConfig.strandFirstSync}'s budget. The measurement behind the default, and
-   * what it costs, are on {@link COHORT_READ_DEADLINE_MS}.
+   * Set this only to break the derivation on purpose: an explicit value wins over whatever
+   * {@link linkRoundTripMs} would derive, so a deployment that is all LAN can make a departed
+   * peer stop holding up a read sooner without declaring a faster link (which would also
+   * shorten the dial budgets). A deployment on a slower link should raise
+   * {@link linkRoundTripMs} instead, which moves this and every dial budget together. The
+   * cost of a larger value is that a peer which is truly gone holds a read of a block missing
+   * locally for that long before the read is declined and retried, and a joining machine's
+   * first sync runs several such consults — so a change here should be weighed against
+   * {@link CadreNodeConfig.strandFirstSync}'s budget. The derivation, its history and what it
+   * costs are on {@link COHORT_READ_DEADLINE_MS}.
    *
    * Handed to db-p2p's `clusterPolicy.cohortQueryTimeoutMs` unchanged and NOT re-validated
    * here. Optimystic refuses a value that is not a finite number above zero, or is above its
@@ -441,11 +475,14 @@ export interface NetworkConfig {
    * This is NOT a timeout. It is the one stated assumption that cadre's own dial and
    * reservation deadlines are DERIVED from, each by the number of round trips that operation
    * was measured to cost: a peer-join catch-up's dial to one peer, its push response, one relay
-   * reservation drive, the control-cohort dial budgets, and libp2p's own `dialTimeout` and
-   * `inboundUpgradeTimeout` on every node. Reaching another machine through a relay costs a
-   * fixed number of exchanges, so a deadline written as milliseconds has a link speed above
-   * which it can never open a connection — which is the defect this declaration exists to make
-   * impossible to reintroduce one budget at a time. The counts, the measurement behind them,
+   * reservation drive, the control-cohort dial budgets, and the per-peer cohort read deadline
+   * ({@link cohortQueryTimeoutMs}, unless set explicitly). It is also handed to Optimystic
+   * (`NodeOptions.linkRoundTripMs`), default included, which derives its own deadlines from it:
+   * its request dials and responses, its block pushes, and libp2p's `dialTimeout` and
+   * `inboundUpgradeTimeout` on every node. Reaching another machine through a
+   * relay costs a fixed number of exchanges, so a deadline written as milliseconds has a link
+   * speed above which it can never open a connection — which is the defect this declaration
+   * exists to make impossible to reintroduce one budget at a time. The counts, the measurement behind them,
    * and what still fails at the supported link are in `link-budget.ts`.
    *
    * The default covers the slowest link sereus supports, a 3-second round trip through a relay.
@@ -459,7 +496,8 @@ export interface NetworkConfig {
    * Refused where the libp2p node is built — inside `CadreNode.start()` for the control
    * network, inside `CadreNode.addStrand` for a strand — if it is not a finite number above
    * zero, because every consumer multiplies it into a deadline where a zero means "give up at
-   * once" and a `NaN` means "never".
+   * once" and a `NaN` means "never". Optimystic refuses, in the same place, a value above its
+   * `MAX_LINK_ROUND_TRIP_MS` (about 1.66 days).
    */
   linkRoundTripMs?: number;
   /**
@@ -530,14 +568,19 @@ export interface NetworkConfig {
      * {@link dialTimeoutMs}. Each address is dialed on its own under this limit,
      * so an address that never answers cannot use up the time the peer's other
      * addresses needed. Defaults to
-     * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}.
+     * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}. A value given
+     * here replaces that whole derived budget, including its allowance for the
+     * called machine's admission decision (`relayedDialBudgetMs`).
      */
     perAddressDialTimeoutMs?: number;
     /**
-     * How often each running strand re-resolves its siblings' strand-network
-     * addresses into its own libp2p address book — a step of the reconcile pass,
-     * on its own much longer throttle. Defaults to `STRAND_PEER_ADDR_REFRESH_MS`
-     * (10 min); must stay well under the peerStore's one-hour address expiry.
+     * How long a running strand waits, after a sibling answers its strand-addr
+     * RPC, before asking that sibling again for its strand-network addresses — a
+     * step of the reconcile pass, scheduled per (sibling, strand). A sibling that
+     * did not answer is retried sooner, on `STRAND_PEER_ADDR_RETRY_MS` (or this
+     * interval, when it is set shorter). Defaults to
+     * `STRAND_PEER_ADDR_REFRESH_MS` (10 min); must stay well under the peerStore's
+     * one-hour address expiry.
      */
     strandAddrRefreshMs?: number;
   };
@@ -656,9 +699,10 @@ export interface ControlNetworkConfig {
  *
  * The two `*ClusterPolicy` BUILDERS are the same objects with the block-repair
  * corroboration yardstick declared from the machines enrolled in this party
- * ({@link resolveRepairYardstick}) and, if the host set one, its own per-peer read
- * deadline in place of {@link COHORT_READ_DEADLINE_MS}. Both arrive in one named
- * declarations object, because both are plain numbers meaning unrelated things;
+ * ({@link resolveRepairYardstick}) and, if the host set one or declared its link, a
+ * per-peer read deadline in place of {@link COHORT_READ_DEADLINE_MS}
+ * (`declaredCohortReadDeadlineMs` in `link-budget.ts` settles which). Both arrive in one
+ * named declarations object, because both are plain numbers meaning unrelated things;
  * declaring neither returns the frozen base constant unchanged. A network picks the
  * derived numbers up when its libp2p node is built, which for a strand is every wake
  * from hibernation.
@@ -722,6 +766,22 @@ export interface CadreNodeConfig {
   /** Which strands to participate in */
   strandFilter?: StrandFilter;
 
+  /**
+   * Run every strand {@link strandFilter} admits, including ones no app on this machine
+   * has claimed with `addStrand`, as a **storage replica**: the strand's own libp2p node,
+   * storage and `Strand` membership schema, storing and serving its blocks, without the
+   * app's schema (no sApp config needed, none of the app's code or schema runs). This is
+   * how an always-on machine keeps a copy of every shared workspace its party runs, so a
+   * lost phone loses nothing that had reached it.
+   *
+   * The strand is still announced as `strand:discovered` (once) and stays in
+   * `getDiscoveredStrands()` until an app claims it. A replica is always a joiner.
+   *
+   * Default: `profile === 'storage'` — always-on machines host replicas, phones
+   * (`'transaction'`) keep today's announce-only behaviour.
+   */
+  hostUnclaimedStrands?: boolean;
+
   /** Storage configuration (only for storage profile) */
   storage?: StorageConfig;
 
@@ -950,11 +1010,12 @@ export interface CadreNodeConfig {
   };
 
   /**
-   * Node-local record of the strands this node joined from ANOTHER party (see
-   * `joined-strand-store.ts`): id, type and the closed strand's read secret, recorded
-   * by `formStrand` and by a joining (not `founder: true`) `addStrand` whose row is
-   * not in this party's control database, and re-offered on every start as `strand:discovered` — so an embedding
-   * app keeps no list of its own.
+   * Node-local record of the strands this node joined from ANOTHER party and has not yet
+   * published to the party-wide `JoinedStrand` table (see `joined-strand-store.ts`): id,
+   * type and the closed strand's read secret, recorded by `formStrand` and by a joining
+   * (not `founder: true`) `addStrand` whose row this party's control database does not
+   * name, offered on every start as `strand:discovered` until an owner machine's
+   * reconcile pass publishes it — so an embedding app keeps no list of its own.
    *
    * Absent ⇒ a `KeyStoreJoinedStrandStore` over {@link keyStore} when one is
    * configured (the record carries a secret, and the KeyStore is where every platform
@@ -969,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;
   };
 
   /**
@@ -1082,6 +1140,12 @@ export interface StrandInstance {
 
   /** Activity tracking */
   connectedPeers: number;
+  /**
+   * When the strand last saw activity: the app's (`recordStrandActivity`), a requested wake
+   * (`wakeStrand`), or a peer delivering a gated joiner's `Strand.Header`. Always a fresh
+   * `Date`. Bringing the runtime up is NOT activity — a check-in window decides whether to
+   * re-hibernate by whether this changed since before its resume.
+   */
   lastActivity: Date;
   nextCheckIn?: Date;
 
@@ -1508,6 +1572,12 @@ export interface CadreNodeEvents {
    * be idempotent (guard on an in-flight set, not only on
    * `getStrands().has(id)` — the strand manager tracks an instance only once
    * `addStrand` has resolved).
+   *
+   * On a node that hosts storage replicas ({@link CadreNodeConfig.hostUnclaimedStrands},
+   * the default for `profile: 'storage'`) the event still fires once, and the node launches
+   * the strand as a replica right after it — so there `getStrands().has(id)` soon turns
+   * true for a strand no app has claimed; an unclaimed instance has no `sAppInfo`. A
+   * launch that fails is retried by the watcher without a second `strand:discovered`.
    */
   'strand:discovered': { strandId: string; strand: StrandRow };
   'control:connected': void;
@@ -1886,7 +1956,11 @@ export interface WakeRequest {
 export interface WakeAck {
   /** Whether the receiver honored the wake (member + participated strand). */
   accepted: boolean;
-  /** The strand's status after the wake (present when `accepted`). */
+  /**
+   * The strand's status when the receiver accepted the wake (present when `accepted`). The
+   * receiver replies before the wake runs, so `hibernating` or `idle` here means "a wake was
+   * started", not "the strand is now up".
+   */
   status?: StrandStatus;
   /** Reason for rejection (non-member, unknown strand, malformed frame). */
   reason?: string;
@@ -1915,17 +1989,32 @@ export interface StrandAddrRequest {
   delegatePeerId?: string;
 }
 
+/**
+ * How a strand-addr responder handled a {@link StrandAddrRequest}. Carried so the
+ * asker can tell "I have nothing" from "I could not answer" — the two need
+ * different retry timing, and an empty address list alone cannot say which.
+ *
+ * - `ok` — looked up; `multiaddrs` is the truth, possibly empty (strand not running here).
+ * - `unavailable` — the responder could not answer: over its concurrency cap, the
+ *   request was unreadable, or its own lookup threw (e.g. a control-database read failed).
+ * - `refused` — the requester is not an authorized member in the responder's
+ *   current view (possibly because its `CadrePeer` row has not replicated there yet);
+ *   any `delegatePeerId` it carried was NOT recorded.
+ */
+export type StrandAddrStatus = 'ok' | 'unavailable' | 'refused';
+
 /**
  * Response to a {@link StrandAddrRequest}, carrying the responder's strand-node
  * multiaddrs, returned on the same stream.
  */
 export interface StrandAddrResponse {
-  /** Echoes the requested strand id (empty on a reject/error reply). */
+  /** How the responder handled the request; a reply without one is malformed. */
+  status: StrandAddrStatus;
+  /** Echoes the requested strand id; always empty on an `unavailable` reply. */
   strandId: string;
   /**
    * Dialable strand-network multiaddr strings (signaling/`p2p-circuit` first);
-   * empty when the responder is a non-member, or does not currently run that
-   * strand, or the exchange failed.
+   * empty unless `status` is `ok` and the responder runs that strand.
    */
   multiaddrs: string[];
 }

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,159 +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;
-    /** Default {@link DEFAULT_READ_TIMEOUT_MS}. */
-    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). Default {@link DEFAULT_EXCHANGE_TIMEOUT_MS}. */
-    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[]>;