@serfab/cadre-core 1.4.0 → 1.6.0

package/src/strand-network-config.ts

@@ -40,8 +40,8 @@
  * absorbed by the per-relay entries when one is.
  *
  * Everything else in `NetworkConfig` — `transports`, `noiseCrypto`, `connectionMonitor`,
- * `connectionGater`, `enableRelay` — is inherited by the caller; this module only owns
- * the two host-endpoint fields above and the relay listen shape. One caveat on
+ * `cohortQueryTimeoutMs`, `connectionGater`, `enableRelay` — is inherited by the caller; this
+ * module only owns the two host-endpoint fields above and the relay listen shape. One caveat on
  * `connectionGater`: an OPEN strand's node gets it unchanged, while a CLOSED strand's
  * node composes revoked-peer denial onto it in `strand-instance-manager.ts` (every
  * supplied hook still honored — see `strand-revocation-enforcer.ts`).

package/src/types.ts

@@ -316,7 +316,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).
    *
@@ -406,6 +407,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()`
@@ -518,6 +572,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,
@@ -594,12 +654,16 @@ 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,
@@ -610,6 +674,14 @@ export {
   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 { DECLARED_LINK_ROUND_TRIP_MS } from './link-budget.js';
+
 /**
  * Main configuration for a CadreNode
  */
@@ -743,10 +815,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;
 
@@ -1322,6 +1396,28 @@ export interface CadreNodeEvents {
    * revoked.
    */
   '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