@serfab/cadre-core 0.10.0 → 0.11.0

package/dist/control-database.d.ts

@@ -49,43 +49,27 @@ export declare class FormationAbortedError extends Error {
     });
 }
 /**
- * A redemption could not be given a `UseNumber` within the invite's seat budget: the use
- * number the writer would have to take is past `FormationInvite.TotalUses`, so the
- * invitation is spent.
+ * The invitation's seat budget is already spent: the count of recorded `FormationUsage` rows
+ * for the token has reached `FormationInvite.TotalUses`, so this redemption cannot be given a
+ * seat.
  *
- * Raised inside {@link ControlDatabase.redeemInvitation} / {@link ControlDatabase.recordFormationUsage}
- * on EVERY attempt, including the first: two redemptions of one token racing on the SAME node
- * serialize behind the local write queue, so the loser's first attempt already takes a use
- * number past the seat budget — `StrandFormationManager.validateToken`'s `isTokenUsed` check
- * cannot catch this, since it ran before either redemption wrote anything. Without this the
- * write would fail as a generic `CHECK constraint failed: Authorized`, which the manager
- * reports as a retryable `Formation conflict, retry` — telling the joiner to retry something
- * that can never succeed.
+ * Raised off the committed-count check ({@link ControlDatabase.assertSeatRemains}) ahead of
+ * the write, inside {@link ControlDatabase.redeemInvitation} /
+ * {@link ControlDatabase.recordFormationUsage} — and off nothing else. It exists because
+ * without it the refusal surfaces as a generic `CHECK constraint failed: Authorized` from the
+ * schema's own count-based cap clause, which the manager reports as a retryable
+ * `Formation conflict, retry` — telling the joiner to retry something that can never succeed.
+ * Two redemptions of one token racing on the SAME node serialize behind the local write
+ * queue, so the loser reads the winner's committed row and is refused here by name —
+ * `StrandFormationManager.validateToken`'s `isTokenUsed` check cannot catch that, since it
+ * ran before either redemption wrote anything.
  */
 export declare class InvitationExhaustedError extends Error {
     readonly token: string;
-    readonly useNumber: number;
+    readonly usesRecorded: number;
     readonly totalUses: number;
-    constructor(token: string, useNumber: number, totalUses: number);
+    constructor(token: string, usesRecorded: number, totalUses: number);
 }
-/**
- * Did this write fail purely because another writer took the `UseNumber` it picked — i.e. is
- * re-presenting the SAME approval under the next free use number the right response?
- *
- * Classifies by MESSAGE, walking the `cause` chain with Quereus' own {@link unwrapError}:
- * neither surface can be recognised by type. The deferred `Monotonic` failure is thrown as a
- * bare `QuereusError`, not a `ConstraintError` (see
- * `quereus/src/runtime/deferred-constraint-queue.ts`), so an `instanceof ConstraintError` gate
- * would silently drop the branch this retry exists for. Messages also carry an
- * ` (at line N, column M)` suffix and arrive wrapped when the write ran inside a transaction,
- * so the match is a substring test rather than an equality one.
- *
- * NOTE: this is the one piece of the retry that depends on engine error TEXT. Its own test
- * (`control-formation-use-number-retry.spec.ts`) produces all three messages from the real
- * engine rather than from string literals, so a reworded storage-layer error fails that spec
- * instead of silently disabling the retry.
- */
-export declare function isLostUseNumberRace(error: unknown): boolean;
 /**
  * What a recorded `FormationUsage` row came out as.
  *
@@ -94,9 +78,7 @@ export declare function isLostUseNumberRace(error: unknown): boolean;
  * `FormationUsage.Authorized` rejects the row (see {@link formationVouchMessage}).
  */
 export interface FormationUsageResult {
-    /** The `UseNumber` assigned to this redemption (1-based per token). */
-    useNumber: number;
-    /** The single-use nonce written to `UsageStampId` — the caller's, or a freshly minted one. */
+    /** The single-use nonce written to `UsageStampId` (the row's primary key) — the caller's, or a freshly minted one. */
     usageStampId: string;
 }
 /**
@@ -314,6 +296,14 @@ export declare class ControlDatabase {
      * membership-gate refresh path; control tables are a handful of rows today, so this
      * is cheap — if they ever grow, fold the exclusion into one statement or cache the
      * retired-stamp set.
+     *
+     * NOTE: this filter is HAND-MIRRORED by the gate suites' fake control databases
+     * (`test/membership-gate-helpers.ts` and `test/cadre-node-authorized-surface.spec.ts`),
+     * which feed the node rows directly. Nothing enforces that the copies stay true, so a
+     * change to the filter's SHAPE here (what it keys on, which table it consults) must be
+     * carried into both, or those suites keep passing against a contract the database no
+     * longer honours. Fine while the filter is one `Set.has` on `StampId`; if it grows a
+     * second dimension, give the fakes a shared fixture or a contract test instead.
      */
     queryCadrePeers(): Promise<CadrePeerRow[]>;
     /**
@@ -937,10 +927,8 @@ export declare class ControlDatabase {
      *
      * The retry wraps the LOCK, it does not live inside it: each attempt takes and
      * releases the lock, and the backoff sleeps with NO lock held, so a write parked in
-     * backoff never stalls the other local writers queued behind it. Same reason
-     * {@link withUseNumberRetry} re-takes the lock per attempt — see the note on
-     * `USE_NUMBER_ATTEMPTS`. Safe because every locked body is atomic and re-runnable
-     * (the contract on {@link withWriteLock}).
+     * backoff never stalls the other local writers queued behind it. Safe because every
+     * locked body is atomic and re-runnable (the contract on {@link withWriteLock}).
      *
      * Also carries {@link loadSchema}'s distributed DDL, the one caller that runs BEFORE
      * `initialized` is set — so it reaches this method directly rather than through
@@ -949,6 +937,11 @@ export declare class ControlDatabase {
      * rather than carving out a lockless path. It is also the ONLY caller that passes a
      * `policy` — everything else takes the default, whose classifier and attempt count are
      * unchanged by that call site existing.
+     *
+     * `label` names the operation in this loop's debug lines and nothing else
+     * ({@link ControlWriteRetryOptions.label}). Every call site in this class supplies one:
+     * several writes retry CONCURRENTLY in a real party, so an unlabelled line cannot be
+     * attributed to a write — keep new call sites labelled.
      */
     private lockedWithRetry;
     /**
@@ -960,8 +953,11 @@ export declare class ControlDatabase {
      * Public so `SeedBootstrapService`'s direct `CadrePeer`/`DeviceToken` SQL writes go
      * through the same seam. Must NOT be called from inside an already-locked body (the
      * lock is not re-entrant); such a caller uses a bare `getDatabase().exec` instead.
+     *
+     * `label` names the write in the retry loop's debug lines (see {@link lockedWithRetry});
+     * optional only because it is log-only, but every caller in this repo passes one.
      */
