@serfab/cadre-core 1.4.0 → 1.6.0

package/dist/types.d.ts

@@ -284,7 +284,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`, 10 s) against a relay that is unreachable
+     * (`DEFAULT_RELAY_RESERVE_TIMEOUT_MS`, four link round trips at
+     * {@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).
      *
@@ -374,6 +375,59 @@ export interface NetworkConfig {
      * see {@link DEFAULT_CONNECTION_MONITOR} for why.
      */
     connectionMonitor?: Libp2pConnectionMonitorInit;
+    /**
+     * 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.
+     *
+     * 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}.
+     *
+     * 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
+     * `MAX_COHORT_QUERY_TIMEOUT_MS` (about 4.97 days — the ceiling exists because a unit mix-up
+     * is the one way to exceed it), by throwing where the libp2p node is built: inside
+     * `CadreNode.start()` for the control network, and inside `CadreNode.addStrand` for a strand.
+     * Fractional values are accepted — this is a duration, not a count of peers.
+     */
+    cohortQueryTimeoutMs?: number;
+    /**
+     * 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} (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, 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`.
+     *
+     * 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
+     * zero, because every consumer multiplies it into a deadline where a zero means "give up at
+     * once" and a `NaN` means "never".
+     */
+    linkRoundTripMs?: number;
     /**
      * Optional async resolver returning the multiaddrs to embed in invites
      * (and other owner-address contexts). When unset, `libp2pNode.getMultiaddrs()`
@@ -485,6 +539,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,
@@ -555,11 +615,21 @@ 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}); handed no count, each returns its frozen base
- * constant unchanged. A network picks the derived number up when its libp2p node is
- * built, which for a strand is every wake from hibernation.
+ * ({@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;
+ * 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.
+ */
+export { MIN_CLUSTER_SIZE, COHORT_READ_DEADLINE_MS, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize, resolveRepairYardstick, controlClusterPolicy, strandClusterPolicy } from '@serfab/quereus-plugin-sereus';
+/**
+ * The declared link round trip every cadre-owned dial and reservation deadline is derived from,
+ * re-exported beside {@link NetworkConfig.linkRoundTripMs} so a host reading the setting finds
+ * the default it replaces. The counts, the measurement and the derivation live in
+ * `link-budget.ts`.
  */
-export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize, resolveRepairYardstick, controlClusterPolicy, strandClusterPolicy } from '@serfab/quereus-plugin-sereus';
+export { DECLARED_LINK_ROUND_TRIP_MS } from './link-budget.js';
 /**
  * Main configuration for a CadreNode
  */
@@ -680,10 +750,12 @@ export interface CadreNodeConfig {
      * to a table it has never fetched creates a private copy of it that never merges.
      * `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`, 30 s;
-     * `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.
+     * `pollIntervalMs` is the probe cadence. Omit for the defaults (`DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`,
+     * 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 */
@@ -1228,6 +1300,30 @@ export interface CadreNodeEvents {
     'strand:revoked': {
         strandId: string;
     };
+    /**
+     * Emitted when this node holds a staged membership invitation for a CLOSED strand
+     * that its own writes cannot redeem — the shape a REMOVED party hits when a manager
+     * hands it a fresh invitation. Redeeming means writing this party's `Strand.Member`
+     * row into the strand, and the machines that would carry that write are the ones the
+     * remaining members refuse, so the attempt is made and fails. Two triggers, reported
+     * at most once per re-arm of the membership loop (a further invitation staged while the
+     * loop is still running does not reset the report):
+     *
+     * - CONFIRMED: the revoked-peer gate already flags this node as removed (the
+     *   `strand:revoked` case) and an invitation is staged.
+     * - PROBABLE: `UNFINISHED_PASSES_BEFORE_ESCALATION` consecutive attempts left the
+     *   invitation staged. This one is a SUSPICION, not a verdict — the invitation's row
+     *   may simply not have replicated here yet on a slow strand — and the accompanying
+     *   warning names both causes.
+     *
+     * Nothing is stopped or torn down. A fresh invitation cannot re-admit a removed
+     * party by itself: the remedy is a remaining manager admitting this party's member
+     * key directly (`addMemberByManager`), after which the membership loop, which keeps
+     * retrying, finishes the join on its own.
+     */
+    'strand:rejoin-blocked': {
+        strandId: string;
+    };
     /**
      * Emitted when the control network advertises a strand this node has no
      * registered `sAppConfig` for — i.e. a strand created by another member, or

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,
@@ -113,9 +119,19 @@ export const DEFAULT_CHECKIN_WINDOW_MS = 15 * 1000;
  *
  * The two `*ClusterPolicy` BUILDERS are the same objects with the block-repair
  * corroboration yardstick declared from the machines enrolled in this party
- * ({@link resolveRepairYardstick}); handed no count, each returns its frozen base
- * constant unchanged. A network picks the derived number up when its libp2p node is
- * built, which for a strand is every wake from hibernation.
+ * ({@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;
+ * 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.
+ */
+export { MIN_CLUSTER_SIZE, COHORT_READ_DEADLINE_MS, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize, resolveRepairYardstick, controlClusterPolicy, strandClusterPolicy } from '@serfab/quereus-plugin-sereus';
+/**
+ * The declared link round trip every cadre-owned dial and reservation deadline is derived from,
+ * re-exported beside {@link NetworkConfig.linkRoundTripMs} so a host reading the setting finds
+ * the default it replaces. The counts, the measurement and the derivation live in
+ * `link-budget.ts`.
  */
-export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize, resolveRepairYardstick, controlClusterPolicy, strandClusterPolicy } from '@serfab/quereus-plugin-sereus';
+export { DECLARED_LINK_ROUND_TRIP_MS } from './link-budget.js';
 //# sourceMappingURL=types.js.map

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;AAqXF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC"}
+{"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;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.4.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -73,7 +73,7 @@
     "@libp2p/tcp": "^11.0.10",
     "@libp2p/webrtc": "6.0.14",
     "@libp2p/websockets": "^10.1.3",
-    "@optimystic/db-p2p-storage-fs": "^1.5.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 +88,12 @@
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
     "@multiformats/multiaddr": "^12.5.1",
-    "@optimystic/db-core": "^1.5.0",
-    "@optimystic/db-p2p": "^1.5.0",
-    "@optimystic/quereus-plugin-crypto": "^1.5.0",
-    "@optimystic/quereus-plugin-optimystic": "^1.5.0",
-    "@quereus/quereus": "^4.19.4",
-    "@serfab/quereus-plugin-sereus": "^1.4.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.6.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"