@serfab/cadre-core 1.7.0 → 1.9.0

package/dist/control-formation-recorder.d.ts

@@ -1,6 +1,6 @@
 import { type ControlDatabase } from './control-database.js';
 import { type FormationApprover } from './formation-approval.js';
-import type { FormationUsageRecorder, ResolvedHostStrand } from './strand-solicitation.js';
+import type { AuthorizedFormationUsage, FormationUsageParams, FormationUsageRecorder, ResolvedHostStrand } from './strand-solicitation.js';
 import type { OpenInvitation } from './types.js';
 /**
  * {@link FormationUsageRecorder} backed by the real `CadreControl` tables.
@@ -11,7 +11,8 @@ import type { OpenInvitation } from './types.js';
  *
  * - **Bound (provision-then-record):** the host strand already exists (owner-signed
  *   up front and named by the invite's `StrandId`), so {@link resolveStrand} reports it
- *   and {@link recordUsage} writes the consent row against that pre-existing strand
+ *   and {@link authorizeUsage} then its `record()` (or {@link recordUsage}, both at once)
+ *   writes the consent row against that pre-existing strand
  *   (record-only) rather than inserting a new `Strand`.
  * - **Unbound (responder-provisions):** the invite carries no `StrandId`, so
  *   {@link provisionAndRecord} mints a fresh strand and records consent against it
@@ -29,7 +30,10 @@ import type { OpenInvitation } from './types.js';
  * approval ({@link obtainApproval}) — the recorder is the one place where the nonce that is
  * SIGNED and the nonce that is INSERTED are trivially the same value, since it also performs
  * the write. That makes this class do network I/O; failures surface as
- * {@link FormationApprovalError}s the manager maps to protocol rejection reasons.
+ * {@link FormationApprovalError}s the manager maps to protocol rejection reasons. The bound
+ * path is split in two ({@link authorizeUsage}, then the returned `record()`) so the manager
+ * can issue the joiner's membership pass between the approval and the write; the handle
+ * carries the approved fields across, which keeps the signed and inserted nonce the same.
  */
 export declare class ControlFormationUsageRecorder implements FormationUsageRecorder {
     private readonly controlDatabase;
@@ -101,18 +105,37 @@ export declare class ControlFormationUsageRecorder implements FormationUsageReco
      * spent on AND provably the joiner that agreed. Use
      * {@link ControlDatabase.redeemInvitation} for the consent-creates-strand path instead.
      *
-     * Reads the invite first (one extra read per redemption) to learn its `ValidationUrl`, and
-     * obtains the approval through {@link obtainApproval} when one is demanded.
+     * Authorizes ({@link authorizeUsage}) and writes in one step, for callers with nothing to do
+     * in between.
      */
-    recordUsage(params: {
-        token: string;
-        peerKey: string;
-        peerSignature: string;
-        usageStampId: string;
-        strandId: string;
-        disclosure: string;
-        signal?: AbortSignal;
-    }): Promise<void>;
+    recordUsage(params: FormationUsageParams): Promise<void>;
+    /**
+     * Everything {@link recordUsage} does before its write, so the manager can issue the
+     * joiner's membership pass into the host strand only once the redemption is cleared, and
+     * spend the token only after that.
+     *
+     * Reads the invite first (one extra read per redemption) to learn its `ValidationUrl` and
+     * seat budget, obtains the approval through {@link obtainApproval} when one is demanded,
+     * re-checks the abort (the approval call may have been long), and pre-checks the seat
+     * budget ({@link assertSeatFree}). The returned `record()` closes over the captured fields
+     * and approval, so the nonce the approver signed is the nonce inserted without the caller
+     * ever passing it back.
+     */
+    authorizeUsage(params: FormationUsageParams): Promise<AuthorizedFormationUsage>;
+    /**
+     * Refuse a redemption whose invite has no seat left, BEFORE anything is written — the
+     * authoritative check is the one `recordFormationUsage` repeats inside its write lock.
+     * Catches a same-node rival that took the last seat while this redemption waited on the
+     * approval hook, which `runSession`'s up-front `isTokenUsed` check could not see.
+     *
+     * NOTE: two redemptions that both pass this check within the time one of them takes to
+     * issue its membership pass still both issue one, and the loser's pass is orphaned
+     * (expiry-bounded, never handed out). Holding the control write lock across issuance would
+     * close it, but `lockedWithRetry` re-runs locked bodies on transient failures (a re-run
+     * would double-issue) and every control write would stall behind a strand-database write.
+     * If orphaned passes from same-node races ever matter, reserve the seat before issuance.
+     */
+    private assertSeatFree;
     /**
      * Classify the host strand this invite binds to (see {@link ResolvedHostStrand}):
      *

package/dist/control-formation-recorder.js

@@ -1,5 +1,5 @@
 import debug from 'debug';
-import { FormationAbortedError } from './control-database.js';
+import { FormationAbortedError, InvitationExhaustedError } from './control-database.js';
 import { mintStrandId } from './strand-id.js';
 import { createHttpFormationApprover, verifyFormationApproval, FormationApprovalError } from './formation-approval.js';
 const log = debug('sereus:cadre:formation-recorder');
@@ -14,7 +14,8 @@ const NEVER_EXPIRES = new Date(8640000000000000);
  *
  * - **Bound (provision-then-record):** the host strand already exists (owner-signed
  *   up front and named by the invite's `StrandId`), so {@link resolveStrand} reports it
- *   and {@link recordUsage} writes the consent row against that pre-existing strand
+ *   and {@link authorizeUsage} then its `record()` (or {@link recordUsage}, both at once)
+ *   writes the consent row against that pre-existing strand
  *   (record-only) rather than inserting a new `Strand`.
  * - **Unbound (responder-provisions):** the invite carries no `StrandId`, so
  *   {@link provisionAndRecord} mints a fresh strand and records consent against it
@@ -32,7 +33,10 @@ const NEVER_EXPIRES = new Date(8640000000000000);
  * approval ({@link obtainApproval}) — the recorder is the one place where the nonce that is
  * SIGNED and the nonce that is INSERTED are trivially the same value, since it also performs
  * the write. That makes this class do network I/O; failures surface as
- * {@link FormationApprovalError}s the manager maps to protocol rejection reasons.
+ * {@link FormationApprovalError}s the manager maps to protocol rejection reasons. The bound
+ * path is split in two ({@link authorizeUsage}, then the returned `record()`) so the manager
+ * can issue the joiner's membership pass between the approval and the write; the handle
+ * carries the approved fields across, which keeps the signed and inserted nonce the same.
  */
 export class ControlFormationUsageRecorder {
     /**
@@ -154,10 +158,25 @@ export class ControlFormationUsageRecorder {
      * spent on AND provably the joiner that agreed. Use
      * {@link ControlDatabase.redeemInvitation} for the consent-creates-strand path instead.
      *
-     * Reads the invite first (one extra read per redemption) to learn its `ValidationUrl`, and
-     * obtains the approval through {@link obtainApproval} when one is demanded.
+     * Authorizes ({@link authorizeUsage}) and writes in one step, for callers with nothing to do
+     * in between.
      */
     async recordUsage(params) {
+        await (await this.authorizeUsage(params)).record();
+    }
+    /**
+     * Everything {@link recordUsage} does before its write, so the manager can issue the
+     * joiner's membership pass into the host strand only once the redemption is cleared, and
+     * spend the token only after that.
+     *
+     * Reads the invite first (one extra read per redemption) to learn its `ValidationUrl` and
+     * seat budget, obtains the approval through {@link obtainApproval} when one is demanded,
+     * re-checks the abort (the approval call may have been long), and pre-checks the seat
+     * budget ({@link assertSeatFree}). The returned `record()` closes over the captured fields
+     * and approval, so the nonce the approver signed is the nonce inserted without the caller
+     * ever passing it back.
+     */
+    async authorizeUsage(params) {
         const { token, peerKey, peerSignature, usageStampId, strandId, disclosure, signal } = params;
         if (signal?.aborted) {
             throw new FormationAbortedError(token, 'usage recording');
@@ -172,11 +191,42 @@ export class ControlFormationUsageRecorder {
             token, usageStampId, strandId, peerKey, disclosure,
             validationUrl: invite?.validationUrl ?? null,
         }, signal);
-        await this.controlDatabase.recordFormationUsage({
-            token, strandId, peerKey, peerSignature, usageStampId, disclosure, signal,
-            totalUses: invite?.totalUses ?? null, ...approval,
-        });
-        log('Recorded formation usage: token=%s strand=%s', token, strandId);
+        if (signal?.aborted) {
+            throw new FormationAbortedError(token, 'usage recording');
+        }
+        const totalUses = invite?.totalUses ?? null;
+        await this.assertSeatFree(token, totalUses);
+        return {
+            record: async () => {
+                await this.controlDatabase.recordFormationUsage({
+                    token, strandId, peerKey, peerSignature, usageStampId, disclosure, signal,
+                    totalUses, ...approval,
+                });
+                log('Recorded formation usage: token=%s strand=%s', token, strandId);
+            }
+        };
+    }
+    /**
+     * Refuse a redemption whose invite has no seat left, BEFORE anything is written — the
+     * authoritative check is the one `recordFormationUsage` repeats inside its write lock.
+     * Catches a same-node rival that took the last seat while this redemption waited on the
+     * approval hook, which `runSession`'s up-front `isTokenUsed` check could not see.
+     *
+     * NOTE: two redemptions that both pass this check within the time one of them takes to
+     * issue its membership pass still both issue one, and the loser's pass is orphaned
+     * (expiry-bounded, never handed out). Holding the control write lock across issuance would
+     * close it, but `lockedWithRetry` re-runs locked bodies on transient failures (a re-run
+     * would double-issue) and every control write would stall behind a strand-database write.
+     * If orphaned passes from same-node races ever matter, reserve the seat before issuance.
+     */
+    async assertSeatFree(token, totalUses) {
+        if (totalUses === null) {
+            return;
+        }
+        const used = await this.controlDatabase.countFormationUsage(token);
+        if (used >= totalUses) {
+            throw new InvitationExhaustedError(token, used, totalUses);
+        }
     }
     /**
      * Classify the host strand this invite binds to (see {@link ResolvedHostStrand}):

package/dist/control-formation-recorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-formation-recorder.js","sourceRoot":"","sources":["../src/control-formation-recorder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"control-formation-recorder.js","sourceRoot":"","sources":["../src/control-formation-recorder.ts"],"names":[],"mappings":"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"}

package/dist/control-read-retry.d.ts

@@ -10,7 +10,7 @@ import type { ControlRetryOptions } from './control-retry.js';
  * was absorbed). This module gives reads the same bounded re-presentation with a SHORTER
  * deadline and a NARROWER failure set, because the tightest caller deadline over a control
  * read is the inbound admission gate's 2 s fail-open timeout
- * (`ADMISSION_DECISION_TIMEOUT_MS`, `membership-connection-gater.ts`) — a read budget that
+ * (`ADMISSION_DECISION_TIMEOUT_MS`, `link-budget.ts`) — a read budget that
  * does not fit inside it with headroom spends its retries after the gate has already
  * admitted.
  *
@@ -60,17 +60,18 @@ export declare const CONTROL_READ_RETRY_DELAYS_MS: readonly number[];
  * 2 s only because each stays well under it. Do not raise these numbers without
  * re-checking against `ADMISSION_DECISION_TIMEOUT_MS`.
  *
- * NOTE: the obligation runs the other way too, and the number that dominates this budget is
- * declared in another package. One attempt whose cohort consult finds a silent peer costs
- * `clusterPolicy.cohortQueryTimeoutMs`, which sereus declares at 5000 ms
- * (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`) for relayed phone
- * links — more than three times this budget, so such an attempt is never retried and the
- * admission gate above it has already fail-opened. That is a widened cost of a deliberate
- * choice, not a hole (the stream gates still decide), and the whole ladder of cadre-core
- * deadlines against Optimystic's is audited by
- * `backlog/debt-cadre-deadlines-sized-against-old-optimystic-bounds`. What this budget still
- * buys is the failure it was built for: the ~25 ms transactor read-phase aggregate off a
- * stream still forming, which retries twice well inside 1500 ms.
+ * It cuts the loop off by design, so it does not grow with the link or with the number that
+ * dominates a slow attempt: an attempt whose cohort consult finds a silent peer costs
+ * `clusterPolicy.cohortQueryTimeoutMs`, two link round trips at the declared link
+ * (`cohortReadDeadlineMs` in `link-budget.ts`, 7 000 ms at the default declaration; the plugin's
+ * `COHORT_READ_DEADLINE_MS` is the same number). That is more than four times this budget, so
+ * such an attempt is never retried and the caller gets its error unchanged. That is deliberate:
+ * the caller this budget is sized for, the admission gate, has
+ * already taken its fail-open answer by then, and a retry would only spend time after it. What
+ * the budget still buys is the fast failures it was built for: the ~25 ms transactor read-phase
+ * aggregate off a stream still forming, and a `cohort-unreachable` read during bring-up, which
+ * fails fast because there is no connection to ask. Both retry twice well inside 1500 ms. See
+ * `docs/cadre-consistency.md` → "Deadlines Over Optimystic's Reads and Commits".
  */
 export declare const CONTROL_READ_RETRY_BUDGET_MS = 1500;
 /**

package/dist/control-read-retry.js

@@ -12,7 +12,7 @@ import { isUncommittedTransactorAggregate } from './control-write-retry.js';
  * was absorbed). This module gives reads the same bounded re-presentation with a SHORTER
  * deadline and a NARROWER failure set, because the tightest caller deadline over a control
  * read is the inbound admission gate's 2 s fail-open timeout
- * (`ADMISSION_DECISION_TIMEOUT_MS`, `membership-connection-gater.ts`) — a read budget that
+ * (`ADMISSION_DECISION_TIMEOUT_MS`, `link-budget.ts`) — a read budget that
  * does not fit inside it with headroom spends its retries after the gate has already
  * admitted.
  *
@@ -62,18 +62,20 @@ export const CONTROL_READ_RETRY_DELAYS_MS = [100, 400];
  * 2 s only because each stays well under it. Do not raise these numbers without
  * re-checking against `ADMISSION_DECISION_TIMEOUT_MS`.
  *
- * NOTE: the obligation runs the other way too, and the number that dominates this budget is
- * declared in another package. One attempt whose cohort consult finds a silent peer costs
- * `clusterPolicy.cohortQueryTimeoutMs`, which sereus declares at 5000 ms
- * (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`) for relayed phone
- * links — more than three times this budget, so such an attempt is never retried and the
- * admission gate above it has already fail-opened. That is a widened cost of a deliberate
- * choice, not a hole (the stream gates still decide), and the whole ladder of cadre-core
- * deadlines against Optimystic's is audited by
- * `backlog/debt-cadre-deadlines-sized-against-old-optimystic-bounds`. What this budget still
- * buys is the failure it was built for: the ~25 ms transactor read-phase aggregate off a
- * stream still forming, which retries twice well inside 1500 ms.
+ * It cuts the loop off by design, so it does not grow with the link or with the number that
+ * dominates a slow attempt: an attempt whose cohort consult finds a silent peer costs
+ * `clusterPolicy.cohortQueryTimeoutMs`, two link round trips at the declared link
+ * (`cohortReadDeadlineMs` in `link-budget.ts`, 7 000 ms at the default declaration; the plugin's
+ * `COHORT_READ_DEADLINE_MS` is the same number). That is more than four times this budget, so
+ * such an attempt is never retried and the caller gets its error unchanged. That is deliberate:
+ * the caller this budget is sized for, the admission gate, has
+ * already taken its fail-open answer by then, and a retry would only spend time after it. What
+ * the budget still buys is the fast failures it was built for: the ~25 ms transactor read-phase
+ * aggregate off a stream still forming, and a `cohort-unreachable` read during bring-up, which
+ * fails fast because there is no connection to ask. Both retry twice well inside 1500 ms. See
+ * `docs/cadre-consistency.md` → "Deadlines Over Optimystic's Reads and Commits".
  */
+// eslint-disable-next-line no-restricted-syntax -- cuts off by design: a slow attempt is not retried, because the admission gate this budget is sized for has already failed open by then; see docs/cadre-consistency.md → "Deadlines Over Optimystic's Reads and Commits"
 export const CONTROL_READ_RETRY_BUDGET_MS = 1500;
 /**
  * The block-unavailability reasons a repeat read can actually improve on, matched against

package/dist/control-read-retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-read-retry.js","sourceRoot":"","sources":["../src/control-read-retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEtF,OAAO,EAAE,gCAAgC,EAAE,MAAM,0BAA0B,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAK,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,2BAA2B,GAChC,uEAAuE,CAAC;AAEzE,kFAAkF;AAClF,SAAS,2BAA2B,CAAC,OAAe;IACnD,OAAO,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClD,CAAC;AAWD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAAc;IAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAC1C,gCAAgC,CAAC,OAAO,CAAC,IAAI,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACrD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpC,IAAI,YAAY,qBAAqB,IAAI,IAAI,CAAC,MAAM,KAAK,oBAAoB,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAC/B,OAAyB,EACzB,UAAmC,EAAE;IAErC,OAAO,qBAAqB,CAAC,OAAO,EAAE;QACrC,QAAQ,EAAE,qBAAqB;QAC/B,QAAQ,EAAE,4BAA4B;QACtC,QAAQ,EAAE,4BAA4B;QACtC,WAAW,EAAE,6BAA6B;QAC1C,SAAS,EAAE,cAAc;KACzB,EAAE,OAAO,CAAC,CAAC;AACb,CAAC"}
+{"version":3,"file":"control-read-retry.js","sourceRoot":"","sources":["../src/control-read-retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEtF,OAAO,EAAE,gCAAgC,EAAE,MAAM,0BAA0B,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,2QAA2Q;AAC3Q,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAK,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,2BAA2B,GAChC,uEAAuE,CAAC;AAEzE,kFAAkF;AAClF,SAAS,2BAA2B,CAAC,OAAe;IACnD,OAAO,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClD,CAAC;AAWD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAAc;IAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAC1C,gCAAgC,CAAC,OAAO,CAAC,IAAI,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACrD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpC,IAAI,YAAY,qBAAqB,IAAI,IAAI,CAAC,MAAM,KAAK,oBAAoB,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAC/B,OAAyB,EACzB,UAAmC,EAAE;IAErC,OAAO,qBAAqB,CAAC,OAAO,EAAE;QACrC,QAAQ,EAAE,qBAAqB;QAC/B,QAAQ,EAAE,4BAA4B;QACtC,QAAQ,EAAE,4BAA4B;QACtC,WAAW,EAAE,6BAA6B;QAC1C,SAAS,EAAE,cAAc;KACzB,EAAE,OAAO,CAAC,CAAC;AACb,CAAC"}