@serfab/cadre-core 0.10.0 → 0.12.0

package/src/control-database.ts

@@ -1,7 +1,7 @@
 import debug from 'debug';
 import { toString as uint8ArrayToString } from 'uint8arrays';
-import { Database, registerPlugin, unwrapError } from '@quereus/quereus';
-import type { VTablePluginInfo, FunctionPluginInfo, SqlParameters } from '@quereus/quereus';
+import { Database, registerPlugin } from '@quereus/quereus';
+import type { VTablePluginInfo, FunctionPluginInfo, SqlParameters, SqlValue } from '@quereus/quereus';
 import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
 import optimysticPlugin from '@optimystic/quereus-plugin-optimystic/plugin';
 import { digest, randomBytes } from '@optimystic/quereus-plugin-crypto';
@@ -15,6 +15,8 @@ import type { ControlTable, RevocableTable, ControlDomain, ControlAction } from
 import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
 import { retryControlWrite, SCHEMA_INIT_RETRY_POLICY } from './control-write-retry.js';
 import type { ControlWriteRetryOptions } from './control-write-retry.js';
+import { retryControlRead } from './control-read-retry.js';
+import type { ControlReadRetryOptions } from './control-read-retry.js';
 
 export type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
 
@@ -90,102 +92,34 @@ export 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 class InvitationExhaustedError extends Error {
   constructor(
     readonly token: string,
-    readonly useNumber: number,
+    readonly usesRecorded: number,
     readonly totalUses: number,
   ) {
     super(
-      `Invitation ${token} is exhausted: use #${useNumber} is past its limit of ${totalUses} use(s)`
+      `Invitation ${token} is exhausted: ${usesRecorded} of ${totalUses} use(s) already recorded`
     );
     this.name = 'InvitationExhaustedError';
   }
 }
 
-/**
- * Attempts allowed per redemption: the first, plus two retries of a use number another
- * writer took. Bounded so sustained contention terminates in a clean rejection rather than
- * spinning; two retries is enough for the realistic case (a handful of nodes redeeming one
- * multi-use token at once) without holding the write lock hostage.
- *
- * NOTE: the attempts fire back-to-back, with no backoff and no jitter — each one only takes
- * and releases the write lock. Fine while cross-node contention on a single token is a
- * handful of writers; if one hot multi-use token ever draws sustained concurrent redemption
- * (a broadcast invite, a bulk onboarding run), all three attempts can burn against the same
- * competitor and the caller gets the engine's error. Add a short randomised delay between
- * attempts then — NOT a longer attempt budget, which would hold the write queue.
- */
-const USE_NUMBER_ATTEMPTS = 3;
-
-/**
- * The two error messages that mean "another writer took the `UseNumber` we picked", and
- * nothing else.
- *
- * - the `(Token, UseNumber)` primary-key collision, which the optimystic vtab reports on the
- *   insert itself (`uniqueConstraintMessage` renders the columns table-qualified, no schema
- *   prefix);
- * - `CHECK constraint failed: Monotonic` — `FormationUsage.Monotonic` contains a subquery, so
- *   Quereus defers it to commit where it reads `committed.FormationUsage`. A concurrent row
- *   that our insert's key probe did not see still trips it there. Same meaning, different
- *   surface.
- *
- * Deliberately NOT matched: `FormationUsage.UsageStampId`'s `unique` (a repeated nonce is
- * replay, never a race — retrying it would re-present a spent approval), and every named
- * CHECK other than `Monotonic`. `Authorized` in particular renders with the same
- * `CHECK constraint failed:` prefix, so the constraint NAME is anchored with `\b` exactly as
- * `expectConstraintFailure` does rather than matched by prefix.
- *
- * NOTE: a CHECK failure names only the CONSTRAINT, never its table, and `Monotonic` is a
- * generic enough name that a second table could plausibly claim it. Today it is unique across
- * `schemas/control.qsql`, so the pattern cannot mis-fire; if another table ever declares a
- * `Monotonic` constraint, a failure of THAT constraint would be read here as a lost use-number
- * race and pointlessly retried up to {@link USE_NUMBER_ATTEMPTS} times. Rename the other
- * constraint (cheapest) rather than trying to recover the table from the message.
- */
-const LOST_USE_NUMBER_PATTERNS = [
-  /UNIQUE constraint failed: FormationUsage\.Token, FormationUsage\.UseNumber/i,
-  /CHECK constraint failed: Monotonic\b/,
-];
-
-/**
- * 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 function isLostUseNumberRace(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
-  }
-  return unwrapError(error).some(({ message }) =>
-    LOST_USE_NUMBER_PATTERNS.some(pattern => pattern.test(message)));
-}
-
 /**
  * What a recorded `FormationUsage` row came out as.
  *
@@ -194,9 +128,7 @@ export 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;
 }
 
@@ -449,6 +381,13 @@ export class ControlDatabase {
    * having to restate the policy's attempts or classifier.
    */
   private controlWriteRetryPacing: ControlWriteRetryOptions = {};
