@serfab/cadre-core 1.3.0 → 1.4.0

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
-import type { IRawStorage, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
+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';
 import type { StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.js';
@@ -91,13 +91,13 @@ export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeou
  * 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 cadre-core mints 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 strand arm of that charset
- * rule is intended but not yet checked — a strand id replicated in from another node
- * in the party reaches this callback verbatim; see
- * `tickets/backlog/bug-strand-scope-key-charset-unenforced`.
+ * 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;
+ * 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.
  *
  * **Called once per scope per runtime lifetime.** The scopes are the control database
  * (once per `CadreNode.start()`) and each strand id (once per `startStrand`).
@@ -358,6 +358,22 @@ export interface NetworkConfig {
      * `NodeOptions.noiseCrypto`.
      */
     noiseCrypto?: NoiseCryptoInterface;
+    /**
+     * libp2p's connection monitor — the liveness ping it runs on every connection — for
+     * the control node and every strand node, as {@link noiseCrypto} is. When omitted,
+     * cadre-core applies {@link DEFAULT_CONNECTION_MONITOR} rather than leaving libp2p's
+     * own defaults in place; an explicit value REPLACES that default wholesale, so `{}`
+     * is how an app asks for libp2p's stock behaviour back.
+     *
+     * Typed from `@optimystic/db-p2p`'s re-export of libp2p's `ConnectionMonitorInit`, so
+     * an app does not need a direct `libp2p` dependency, and handed to db-p2p's
+     * `NodeOptions.connectionMonitor` unchanged.
+     *
+     * An app that widens the ping deadline itself must raise `pingInterval` above it in
+     * the same object, or libp2p aborts the connection on the second overlapping ping —
+     * see {@link DEFAULT_CONNECTION_MONITOR} for why.
+     */
+    connectionMonitor?: Libp2pConnectionMonitorInit;
     /**
      * Optional async resolver returning the multiaddrs to embed in invites
      * (and other owner-address contexts). When unset, `libp2pNode.getMultiaddrs()`
@@ -438,6 +454,63 @@ export interface NetworkConfig {
         strandAddrRefreshMs?: number;
     };
 }
+/**
+ * The connection-monitor settings every cadre node runs with when
+ * {@link NetworkConfig.connectionMonitor} is unset: a 30 second ping deadline in place
+ * of libp2p's 5 second one, and a 35 second gap between pings so a ping is never
+ * outstanding when the next one starts.
+ *
+ * WHY this is a default and not opt-in. libp2p's monitor pings every connection and,
+ * with its own `abortConnectionOnPingFailure: true`, aborts the connection on the FIRST
+ * timeout. A peer whose event loop is saturated by pure-JS Noise crypto — a slow phone
+ * under React Native, see {@link NetworkConfig.noiseCrypto} — misses that deadline while
+ * perfectly healthy; the other end aborts, the peer redials, and the new handshake
+ * saturates it further. Measured on gotchoices/sereus#13 at a Galaxy S7's crypto cost, a
+ * two-party bring-up failed 3 of 3 runs on stock settings, with 30 `aborting connection
+ * due to ping failure` entries in the relay's log for one run, and passed 4 of 4 in about
+ * 90 seconds once the deadline was widened on every node. The monitor runs on BOTH ends
+ * of a connection and either end's abort closes it for both, so a setting the phone alone
+ * applies does not cover the peer dropping it. That is what rules out scoping this to
+ * React Native.
+ *
+ * WHY `pingInterval` MOVES WITH THE DEADLINE, and is not left at libp2p's 10 seconds.
+ * The monitor opens a ping stream per connection per interval whether or not the previous
+ * ping has answered, and `/ipfs/ping/1.0.0` is registered by `@libp2p/ping` with
+ * `maxOutboundStreams: 1`. A second concurrent ping stream on one connection therefore
+ * fails in `Connection.newStream` with `TooManyOutboundProtocolStreamsError`, which
+ * reaches the monitor's own catch and aborts the connection exactly as a timeout does. A
+ * widened deadline alone is thus capped by the ping interval: measured against two local
+ * libp2p 3.1.3 nodes whose ping handler answered 600ms late, an interval of 300ms with a
+ * 900ms deadline aborted the connection, while a 900ms interval with the same deadline
+ * 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 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,
+ * so the worst case is those slots held about a minute longer than before; at that scale
+ * it is not a starvation risk.
+ *
+ * WHY THE DEADLINE IS PINNED rather than given room to adapt. `pingTimeout` is an
+ * adaptive-timeout init, and equal `minTimeout`/`maxTimeout` clamp it to one value on
+ * every libp2p version. Under libp2p 3.1.3, which sereus resolves today, it is already
+ * flat at `minTimeout`: `ConnectionMonitor` asks its `AdaptiveTimeout` for a deadline but
+ * never calls `cleanUp` to report how long the ping took, so the moving average the
+ * deadline derives from stays at zero. libp2p 3.3 does report ping durations back, and a
+ * ceiling above `pingInterval` would then let the deadline grow past the interval and put
+ * the overlapping-ping abort above straight back. Pinning both ends keeps the interval's
+ * margin true on the version bump instead of making it something to remember. It also
+ * sidesteps 3.3's other surprise: the monitor keeps one `AdaptiveTimeout` for all of a
+ * node's connections, so one slow peer would otherwise lengthen the deadline for every
+ * connection on that node.
+ */
+export declare const DEFAULT_CONNECTION_MONITOR: Readonly<{
+    pingInterval: number;
+    pingTimeout: Readonly<{
+        minTimeout: 30000;
+        maxTimeout: 30000;
+    }>;
+}>;
 /**
  * Hibernation configuration
  */
@@ -1164,13 +1237,19 @@ export interface CadreNodeEvents {
      * Carries the full {@link StrandRow} so the app can join without re-querying
      * the control DB.
      *
-     * **Fired exactly 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 party is normally offered while the embedding app is
-     * still inside its own `start()` await. The watcher then records the strand as
-     * seen and no later poll re-offers it, so a listener attached a moment late
-     * misses those strands for the life of the process.
+     * **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
+     * party is normally offered while the embedding app is still inside its own
+     * `start()` await. The watcher then records the strand as seen and no later poll
+     * re-offers it, so a listener attached a moment late misses those strands for the
+     * life of the process.
+     *
+     * One exception, and it does NOT produce a second event: when an `addStrand` that
+     * claims a discovered strand FAILS, the watcher is told to forget the strand so a
+     * later poll retries it. That claim left the sApp config registered, so the retry
+     * takes the auto-launch branch — what the app sees is `strand:error` per failed
+     * retry and `strand:started` when one succeeds.
      *
      * So an app that auto-joins discovered strands must **subscribe first, then
      * drain `CadreNode.getDiscoveredStrands()`** — the map of strands no local

package/dist/types.js

@@ -35,6 +35,65 @@ export const HIBERNATION_TIMEOUTS = {
         checkInMaxInterval: 3 * 24 * 60 * 60 * 1000 // cap: ~3 days
     }
 };
+/**
+ * The connection-monitor settings every cadre node runs with when
+ * {@link NetworkConfig.connectionMonitor} is unset: a 30 second ping deadline in place
+ * of libp2p's 5 second one, and a 35 second gap between pings so a ping is never
+ * outstanding when the next one starts.
+ *
+ * WHY this is a default and not opt-in. libp2p's monitor pings every connection and,
+ * with its own `abortConnectionOnPingFailure: true`, aborts the connection on the FIRST
+ * timeout. A peer whose event loop is saturated by pure-JS Noise crypto — a slow phone
+ * under React Native, see {@link NetworkConfig.noiseCrypto} — misses that deadline while
+ * perfectly healthy; the other end aborts, the peer redials, and the new handshake
+ * saturates it further. Measured on gotchoices/sereus#13 at a Galaxy S7's crypto cost, a
+ * two-party bring-up failed 3 of 3 runs on stock settings, with 30 `aborting connection
+ * due to ping failure` entries in the relay's log for one run, and passed 4 of 4 in about
+ * 90 seconds once the deadline was widened on every node. The monitor runs on BOTH ends
+ * of a connection and either end's abort closes it for both, so a setting the phone alone
+ * applies does not cover the peer dropping it. That is what rules out scoping this to
+ * React Native.
+ *
+ * WHY `pingInterval` MOVES WITH THE DEADLINE, and is not left at libp2p's 10 seconds.
+ * The monitor opens a ping stream per connection per interval whether or not the previous
+ * ping has answered, and `/ipfs/ping/1.0.0` is registered by `@libp2p/ping` with
+ * `maxOutboundStreams: 1`. A second concurrent ping stream on one connection therefore
+ * fails in `Connection.newStream` with `TooManyOutboundProtocolStreamsError`, which
+ * reaches the monitor's own catch and aborts the connection exactly as a timeout does. A
+ * widened deadline alone is thus capped by the ping interval: measured against two local
+ * libp2p 3.1.3 nodes whose ping handler answered 600ms late, an interval of 300ms with a
+ * 900ms deadline aborted the connection, while a 900ms interval with the same deadline
+ * 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 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,
+ * so the worst case is those slots held about a minute longer than before; at that scale
+ * it is not a starvation risk.
+ *
+ * WHY THE DEADLINE IS PINNED rather than given room to adapt. `pingTimeout` is an
+ * adaptive-timeout init, and equal `minTimeout`/`maxTimeout` clamp it to one value on
+ * every libp2p version. Under libp2p 3.1.3, which sereus resolves today, it is already
+ * flat at `minTimeout`: `ConnectionMonitor` asks its `AdaptiveTimeout` for a deadline but
+ * never calls `cleanUp` to report how long the ping took, so the moving average the
+ * deadline derives from stays at zero. libp2p 3.3 does report ping durations back, and a
+ * ceiling above `pingInterval` would then let the deadline grow past the interval and put
+ * the overlapping-ping abort above straight back. Pinning both ends keeps the interval's
+ * margin true on the version bump instead of making it something to remember. It also
+ * sidesteps 3.3's other surprise: the monitor keeps one `AdaptiveTimeout` for all of a
+ * node's connections, so one slow peer would otherwise lengthen the deadline for every
+ * connection on that node.
+ */
+export const DEFAULT_CONNECTION_MONITOR = Object.freeze({
+    // Strictly greater than the deadline below, so the previous ping is always resolved or
+    // aborted before the next one opens a stream. `types.spec.ts` holds the two apart.
+    pingInterval: 35000,
+    // Frozen at both levels, as `CONTROL_CLUSTER_POLICY` is: one object reaches every
+    // libp2p node this process builds, so a mutation anywhere would move the deadline
+    // for all of them.
+    pingTimeout: Object.freeze({ minTimeout: 30000, maxTimeout: 30000 })
+});
 /**
  * Default duration of the resume-and-probe window during a strand check-in.
  * See {@link HibernationConfig.checkInWindowMs}.

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;AAsXF;;;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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "1.3.0",
+  "version": "1.4.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.3.0",
+    "@optimystic/db-p2p-storage-fs": "^1.5.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.3.0",
-    "@optimystic/db-p2p": "^1.3.0",
-    "@optimystic/quereus-plugin-crypto": "^1.3.0",
-    "@optimystic/quereus-plugin-optimystic": "^1.3.0",
+    "@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.3.0",
+    "@serfab/quereus-plugin-sereus": "^1.4.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"

package/src/cadre-node.ts

@@ -37,11 +37,17 @@ import type {
   PeerAddressRecord,
   ResolveDeviceTokenOpts
 } from './types.js';
-import { controlClusterPolicy, CONTROL_REPLICATION_BREADTH, DEFAULT_CHECKIN_WINDOW_MS } from './types.js';
+import { controlClusterPolicy, CONTROL_REPLICATION_BREADTH, DEFAULT_CHECKIN_WINDOW_MS, DEFAULT_CONNECTION_MONITOR } from './types.js';
 import { sign } from '@optimystic/quereus-plugin-crypto';
 import { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, requireEd25519PublicKeyB64, type Ed25519KeyPair } from './ed25519-key.js';
 import { strandTransportKey } from './strand-transport-key.js';
-import { controlStorageScope } from './storage-scope.js';
+import {
+  assertScopeKeyCharset,
+  assertStrandScopeKey,
+  controlStorageScope,
+  InvalidStrandIdError,
+  isValidStrandScopeKey
+} from './storage-scope.js';
 import { generateStrandMemberKey, strandMemberKeyPair } from './strand-member-key.js';
 import { assertNotPreSplitStrand, issueInvite, PreSplitStrandIdentityError } from './strand-membership-writer.js';
 import { MEMBERSHIP_INVITE_TTL_MS } from './strand-formation-manager.js';
@@ -533,8 +539,10 @@ export class CadreNode implements SAppIdLookup {
    * dead entry behind; recovery today is a fresh invitation.
    *
    * NOTE: entries are kept for the node's lifetime, including across a
-   * {@link stopStrand} — a stopped strand may be rediscovered by the watcher and must
-   * still get its seed. Each strand's list is capped at `MAX_STRAND_ADDRS`, but the
+   * {@link stopStrand} — a stopped strand may be claimed again with {@link addStrand}
+   * (the watcher itself will not re-offer it: the stop suppresses the id for the rest of
+   * the session) and must still get its seed. Each strand's list is capped at
+   * `MAX_STRAND_ADDRS`, but the
    * number of KEYS is bounded only by the strands this node has ever formed as an
    * initiator (not by time); if a node ever forms strands at scale, evict on
    * `unpublishStrand` or cap the map.
@@ -1436,6 +1444,12 @@ export class CadreNode implements SAppIdLookup {
    * derivation from it (`db-p2p` namespaces all of the node's protocol ids as
    * `/optimystic/<networkName>/...`), so the node options and the block-transfer
    * protocol prefix the control backfill dials can never drift apart.
+   *
+   * NOTE: the party id goes in UNENCODED here, unlike in `controlStorageScope`. Safe
+   * today because a party id is locally configured rather than replicated in, and both
+   * ends of a connection derive this string identically — an odd party id yields an odd
+   * but consistent protocol id, not a mismatch or an escaped name. If a party id ever
+   * arrives from the network, encode it here as the storage scope key already does.
    */
   private controlNetworkName(): string {
     return `control-${this.config.controlNetwork.partyId}`;
@@ -1548,6 +1562,11 @@ export class CadreNode implements SAppIdLookup {
     // party's records, so two parties on one device must not land in one store.
     // Same key as the cache label, which also makes the shared pool's `stats()` readable.
     const scope = controlStorageScope(this.config.controlNetwork.partyId);
+    // The second seam that hands a scope key to an embedder's provider; the first
+    // (`StrandInstanceManager.startStrand`) asserts the stricter strand rule. Holds by
+    // construction today — base64url is inside the charset — so this guards a future
+    // edit to `controlStorageScope`, not a reachable input.
+    assertScopeKeyCharset(scope);
     const resolved = typeof provider === 'function' ? provider(scope) : provider;
     this.controlStorage = wrapStorageWithCache(resolved, scope);
     return this.controlStorage;
@@ -1650,6 +1669,11 @@ export class CadreNode implements SAppIdLookup {
       ...(identityKey && { privateKey: identityKey }),
       ...(network?.transports && { transports: network.transports }),
       ...(network?.noiseCrypto && { noiseCrypto: network.noiseCrypto }),
+      // Always present, unlike the conditional spreads around it: an absent
+      // `connectionMonitor` would leave libp2p's 5s ping deadline, which drops a peer
+      // whose event loop is saturated by pure-JS Noise crypto. A configured value
+      // replaces the default whole (see DEFAULT_CONNECTION_MONITOR).
+      connectionMonitor: network?.connectionMonitor ?? DEFAULT_CONNECTION_MONITOR,
       // `{ wsPort }` when a listen entry names WebSocket, otherwise `{}` — and always
       // `{}` when `network.transports` is set, since the embedder owns transport policy
       // then. Spread NEXT to `transports` because the two answer the same question.
@@ -4069,6 +4093,24 @@ export class CadreNode implements SAppIdLookup {
   private async handleStrandAdded(strand: StrandRow): Promise<void> {
     log('Handling strand added from control network: %s', strand.Id);
 
+    // A replicated row carries whatever id the founding node wrote, and the id becomes a
+    // storage scope key and a libp2p protocol prefix. Checked FIRST — above the
+    // discovery branch below — so a malformed id is never offered to the hosting app as
+    // a strand it could join; that app's `addStrand` could only fail on it.
+    //
+    // Suppressed rather than retried: the id is a property of the row, so every later
+    // attempt fails identically, and without this the watcher's ladder would re-emit
+    // `strand:error` every five minutes for the life of the process. The throw still
+    // matters — the watcher's catch runs `forgetStrand`, dropping the id from
+    // `knownStrands`, so its removed-strand loop never detaches a strand that never ran.
+    if (!isValidStrandScopeKey(strand.Id)) {
+      const error = new InvalidStrandIdError(strand.Id);
+      log('Refusing strand %s: %s', strand.Id, error.message);
+      this.emit('strand:error', { strandId: strand.Id, error });
+      this.strandWatcher?.suppressStrand(strand.Id);
+      throw error;
+    }
+
     // Check if we have sApp config for this strand
     const sAppConfig = this.sAppConfigs.get(strand.Id);
     if (!sAppConfig) {
@@ -4080,10 +4122,12 @@ export class CadreNode implements SAppIdLookup {
       // already present) keeps auto-starting below, unchanged.
       //
       // Recorded BEFORE the emit so a handler that synchronously drains
-      // `getDiscoveredStrands()` sees this strand too. The watcher never offers
-      // the same strand twice (its `knownStrands` retains the id for the life of
-      // the process), so this map — not the event — is what a late subscriber
-      // reads. See the `strand:discovered` doc in types.ts.
+      // `getDiscoveredStrands()` sees this strand too. The watcher does not offer the
+      // same strand twice — its `knownStrands` retains the id, and the one thing that
+      // un-retains it (a failed `addStrand`, via `StrandWatcher.forgetStrand`) leaves the
+      // sApp config registered, so the retry takes the auto-launch branch below rather
+      // than this one. So this map — not the event — is what a late subscriber reads.
+      // See the `strand:discovered` doc in types.ts.
       this.discoveredStrands.set(strand.Id, strand);
       this.emit('strand:discovered', { strandId: strand.Id, strand });
       return;
@@ -4523,17 +4567,17 @@ export class CadreNode implements SAppIdLookup {
    *
    * A rejected call leaves nothing running but DOES leave the sApp config
    * registered, deliberately: both an explicit retry and the {@link StrandWatcher}'s
-   * automatic relaunch need it. That background relaunch covers only a strand the
-   * WATCHER launched: it forgets a row whose `onStrandAdded` threw and re-attempts it
-   * on a later poll (each failure re-emitting `strand:error`) until it succeeds. A
-   * strand claimed here after it was DISCOVERED gets no such retry — the watcher
-   * already recorded it in its `knownStrands` when it offered it as
-   * `strand:discovered`, and no later poll re-offers a strand it knows. This call has
-   * also already dropped it from {@link getDiscoveredStrands}, so a failed claim
-   * leaves the strand dormant until the caller retries or the node restarts (see
-   * `backlog/bug-discovered-strand-lost-when-claim-fails`).
-   * {@link detachStrand} (reached via {@link stopStrand}) is what abandons a strand
-   * for good.
+   * automatic relaunch need it. A failed launch here hands the strand back to that
+   * relaunch — `StrandWatcher.forgetStrand` drops the id from the watcher's
+   * `knownStrands` and records the backoff, so a later poll re-attempts it on the same
+   * `pollInterval * 2^(failures-1)` ladder a watcher-driven failure gets. Because the
+   * config stays registered, the retry takes `handleStrandAdded`'s auto-launch branch:
+   * what the app sees is `strand:error` per failed retry and `strand:started` when one
+   * succeeds, never a second `strand:discovered`. {@link detachStrand} (reached via
+   * {@link stopStrand}) is what abandons a strand for good, and its stop suppresses the
+   * strand in the watcher so this retry cannot resurrect it — a call to THIS method lifts
+   * that suppression again, since an explicit claim is a deliberate reversal of the
+   * deliberate stop.
    */
   async addStrand(config: StrandConfig): Promise<StrandInstance> {
     if (!this._running) {
@@ -4541,6 +4585,9 @@ export class CadreNode implements SAppIdLookup {
     }
 
     const { strandRow, sAppConfig, founder, partyMemberPrivateKey } = config;
+    // Before anything is recorded: an unusable id must not leave a registered sApp
+    // config behind, and must not lift a suppression this node set deliberately.
+    assertStrandScopeKey(strandRow.Id);
     if (partyMemberPrivateKey !== undefined && strandRow.Type !== 'c') {
       // Only a closed strand seats a Member/Manager, so an open launch would drop this
       // key silently. Refuse instead: the caller has confused the party identity key
@@ -4556,6 +4603,9 @@ export class CadreNode implements SAppIdLookup {
     // unclaimed backlog — a later `getDiscoveredStrands()` drain must not re-offer it.
     this.sAppConfigs.set(strandRow.Id, sAppConfig);
     this.discoveredStrands.delete(strandRow.Id);
+    // A claim also overrides any earlier `stopStrand` of this id: the watcher must track
+    // the strand again, or a party-wide removal would never stop it here.
+    this.strandWatcher?.unsuppressStrand(strandRow.Id);
     log('Registered sAppConfig for strand %s (sApp: %s, founder: %s)',
       strandRow.Id, sAppConfig.id, founder ?? 'derived');
 
@@ -4564,7 +4614,31 @@ export class CadreNode implements SAppIdLookup {
     // formation/responder flows pass one deliberately, since their consent-seated rows
     // carry a null column. See StrandConfig.founder. Same rule for the explicit
     // partyMemberPrivateKey: it wins over the StrandPartyKey control-row read.
-    const instance = await this.launchStrand(strandRow, sAppConfig, founder, partyMemberPrivateKey);
+    // Only the launch is wrapped, NOT the first-sync wait below: a wait that times out
+    // rejects with the retryable StrandAwaitingFirstSyncError and deliberately leaves the
+    // instance running, so there is nothing to re-offer and forgetting it would only have
+    // the watcher re-enter a launch for a strand that is already up.
+    let instance: StrandInstance;
+    try {
+      instance = await this.launchStrand(strandRow, sAppConfig, founder, partyMemberPrivateKey);
+    } catch (error) {
+      // Hand the strand back to the watcher's retry ladder. Harmless on the founder path
+      // (`foundStrand` → `publishStrand` + this call), where the watcher may never have
+      // offered the strand: the `knownStrands` delete is a no-op and the recorded backoff
+      // only delays the watcher's own first attempt by one poll interval, which is what
+      // should happen right after an attempt that just failed.
+      //
+      // NOTE: the retry relaunches from the CONTROL row plus the registered config, not
+      // from the row and arguments passed here — so a caller that enriched either (a
+      // synthetic `MemberPrivateKey`, an explicit `founder` or `partyMemberPrivateKey`)
+      // is retried with less than it asked for. Inert today: founder-ness re-derives from
+      // `FounderOwnerKey`, the party key re-reads from `StrandPartyKey`, and the row's
+      // shared `MemberPrivateKey` is read only by the founder bootstrap. If a joiner
+      // launch ever starts depending on that key, gate this hand-back on the passed row
+      // matching the control one.
+      this.strandWatcher?.forgetStrand(strandRow.Id);
+      throw error;
+    }
 
     // The first-sync write gate: a JOINING machine's database is withheld until it has
     // received the strand's Header from another member, because a write before that
@@ -4656,7 +4730,8 @@ export class CadreNode implements SAppIdLookup {
    * @returns The live `Strand` row — the one just inserted, or the matching one already
    *   there. A closed strand's caller should carry THIS row's `MemberPrivateKey` forward:
    *   on a repeat it is the stored key, not the argument.
-   * @throws if the node is not started, exposes no owner signing key, the id is blank, a
+   * @throws if the node is not started, exposes no owner signing key, the id is blank or
+   *   unusable as a storage scope key (`InvalidStrandIdError` — see `storage-scope.ts`), a
    *   row with the same id holds different content, or the control DB rejects the
    *   (unauthorized) insert.
    */
@@ -4665,6 +4740,11 @@ export class CadreNode implements SAppIdLookup {
     // Trim/reject here so the id that lands matches the one unpublishStrand looks up: it
     // trims too, and an untrimmed row would be unreachable by the same string.
     const trimmed = requireNonBlank(strandId, 'strand id');
+    // Refuse an unusable id HERE, not only at launch. `addStrand` already asserts, but it
+    // runs after this row is written, and this row replicates: an id no node can turn into
+    // a storage scope key would otherwise reach the whole party's control database and be
+    // declined once per member. Asserted after the trim so the id checked is the id stored.
+    assertStrandScopeKey(trimmed);
     // FounderOwnerKey records THIS machine as the row's publisher (the schema pins it to
     // the signing owner), which is what later lets a relaunch derive founder-ness.
     const desired: StrandRow = {
@@ -4925,13 +5005,20 @@ export class CadreNode implements SAppIdLookup {
     // one never cleared).
     await this.strandManager.clearOwnMemberPeerBinding(trimmed);
     // Converge locally now rather than waiting up to a poll interval. The watcher fires
-    // onStrandRemoved for a strand it tracked; the explicit stop below covers a node whose
-    // strandFilter never admitted this strand (the watcher never knew it, so it will never
-    // fire). StrandInstanceManager.stopStrand no-ops on an unknown id, so the two paths
-    // cannot double-stop into an error.
+    // onStrandRemoved for a strand it tracked; the explicit teardown below covers a node
+    // whose strandFilter never admitted this strand (the watcher never knew it, so it will
+    // never fire). StrandInstanceManager.stopStrand no-ops on an unknown id, so the two
+    // paths cannot double-stop into an error.
+    //
+    // detachStrand, NOT stopStrand: this is a party-wide removal, not a local abandonment
+    // of a strand that still exists, so it must not SUPPRESS the id in the watcher. The
+    // row is already gone — there is nothing to suppress — and an id re-published before
+    // the next poll's suppression cleanup would then never be offered again this session.
+    // (Same reasoning as handleStrandRemoved, which also avoids stopStrand's `_running`
+    // guard; here the guard is already satisfied by requireOwnerSigningKey above.)
     await this.strandWatcher?.forcePoll();
     if (this.strandManager.getInstance(trimmed)) {
-      await this.stopStrand(trimmed);
+      await this.detachStrand(trimmed);
     }
     log('Unpublished strand %s from control DB under owner %s', trimmed, signingKey.publicKeyB64);
   }
@@ -5862,17 +5949,21 @@ export class CadreNode implements SAppIdLookup {
    * Stop a strand on THIS node only: untrack it from hibernation, drop its sApp config,
    * stop the local instance, and emit `strand:stopped`. The shared `Strand` row is left
    * intact, so on the next node RESTART the strand is rediscovered and surfaces as
-   * `strand:discovered` again — not on the next watcher poll, which never re-offers a
-   * strand it has already seen (`StrandWatcher.knownStrands` retains the id for the life
-   * of the process). The stop also drops the strand from {@link getDiscoveredStrands},
-   * so a drain cannot undo a deliberate stop. Party-wide removal is
-   * {@link unpublishStrand}.
+   * `strand:discovered` again — but never again in THIS session: the stop suppresses the
+   * id in the watcher (`StrandWatcher.suppressStrand`) and drops it from
+   * {@link getDiscoveredStrands}, so neither a later poll nor a drain can undo a
+   * deliberate stop. Only an explicit {@link addStrand} does, which is the caller
+   * reversing its own decision. Party-wide removal is {@link unpublishStrand}.
    */
   async stopStrand(strandId: string): Promise<void> {
     if (!this._running) {
       throw new Error('CadreNode not running');
     }
 
+    // Suppressed HERE and not in detachStrand: the other caller of that method is
+    // `handleStrandRemoved`, which arrives precisely because the control row is gone, and
+    // a row that later reappears is a fresh strand that should be offered again.
+    this.strandWatcher?.suppressStrand(strandId);
     await this.detachStrand(strandId);
   }
 
@@ -5894,6 +5985,10 @@ export class CadreNode implements SAppIdLookup {
    * readings are the intended one: `handleStrandRemoved` arrives because the control row
    * is gone, and an explicit {@link stopStrand} is a deliberate abandonment — neither
    * strand may be re-offered to a later `getDiscoveredStrands()` drain.
+   *
+   * The watcher-level suppression that makes a stop permanent is deliberately NOT here,
+   * only in {@link stopStrand}: the two callers diverge on it. A vanished control row
+   * that reappears is a fresh strand and must be offered again.
    */
   private async detachStrand(strandId: string): Promise<void> {
     this.hibernationManager.untrackStrand(strandId);

package/src/control-formation-recorder.ts

@@ -1,6 +1,6 @@
 import debug from 'debug';
-import { randomBytes } from '@optimystic/quereus-plugin-crypto';
 import { FormationAbortedError, type ControlDatabase } from './control-database.js';
+import { mintStrandId } from './strand-id.js';
 import {
   createHttpFormationApprover,
   verifyFormationApproval,
@@ -252,10 +252,10 @@ export class ControlFormationUsageRecorder implements FormationUsageRecorder {
    * Provision a NEW strand for an UNBOUND invite and record consent against it in ONE
    * transaction (the responder-provisions fallback, now single-use-enforced).
    *
-   * Mints a fresh, globally-unique strand id from {@link randomBytes} — the same
-   * cross-platform CSPRNG `control-database`'s `generateStampId` uses, NOT
-   * `crypto.randomUUID` / `Date.now` / `Math.random` (not uniformly available across
-   * node/browser/RN) — then delegates to {@link ControlDatabase.redeemInvitation}, whose
+   * Mints a fresh, globally-unique strand id with {@link mintStrandId} — an
+   * unguessable CSPRNG id, and one `strand-id.ts` has already checked is usable as a
+   * storage scope key and network name — then delegates to
+   * {@link ControlDatabase.redeemInvitation}, whose
    * single `begin … commit` inserts the consent-authorized `Strand` row AND the matching
    * `FormationUsage` row together (both deferred CHECKs see both rows at commit). That one
    * `FormationUsage` row makes the unbound redemption single-use exactly like the bound
@@ -289,7 +289,7 @@ export class ControlFormationUsageRecorder implements FormationUsageRecorder {
     if (signal?.aborted) {
       throw new FormationAbortedError(token, 'redemption');
     }
-    const strandId = `strand-${randomBytes(128, 'hex') as string}`;
+    const strandId = mintStrandId();
     const invite = await this.controlDatabase.queryFormationInvite(token);
     const approval = await this.obtainApproval({
       token, usageStampId, strandId, peerKey, disclosure,