-    execWrite(sql: string, params?: SqlParameters): Promise<void>;
+    execWrite(sql: string, params?: SqlParameters, label?: string): Promise<void>;
     /**
      * Throw unless the database sits at a committed boundary — `getAutocommit()` is false
      * exactly while a transaction is open.
@@ -1062,13 +1058,12 @@ export declare class ControlDatabase {
      * takes an owner re-seat ({@link insertStrand}) plus a bound invite, never another
      * redemption.
      *
-     * `UseNumber` is computed as `max(UseNumber)+1` for the token (the `Monotonic`
-     * constraint), inside the write lock and re-read per attempt by
-     * {@link withUseNumberRetry} — so concurrent redemptions of one token no longer need
-     * the caller to serialise them, and a use number lost to another writer is retried here
-     * with the caller's parameters passed through UNCHANGED. That is what makes the retry
-     * safe: the approval is bound to the nonce, not to the use number, so re-presenting it
-     * cannot drift, and no second trip through the approval hook is possible from in here.
+     * The usage row is keyed by the joiner's own nonce (`UsageStampId` is the primary key), so
+     * concurrent redemptions of one token never contend for a shared row key — there is no
+     * lost race to retry and no second trip through the approval hook. The invite's seat
+     * budget is checked by COUNT ({@link assertSeatRemains}) inside the write lock, ahead of
+     * the write, so a spent invite is refused by name (`InvitationExhaustedError`) instead of
+     * as the schema cap clause's generic `Authorized` CHECK failure.
      */
     redeemInvitation(params: {
         token: string;
@@ -1091,9 +1086,9 @@ export declare class ControlDatabase {
         signal?: AbortSignal;
         /**
          * The invite's seat budget, when the caller already has it in hand (e.g. it already read
-         * the `FormationInvite` row to get here). Passed through to {@link withUseNumberRetry} so
-         * every attempt can check the seat budget without an extra read. `undefined` falls back to
-         * a fresh {@link queryFormationInvite} read; `null` means "no invite row" / unlimited.
+         * the `FormationInvite` row to get here). Passed through to {@link assertSeatRemains} so
+         * the seat check needs no extra read. `undefined` falls back to a fresh
+         * {@link queryFormationInvite} read; `null` means "no invite row" / unlimited.
          */
         totalUses?: number | null;
     }): Promise<FormationUsageResult>;
@@ -1102,8 +1097,8 @@ export declare class ControlDatabase {
      * insert). This is the redemption path when the strand was provisioned
      * separately (e.g. owner-signed) and the consent record is added after the
      * fact: the single insert auto-commits, and the deferred `StrandExists` CHECK
-     * is satisfied by the pre-existing committed strand row. Returns the assigned
-     * `UseNumber`.
+     * is satisfied by the pre-existing committed strand row. Echoes back the
+     * redemption's `usageStampId` (the row's primary key).
      *
      * Use {@link redeemInvitation} instead when the strand must be created by
      * consent atomically with the usage.
