@serfab/cadre-core 1.3.0 → 1.5.0

package/dist/strand-watcher.js

@@ -20,6 +20,13 @@ export class StrandWatcher {
         this.provisional = new Set();
         /** Ids whose last launch attempt threw, with the backoff gating their retry. */
         this.failureStates = new Map();
+        /**
+         * Ids a deliberate local stop has withdrawn from offer for the rest of the session
+         * (see {@link suppressStrand}). Before {@link forgetStrand} existed, `knownStrands`
+         * retention alone made a stop permanent; now that a failed claim can un-know a
+         * strand, the permanence has to be recorded explicitly.
+         */
+        this.suppressed = new Set();
         this.pollTimer = null;
         this.initialPollTimer = null;
         this.running = false;
@@ -84,6 +91,8 @@ export class StrandWatcher {
             const currentMap = new Map(currentStrands.map(s => [s.Id, s]));
             // Find added strands
             for (const strand of currentStrands) {
+                if (this.suppressed.has(strand.Id))
+                    continue; // deliberately stopped locally
                 if (this.knownStrands.has(strand.Id))
                     continue;
                 const failure = this.failureStates.get(strand.Id);
@@ -108,17 +117,7 @@ export class StrandWatcher {
                 }
                 catch (error) {
                     log('Error handling strand add for %s: %o', strand.Id, error);
-                    // A failed launch leaves nothing running (StrandInstanceManager drops the
-                    // record), so forget the strand and let a later poll retry it — gated by
-                    // the backoff recorded here. One case does leave something running: a row
-                    // this machine published lands on an instance something else already
-                    // attached, and honouring the founder request on it (CadreNode.launchStrand
-                    // → StrandInstanceManager.foundExistingStrand) throws. The instance stays up
-                    // as a joiner and the retry re-attempts the bootstrap on it, which is what
-                    // should happen — but do not read the line above as "nothing is running".
-                    this.knownStrands.delete(strand.Id);
-                    this.provisional.delete(strand.Id);
-                    this.recordFailure(strand.Id);
+                    this.forgetStrand(strand.Id);
                 }
             }
             // Re-evaluate provisional admissions whose sAppId may now be resolvable.
@@ -162,13 +161,25 @@ export class StrandWatcher {
                     }
                 }
             }
-            // Drop backoff state for strands whose control-network row is gone; a row
-            // that reappears is a fresh strand and gets a fresh first attempt.
+            // Drop backoff and suppression state for strands whose control-network row is
+            // gone; a row that reappears is a fresh strand and gets a fresh first attempt,
+            // un-backed-off and un-suppressed.
             for (const strandId of [...this.failureStates.keys()]) {
                 if (!currentMap.has(strandId)) {
                     this.failureStates.delete(strandId);
                 }
             }
