@serfab/cadre-core 0.10.0 → 0.12.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;
 }
 /**
@@ -245,12 +227,111 @@ export declare class ControlDatabase {
      * having to restate the policy's attempts or classifier.
      */
     private controlWriteRetryPacing;
+    /**
+     * Pacing seams for {@link readRows}'s retry — the read twin of
+     * {@link controlWriteRetryPacing}, with the same contract: production leaves this
+     * empty, specs inject a recorded `sleep` / fake `now` so no test waits out a real
+     * backoff. Applied OVER the read policy's defaults but UNDER the call site's `label`.
+     */
+    private controlReadRetryPacing;
     constructor(config: ControlDatabaseConfig);
     /**
      * Initialize the database - load schema and register plugins
      */
     initialize(): Promise<void>;
     private loadSchema;
+    /**
+     * One UNRETRIED drain of a control read to rows — every read in this class bottoms out
+     * here (almost all via {@link readRows}, which adds the transient-failure retry), and
+     * this is the ONE place the committed-read opt-in is spelled.
+     *
+     * Reached only through {@link readRows}, which drops straight here for the call sites
+     * that pass `retry: false` — reads issued from INSIDE a locked write body, where a
+     * backoff sleep would hold the write lock and the write funnel re-runs the read anyway
+     * (see the NOTE on {@link readRows}).
+     *
+     * A control read normally queues on the database's exec mutex, so it does not answer
+     * until whatever statement holds that mutex finishes. When a control WRITE is parked
+     * against an unresponsive cohort member that is minutes, and a read that only wants
+     * the last committed state waits the whole time for no reason
+     * (`complete/control-reads-blocked-by-stalled-write`).
+     *
+     * Quereus's remedy is `readConcurrency: 'committed'` — a PER-CALL opt-in
+     * (`Statement.tryRouteConcurrent` refuses anything that did not ask for it by name)
+     * that runs an eligible read off the mutex against each table's last committed state.
+     * Routing is best-effort and never an error: an ineligible statement falls back to
+     * the serialized path silently — any side-effecting node, any table-valued function
+     * call (pure ones included), any table whose module does not declare
+     * `readCommittedSnapshot`, or an EXPLICIT transaction being open on this database.
+     *
+     * **It is asked for only while a write is in flight, and that condition is the whole
+     * point.** The opt-in does not merely move the read off the mutex: it connects the
+     * table with `_readCommitted`, and the optimystic vtab serves such a connection from
+     * a pinned pre-transaction snapshot that NEVER refreshes from the network, where an
+     * ordinary read calls `update()` on the collection first. Taking that path
+     * unconditionally therefore trades "reads block behind a stalled write" for "reads
+     * stop seeing what other machines wrote" — measured, not theorised: with every read
+     * opted in, `control-write-degraded-cohort-member` could no longer observe a sibling
+     * publishing its own `CadrePeer` row and failed at suite setup on two runs out of two.
+     *
+     * `getAutocommit()` reports the whole `Database` rather than this call (the same
+     * property {@link assertCommitBoundary} leans on), which is exactly what is wanted:
+     * false means some writer's transaction is open, which is the only situation where a
+     * read would have blocked. The check races that writer harmlessly in both directions
+     * — losing it either reads normally (today's behaviour) or reads committed state.
+     *
+     * What a committed read gives up is observing a write that has not finished
+     * committing, and that is safe for every caller here: an AWAITED write is committed by
+     * the time it returns, and a read inside {@link inTransaction} is disqualified by the
+     * open explicit transaction and stays serialized, so it still sees its own
+     * transaction's rows. A read after an UNAWAITED write on this database would be wrong
+     * — no such caller exists, and {@link withWriteLock} is what keeps it that way.
+     */
+    private readRowsOnce;
+    /**
+     * {@link readRowsOnce} plus the bounded transient-failure retry
+     * ({@link retryControlRead}) — the funnel every UNLOCKED control read goes through, so a
+     * read that failed because the cluster could not be asked properly (a stream reset
+     * mid-scan, a partially unreachable cohort) is re-presented a moment later instead of
+     * surfacing to every reader.
+     *
+     * MATERIALIZES the read rather than returning a lazy iterator, and that shape is what
+     * makes the retry possible at all: the failure happens during ITERATION, not at call
+     * time, and a half-consumed iterator cannot be retried without re-yielding rows the
+     * caller already saw. Materializing is safe here — every caller either drains to an
+     * array anyway or takes the first row of a statement that yields at most one (a
+     * primary-key lookup or a `count(1)`); nothing streams.
+     *
+     * Each ATTEMPT is a fresh {@link readRowsOnce} call, so the committed-read opt-in
+     * (`getAutocommit()`) is re-evaluated per attempt — a write can finish between attempts
+     * and change the right answer.
+     *
+     * The retry's budget ({@link CONTROL_READ_RETRY_BUDGET_MS}, 1.5 s) is deliberately far
+     * under the write funnel's: the tightest caller deadline over a control read is the
+     * inbound admission gate's 2 s FAIL-OPEN timeout, and a read that outlives it spends its
+     * retries after the gate has already admitted (see `control-read-retry.ts`).
+     *
+     * `label` names the read in the retry loop's `Control read [<label>] …` debug lines and
+     * nothing else; several reads are in flight concurrently in a real party, so an
+     * unlabelled line cannot be attributed — keep new call sites labelled.
+     *
+     * `retry: false` drops straight to {@link readRowsOnce}: reads issued from INSIDE a
+     * locked write body must not retry on their own. `retryControlWrite`'s contract is that
+     * backoff sleeps happen with NO lock held; a read retrying its own backoff inside a
+     * locked body would sleep holding the write lock (stalling every other local writer),
+     * and the write funnel already re-runs the body's reads when it re-runs the body. See
+     * {@link queryStampId} / {@link assertSeatRemains} / {@link queryCadrePeers} for the
+     * per-call opt-outs.
+     *
+     * NOTE: nothing structural enforces that opt-out — it is per-call because an unlocked
+     * read runs CONCURRENTLY with a locked body, so `this`-state cannot tell the two apart,
+     * and there is no async-context primitive available on every target platform (browser,
+     * React Native) to carry the answer. Reads reached through a CALLBACK invoked under the
+     * lock are the easy miss: `notifyMembershipChanged` runs its listener with the lock
+     * held, and its membership read is opted out at {@link queryCadrePeers}. If another
+     * under-lock callback seam is ever added, audit its read graph the same way.
+     */
+    private readRows;
     /**
      * Query all strands from the control database
      */
