@serfab/cadre-core 1.6.0 → 1.8.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,9 @@ 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 { EnrolledMachineStore } from './enrolled-machine-store.js';
+import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
 import type { RevocableTable } from './control-authorization.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
@@ -121,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.
@@ -169,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:
@@ -317,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).
    *
@@ -340,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
@@ -411,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
@@ -439,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.
@@ -457,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;
   /**
@@ -528,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;
   };
@@ -654,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.
@@ -720,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;
 
@@ -947,6 +1009,55 @@ export interface CadreNodeConfig {
     store?: EnrolledMachineStore;
   };
 
+  /**
+   * 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
+   * already keeps secrets), else an in-memory store that warns once and forgets every
+   * join on restart. An embedder that passes {@link privateKey} rather than a
+   * `keyStore` injects a durable store here, e.g.
+   * `new KeyStoreJoinedStrandStore(new FileKeyStore(dir), partyId)`.
+   */
+  joinedStrands?: {
+    /** Its `partyId` must match `controlNetwork.partyId`; start() fails closed on a mismatch. */
+    store?: JoinedStrandStore;
+  };
+
+  /**
+   * 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?: {
+    /**
+     * Injected store instance — e.g. a `FileStrandPeerBookStore` from the
+     * Node-only subpath `@serfab/cadre-core/strand-peer-book-file`, persisted in
+     * the node's state directory. Its `partyId` must match
+     * `controlNetwork.partyId`; start() fails closed on a mismatch.
+     */
+    store?: StrandPeerBookStore;
+  };
+
   /**
    * Platform push-delivery for suspended mobile peers. When present, the node's
    * server fan-out can deliver strand-wake data messages over the platform push
@@ -1032,6 +1143,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;
 
@@ -1394,6 +1511,10 @@ export interface CadreNodeEvents {
    * re-admits this party, so a second removal is reported again — and a
    * hibernation wake rebuilds the gate, which may re-emit for a strand still
    * revoked.
+   *
+   * For a strand joined from another party, the node also forgets its remembered
+   * join (see {@link CadreNodeConfig.joinedStrands}): it keeps running this session
+   * and is not re-offered after the next start.
    */
   'strand:revoked': { strandId: string };
   /**
@@ -1427,6 +1548,12 @@ export interface CadreNodeEvents {
    * Carries the full {@link StrandRow} so the app can join without re-querying
    * the control DB.
    *
+   * Also emitted for a strand this node joined from ANOTHER party, which no control
+   * row names: the node remembers every such join (see
+   * {@link CadreNodeConfig.joinedStrands}) and offers it here on each start, as a row
+   * with `FounderOwnerKey: null` carrying the closed strand's `MemberPrivateKey`. That
+   * row is the product of the formation's consent, so claiming it needs no second one.
+   *
    * **Fired once per strand per session, and it can fire before your listener is
    * attached.** The strand watcher's first poll runs inside `CadreNode.start()`
    * (100 ms after the watcher starts), so every strand already stored for this
@@ -1448,6 +1575,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;
@@ -1826,7 +1959,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;
@@ -1855,17 +1992,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[];
 }