+            // NOTE: the clear needs a poll that actually SEES the row absent, so a sibling that
+            // unpublishes and re-publishes a locally-stopped id inside one poll interval leaves
+            // it suppressed for the session. Contrived today — re-seating a removed id is
+            // owner-gated and manual — and there is no row version to distinguish the new row
+            // from the old. If re-publishing a removed id ever becomes routine, give the row a
+            // generation column and clear suppression on a change rather than on absence.
+            for (const strandId of [...this.suppressed]) {
+                if (!currentMap.has(strandId)) {
+                    this.suppressed.delete(strandId);
+                }
+            }
         }
         catch (error) {
             // NOTE: a machine cut off from its party before it ever received the `Strand` block
@@ -222,8 +233,58 @@ export class StrandWatcher {
         this.knownStrands.clear();
         this.provisional.clear();
         this.failureStates.clear();
+        this.suppressed.clear();
         log('StrandWatcher stopped');
     }
+    /**
+     * Forget a strand whose launch failed outside this watcher, so a later poll
+     * re-offers it — gated by the same backoff a watcher-driven failure gets.
+     *
+     * A failed launch normally leaves nothing running (StrandInstanceManager drops the
+     * record), which is what makes re-offering it correct. One case does leave something
+     * running: a row this machine published lands on an instance something else already
+     * attached, and honouring the founder request on it (CadreNode.launchStrand →
+     * StrandInstanceManager.foundExistingStrand) throws. The instance stays up as a joiner
+     * and the retry re-attempts the bootstrap on it, which is what should happen — but do
+     * not read the line above as "nothing is running".
+     */
+    forgetStrand(strandId) {
+        this.knownStrands.delete(strandId);
+        this.provisional.delete(strandId);
+        this.recordFailure(strandId);
+    }
+    /**
+     * Never offer this strand again this session. Two callers, both meaning "the retry
+     * ladder cannot help here": a deliberate local stop, and a launch that can never
+     * succeed — a strand whose id is unusable as a storage scope key
+     * (`CadreNode.handleStrandAdded`), which every later attempt would reject identically.
+     * A launch that merely FAILED is not one of them; that goes to {@link forgetStrand}.
+     *
+     * Cleared when the strand's control row disappears, because a row that reappears is a
+     * strand the party re-published and the stop said nothing about it; also cleared by
+     * {@link stop}, since sApp configs do not survive it either, and by
+     * {@link unsuppressStrand} when the caller claims the strand again.
+     */
+    suppressStrand(strandId) {
+        log('Suppressing strand %s — deliberate local stop, will not be re-offered', strandId);
+        this.suppressed.add(strandId);
+    }
+    /**
+     * Revoke a {@link suppressStrand}: a deliberate local claim overrides the deliberate
+     * local stop that preceded it.
+     *
+     * Not cosmetic — the suppression check runs before the `knownStrands` one, so a
+     * suppressed id is never re-recorded there, and the removed-strand loop iterates
+     * `knownStrands`. A strand re-claimed while still suppressed would therefore run with
+     * the watcher blind to it: a party-wide removal would never stop it locally. That is
+     * reachable whenever the stop found the id already un-known — after a claim that
+     * failed, or for a strand the filter never admitted.
+     */
+    unsuppressStrand(strandId) {
+        if (this.suppressed.delete(strandId)) {
+            log('Strand %s re-claimed — suppression lifted', strandId);
+        }
+    }
     /**
      * Get currently known strands
      */

package/dist/strand-watcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"strand-watcher.js","sourceRoot":"","sources":["../src/strand-watcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,MAAM,GAAG,GAAG,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAUjD;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AA0C3C;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IAwBxB,YACE,SAA0B,EAC1B,SAAiC,EACjC,SAAuB,EAAE,IAAI,EAAE,KAAK,EAAE,EACtC,eAAuB,IAAI,EAC3B,YAA2B,EAC3B,MAAoB,IAAI,CAAC,GAAG;QAftB,iBAAY,GAA2B,IAAI,GAAG,EAAE,CAAC;QACzD,wFAAwF;QAChF,gBAAW,GAAgB,IAAI,GAAG,EAAE,CAAC;QAC7C,gFAAgF;QACxE,kBAAa,GAAoC,IAAI,GAAG,EAAE,CAAC;QAC3D,cAAS,GAA0C,IAAI,CAAC;QACxD,qBAAgB,GAAyC,IAAI,CAAC;QAC9D,YAAO,GAAG,KAAK,CAAC;QAUtB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,GAAG,CAAC,uDAAuD,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IACrF,CAAC;IAED;;;;OAIG;IACK,cAAc,CAAC,MAAiB;QACtC,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACzB,KAAK,KAAK;gBACR,OAAO,MAAM,CAAC;YAChB,KAAK,MAAM;gBACT,OAAO,QAAQ,CAAC;YAClB,KAAK,UAAU;gBACb,OAAO,MAAM,CAAC,EAAE,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;YAChE,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;oBACvB,oEAAoE;oBACpE,OAAO,MAAM,CAAC;gBAChB,CAAC;gBACD,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACtD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,wEAAwE;oBACxE,GAAG,CAAC,0DAA0D,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;oBAC3E,OAAO,OAAO,CAAC;gBACjB,CAAC;gBACD,MAAM,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;gBAC9C,GAAG,CAAC,mEAAmE,EACnE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBACpD,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;YACrC,CAAC;YACD;gBACE,OAAO,MAAM,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,aAAa,CAAC,QAAgB;QACpC,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACvE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAC;QACtF,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QAClF,GAAG,CAAC,iEAAiE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACpG,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,IAAI;QAChB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAE1B,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;YAC3D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAE/D,qBAAqB;YACrB,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;gBACpC,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBAAE,SAAS;gBAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAClD,0EAA0E;gBAC1E,qEAAqE;gBACrE,IAAI,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,aAAa;oBAAE,SAAS,CAAC,oCAAoC;gBACjG,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;gBAC7C,IAAI,QAAQ,KAAK,QAAQ;oBAAE,SAAS;gBACpC,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;gBACnC,2EAA2E;gBAC3E,+EAA+E;gBAC/E,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;gBACzC,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;oBACzB,kEAAkE;oBAClE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAClC,CAAC;gBACD,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;oBAC3C,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACvC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,GAAG,CAAC,sCAAsC,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;oBAC9D,0EAA0E;oBAC1E,yEAAyE;oBACzE,0EAA0E;oBAC1E,qEAAqE;oBACrE,4EAA4E;oBAC5E,6EAA6E;oBAC7E,2EAA2E;oBAC3E,0EAA0E;oBAC1E,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;oBACpC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;oBACnC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAChC,CAAC;YACH,CAAC;YAED,yEAAyE;YACzE,0EAA0E;YAC1E,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACxC,IAAI,CAAC,MAAM;oBAAE,SAAS,CAAC,2CAA2C;gBAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;gBAC7C,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;oBACxB,gDAAgD;oBAChD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACpC,CAAC;qBAAM,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBACjC,oEAAoE;oBACpE,GAAG,CAAC,kDAAkD,EAAE,QAAQ,CAAC,CAAC;oBAClE,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBACnC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBAClC,IAAI,CAAC;wBACH,MAAM,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;oBACjD,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,GAAG,CAAC,yCAAyC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;oBAClE,CAAC;gBACH,CAAC;gBACD,wEAAwE;YAC1E,CAAC;YAED,qEAAqE;YACrE,0EAA0E;YAC1E,uBAAuB;YACvB,KAAK,MAAM,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC9B,GAAG,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;oBACpC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBACnC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBAClC,IAAI,CAAC;wBACH,MAAM,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;oBACjD,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,GAAG,CAAC,yCAAyC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;oBAClE,CAAC;gBACH,CAAC;YACH,CAAC;YAED,0EAA0E;YAC1E,mEAAmE;YACnE,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBACtD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC9B,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACtC,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,oFAAoF;YACpF,gFAAgF;YAChF,wFAAwF;YACxF,mFAAmF;YACnF,sFAAsF;YACtF,qFAAqF;YACrF,GAAG,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,GAAG,CAAC,+BAA+B,CAAC,CAAC;YACrC,OAAO;QACT,CAAC;QAED,GAAG,CAAC,wBAAwB,CAAC,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QAEpB,0BAA0B;QAC1B,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YAChC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAEtB,4DAA4D;QAC5D,0EAA0E;QAC1E,IAAI,CAAC,gBAAgB,GAAG,UAAU,CAAC,GAAG,EAAE;YACtC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;YAC7B,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC,EAAE,GAAG,CAAC,CAAC;QAER,GAAG,CAAC,uBAAuB,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QAED,GAAG,CAAC,wBAAwB,CAAC,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QAErB,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACpC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;QAED,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,GAAG,CAAC,uBAAuB,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS;QACb,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;CACF"}
+{"version":3,"file":"strand-watcher.js","sourceRoot":"","sources":["../src/strand-watcher.ts"],"names":[],"mappings":"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"}

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`).
@@ -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} — 8 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).
      *
@@ -358,6 +359,72 @@ 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;
+    /**
+     * 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} (2000 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`.
+     *
+     * 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`).
+     *
+     * 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()`
@@ -438,6 +505,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
  */
@@ -482,11 +606,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
  */
@@ -607,10 +741,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`,
+     * 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.
      */
     strandFirstSync?: StrandFirstSyncConfig;
     /** Hibernation configuration */
@@ -1155,6 +1291,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
@@ -1164,13 +1324,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}.
@@ -54,9 +113,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;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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "1.3.0",
+  "version": "1.5.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.6.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",
-    "@quereus/quereus": "^4.19.4",
-    "@serfab/quereus-plugin-sereus": "^1.3.0",
+    "@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",
+    "@quereus/quereus": "^4.20.0",
+    "@serfab/quereus-plugin-sereus": "^1.5.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"