@@ -314,8 +395,25 @@ 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.
+     *
+     * `retry: false` is passed by exactly one caller —
+     * `CadreNode.refreshAuthorizedControlPeers`, the membership-gate snapshot refresh —
+     * because {@link notifyMembershipChanged} invokes that listener with the write lock
+     * HELD, and a retrying read there would sleep its backoff holding the lock (see the
+     * NOTE on {@link readRows}). It costs nothing: that refresh is best-effort, keeps the
+     * previous snapshot on failure, and is re-driven by the next write and by the timed
+     * reconcile. BOTH of this method's reads take the flag — retrying either one under the
+     * lock is the same defect.
      */
-    queryCadrePeers(): Promise<CadrePeerRow[]>;
+    queryCadrePeers(retry?: boolean): Promise<CadrePeerRow[]>;
     /**
      * Every approver public key currently enrolled in `CadreControl.ValidationKey` — the
      * set a `ValidationUrl` redemption's approval signature must be signed by (see
@@ -340,6 +438,16 @@ export declare class ControlDatabase {
      * `table` and its {@link GUARDED_KEY_COLUMN} column are interpolated into the SQL; both
      * come from closed literal unions — no caller-supplied string can reach the statement
      * (same injection-surface discipline as {@link countRows}'s `CONTROL_TABLE_SET` guard).
+     *
+     * NOTE: `retry: false` is passed by exactly the call sites that run INSIDE a locked
+     * write body — {@link deleteGuardedRow} and {@link insertCadrePeer}'s insert-if-absent
+     * guard. A read retrying there would sleep its backoff HOLDING the write lock
+     * (`retryControlWrite`'s contract is that backoff sleeps happen with no lock held), and
+     * the write funnel already re-runs the body's reads when it re-runs the body. The
+     * unlocked callers — the public stamp readers, {@link reauthorizeCadrePeer} and
+     * {@link reapRevokedRow}, whose stamp reads run BEFORE their locks are taken — keep the
+     * default retried path. Explicit per call rather than an ambient flag: unlocked reads
+     * run concurrently with a locked body, so `this`-state cannot tell the two apart.
      */
     private queryStampId;
     /**
@@ -374,8 +482,11 @@ export declare class ControlDatabase {
      * NOTE: re-reads the whole retired set on every call, and the caller runs per inbound
      * gate request while the table only ever grows. Cheap today (a cadre removes peers
      * rarely); if removals ever become routine, cache the set and invalidate it on write.
+     *
+     * `retry: false` is forwarded by {@link queryCadrePeers} for the one caller that reads
+     * under the write lock — see that method's note.
      */
