@serfab/cadre-core 0.10.0 → 0.12.0

package/src/strand-formation-manager.ts

@@ -299,14 +299,14 @@ export class StrandFormationManager {
    * Defense-in-depth: known provisioning/redeem failures are caught and mapped to a logged
    * protocol rejection rather than a thrown insert + a silently-closed stream. The mapping is
    * per-failure, NOT blanket retry-suggesting: an exhausted invitation
-   * ({@link InvitationExhaustedError}, raised by `ControlDatabase` whenever a redemption's use
-   * number is past the invite's seat budget — including a first attempt racing another
-   * redemption of the same token on this node, not only a retry) is reported as `'Invalid
-   * token'`, because retrying it can never succeed. The
-   * `(Token, UseNumber)` PK collision that concurrent redemptions of one invite used to
-   * surface here is now retried a layer down and no longer reaches this method. The
-   * LOG-before-reject keeps this a deliberate internal-error→protocol-rejection conversion
-   * (AGENTS.md: don't eat exceptions silently), not control-flow-by-exception.
+   * ({@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
+   * 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),
+   * not control-flow-by-exception.
    */
   private async provisionAsResponder(
     contact: FormationContactMessage,
@@ -366,26 +366,23 @@ export class StrandFormationManager {
       }
       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 — same-node, first attempt, or a retry that
-        // ran out — sees exactly what a non-racing latecomer sees. No wire-visible distinction between "invalid" and "exhausted" — the
+        // 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.
         log(
-          'invitation exhausted for token %s: use #%d past limit of %d',
+          'invitation exhausted for token %s: %d of %d use(s) already recorded',
           err.token,
-          err.useNumber,
+          err.usesRecorded,
           err.totalUses
         );
         return { approved: false, reason: INVALID_TOKEN_REASON };
       }
-      // An approval obtained before landing here is RETRIED, not discarded: the database
-      // layer re-presents the same approver sign-off under a fresh use number when it loses
-      // one to a writer its local write queue does not serialize — another node of the cadre,
-      // another `Database` handle over the same store (see
-      // `ControlDatabase.withUseNumberRetry`). Reaching this catch-all means either that retry
-      // ran out (surfaced above as `InvitationExhaustedError`) or the failure was never
-      // retryable to begin with.
+      // 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' };
     }
@@ -397,20 +394,21 @@ export class StrandFormationManager {
    * 1. `recorder.provisionAndRecord` present (a real DB recorder) → atomic create-strand +
    *    record-consent, so the unbound redemption is single-use just like the bound path.
    *    Returns the new strand (+ key, null for an open responder-provisioned strand).
-   * 2. else `strandProvisioner` present → the legacy/mock contract: provision a bare strand,
-   *    NO inline usage write (those callers record usage explicitly via
+   * 2. else `strandProvisioner` present → the mock/transport-test contract: provision a bare
+   *    strand, NO inline usage write (those callers record usage explicitly via
    *    `recordFormationComplete`, or assert transport invariants only). Threads the invite's
    *    REAL `sAppId`.
    * 3. else → a structural placeholder (no recorder + no provisioner ⇒ no single-use semantics
    *    exist to enforce).
    *
-   * Plan tradeoff — option (a) "record usage on the fallback" over (b) "remove the fallback":
-   * (a) closes the single-use hole with a targeted atomic create+record and leaves the
-   * `StrandProvisioner` mock-transport tests untouched; (b) would delete the provisioner
-   * surface and churn ~6 unit + ~6 integration sites for ZERO production benefit (production
-   * — `cadre-web.ts` / `cadre-phone.ts` — always publishes strand-BOUND invites and treats
-   * the responder-provisions placeholder as failure). The broader "should this fallback exist
-   * at all?" question lives in backlog `formation-initiatorcreates-cover-or-remove`.
+   * NOTE: accepted tradeoff — the plan chose (a) "record usage on the fallback" over (b)
+   * "remove the fallback", so arm 2 (`strandProvisioner`, no recorder) is kept. (a) closes the
+   * single-use hole with a targeted atomic create+record and leaves the `StrandProvisioner`
+   * mock-transport tests untouched; (b) would delete the provisioner surface and churn ~6 unit
+   * + ~6 integration sites for ZERO production benefit (production — `cadre-web.ts` /
+   * `cadre-phone.ts` — always publishes strand-BOUND invites and treats the
+   * responder-provisions placeholder as failure). Revisit if production starts publishing
+   * unbound invites, or the mock-transport tests go away.
    */
   private async provisionUnbound(
     contact: FormationContactMessage,