@serfab/cadre-core 1.9.0 → 1.11.0

package/dist/types.d.ts

@@ -17,6 +17,7 @@ import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
 import type { RevocableTable } from './control-authorization.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
+import type { FormationRejectionCode } from './strand-formation-rejection.js';
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
  * createLibp2pNode after node creation (not surfaced on the base Libp2p type).
@@ -446,8 +447,9 @@ export interface NetworkConfig {
      * reservation drive, the control-cohort dial budgets, and the per-peer cohort read deadline
      * ({@link cohortQueryTimeoutMs}, unless set explicitly). It is also handed to Optimystic
      * (`NodeOptions.linkRoundTripMs`), default included, which derives its own deadlines from it:
-     * its request dials and responses, its block pushes, and libp2p's `dialTimeout` and
-     * `inboundUpgradeTimeout` on every node. Reaching another machine through a
+     * its request dials and responses, its block pushes, and libp2p's `addressDialTimeout`,
+     * `dialTimeout` and `inboundUpgradeTimeout` on every node, cadre adding its admission decisions
+     * to the three that open a connection. 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,
@@ -464,8 +466,12 @@ export interface NetworkConfig {
      * 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". Optimystic refuses, in the same place, a value above its
-     * `MAX_LINK_ROUND_TRIP_MS` (about 1.66 days).
+     * once" and a `NaN` means "never". A value above about 10.8 hours is refused in the same place,
+     * by Optimystic: the request dial cadre states from it (eleven round trips plus two admission
+     * decisions, `optimysticDialLimits` in `link-budget.ts`) then exceeds its
+     * `MAX_RPC_DIAL_TIMEOUT_MS` (about 4.97 days), and its error names `rpcDeadlines.dialTimeoutMs`.
+     * That is below Optimystic's own `MAX_LINK_ROUND_TRIP_MS` (about 13.3 hours) and far above any
+     * real link, so cadre adds no check of its own.
      */
     linkRoundTripMs?: number;
     /**
@@ -537,8 +543,8 @@ export interface NetworkConfig {
          * so an address that never answers cannot use up the time the peer's other
          * addresses needed. Defaults to
          * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}. A value given
-         * here replaces that whole derived budget, including its allowance for the
-         * called machine's admission decision (`relayedDialBudgetMs`).
+         * here replaces that whole derived budget, including its allowances for the
+         * relay's and the called machine's admission decisions (`relayedDialBudgetMs`).
          */
         perAddressDialTimeoutMs?: number;
         /**
@@ -598,15 +604,11 @@ export interface NetworkConfig {
  *
  * 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
+ * every libp2p version. libp2p 3.3 reports each ping's duration back to the monitor's
+ * `AdaptiveTimeout`, so a ceiling above `pingInterval` would 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. It also sidesteps the monitor keeping one `AdaptiveTimeout`
+ * for all of a node's connections, so one slow peer cannot lengthen the deadline for every
  * connection on that node.
  */
 export declare const DEFAULT_CONNECTION_MONITOR: Readonly<{
@@ -1102,6 +1104,73 @@ export interface StrandRow {
      */
     FounderOwnerKey: string | null;
 }
+/**
+ * A `CadreControl.PendingJoin` row: a join this party asked for through another party's
+ * invitation, readable by every machine of the party. Each outcome carries only its own
+ * columns (the schema's `OutcomeShape` check): `'joined'` sets `StrandId` (and, for a
+ * closed strand, `MembershipInvite`), `'failed'` sets `FailureCode`, and a pending row
+ * (`Outcome: null`) sets neither.
+ */
+export interface PendingJoinRow {
+    /** base64url sha256 of the invitation token (`pendingJoinId`). */
+    Id: string;
+    /** `CadreNode.encodeInvitation` of the invitation. A bearer credential. */
+    Invitation: string;
+    /** `canonicalJson` of the disclosure the requester gave. */
+    Disclosure: string;
+    /** Epoch ms. */
+    RequestedAt: number;
+    /** Epoch ms; no attempt starts at or after it. */
+    ExpiresAt: number;
+    Outcome: null | 'joined' | 'failed';
+    /** Epoch ms the outcome was recorded; null while pending. */
+    OutcomeAt: number | null;
+    /** `'joined'`: the strand the formation returned. */
+    StrandId: string | null;
+    /** `'joined'`, closed strand: JSON of the {@link StrandMembershipInvite} the formation delivered. */
+    MembershipInvite: string | null;
+    /** `'failed'`: a `FormationRejectionCode`, `'expired'` or `'local'`. Not constrained by the schema. */
+    FailureCode: string | null;
+    /** `'failed'`: human-readable text. */
+    FailureReason: string | null;
+    /** Single-use nonce of this row incarnation; `ControlDatabase.replacePendingJoin` names it as the row it replaces. */
+    StampId: string;
+}
+/**
+ * A join this party asked for through `CadreNode.requestJoin`, as one machine sees it.
+ *
+ * `pending`, `joined` and `failed` come from the party-wide `PendingJoin` row and read the same
+ * on every machine. `trying` (an attempt is running on this machine) and `waiting` (this
+ * machine's last attempt failed in a way worth retrying) are this machine's own view of a
+ * pending row, so two machines can report different states for it.
+ */
+export interface PendingJoinStatus {
+    /** `PendingJoin.Id`: the sha256 of the invitation token. */
+    id: string;
+    sAppId: string;
+    /** Epoch ms. */
+    requestedAt: number;
+    /** Epoch ms; no attempt starts at or after it. */
+    expiresAt: number;
+    state: 'pending' | 'trying' | 'waiting' | 'joined' | 'failed';
+    /** `'waiting'`: when this machine tries again, epoch ms. */
+    nextAttemptAt?: number;
+    /**
+     * `'waiting'`: why this machine's last attempt failed. `'unreachable'` means no answer came
+     * back; `'local'` means the attempt failed on this machine before an answer.
+     */
+    lastError?: {
+        code: FormationRejectionCode | 'unrecognized' | 'unreachable' | 'local';
+        reason: string;
+    };
+    /** `'joined'`: the strand the join produced. */
+    strandId?: string;
+    /** `'failed'`: a `FormationRejectionCode`, `'expired'`, or `'local'` (approved, then a step on the joining machine failed). */
+    failure?: {
+        code: string;
+        reason: string;
+    };
+}
 /**
  * sApp configuration provided by the hosting application when creating a strand.
  * This is what the app developer provides - NOT loaded from the network.
@@ -1263,7 +1332,13 @@ export interface OpenInvitation {
     sAppId: string;
     /** When this invitation expires */
     expiration: Date;
-    /** Bootstrap addresses to contact the inviter's cadre */
+    /**
+     * Addresses of the inviting party's machines, each ending in `/p2p/<peerId>`: the minting
+     * machine's own first, then up to three of its siblings with up to four addresses each
+     * (`CadreNode.createOpenInvitation`). A joiner tries the machines in order, one formation
+     * session each, so an entry may be dead by the time it is used; one that names no machine
+     * is ignored.
+     */
     bootstrap: string[];
 }
 /**
@@ -1282,7 +1357,11 @@ export interface StrandMembershipInvite {
      * The invite ed25519 PRIVATE seed (base64url). A single-use bearer credential:
      * whoever holds it can `consumeInvite` exactly once. Same sensitivity class and
      * handling as `memberPrivateKey` — delivered only inside the validated,
-     * post-approval formation result, never written to either side's control DB.
+     * post-approval formation result. The inviting side never writes it to its control
+     * DB. The joining side may copy it into its own `PendingJoin` row
+     * (`MembershipInvite`), owner-signed and party-private like
+     * `JoinedStrand.MemberPrivateKey`, so a join finished on one machine of the party
+     * can be seated by whichever machine launches the strand first.
      */
     invitePrivateKey: string;
 }
@@ -1507,6 +1586,13 @@ export interface CadreNodeEvents {
      * or connection state change.
      */
     'control:write-abandoned': ControlRetryAbandonment;
+    /**
+     * Emitted when this machine's view of a join asked for with `CadreNode.requestJoin` changes:
+     * its own attempt started or ended, or a pass read an outcome another owner machine wrote.
+     * Owner machines only, since only they run the retry loop. A dismissed join emits nothing
+     * further; `listPendingJoins` no longer names it.
+     */
+    'pendingJoin:changed': PendingJoinStatus;
     /** Emitted when a seed is received via the seed protocol */
     'seed:received': {
         partyId: string;

package/dist/types.js

@@ -80,15 +80,11 @@ export const HIBERNATION_TIMEOUTS = {
  *
  * 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
+ * every libp2p version. libp2p 3.3 reports each ping's duration back to the monitor's
+ * `AdaptiveTimeout`, so a ceiling above `pingInterval` would 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. It also sidesteps the monitor keeping one `AdaptiveTimeout`
+ * for all of a node's connections, so one slow peer cannot lengthen the deadline for every
  * connection on that node.
  */
 export const DEFAULT_CONNECTION_MONITOR = Object.freeze({

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAmFA;;;;;;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;AAqdF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,uFAAuF;IACvF,mFAAmF;IACnF,YAAY,EAAE,KAAM;IACpB,kFAAkF;IAClF,kFAAkF;IAClF,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAM,EAAE,UAAU,EAAE,KAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAmBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAoFA;;;;;;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;AA0dF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;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;;;;;;;;;;;;;;;;;;;;;GAqBG;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.9.0",
+  "version": "1.11.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -70,37 +70,37 @@
   "devDependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
     "@chainsafe/libp2p-yamux": "^8.0.1",
-    "@libp2p/circuit-relay-v2": "^4.1.3",
-    "@libp2p/identify": "4.0.10",
-    "@libp2p/logger": "^6.2.2",
-    "@libp2p/peer-store": "^12.0.10",
-    "@libp2p/tcp": "^11.0.10",
-    "@libp2p/webrtc": "6.0.14",
-    "@libp2p/websockets": "^10.1.3",
-    "@optimystic/db-p2p-storage-fs": "^1.8.1",
+    "@libp2p/circuit-relay-v2": "^4.2.13",
+    "@libp2p/identify": "4.1.14",
+    "@libp2p/logger": "^6.2.13",
+    "@libp2p/peer-store": "^12.0.28",
+    "@libp2p/tcp": "^11.0.28",
+    "@libp2p/webrtc": "6.0.33",
+    "@libp2p/websockets": "^10.1.21",
+    "@optimystic/db-p2p-storage-fs": "^1.9.0",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
-    "datastore-core": "^11.0.1",
+    "datastore-core": "^12.0.1",
     "main-event": "^1.0.1",
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
   },
   "dependencies": {
-    "@libp2p/crypto": "^5.1.13",
-    "@libp2p/interface": "^3.1.0",
-    "@libp2p/peer-id": "^6.0.4",
-    "@libp2p/peer-record": "^9.0.5",
-    "@multiformats/multiaddr": "^12.5.1",
-    "@optimystic/db-core": "^1.8.1",
-    "@optimystic/db-p2p": "^1.8.1",
-    "@optimystic/quereus-plugin-crypto": "^1.8.1",
-    "@optimystic/quereus-plugin-optimystic": "^1.8.1",
+    "@libp2p/crypto": "^5.1.23",
+    "@libp2p/interface": "^3.3.0",
+    "@libp2p/peer-id": "^6.0.15",
+    "@libp2p/peer-record": "^9.0.16",
+    "@multiformats/multiaddr": "^13.0.3",
+    "@optimystic/db-core": "^1.9.0",
+    "@optimystic/db-p2p": "^1.9.0",
+    "@optimystic/quereus-plugin-crypto": "^1.9.0",
+    "@optimystic/quereus-plugin-optimystic": "^1.9.0",
     "@quereus/quereus": "^4.20.0",
-    "@serfab/quereus-plugin-sereus": "^1.9.0",
+    "@serfab/quereus-plugin-sereus": "^1.11.0",
     "debug": "^4.4.3",
-    "libp2p": "^3.1.3",
-    "uint8arrays": "^5.1.0"
+    "libp2p": "^3.3.11",
+    "uint8arrays": "^6.1.1"
   }
 }