-    queryRevokedStamps(tableName: RevocableTable): Promise<Set<string>>;
+    queryRevokedStamps(tableName: RevocableTable, retry?: boolean): Promise<Set<string>>;
     /**
      * Every locally-held `CadreControl.Revocation` tombstone — identity triple plus its
      * `ReissuedAt` counter. Consumed by the cohort-growth re-issue sweep, which
@@ -396,7 +507,7 @@ export declare class ControlDatabase {
      * {@link queryRevokedStamps} rather than inlining the SQL, so tests can interpose on
      * that seam (see {@link queryCadrePeers}).
      *
-     * Missing/legacy column values are coalesced
+     * Missing/null column values are coalesced
      * to their empty form (`''` key/sig, `[]` addrs, `0` stamp) so the caller's
      * verify/freshness gates uniformly reject an unpublished or malformed row.
      * The split `addrs` re-join to the exact stored `Multiaddr` (split-on-`,` is
@@ -431,7 +542,7 @@ export declare class ControlDatabase {
     /**
      * Read a single peer's device push token (the full `DeviceToken` row) by PeerId.
      *
-     * Returns null when no row exists. Missing/legacy column values are coalesced to
+     * Returns null when no row exists. Missing/null column values are coalesced to
      * their empty form (`''` token/sig, `0` stamp) so the caller's verify/freshness
      * gates uniformly reject an unpublished or malformed row. `platform` is returned
      * verbatim (the resolver validates it against {@link PushPlatform} and re-verifies
@@ -900,7 +1011,8 @@ export declare class ControlDatabase {
      * {@link assertCommitBoundary} (any `CadrePeer` path) or silently join each other's
      * open transaction — a torn commit if either side rolls back. This lock closes that
      * class: every public write method of this class runs its statement(s) under it, and
-     * `SeedBootstrapService` wraps its direct `db.exec` writes in it too. The race is
+     * `SeedBootstrapService` reaches it through {@link execWrite} rather than touching the
+     * `Database` directly, so it is covered too. The race is
      * real, not theoretical: the background self-record publish on a control connection
      * opening (`CadreNode.drainPendingControlReplication` → `registerSelf`) collided with
      * a foreground `authorizePeer` — both `CadrePeer` inserts — and tripped the boundary
@@ -937,10 +1049,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 +1059,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 +1075,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.
@@ -1012,7 +1130,8 @@ export declare class ControlDatabase {
      * `StrandId` binds the invite to a pre-existing host strand (provision-then-record):
      * when set, a responder redeeming this token records a `FormationUsage` against that
      * strand and returns it (see {@link ControlFormationUsageRecorder.resolveStrand}); a
-     * null `StrandId` (the default) leaves the legacy responder-provisions path in place.
+     * null `StrandId` (the default) takes the unbound responder-provisions path: the
+     * responder provisions a fresh open strand and atomically records its one consent row.
      * Like ValidationUrl it is a nullable bound field, signed as `''` when absent.
      *
      * The ExpiresAt and TotalUses message fields must byte-match what the (auto-deferred,
@@ -1062,13 +1181,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 +1209,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 +1220,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 +1235,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 +1256,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 +1287,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. */
@@ -1216,8 +1296,12 @@ export declare class ControlDatabase {
      * Read a `FormationInvite` row by token, or null when absent. `expiresAtMs` is
      * the parsed epoch-ms of the stored `datetime` (null when the invite never
      * expires); the caller compares it against the wall clock for freshness.
+     *
+     * `retry: false` is passed only by {@link assertSeatRemains}, which runs INSIDE a
+     * locked write body — same per-call opt-out, and for the same reason, as
+     * {@link queryStampId}'s. Every unlocked caller keeps the default retried path.
      */
-    queryFormationInvite(token: string): Promise<{
+    queryFormationInvite(token: string, retry?: boolean): Promise<{
         token: string;
         sAppId: string;
         expiresAtMs: number | null;
@@ -1227,8 +1311,29 @@ export declare class ControlDatabase {
     } | null>;
     /**
      * Count `FormationUsage` rows recorded against a token (uses consumed so far).
+     *
+     * This count IS the seat cap (`enforceFormationUseCap`), so an under-report admits a seat
+     * the invitation never paid for. It is served by a table SCAN, deliberately: a bare
+     * equality on a non-key column is a shape the optimystic vtab declines to claim, so the
+     * engine applies the filter itself over a full read of the table.
+     *
+     * NOTE: it was briefly an index seek, and that is what the scan is protecting against.
+     * `formation-unique-token-redesign` took `Token` out of the primary key and declared
+     * `FormationUsageByToken` purely to spare this scan, recording as a tripwire that an
+     * under-reporting descent would admit an unpaid-for seat — "a failure mode a scan could
+     * not produce". The tripwire fired. Across machines a secondary-index descent returns only
+     * the rows the READING machine wrote, so this count under-reported without bound on a
+     * multi-machine party and the cap over-admitted. The index was removed 2026-08-25; the
+     * measurement is recorded in the block comment at the `FormationUsage` declaration in
+     * `schemas/control.qsql`, and the engine defect in
+     * `blocked/secondary-index-seek-blind-to-sibling-rows`. Do NOT re-declare the index to
+     * speed this up while that ticket is open.
+     *
+     * `retry: false` is passed only by {@link assertSeatRemains}, which runs INSIDE a
+     * locked write body — same per-call opt-out, and for the same reason, as
+     * {@link queryStampId}'s. Every unlocked caller keeps the default retried path.
      */
-    countFormationUsage(token: string): Promise<number>;
+    countFormationUsage(token: string, retry?: boolean): Promise<number>;
     /**
      * Is any `FormationInvite` row still redeemable — unexpired AND with usage
      * below its `TotalUses`? A null `ExpiresAt` never expires and a null
@@ -1247,14 +1352,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.
      *