@serfab/cadre-core 1.5.0 → 1.7.0

package/dist/types.d.ts

@@ -10,7 +10,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';
@@ -285,7 +287,7 @@ 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} — 8 s at its default) against a relay that is unreachable
+     * {@link linkRoundTripMs} — 14 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).
      *
@@ -402,22 +404,25 @@ export interface NetworkConfig {
      * The round trip this node assumes between itself and another machine, in milliseconds, for
      * the control node and every strand node — as {@link cohortQueryTimeoutMs} 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 DECLARED_LINK_ROUND_TRIP_MS} (2000 ms).
+     * nodes ride the same one. Omitted takes {@link DECLARED_LINK_ROUND_TRIP_MS} (3500 ms).
      *
      * 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, and the control-cohort dial budgets. 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 the ceiling that no declaration here can lift are in `link-budget.ts`.
+     * 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,
+     * and what still fails at the supported link are in `link-budget.ts`.
      *
-     * Raise it for a link slower than the relayed phone-to-phone band sereus assumes; the cost is
-     * the ordinary cost of longer deadlines, a peer that is genuinely gone holding each operation
-     * that much longer before it is abandoned and retried. Above about 2500 it buys nothing: two
-     * libp2p budgets that sereus cannot reach abandon the connection first
-     * (`tickets/blocked/how-slow-a-relayed-link-does-sereus-carry`).
+     * The default covers the slowest link sereus supports, a 3-second round trip through a relay.
+     * Raise it for a link slower still; the cost is the ordinary cost of longer deadlines, a peer
+     * that is genuinely gone holding each operation that much longer before it is abandoned and
+     * retried. Lower it only if EVERY machine of the party is that close: this node is also the
+     * listener for connections other machines open to it, and its `inboundUpgradeTimeout` comes
+     * from this value, so a node declaring a faster link than its peers discards their
+     * half-built connections — silently, from the dialer's side.
      *
      * 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
@@ -536,6 +541,12 @@ export interface NetworkConfig {
  * kept it (the same pair aborted at a 200ms stall only when the deadline was 300ms). An
  * interval strictly above the deadline is what makes the 30 seconds real.
  *
+ * WHAT THE LINK NEEDS OF IT. One ping opens a fresh stream and echoes over it: a protocol
+ * negotiation plus the echo, two link round trips by `link-budget.ts`'s counts (a `newStream`
+ * over a relayed circuit measured 3016 ms at 1500 ms one-way). At the slowest link sereus
+ * supports, a 3-second relayed round trip, that is about 6 s — well inside the 30 s deadline,
+ * which exists for the phone's CPU rather than the link.
+ *
  * WHAT IT COSTS. A dead peer is reclaimed 30 to 65 seconds after it stops answering — the
  * deadline, plus up to one interval of waiting for the ping that will fail — where
  * libp2p's defaults took about 5 to 15 seconds. `db-p2p` caps a node at 16 connections,
@@ -742,11 +753,11 @@ export interface CadreNodeConfig {
      * `timeoutMs` bounds how long {@link CadreNode.addStrand} waits before rejecting with
      * `StrandAwaitingFirstSyncError` (retryable — the launch stays up and keeps probing);
      * `pollIntervalMs` is the probe cadence. Omit for the defaults (`DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`,
-     * 120 s — sized for a machine joining through a relay on a slow link; that constant's doc
-     * comment carries the measurement behind the number and what the budget costs, and is the
-     * only copy of it; `DEFAULT_STRAND_FIRST_SYNC_POLL_MS`, 500 ms). There is
-     * deliberately no way to disable the gate: a machine that already holds the Header is never
-     * gated, so nothing that works today is blocked by it.
+     * sized for a machine re-attaching through a relay on a slow link, the slowest attach
+     * measured; that constant's doc comment carries the number, the measurement behind it and
+     * what the budget costs, and is the only copy of them; `DEFAULT_STRAND_FIRST_SYNC_POLL_MS`,
+     * 500 ms). There is deliberately no way to disable the gate: a machine whose store already
+     * holds the Header is never gated, so nothing that works today is blocked by it.
      */
     strandFirstSync?: StrandFirstSyncConfig;
     /** Hibernation configuration */
@@ -865,6 +876,52 @@ export interface CadreNodeConfig {
          */
         store?: EnrolledMachineStore;
     };
+    /**
+     * 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.
+     *
+     * 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
@@ -1287,6 +1344,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;
@@ -1324,6 +1385,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

package/dist/types.js

@@ -66,6 +66,12 @@ export const HIBERNATION_TIMEOUTS = {
  * kept it (the same pair aborted at a 200ms stall only when the deadline was 300ms). An
  * interval strictly above the deadline is what makes the 30 seconds real.
  *
+ * WHAT THE LINK NEEDS OF IT. One ping opens a fresh stream and echoes over it: a protocol
+ * negotiation plus the echo, two link round trips by `link-budget.ts`'s counts (a `newStream`
+ * over a relayed circuit measured 3016 ms at 1500 ms one-way). At the slowest link sereus
+ * supports, a 3-second relayed round trip, that is about 6 s — well inside the 30 s deadline,
+ * which exists for the phone's CPU rather than the link.
+ *
  * WHAT IT COSTS. A dead peer is reclaimed 30 to 65 seconds after it stops answering — the
  * deadline, plus up to one interval of waiting for the ping that will fail — where
  * libp2p's defaults took about 5 to 15 seconds. `db-p2p` caps a node at 16 connections,

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAgFA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AAwaF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,uFAAuF;IACvF,mFAAmF;IACnF,YAAY,EAAE,KAAM;IACpB,kFAAkF;IAClF,kFAAkF;IAClF,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAM,EAAE,UAAU,EAAE,KAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAmBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkFA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AA2aF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,uFAAuF;IACvF,mFAAmF;IACnF,YAAY,EAAE,KAAM;IACpB,kFAAkF;IAClF,kFAAkF;IAClF,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAM,EAAE,UAAU,EAAE,KAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAmBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -36,6 +36,10 @@
       "types": "./dist/enrolled-machine-store-file.d.ts",
       "import": "./dist/enrolled-machine-store-file.js"
     },
+    "./strand-peer-book-file": {
+      "types": "./dist/strand-peer-book-file.d.ts",
+      "import": "./dist/strand-peer-book-file.js"
+    },
     "./push-node": {
       "types": "./dist/push-node.d.ts",
       "import": "./dist/push-node.js"
@@ -73,7 +77,7 @@
     "@libp2p/tcp": "^11.0.10",
     "@libp2p/webrtc": "6.0.14",
     "@libp2p/websockets": "^10.1.3",
-    "@optimystic/db-p2p-storage-fs": "^1.6.0",
+    "@optimystic/db-p2p-storage-fs": "^1.7.0",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
@@ -88,12 +92,12 @@
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
     "@multiformats/multiaddr": "^12.5.1",
-    "@optimystic/db-core": "^1.6.0",
-    "@optimystic/db-p2p": "^1.6.0",
-    "@optimystic/quereus-plugin-crypto": "^1.6.0",
-    "@optimystic/quereus-plugin-optimystic": "^1.6.0",
+    "@optimystic/db-core": "^1.7.0",
+    "@optimystic/db-p2p": "^1.7.0",
+    "@optimystic/quereus-plugin-crypto": "^1.7.0",
+    "@optimystic/quereus-plugin-optimystic": "^1.7.0",
     "@quereus/quereus": "^4.20.0",
-    "@serfab/quereus-plugin-sereus": "^1.5.0",
+    "@serfab/quereus-plugin-sereus": "^1.7.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"