@@ -1117,12 +1112,12 @@ export declare class ControlDatabase {
      * by {@link ControlFormationUsageRecorder.resolveStrand}, so an absent row at this
      * point is a genuine race and deserves a named error, not a silent rollback.
      *
-     * `UseNumber` is read inside the write lock and re-read per attempt by
-     * {@link withUseNumberRetry}: this is the path production actually races on (a bound
-     * invite published by `cadre-web` / `cadre-phone` is always record-only), and a use number
-     * lost to another writer is retried here with the caller's parameters — nonce, approver
-     * sign-off, strand, peer key, disclosure — passed through UNCHANGED, so a granted approval
-     * is never thrown away for a second trip through the approval hook.
+     * The row is keyed by the joiner's own nonce (`UsageStampId` is the primary key), so this
+     * path — the one production actually races on (a bound invite published by `cadre-web` /
+     * `cadre-phone` is always record-only) — never contends with another redemption for a
+     * shared row key: there is no lost race to retry and no second trip through the approval
+     * hook. The invite's seat budget is checked by COUNT ({@link assertSeatRemains}) inside
+     * the write lock, ahead of the write.
      */
     recordFormationUsage(params: {
         token: string;
@@ -1138,66 +1133,28 @@ export declare class ControlDatabase {
         validationKey?: string;
         validationSignature?: string;
         /**
-         * Aborted when the caller has given up. Checked once PER ATTEMPT, inside the write lock,
-         * at the top of the attempt — before it reads a use number and before its insert is
-         * issued — throwing {@link FormationAbortedError} with the invite unspent. Never checked
-         * once an insert has been issued.
+         * Aborted when the caller has given up. Checked inside the write lock, before the insert
+         * is issued, throwing {@link FormationAbortedError} with the invite unspent. Never
+         * checked once the insert has been issued.
          */
         signal?: AbortSignal;
         /**
          * The invite's seat budget, when the caller already has it in hand (e.g. it already read
-         * the `FormationInvite` row to get here). Passed through to {@link withUseNumberRetry} so
-         * every attempt can check the seat budget without an extra read. `undefined` falls back to
-         * a fresh {@link queryFormationInvite} read; `null` means "no invite row" / unlimited.
+         * the `FormationInvite` row to get here). Passed through to {@link assertSeatRemains} so
+         * the seat check needs no extra read. `undefined` falls back to a fresh
+         * {@link queryFormationInvite} read; `null` means "no invite row" / unlimited.
          */
         totalUses?: number | null;
     }): Promise<FormationUsageResult>;
     /**
-     * Assign a `UseNumber` and run `write` under it, re-picking and retrying when another
-     * writer took that number first.
-     *
-     * Each attempt takes {@link withWriteLock} and, inside it, reads {@link nextUseNumber}
-     * afresh. Reading under the lock is the whole fix for the common case: two redemptions of
-     * one token on the SAME node are serialized by the local write queue, so each computes a
-     * number the other has already committed and neither collides. The retry covers the writers
-     * this lock does not reach — another node of the cadre, another `Database` handle over the
-     * same store — which can still take the number between our read and our commit.
-     *
-     * `write` receives ONLY the use number; every other parameter of the redemption (the nonce,
-     * the approver's signature, the strand, the joining peer key, the disclosure) is closed over
-     * by the caller and passed through untouched. So by construction a retry re-presents the
-     * IDENTICAL approval and the four non-nonce fields inside the approver's signed digest
-     * cannot drift. No second call to the approval hook is reachable from in here either:
-     * `obtainApproval` lives a layer up in `ControlFormationUsageRecorder` and is never
-     * re-entered.
-     *
-     * `write` must be a BARE private body ({@link inTransaction} /
-     * {@link execFormationUsageInsert}) — {@link withWriteLock} is not re-entrant and a `write`
-     * that called another locked public method would hang silently and strand the write queue.
-     *
-     * A failed attempt has written nothing (a bare insert never landed; a transactional one
-     * rolled back), so the abort check at the top of each attempt stays inside
-     * {@link FormationAbortedError}'s contract — it is only ever thrown before this attempt's
-     * write is issued.
-     *
-     * @param operation - `'redemption'` | `'usage recording'`, for the abort error's text.
-     * @param knownTotalUses - The invite's seat budget when the caller already has it in hand
-     * (`undefined` to fall back to a fresh {@link queryFormationInvite} read; `null` for "no
-     * invite row" / unlimited). Passed through to {@link assertSeatRemains} on every attempt.
-     * @returns The `UseNumber` the successful attempt wrote under.
-     */
-    private withUseNumberRetry;
-    /**
-     * Refuse an attempt that would consume a seat the invite does not have.
+     * Refuse a redemption that would consume a seat the invite does not have.
      *
-     * `FormationUsage.Authorized` already enforces `FI.TotalUses is null or FI.TotalUses >=
-     * new.UseNumber`, so an over-limit write fails at the database anyway — but it fails as a
-     * generic `CHECK constraint failed: Authorized`, which the manager reports as a retryable
-     * conflict. Catching it here as {@link InvitationExhaustedError} lets the joiner be told the
-     * invitation is spent instead of being sent around a loop that can never close. Run on EVERY
-     * attempt, including the first: two redemptions racing on the SAME node serialize behind the
-     * local write queue, so the loser's first attempt is already over budget, with no retry
-     * involved.
+     * The schema's count-based cap clause (`FormationUsage.Authorized`) refuses an over-limit
+     * write at the database anyway — but it fails as a generic `CHECK constraint failed:
+     * Authorized`, which the manager reports as a retryable conflict. Catching it here as
+     * {@link InvitationExhaustedError} lets the joiner be told the invitation is spent instead
+     * of being sent around a loop that can never close. Runs inside the write lock, so on a
+     * same-node race the loser reads the winner's committed row and is refused by name.
      *
      * `knownTotalUses` lets a caller that already read the `FormationInvite` row (both
      * production callers in `ControlFormationUsageRecorder` do) skip a second read on the common,
@@ -1207,7 +1164,7 @@ export declare class ControlDatabase {
      * invite, before an outbound approval call). Safe today because `FormationInvite` is
      * insert/delete only (its `Immutable` constraint), so the only way to stale it is an owner
      * revoking the token and re-issuing it with MORE seats mid-redemption; if invites ever gain
-     * an update path, drop the parameter and read here on every attempt instead.
+     * an update path, drop the parameter and read here instead.
      */
     private assertSeatRemains;
     /** Parameterised `FormationUsage` insert shared by redeem + record paths. */
@@ -1227,6 +1184,22 @@ export declare class ControlDatabase {
     } | null>;
     /**
      * Count `FormationUsage` rows recorded against a token (uses consumed so far).
+     *
+     * NOTE: `Token` left the primary key in `formation-unique-token-redesign` and gained the
+     * `FormationUsageByToken` secondary index, so this filter is now served by an index SEEK
+     * (a descent through the index collection) where it used to be a leading-key partial match
+     * the optimystic vtab declined and the engine served by scan. That matters because the seat
+     * cap is this count: a descent that under-reports admits a seat the invite does not have,
+     * where a scan could not. Descent misses have been observed on a NETWORKED store (tracked
+     * by `debt-composite-pk-point-lookup-unreliable-untracked`, for full-primary-key lookups);
+     * no miss has been observed on this index on a SINGLE node. Across nodes the index is
+     * currently blind: a sibling never learns index entries for rows written elsewhere (the
+     * distributed commit drops the index update — measured 2026-08-12, tracked by
+     * `blocked/secondary-index-seek-blind-to-sibling-rows`), so on a multi-machine party this
+     * count under-reports and the cap over-admits until the upstream fix lands. If
+     * over-admission ever shows up on a converged single node — a token with more usage rows
+     * than its `TotalUses` and no concurrent redeemers to explain it — suspect this seek first
+     * and drop the index to fall back to the scan.
      */
     countFormationUsage(token: string): Promise<number>;
     /**
@@ -1247,14 +1220,6 @@ export declare class ControlDatabase {
      * unlimited-use invite anywhere in the scan short-circuits all of them.
      */
     hasOutstandingFormationInvite(nowMs?: number): Promise<boolean>;
-    /**
-     * Next `UseNumber` for a token = max(existing)+1, per the `Monotonic` constraint.
-     *
-     * Called only from inside {@link withUseNumberRetry}'s locked body — a read takes no
-     * transaction of its own, so it is safe there, and reading it under the lock is what stops
-     * two local redemptions of one token from picking the same number.
-     */
-    private nextUseNumber;
     /**
      * Close the database and cleanup resources.
      *