@serfab/cadre-core 1.8.0 → 1.10.0

package/src/push-fanout.ts

@@ -200,7 +200,7 @@ export class PushFanoutService {
    * through to FCM/APNs.
    *
    * NOTE: the platform push waits for the whole direct dial to fail, up to
-   * `DEFAULT_WAKE_DIAL_BUDGET_MS` (46 s at the default declared link). A suspended
+   * `DEFAULT_WAKE_DIAL_BUDGET_MS` (57 s at the default declared link). A suspended
    * phone typically fails its relay address fast and spends the rest on its direct
    * one. If that delay shows up, start the platform push in parallel with the dial,
    * or after its first attempt.

package/src/seed-bootstrap.ts

@@ -209,7 +209,7 @@ export interface SeedBootstrapConfig {
    * not-yet-trusted node during onboarding, so this is the more exposed
    * direction than the receiver knobs above.
    *
-   * Defaults to `relayedRequestBudgetMs(linkRoundTripMs)` (`link-budget.ts`; 23 s at the
+   * Defaults to `relayedRequestBudgetMs(linkRoundTripMs)` (`link-budget.ts`; 28.5 s at the
    * default declaration): one dial that may need a relay, then one request and its answer.
    * Delivery does not set `runOnLimitedConnection`, so it does not use a limited relayed
    * connection today; the relayed-dial count is the upper bound on the dial it can use, the
@@ -1138,7 +1138,7 @@ export class SeedBootstrapService {
    * stream, then dial the seed's owners.
    *
    * The ack and the close come BEFORE the owner dials: an unreachable owner can hold
-   * a dial for `dialBudget.totalMs` (64 s at the default declared link), which is not
+   * a dial for `dialBudget.totalMs` (86 s at the default declared link), which is not
    * link time and does not belong inside the sender's delivery deadline. The close is
    * what releases the sender, which reads the ack to end-of-stream. The stream stays
    * counted in {@link activeStreams} through the dials, so {@link maxConcurrentSeeds}

package/src/strand-addr-protocol.ts

@@ -387,7 +387,7 @@ export async function collectStrandAddrs(
  * per-target lines scattered through a concurrent fan-out do not reassemble into
  * "this sibling was unreachable".
  *
- * NOTE: cost is (targets × `timeoutMs`, 23 s each at the default declared link) with
+ * NOTE: cost is (targets × `timeoutMs`, 28.5 s each at the default declared link) with
  * no whole-sibling budget, the same shape `dialWake` bounds with
  * `DEFAULT_WAKE_DIAL_BUDGET_MS`. Siblings are asked concurrently, so a collection costs
  * its slowest sibling, not the sum. Fine today — `dialTargets` yields the peerId plus
@@ -434,7 +434,7 @@ async function dialOneSibling(
 
 /**
  * Deadline for ONE attempt to ask a sibling — dial, request, response — unless the caller set
- * its own: `relayedRequestBudgetMs` at the declared link (23 s at the default).
+ * its own: `relayedRequestBudgetMs` at the declared link (28.5 s at the default).
  *
  * An attempt is either a dial by peer id, which normally reuses an open control connection
  * (`CIRCUIT_REQUEST_ROUND_TRIPS`, 2), or the fallback to the sibling's control addresses, a

package/src/strand-formation-deadlines.ts

@@ -62,14 +62,14 @@ export interface FormationDeadlines {
  * cohort read at that link (`cohortReadDeadlineMs`, 2L: one request and its answer over an
  * open circuit) and `K` one commit (`commitBudgetMs`, 20L, measured):
  *
- *   dialMs                   = a relayed dial plus one protocol negotiation    (5L + 2 000)
+ *   dialMs                   = a relayed dial plus one protocol negotiation    (6L + 4 000)
  *   awaitContactMs           = one request over the open stream               (2L)
  *   validationMs             = 2R                                             (4L)
  *   provisionWorkMs          = approval hook (10 000, flat) + 2R + K           (10 000 + 24L)
  *   provisionGraceMs         = R + K                                          (22L)
  *   responseTravelMarginMs   = L + validationMs                               (5L)
  *   initiatorAwaitResponseMs = work + grace + margin                          (10 000 + 51L)
- *   sessionMs                = dialMs + initiatorAwaitResponseMs              (12 000 + 56L)
+ *   sessionMs                = dialMs + initiatorAwaitResponseMs              (14 000 + 57L)
  *
  * Why each term:
  *
@@ -120,10 +120,10 @@ export interface FormationDeadlines {
  * **What this costs.** At the default declaration (3 500 ms) a joiner whose responder
  * accepts the contact and then hangs waits up to 188.5 s, about three minutes, before it is
  * told, where the fixed ladder this replaced told it after 15 s; the whole session is
- * bounded at 208 s. A responder that is unreachable still fails at the dial, 19.5 s. A host
+ * bounded at 213.5 s. A responder that is unreachable still fails at the dial, 25 s. A host
  * that knows its party is on a fast link lowers `linkRoundTripMs` and gets roughly the old
- * numbers back (at L = 100: dial 2.5 s, provisioning 14.6 s, await-response 15.1 s, session
- * 17.6 s). Before this derivation, the fixed 5 s dial could not open a relayed connection
+ * numbers back (at L = 100: dial 4.6 s, provisioning 14.6 s, await-response 15.1 s, session
+ * 19.7 s). Before this derivation, the fixed 5 s dial could not open a relayed connection
  * above a 1.25-second round trip, and the fixed 2 s grace could not contain one commit at the
  * supported link, so a joiner could be told 'timed out' over an invite that was in fact
  * spent.

package/src/strand-formation-manager.ts

@@ -28,12 +28,14 @@ import type {
 import {
   FormationListener,
   INVALID_TOKEN_REASON,
-  dialFormation,
+  dialFormationByMachine,
   isValidResponderCreatesResult,
   isWellFormedMembershipInvite,
   type FormationContactMessage,
   type FormationProvisionResult,
+  type FormationRejection,
   type FormationResultMessage,
+  type FormationTokenCheck,
   type ResponderProvisionOutcome
 } from './strand-formation-protocol.js';
 import { formationDeadlines } from './strand-formation-deadlines.js';
@@ -84,17 +86,18 @@ export const MEMBERSHIP_INVITE_UNAVAILABLE_REASON = 'Strand membership invitatio
 export const HOST_STRAND_MUST_BE_RECREATED_REASON = 'Host strand must be recreated';
 
 /**
- * Rejection reason a would-be joiner is told for each approval-failure category
+ * The rejection a would-be joiner is told for each approval-failure category
  * (see {@link FormationApprovalFailure}). Distinct per category on purpose: mapping any
- * of these onto the generic 'Formation conflict, retry' would tell an operator to retry
- * what retrying can never fix (e.g. a non-enrolled validation key).
+ * of these onto the generic `'conflict'` would tell a joiner to retry what retrying can
+ * never fix (e.g. a non-enrolled validation key). The three inviter-setup faults share
+ * one code; the reason text still names which one for the operator.
  */
-const APPROVAL_REJECTION_REASONS: Record<FormationApprovalFailure, string> = {
-  refused: 'Formation approval refused',
-  unavailable: 'Formation approval unavailable, retry',
-  malformed: 'Formation approval invalid',
-  unenrolled: 'Formation approval key is not enrolled',
-  misconfigured: 'Formation approval misconfigured'
+const APPROVAL_REJECTIONS: Record<FormationApprovalFailure, FormationRejection> = {
+  refused: { approved: false, code: 'approval-refused', reason: 'Formation approval refused' },
+  unavailable: { approved: false, code: 'approval-unavailable', reason: 'Formation approval unavailable, retry' },
+  malformed: { approved: false, code: 'approval-invalid', reason: 'Formation approval invalid' },
+  unenrolled: { approved: false, code: 'approval-invalid', reason: 'Formation approval key is not enrolled' },
+  misconfigured: { approved: false, code: 'approval-invalid', reason: 'Formation approval misconfigured' }
 };
 
 /**
@@ -138,6 +141,13 @@ export interface StrandFormationManagerConfig {
   protocolId?: string;
 }
 
+/**
+ * A node's own cadre addresses, sent on every formation. A function is read at each
+ * formation, for a node whose addresses change after the manager is built — a
+ * `CadreNode` installs its responder before a relay reservation gives it any.
+ */
+export type CadrePeerAddrsSource = string[] | (() => string[]);
+
 /**
  * Options for creating a StrandFormationManager
  */
@@ -153,7 +163,7 @@ export interface StrandFormationManagerOptions {
   /** This party's ID for identification */
   partyId: string;
   /** This party's cadre peer addresses */
-  cadrePeerAddrs?: string[];
+  cadrePeerAddrs?: CadrePeerAddrsSource;
   /**
    * This node's live STRAND-network multiaddrs for a strand it is running (responder
    * side). Wired by `CadreNode` to its own per-strand address lookup; the manager has no
@@ -213,7 +223,7 @@ export class StrandFormationManager {
   private readonly strandProvisioner?: StrandProvisioner;
   private readonly formationResponseValidator?: FormationResponseValidator;
   private readonly partyId: string;
-  private readonly cadrePeerAddrs: string[];
+  private readonly cadrePeerAddrs: CadrePeerAddrsSource;
   private readonly resolveStrandAddrs?: (strandId: string) => string[];
   private readonly issueMembershipInvite?: MembershipInviteIssuer;
   private readonly config: StrandFormationManagerConfig;
@@ -237,7 +247,7 @@ export class StrandFormationManager {
       validateDisclosure: (token, disclosure) => this.validateDisclosure(token, disclosure),
       provisionStrand: (contact, signal) =>
         this.provisionAsResponder(contact, signal),
-      getResponderIdentity: () => ({ partyId: this.partyId, cadrePeerAddrs: this.cadrePeerAddrs }),
+      getResponderIdentity: () => ({ partyId: this.partyId, cadrePeerAddrs: this.currentCadrePeerAddrs() }),
       // Forwarded only when wired, so `FormationListenerOptions.resolveStrandAddrs`
       // stays genuinely absent (and the listener short-circuits) for an unwired manager.
       ...(this.resolveStrandAddrs && { resolveStrandAddrs: this.resolveStrandAddrs }),
@@ -251,6 +261,10 @@ export class StrandFormationManager {
     log('StrandFormationManager created for party: %s', this.partyId);
   }
 
+  private currentCadrePeerAddrs(): string[] {
+    return typeof this.cadrePeerAddrs === 'function' ? this.cadrePeerAddrs() : this.cadrePeerAddrs;
+  }
+
   /**
    * Register this manager as a protocol handler on a libp2p node.
    * Call this on the control network node to handle incoming formation requests.
@@ -283,8 +297,10 @@ export class StrandFormationManager {
    * Builds a contact message carrying the real token + disclosure + this party's
    * real cadre addresses + the joiner's consent (minted and signed by the
    * solicitation layer — this manager only places it on the contact), dials the
-   * responder over the native protocol, and validates the responder's result
-   * before returning.
+   * inviting party's machines the invitation names, one at a time, over the native
+   * protocol ({@link dialFormationByMachine}), and validates the responder's result
+   * before returning. Every machine gets the same contact, so at most one of them can
+   * record this redemption.
    */
   async formStrand(
     invitation: OpenInvitation,
@@ -301,12 +317,12 @@ export class StrandFormationManager {
       usageStampId: consent.usageStampId,
       peerSignature: consent.peerSignature,
       disclosure,
-      cadrePeerAddrs: this.cadrePeerAddrs
+      cadrePeerAddrs: this.currentCadrePeerAddrs()
     };
 
     this.dialerSessions++;
     try {
-      const dialed = await dialFormation(node, {
+      const dialed = await dialFormationByMachine(node, {
         contact,
         responderAddrs: invitation.bootstrap,
         validateResponse: (response) => this.validateResponse(invitation, disclosure, response),
@@ -383,7 +399,12 @@ export class StrandFormationManager {
 
   // ── Responder-side hooks ─────────────────────────────────────────────────────
 
-  private async validateToken(token: string): Promise<{ valid: boolean }> {
+  /**
+   * An expired or used-up invitation is `'token-spent'` (final); one with no row here is
+   * `'token-unknown'` (retryable — the row may not have replicated to this machine yet), and
+   * so is one from a recorder that does not say why.
+   */
+  private async validateToken(token: string): Promise<FormationTokenCheck> {
     if (!this.formationUsageRecorder) {
       // No recorder configured — accept all tokens.
       return { valid: true };
@@ -391,13 +412,13 @@ export class StrandFormationManager {
 
     const tokenCheck = await this.formationUsageRecorder.isTokenValid(token);
     if (!tokenCheck.valid) {
-      log('Token invalid: %s', token);
-      return { valid: false };
+      log('Token invalid (%s): %s', tokenCheck.reason ?? 'unknown', token);
+      return { valid: false, code: tokenCheck.reason === 'expired' ? 'token-spent' : 'token-unknown' };
     }
 
     if (await this.formationUsageRecorder.isTokenUsed(token)) {
       log('Token already used: %s', token);
-      return { valid: false };
+      return { valid: false, code: 'token-spent' };
     }
 
     return { valid: true };
@@ -438,7 +459,7 @@ export class StrandFormationManager {
    * ({@link InvitationExhaustedError}, raised by `ControlDatabase` when the count of recorded
    * uses has reached the invite's seat budget — which is how the loser of a same-node race
    * surfaces, the local write queue having serialized the two writes) is reported as
-   * `'Invalid token'`, because retrying it can never succeed. Concurrent redemptions never
+   * `'token-spent'`, because retrying it can never succeed. Concurrent redemptions never
    * contend for a shared row key — each writes under its own `UsageStampId` — so there is no
    * key collision to surface here at all. The LOG-before-reject keeps this a deliberate
    * internal-error→protocol-rejection conversion (AGENTS.md: don't eat exceptions silently),
@@ -456,7 +477,7 @@ export class StrandFormationManager {
     const disclosureText = canonicalJson(contact.disclosure);
     if (uint8ArrayFromString(disclosureText, 'utf8').byteLength > MAX_DISCLOSURE_BYTES) {
       log('Disclosure over %d bytes; rejecting token %s', MAX_DISCLOSURE_BYTES, token);
-      return { approved: false, reason: 'Disclosure too large' };
+      return { approved: false, code: 'disclosure-too-large', reason: 'Disclosure too large' };
     }
 
     const recorder = this.formationUsageRecorder;
@@ -487,7 +508,7 @@ export class StrandFormationManager {
           // here can atomically un-issue a strand-DB row.
           const issued = await this.issueBoundMembershipInvite(token, resolved.strandId, signal);
           if (!issued.ok) {
-            return { approved: false, reason: issued.reason };
+            return issued.rejection;
           }
           await authorized.record();
           return this.approve({
@@ -501,7 +522,7 @@ export class StrandFormationManager {
         }
         case 'missing': {
           log('Host strand %s not yet available on this responder; rejecting token %s', resolved.strandId, token);
-          return { approved: false, reason: 'Host strand not yet available on this responder' };
+          return { approved: false, code: 'host-strand-unavailable', reason: 'Host strand not yet available on this responder' };
         }
         case 'unbound':
           return await this.provisionUnbound(contact, disclosureText, signal);
@@ -514,29 +535,27 @@ export class StrandFormationManager {
       }
       if (err instanceof FormationApprovalError) {
         log('approval failed (%s) for token %s: %o', err.failure, token, err);
-        return { approved: false, reason: APPROVAL_REJECTION_REASONS[err.failure] };
+        return APPROVAL_REJECTIONS[err.failure];
       }
       if (err instanceof InvitationExhaustedError) {
-        // Shares `INVALID_TOKEN_REASON` with the up-front `validateToken` rejection so the loser
-        // of the race that exposed the spent invite sees exactly what a non-racing latecomer
-        // sees. No wire-visible distinction between "invalid" and "exhausted" — the
-        // operator signal lives in this log line instead.
-        // NOTE: if a joining client ever has to tell "never valid" from "used up" WITHOUT node
-        // logs, that is a new protocol reason string, not a local change here.
+        // Shares `INVALID_TOKEN_REASON` and `'token-spent'` with the up-front `validateToken`
+        // rejection so the loser of the race that exposed the spent invite sees exactly what a
+        // non-racing latecomer sees. How many uses were recorded against the total is for the
+        // operator, in this log line, not for the joiner.
         log(
           'invitation exhausted for token %s: %d of %d use(s) already recorded',
           err.token,
           err.usesRecorded,
           err.totalUses
         );
-        return { approved: false, reason: INVALID_TOKEN_REASON };
+        return { approved: false, code: 'token-spent', reason: INVALID_TOKEN_REASON };
       }
       // An approval is never discarded to a lost key race: each redemption writes under its
       // own `UsageStampId`, so no other writer can take its row key. Reaching this catch-all
       // means the failure was never retryable at the database layer to begin with (or the
       // transient-cluster retry inside `ControlDatabase.lockedWithRetry` ran out).
       log('provisionAsResponder failed for token %s: %o', token, err);
-      return { approved: false, reason: 'Formation conflict, retry' };
+      return { approved: false, code: 'conflict', reason: 'Formation conflict, retry' };
     }
   }
 
@@ -579,7 +598,7 @@ export class StrandFormationManager {
     token: string,
     strandId: string,
     signal?: AbortSignal
-  ): Promise<{ ok: true; invite?: StrandMembershipInvite } | { ok: false; reason: string }> {
+  ): Promise<{ ok: true; invite?: StrandMembershipInvite } | { ok: false; rejection: FormationRejection }> {
     if (!this.issueMembershipInvite) {
       return { ok: true };
     }
@@ -589,10 +608,16 @@ export class StrandFormationManager {
     } catch (err) {
       if (err instanceof PreSplitStrandIdentityError) {
         log('host strand %s is pre-split (token %s); rejecting — it must be recreated: %o', strandId, token, err);
-        return { ok: false, reason: HOST_STRAND_MUST_BE_RECREATED_REASON };
+        return {
+          ok: false,
+          rejection: { approved: false, code: 'host-strand-must-be-recreated', reason: HOST_STRAND_MUST_BE_RECREATED_REASON }
+        };
       }
       log('membership-invite issue for strand %s failed (token %s); rejecting retryably: %o', strandId, token, err);
-      return { ok: false, reason: MEMBERSHIP_INVITE_UNAVAILABLE_REASON };
+      return {
+        ok: false,
+        rejection: { approved: false, code: 'host-strand-unavailable', reason: MEMBERSHIP_INVITE_UNAVAILABLE_REASON }
+      };
     }
   }