+  /**
+   * 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: ControlReadRetryOptions = {};
 
   constructor(config: ControlDatabaseConfig) {
     this.config = config;
@@ -532,6 +471,20 @@ export class ControlDatabase {
     log('Hydrated control catalog (tables=%d, indexes=%d)', hydrated.tables, hydrated.indexes);
 
     // Load and execute the schema
+    // NOTE: this is where a slow launch is felt. Duration is (raw-storage operations
+    // issued) × per-operation storage latency: ~1ms/op on an idle machine, but
+    // 50-90ms/op on a loaded disk or a phone's flash under launch contention. A cold
+    // start now reaches the backend 172 times (8 tables + 1 index, 21 distinct blocks
+    // — dominated by its 130 genuine writes), a warm restart 52, because cadre-core
+    // wraps every embedder storage in `@optimystic/db-p2p`'s write-through cache
+    // (@serfab/quereus-plugin-sereus's cached-storage.ts). Uncached the same start issued ~2000 operations — the
+    // upstream re-read amplification measured in
+    // tickets/complete/optimystic-block-read-amplification-on-control-start.md (and
+    // its follow-up ...-schema-catalog-reread-per-write-blows-storage-budgets.md),
+    // which also rules out the retry policy and cluster deadlines. The counts are
+    // pinned by packages/cadre-core/test/control-start-storage-op-budget.spec.ts; if
+    // they grow — e.g. the cache leaves this path — that spec fails before anyone
+    // has to debug a launch.
     t0 = performance.now();
     await this.loadSchema();
     timing('[controlDb] loadSchema: %dms', Math.round(performance.now() - t0));
@@ -605,17 +558,139 @@ export class ControlDatabase {
     // also what lets schema init absorb optimystic's self-coordination grace refusal, which
     // is unsafe for control writes in general. Why, on
     // `RETRIABLE_SCHEMA_INIT_MATCHERS` in `control-write-retry.ts`.
-    await this.lockedWithRetry(() => this.db!.exec(schemaContent), SCHEMA_INIT_RETRY_POLICY);
+    await this.lockedWithRetry(() => this.db!.exec(schemaContent), SCHEMA_INIT_RETRY_POLICY, 'schema-init');
     log('Schema loaded and executed');
   }
 
+  /**
+   * 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 async readRowsOnce(sql: string, params?: SqlParameters): Promise<Record<string, SqlValue>[]> {
+    let iterator: AsyncIterableIterator<Record<string, SqlValue>>;
+    if (this.db!.getAutocommit()) {
+      iterator = this.db!.eval(sql, params);
+    } else {
+      log('read-eval: a write is in flight, asking for a committed read: %s', sql);
+      iterator = this.db!.eval(sql, params, { readConcurrency: 'committed' });
+    }
+    const rows: Record<string, SqlValue>[] = [];
+    for await (const row of iterator) {
+      rows.push(row);
+    }
+    return rows;
+  }
+
+  /**
+   * {@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(
+    sql: string,
+    params: SqlParameters | undefined,
+    label: string,
+    retry = true
+  ): Promise<Record<string, SqlValue>[]> {
+    if (!retry) {
+      return this.readRowsOnce(sql, params);
+    }
+    // The label lands LAST so the call site's name survives the spec-injected pacing —
+    // it changes log attribution only, never behaviour (same layering as lockedWithRetry).
+    return retryControlRead(
+      () => this.readRowsOnce(sql, params),
+      { ...this.controlReadRetryPacing, label }
+    );
+  }
+
   /**
    * Query all strands from the control database
    */
   async queryStrands(): Promise<StrandRow[]> {
     this.ensureInitialized();
     const results: StrandRow[] = [];
-    for await (const row of this.db!.eval('select Id, MemberPrivateKey, Type from CadreControl.Strand')) {
+    for (const row of await this.readRows('select Id, MemberPrivateKey, Type from CadreControl.Strand', undefined, 'strands')) {
       results.push({
         Id: row.Id as string,
         MemberPrivateKey: row.MemberPrivateKey as string | null,
@@ -633,9 +708,10 @@ export class ControlDatabase {
    */
   async queryStrand(strandId: string): Promise<StrandRow | null> {
     this.ensureInitialized();
-    for await (const row of this.db!.eval(
+    for (const row of await this.readRows(
       'select Id, MemberPrivateKey, Type from CadreControl.Strand where Id = ?',
-      [strandId]
+      [strandId],
+      'strand'
     )) {
       return {
         Id: row.Id as string,
@@ -662,7 +738,7 @@ export class ControlDatabase {
     if (!CONTROL_TABLE_SET.has(table)) {
       throw new Error(`Unknown CadreControl table: ${table}`);
     }
-    for await (const row of this.db!.eval(`select count(1) as Count from CadreControl.${table}`)) {
+    for (const row of await this.readRows(`select count(1) as Count from CadreControl.${table}`, undefined, 'count-rows')) {
       return (row.Count as number) ?? 0;
     }
     return 0;
@@ -682,7 +758,7 @@ export class ControlDatabase {
    */
   async hasOwnerKey(): Promise<boolean> {
     this.ensureInitialized();
-    for await (const row of this.db!.eval('select count(1) as Count from CadreControl.OwnerKey')) {
+    for (const row of await this.readRows('select count(1) as Count from CadreControl.OwnerKey', undefined, 'owner-key-exists')) {
       return (row.Count as number) > 0;
     }
     return false;
@@ -715,7 +791,7 @@ export class ControlDatabase {
   async getOwnerKeys(): Promise<Set<string>> {
     this.ensureInitialized();
     const keys = new Set<string>();
-    for await (const row of this.db!.eval('select Key from CadreControl.OwnerKey')) {
+    for (const row of await this.readRows('select Key from CadreControl.OwnerKey', undefined, 'owner-keys')) {
       keys.add(row.Key as string);
     }
     return keys;
@@ -737,12 +813,29 @@ export 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.
    */
-  async queryCadrePeers(): Promise<CadrePeerRow[]> {
+  async queryCadrePeers(retry = true): Promise<CadrePeerRow[]> {
     this.ensureInitialized();
-    const revoked = await this.queryRevokedStamps('CadrePeer');
+    const revoked = await this.queryRevokedStamps('CadrePeer', retry);
     const rows: CadrePeerRow[] = [];
-    for await (const row of this.db!.eval('select PeerId, Multiaddr, StampId, VouchOwner, VouchSig from CadreControl.CadrePeer')) {
+    for (const row of await this.readRows('select PeerId, Multiaddr, StampId, VouchOwner, VouchSig from CadreControl.CadrePeer', undefined, 'cadre-peers', retry)) {
       const stampId = (row.StampId as string | null) ?? null;
       if (stampId !== null && revoked.has(stampId)) {
         continue;
@@ -770,7 +863,7 @@ export class ControlDatabase {
   async queryValidationKeys(): Promise<string[]> {
     this.ensureInitialized();
     const keys: string[] = [];
-    for await (const row of this.db!.eval('select Key from CadreControl.ValidationKey')) {
+    for (const row of await this.readRows('select Key from CadreControl.ValidationKey', undefined, 'validation-keys')) {
       keys.push(row.Key as string);
     }
     return keys.sort();
@@ -790,14 +883,25 @@ export 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 async queryStampId(
     table: RevocableTable,
-    keyValue: string
+    keyValue: string,
+    retry = true
   ): Promise<string | null> {
     this.ensureInitialized();
     const sql = `select StampId from CadreControl.${table} where ${GUARDED_KEY_COLUMN[table]} = ?`;
-    for await (const row of this.db!.eval(sql, [keyValue])) {
+    for (const row of await this.readRows(sql, [keyValue], `stamp-${table}`, retry)) {
       return (row.StampId as string | null) ?? null;
     }
     return null;
@@ -847,11 +951,14 @@ export 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.
    */
-  async queryRevokedStamps(tableName: RevocableTable): Promise<Set<string>> {
+  async queryRevokedStamps(tableName: RevocableTable, retry = true): Promise<Set<string>> {
     this.ensureInitialized();
     const stamps = new Set<string>();
-    for await (const row of this.db!.eval('select StampId from CadreControl.Revocation where TableName = ?', [tableName])) {
+    for (const row of await this.readRows('select StampId from CadreControl.Revocation where TableName = ?', [tableName], 'revoked-stamps', retry)) {
       stamps.add(row.StampId as string);
     }
     return stamps;
@@ -868,7 +975,7 @@ export class ControlDatabase {
   async queryRevocations(): Promise<RevocationRow[]> {
     this.ensureInitialized();
     const rows: RevocationRow[] = [];
-    for await (const row of this.db!.eval('select TableName, RowKey, StampId, ReissuedAt from CadreControl.Revocation')) {
+    for (const row of await this.readRows('select TableName, RowKey, StampId, ReissuedAt from CadreControl.Revocation', undefined, 'revocations')) {
       rows.push({
         tableName: row.TableName as RevocableTable,
         rowKey: row.RowKey as string,
@@ -890,7 +997,7 @@ export 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
@@ -900,9 +1007,10 @@ export class ControlDatabase {
   async queryPeerRecord(peerId: string): Promise<PeerAddressRecord | null> {
     this.ensureInitialized();
     const revoked = await this.queryRevokedStamps('CadrePeer');
-    for await (const row of this.db!.eval(
+    for (const row of await this.readRows(
       'select PeerId, PublicKey, Multiaddr, UpdatedAt, Sig, StampId from CadreControl.CadrePeer where PeerId = ?',
-      [peerId]
+      [peerId],
+      'peer-record'
     )) {
       const stampId = (row.StampId as string | null) ?? null;
       if (stampId !== null && revoked.has(stampId)) {
@@ -951,14 +1059,14 @@ export class ControlDatabase {
         with context OwnerKey = null, Signature = ?
         set Multiaddr = ?, UpdatedAt = ?, Sig = ?
         where PeerId = ?
-    `, [record.sig, multiaddr, record.updatedAt, record.sig, record.peerId]);
+    `, [record.sig, multiaddr, record.updatedAt, record.sig, record.peerId], 'self-record-update');
     log('Self peer record updated: %s (updatedAt=%d)', record.peerId, record.updatedAt);
   }
 
   /**
    * 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
@@ -970,9 +1078,10 @@ export class ControlDatabase {
    */
   async queryDeviceToken(peerId: string): Promise<DeviceTokenRow | null> {
     this.ensureInitialized();
-    for await (const row of this.db!.eval(
+    for (const row of await this.readRows(
       'select PeerId, Platform, Token, UpdatedAt, Sig, StampId from CadreControl.DeviceToken where PeerId = ?',
-      [peerId]
+      [peerId],
+      'device-token'
     )) {
       return {
         peerId: row.PeerId as string,
@@ -1004,7 +1113,7 @@ export class ControlDatabase {
         with context OwnerKey = null, Signature = ?
         set Platform = ?, Token = ?, UpdatedAt = ?, Sig = ?
         where PeerId = ?
-    `, [record.sig, record.platform, record.token, record.updatedAt, record.sig, record.peerId]);
+    `, [record.sig, record.platform, record.token, record.updatedAt, record.sig, record.peerId], 'device-token-update');
     log('Self device token updated: %s (platform=%s, updatedAt=%d)', record.peerId, record.platform, record.updatedAt);
   }
 
@@ -1028,7 +1137,7 @@ export class ControlDatabase {
       insert into CadreControl.OwnerKey (Key, StampId)
         with context OwnerKey = null, Signature = null
         values (?, ?)
-    `, [key, stampId]);
+    `, [key, stampId], 'owner-key-insert');
     log('Owner key inserted');
   }
 
@@ -1071,7 +1180,7 @@ export class ControlDatabase {
       insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
         with context OwnerKey = ?, Signature = ?
         values (?, ?, ?, ?)
-    `, [ownerKey, signature, strandId, type, memberPrivateKey ?? null, stampId]);
+    `, [ownerKey, signature, strandId, type, memberPrivateKey ?? null, stampId], 'strand-insert');
 
     log('Strand inserted: %s', strandId);
   }
@@ -1099,7 +1208,7 @@ export class ControlDatabase {
     ownerKey: string,
     signMessage: (message: Uint8Array) => string
   ): Promise<boolean> {
-    return this.lockedWithRetry(() => this.deleteGuardedRow('Strand', strandId, ownerKey, signMessage));
+    return this.lockedWithRetry(() => this.deleteGuardedRow('Strand', strandId, ownerKey, signMessage), {}, 'strand-delete');
   }
 
   /**
@@ -1134,7 +1243,7 @@ export class ControlDatabase {
       insert into CadreControl.ValidationKey (Key, StampId)
         with context OwnerKey = ?, Signature = ?
         values (?, ?)
-    `, [ownerKey, signature, key, stampId]);
+    `, [ownerKey, signature, key, stampId], 'validation-key-insert');
 
     log('Validation key inserted: %s', key);
   }
@@ -1160,7 +1269,7 @@ export class ControlDatabase {
     ownerKey: string,
     signMessage: (message: Uint8Array) => string
   ): Promise<boolean> {
-    return this.lockedWithRetry(() => this.deleteGuardedRow('ValidationKey', key, ownerKey, signMessage));
+    return this.lockedWithRetry(() => this.deleteGuardedRow('ValidationKey', key, ownerKey, signMessage), {}, 'validation-key-delete');
   }
 
   /**
@@ -1219,7 +1328,8 @@ export class ControlDatabase {
       buildAuthorizationMessage('CadreControl.CadrePeer', 'vouch', [row.peerId, stampId])
     );
     return await this.mutateCadrePeer('peer-insert', async () => {
-      if (await this.queryStampId('CadrePeer', row.peerId) !== null) {
+      // retry: false — this guard runs inside the locked write body (see queryStampId's NOTE).
+      if (await this.queryStampId('CadrePeer', row.peerId, false) !== null) {
         log('CadrePeer row already present for %s; insert skipped (already a member)', row.peerId);
         return false;
       }
@@ -1360,7 +1470,7 @@ export class ControlDatabase {
     ownerKey: string,
     signMessage: (message: Uint8Array) => string
   ): Promise<boolean> {
-    return this.lockedWithRetry(() => this.deleteGuardedRow('DeviceToken', peerId, ownerKey, signMessage));
+    return this.lockedWithRetry(() => this.deleteGuardedRow('DeviceToken', peerId, ownerKey, signMessage), {}, 'device-token-delete');
   }
 
   /**
@@ -1403,7 +1513,8 @@ export class ControlDatabase {
     signMessage: (message: Uint8Array) => string
   ): Promise<boolean> {
     this.ensureInitialized();
-    const stampId = await this.queryStampId(table, keyValue);
+    // retry: false — this runs inside the locked write body (see queryStampId's NOTE).
+    const stampId = await this.queryStampId(table, keyValue, false);
     if (stampId === null) {
       log('delete %s: no row for %s (already absent)', table, keyValue);
       return false;
@@ -1527,7 +1638,7 @@ export class ControlDatabase {
       // in one pass, hoist the notify to one refresh after the sweep instead.
       await this.mutateCadrePeer('peer-reap', () => this.db!.exec(sql, [rowKey, stampId]));
     } else {
-      await this.execWrite(sql, [rowKey, stampId]);
+      await this.execWrite(sql, [rowKey, stampId], `reap-${table}`);
     }
     // A row leaving the control plane without an owner signature at the write site
     // should be visible in a log.
@@ -1689,7 +1800,7 @@ export class ControlDatabase {
       });
       log('Reissued %d revocation tombstone(s) at %d', executed, reissuedAt);
       return executed;
-    });
+    }, {}, 'revocation-reissue');
   }
 
   /**
@@ -1794,7 +1905,7 @@ export class ControlDatabase {
       this.assertCommitBoundary(reason, 'on return from');
       await this.notifyMembershipChanged(reason);
       return result;
-    });
+    }, {}, reason);
   }
 
   /**
@@ -1807,7 +1918,8 @@ export 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
@@ -1851,10 +1963,8 @@ export 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
@@ -1863,11 +1973,18 @@ export 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<T>(fn: () => Promise<T>, policy: ControlWriteRetryOptions = {}): Promise<T> {
+  private lockedWithRetry<T>(fn: () => Promise<T>, policy: ControlWriteRetryOptions = {}, label?: string): Promise<T> {
+    // The label lands LAST so a call site's own name survives both the policy and the
+    // spec-injected pacing; it changes log attribution only, never behaviour.
     return retryControlWrite(
       () => this.withWriteLock(fn),
-      { ...policy, ...this.controlWriteRetryPacing }
+      { ...policy, ...this.controlWriteRetryPacing, ...(label !== undefined ? { label } : {}) }
     );
   }
 
@@ -1880,10 +1997,13 @@ export 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> {
     this.ensureInitialized();
-    return this.lockedWithRetry(() => this.db!.exec(sql, params));
+    return this.lockedWithRetry(() => this.db!.exec(sql, params), {}, label);
   }
 
   /**
@@ -1956,7 +2076,8 @@ export 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,
@@ -2023,7 +2144,7 @@ export class ControlDatabase {
       options.validationUrl ?? null,
       options.strandId ?? null,
       stampId,
-    ]);
+    ], 'formation-invite-insert');
 
     log('Formation invite inserted: %s', token);
   }
@@ -2053,13 +2174,12 @@ export 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.
    */
   async redeemInvitation(params: {
     token: string;
@@ -2082,9 +2202,9 @@ export 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> {
@@ -2097,13 +2217,22 @@ export class ControlDatabase {
     log('Redeeming invitation %s -> strand %s', token, strandId);
 
     const localPeerId = this.config.libp2pNode.peerId.toString();
-    // Minted ONCE, outside the loop: a failed attempt rolls its whole transaction back, so
-    // nothing was ever persisted under this stamp, and it is deliberately not part of the
-    // approver's signed digest. Re-minting per attempt would only churn.
+    // A failed attempt rolls its whole transaction back, so nothing was ever persisted under
+    // this stamp, and it is deliberately not part of the approver's signed digest.
     const strandStampId = generateStampId(localPeerId);
 
-    const useNumber = await this.withUseNumberRetry(token, 'redemption', signal, totalUses, attemptUseNumber =>
-      this.inTransaction('redemption', async () => {
+    // Ordering inside the locked body is contractual: the abort check, then the seat check,
+    // then the write — FormationAbortedError may only ever be thrown before the write is
+    // issued, and a transient-failure retry (lockedWithRetry re-runs the whole body) must
+    // re-check both before re-presenting the write.
+    await this.lockedWithRetry(async () => {
+      // Inside the lock: a write still parked behind another writer when the caller's
+      // budget expired is abandoned rather than executed.
+      if (signal?.aborted) {
+        throw new FormationAbortedError(token, 'redemption');
+      }
+      await this.assertSeatRemains(token, totalUses);
+      await this.inTransaction('redemption', async () => {
         // 1. Strand row — authorised by the FormationUsage branch (no owner sig),
         //    still carrying a fresh unique StampId for the anti-replay column.
         //    Hard-coded open + keyless: the consent branch admits no other shape.
@@ -2116,14 +2245,15 @@ export class ControlDatabase {
         // 2. FormationUsage row — authorised by the matching FormationInvite, and
         //    carrying the strand's stamp so it authorizes THIS row and no other.
         await this.execFormationUsageInsert({
-          token, useNumber: attemptUseNumber, usageStampId, disclosure, strandId, strandStampId,
+          token, usageStampId, disclosure, strandId, strandStampId,
           peerKey, peerSignature, nowMs: nowMs ?? Date.now(),
           validationKey: validationKey ?? null, validationSignature: validationSignature ?? null,
         });
-      }));
+      });
+    }, {}, 'formation-usage');
 
-    log('Redeemed invitation %s -> strand %s (use #%d)', token, strandId, useNumber);
-    return { useNumber, usageStampId };
+    log('Redeemed invitation %s -> strand %s (stamp %s)', token, strandId, usageStampId);
+    return { usageStampId };
   }
 
   /**
@@ -2131,8 +2261,8 @@ export 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.
@@ -2146,12 +2276,12 @@ export 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.
    */
   async recordFormationUsage(params: {
     token: string;
@@ -2167,17 +2297,16 @@ export 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> {
@@ -2188,109 +2317,40 @@ export class ControlDatabase {
       totalUses,
     } = params;
 
-    // Read ONCE, outside the loop: the host strand is pre-existing and owner-signed, and a
-    // retry changes which use number we take, never which strand row we name.
+    // The host strand is pre-existing and owner-signed; its stamp names the strand ROW the
+    // consent record authorizes.
     const strandStampId = await this.queryStrandStampId(strandId);
     if (strandStampId === null) {
       throw new MissingHostStrandError(strandId, token);
     }
 
-    const useNumber = await this.withUseNumberRetry(token, 'usage recording', signal, totalUses, attemptUseNumber =>
-      this.execFormationUsageInsert({
-        token, useNumber: attemptUseNumber, usageStampId, disclosure, strandId, strandStampId,
+    // Ordering inside the locked body is contractual — abort check, seat check, write — see
+    // the matching note in redeemInvitation.
+    await this.lockedWithRetry(async () => {
+      if (signal?.aborted) {
+        throw new FormationAbortedError(token, 'usage recording');
+      }
+      await this.assertSeatRemains(token, totalUses);
+      await this.execFormationUsageInsert({
+        token, usageStampId, disclosure, strandId, strandStampId,
         peerKey, peerSignature, nowMs: nowMs ?? Date.now(),
         validationKey: validationKey ?? null, validationSignature: validationSignature ?? null,
-      }));
+      });
+    }, {}, 'formation-usage');
 
-    log('Recorded formation usage: token=%s strand=%s (use #%d)', token, strandId, useNumber);
-    return { useNumber, usageStampId };
+    log('Recorded formation usage: token=%s strand=%s (stamp %s)', token, strandId, usageStampId);
+    return { usageStampId };
   }
 
   /**
-   * 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 async withUseNumberRetry(
-    token: string,
-    operation: string,
-    signal: AbortSignal | undefined,
-    knownTotalUses: number | null | undefined,
-    write: (useNumber: number) => Promise<void>,
-  ): Promise<number> {
-    let lastError: unknown;
-    for (let attempt = 1; attempt <= USE_NUMBER_ATTEMPTS; attempt++) {
-      try {
-        // lockedWithRetry carries the transient-cluster retry INSIDE this use-number
-        // retry. The loops cannot multiply: a lost use number is a constraint failure,
-        // which `isRetriableControlWriteFailure` never matches, and a transient cluster
-        // failure is not a lost use number, so exactly one loop claims any given error.
-        return await this.lockedWithRetry(async () => {
-          // Inside the lock: a write still parked behind another writer when the caller's
-          // budget expired is abandoned rather than executed.
-          if (signal?.aborted) {
-            throw new FormationAbortedError(token, operation);
-          }
-          const useNumber = await this.nextUseNumber(token);
-          await this.assertSeatRemains(token, useNumber, knownTotalUses);
-          await write(useNumber);
-          return useNumber;
-        });
-      } catch (error) {
-        if (!isLostUseNumberRace(error)) {
-          throw error;
-        }
-        lastError = error;
-        log('Use number for token %s was taken by another writer (attempt %d/%d): %s',
-          token, attempt, USE_NUMBER_ATTEMPTS, error);
-      }
-    }
-    // Out of attempts under sustained contention. Rethrowing the engine's own error keeps
-    // today's behaviour: `StrandFormationManager.provisionAsResponder`'s catch-all maps it to
-    // `Formation conflict, retry` and the joiner starts over with a fresh nonce.
-    throw lastError;
-  }
-
-  /**
-   * 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,
@@ -2300,11 +2360,10 @@ export 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 async assertSeatRemains(
     token: string,
-    useNumber: number,
     knownTotalUses: number | null | undefined,
   ): Promise<void> {
     // A missing invite is left to `Authorized` — it is not an exhaustion, and the CHECK's
@@ -2314,19 +2373,26 @@ export class ControlDatabase {
     // is still open (tracked by `debt-composite-pk-point-lookup-unreliable-untracked`). A
     // spurious empty result only costs the attempt its NAMED exhaustion error, reverting it to
     // today's generic `Authorized` refusal — never a seat the invite does not have.
+    // Both reads pass retry: false — assertSeatRemains only ever runs inside the locked
+    // write bodies of redeemInvitation / recordFormationUsage, where a read retrying its
+    // own backoff would sleep holding the write lock and the write funnel re-runs these
+    // reads anyway (see the NOTE on readRows).
     const totalUses = knownTotalUses !== undefined
       ? knownTotalUses
-      : (await this.queryFormationInvite(token))?.totalUses ?? null;
-    if (totalUses != null && useNumber > totalUses) {
-      throw new InvitationExhaustedError(token, useNumber, totalUses);
+      : (await this.queryFormationInvite(token, false))?.totalUses ?? null;
+    if (totalUses == null) {
+      return;
+    }
+    const used = await this.countFormationUsage(token, false);
+    if (used >= totalUses) {
+      throw new InvitationExhaustedError(token, used, totalUses);
     }
   }
 
   /** Parameterised `FormationUsage` insert shared by redeem + record paths. */
   private async execFormationUsageInsert(opts: {
     token: string;
-    useNumber: number;
-    /** Single-use nonce bound into the approver's signed digest; `unique`, so one approval spends once. */
+    /** Single-use nonce bound into the approver's signed digest; the row's primary key, so one approval spends once. */
     usageStampId: string;
     disclosure: string;
     strandId: string;
@@ -2348,12 +2414,12 @@ export class ControlDatabase {
     // not a fix for an observable mis-ordering.
     const nowCanonical = await canonicalDatetime(this.db!, opts.nowMs);
     await this.db!.exec(`
-      insert into CadreControl.FormationUsage (Token, UseNumber, UsageStampId, PeerKey, PeerSig, Disclosure, StrandId, StrandStampId)
+      insert into CadreControl.FormationUsage (Token, UsageStampId, PeerKey, PeerSig, Disclosure, StrandId, StrandStampId)
         with context Now = ?, ValidationKey = ?, ValidationSignature = ?
-        values (?, ?, ?, ?, ?, ?, ?, ?)
+        values (?, ?, ?, ?, ?, ?, ?)
     `, [
       nowCanonical, opts.validationKey, opts.validationSignature,
-      opts.token, opts.useNumber, opts.usageStampId, opts.peerKey,
+      opts.token, opts.usageStampId, opts.peerKey,
       opts.peerSignature, opts.disclosure, opts.strandId, opts.strandStampId,
     ]);
   }
@@ -2362,8 +2428,12 @@ export 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.
    */
-  async queryFormationInvite(token: string): Promise<{
+  async queryFormationInvite(token: string, retry = true): Promise<{
     token: string;
     sAppId: string;
     expiresAtMs: number | null;
@@ -2372,10 +2442,8 @@ export class ControlDatabase {
     strandId: string | null;
   } | null> {
     this.ensureInitialized();
-    for await (const row of this.db!.eval(
-      'select Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId from CadreControl.FormationInvite where Token = ?',
-      [token]
-    )) {
+    const sql = 'select Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId from CadreControl.FormationInvite where Token = ?';
+    for (const row of await this.readRows(sql, [token], 'formation-invite', retry)) {
       return {
         token: row.Token as string,
         sAppId: row.sAppId as string,
@@ -2390,13 +2458,32 @@ export class ControlDatabase {
 
   /**
    * 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.
    */
-  async countFormationUsage(token: string): Promise<number> {
+  async countFormationUsage(token: string, retry = true): Promise<number> {
     this.ensureInitialized();
-    for await (const row of this.db!.eval(
-      'select count(1) as Count from CadreControl.FormationUsage where Token = ?',
-      [token]
-    )) {
+    const sql = 'select count(1) as Count from CadreControl.FormationUsage where Token = ?';
+    for (const row of await this.readRows(sql, [token], 'formation-usage-count', retry)) {
       return (row.Count as number) ?? 0;
     }
     return 0;
@@ -2428,8 +2515,10 @@ export class ControlDatabase {
     // prune redeemed/expired rows.
     const metered: Array<{ token: string; totalUses: number }> = [];
     let unlimitedOutstanding = false;
-    for await (const row of this.db!.eval(
-      'select Token, ExpiresAt, TotalUses from CadreControl.FormationInvite'
+    for (const row of await this.readRows(
+      'select Token, ExpiresAt, TotalUses from CadreControl.FormationInvite',
+      undefined,
+      'outstanding-invites'
     )) {
       const expiresAtMs = parseNullableStoredDatetimeMs(row.ExpiresAt as string | number | null);
       if (expiresAtMs !== null && expiresAtMs <= nowMs) {
@@ -2445,6 +2534,12 @@ export class ControlDatabase {
     if (unlimitedOutstanding) {
       return true;
     }
+    // NOTE: this loop issues one retried read per metered invite, each carrying its own
+    // CONTROL_READ_RETRY_BUDGET_MS, on a path the inbound admission gate awaits under a
+    // 2 s FAIL-OPEN deadline — so with N unexpired metered invites the worst case is
+    // (1 + N) budgets, not one. Fine while a cadre holds a couple of live invites and
+    // transient read failures are rare; if a party ever keeps many metered invites open,
+    // give this whole method one shared deadline rather than raising the per-read budget.
     for (const invite of metered) {
       if (await this.countFormationUsage(invite.token) < invite.totalUses) {
         return true;
@@ -2453,23 +2548,6 @@ export class ControlDatabase {
     return false;
   }
 
-  /**
-   * 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 async nextUseNumber(token: string): Promise<number> {
-    for await (const row of this.db!.eval(
-      'select coalesce(max(UseNumber), 0) as MaxUse from CadreControl.FormationUsage where Token = ?',
-      [token]
-    )) {
-      return (row.MaxUse as number) + 1;
-    }
-    return 1;
-  }
-
   /**
    * Close the database and cleanup resources.
    *