@serfab/cadre-core 0.10.0 → 0.12.0

package/dist/control-database.js

@@ -1,6 +1,6 @@
 import debug from 'debug';
 import { toString as uint8ArrayToString } from 'uint8arrays';
-import { Database, registerPlugin, unwrapError } from '@quereus/quereus';
+import { Database, registerPlugin } 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';
@@ -9,6 +9,7 @@ import { canonicalDatetime } from './canonical-datetime.js';
 import { controlAuthorizationFields, CONTROL_TABLES } from './control-authorization.js';
 import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
 import { retryControlWrite, SCHEMA_INIT_RETRY_POLICY } from './control-write-retry.js';
+import { retryControlRead } from './control-read-retry.js';
 const log = debug('sereus:cadre:control-db');
 const timing = debug('sereus:cadre:timing');
 /**
@@ -73,94 +74,30 @@ 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(token, useNumber, totalUses) {
-        super(`Invitation ${token} is exhausted: use #${useNumber} is past its limit of ${totalUses} use(s)`);
+    constructor(token, usesRecorded, totalUses) {
+        super(`Invitation ${token} is exhausted: ${usesRecorded} of ${totalUses} use(s) already recorded`);
         this.token = token;
-        this.useNumber = useNumber;
+        this.usesRecorded = usesRecorded;
         this.totalUses = totalUses;
         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) {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    return unwrapError(error).some(({ message }) => LOST_USE_NUMBER_PATTERNS.some(pattern => pattern.test(message)));
-}
 /**
  * Parse a stored Quereus `datetime` value into epoch milliseconds.
  *
@@ -312,6 +249,13 @@ export class ControlDatabase {
          * having to restate the policy's attempts or classifier.
          */
         this.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`.
+         */
+        this.controlReadRetryPacing = {};
         this.config = config;
     }
     /**
@@ -377,6 +321,20 @@ export class ControlDatabase {
         timing('[controlDb] hydrate: %dms (tables=%d, indexes=%d)', Math.round(performance.now() - t0), hydrated.tables, hydrated.indexes);
         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));
@@ -443,16 +401,129 @@ 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.
+     */
+    async readRowsOnce(sql, params) {
+        let iterator;
+        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 = [];
+        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.
+     */
+    readRows(sql, params, label, retry = true) {
+        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() {
         this.ensureInitialized();
         const results = [];
-        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,
                 MemberPrivateKey: row.MemberPrivateKey,
@@ -469,7 +540,7 @@ export class ControlDatabase {
      */
     async queryStrand(strandId) {
         this.ensureInitialized();
-        for await (const row of this.db.eval('select Id, MemberPrivateKey, Type from CadreControl.Strand where Id = ?', [strandId])) {
+        for (const row of await this.readRows('select Id, MemberPrivateKey, Type from CadreControl.Strand where Id = ?', [strandId], 'strand')) {
             return {
                 Id: row.Id,
                 MemberPrivateKey: row.MemberPrivateKey,
@@ -494,7 +565,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 ?? 0;
         }
         return 0;
@@ -512,7 +583,7 @@ export class ControlDatabase {
      */
     async hasOwnerKey() {
         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 > 0;
         }
         return false;
@@ -543,7 +614,7 @@ export class ControlDatabase {
     async getOwnerKeys() {
         this.ensureInitialized();
         const keys = new Set();
-        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);
         }
         return keys;
@@ -564,12 +635,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() {
+    async queryCadrePeers(retry = true) {
         this.ensureInitialized();
-        const revoked = await this.queryRevokedStamps('CadrePeer');
+        const revoked = await this.queryRevokedStamps('CadrePeer', retry);
         const rows = [];
-        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 ?? null;
             if (stampId !== null && revoked.has(stampId)) {
                 continue;
@@ -596,7 +684,7 @@ export class ControlDatabase {
     async queryValidationKeys() {
         this.ensureInitialized();
         const keys = [];
-        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);
         }
         return keys.sort();
@@ -615,11 +703,21 @@ 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.
      */
-    async queryStampId(table, keyValue) {
+    async queryStampId(table, keyValue, retry = true) {
         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 ?? null;
         }
         return null;
@@ -664,11 +762,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) {
+    async queryRevokedStamps(tableName, retry = true) {
         this.ensureInitialized();
         const stamps = new Set();
-        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);
         }
         return stamps;
@@ -684,7 +785,7 @@ export class ControlDatabase {
     async queryRevocations() {
         this.ensureInitialized();
         const rows = [];
-        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,
                 rowKey: row.RowKey,
@@ -705,7 +806,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
@@ -715,7 +816,7 @@ export class ControlDatabase {
     async queryPeerRecord(peerId) {
         this.ensureInitialized();
         const revoked = await this.queryRevokedStamps('CadrePeer');
-        for await (const row of this.db.eval('select PeerId, PublicKey, Multiaddr, UpdatedAt, Sig, StampId from CadreControl.CadrePeer where PeerId = ?', [peerId])) {
+        for (const row of await this.readRows('select PeerId, PublicKey, Multiaddr, UpdatedAt, Sig, StampId from CadreControl.CadrePeer where PeerId = ?', [peerId], 'peer-record')) {
             const stampId = row.StampId ?? null;
             if (stampId !== null && revoked.has(stampId)) {
                 return null;
@@ -762,13 +863,13 @@ 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
@@ -780,7 +881,7 @@ export class ControlDatabase {
      */
     async queryDeviceToken(peerId) {
         this.ensureInitialized();
-        for await (const row of this.db.eval('select PeerId, Platform, Token, UpdatedAt, Sig, StampId from CadreControl.DeviceToken where PeerId = ?', [peerId])) {
+        for (const row of await this.readRows('select PeerId, Platform, Token, UpdatedAt, Sig, StampId from CadreControl.DeviceToken where PeerId = ?', [peerId], 'device-token')) {
             return {
                 peerId: row.PeerId,
                 platform: (row.Platform ?? ''),
@@ -810,7 +911,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);
     }
     /**
@@ -832,7 +933,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');
     }
     /**
@@ -865,7 +966,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);
     }
     /**
@@ -887,7 +988,7 @@ export class ControlDatabase {
      * when a row was actually removed.
      */
     deleteStrand(strandId, ownerKey, signMessage) {
-        return this.lockedWithRetry(() => this.deleteGuardedRow('Strand', strandId, ownerKey, signMessage));
+        return this.lockedWithRetry(() => this.deleteGuardedRow('Strand', strandId, ownerKey, signMessage), {}, 'strand-delete');
     }
     /**
      * Insert a validation key into the control database using an owner signature.
@@ -914,7 +1015,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);
     }
     /**
@@ -934,7 +1035,7 @@ export class ControlDatabase {
      * when a row was actually removed.
      */
     deleteValidationKey(key, ownerKey, signMessage) {
-        return this.lockedWithRetry(() => this.deleteGuardedRow('ValidationKey', key, ownerKey, signMessage));
+        return this.lockedWithRetry(() => this.deleteGuardedRow('ValidationKey', key, ownerKey, signMessage), {}, 'validation-key-delete');
     }
     /**
      * Owner-vouched INSERT of one `CadrePeer` membership row, notifying the membership
@@ -980,7 +1081,8 @@ export class ControlDatabase {
         const stampId = generateStampId(row.peerId);
         const signature = signMessage(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;
             }
@@ -1102,7 +1204,7 @@ export class ControlDatabase {
      * when a row was actually removed.
      */
     deleteDeviceToken(peerId, ownerKey, signMessage) {
-        return this.lockedWithRetry(() => this.deleteGuardedRow('DeviceToken', peerId, ownerKey, signMessage));
+        return this.lockedWithRetry(() => this.deleteGuardedRow('DeviceToken', peerId, ownerKey, signMessage), {}, 'device-token-delete');
     }
     /**
      * Owner-signed delete of one guarded row plus the `Revocation` tombstone retiring its
@@ -1139,7 +1241,8 @@ export class ControlDatabase {
      */
     async deleteGuardedRow(table, keyValue, ownerKey, signMessage) {
         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;
@@ -1259,7 +1362,7 @@ export class ControlDatabase {
             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.
@@ -1411,7 +1514,7 @@ export class ControlDatabase {
             });
             log('Reissued %d revocation tombstone(s) at %d', executed, reissuedAt);
             return executed;
-        });
+        }, {}, 'revocation-reissue');
     }
     /**
      * Run `body` between `beginTransaction` and `commit`, rolling back on failure.
@@ -1514,7 +1617,7 @@ export class ControlDatabase {
             this.assertCommitBoundary(reason, 'on return from');
             await this.notifyMembershipChanged(reason);
             return result;
-        });
+        }, {}, reason);
     }
     /**
      * Run one local write under the database-wide write lock, serializing it against
@@ -1526,7 +1629,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
@@ -1569,10 +1673,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
@@ -1581,9 +1683,16 @@ 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.
      */
-    lockedWithRetry(fn, policy = {}) {
-        return retryControlWrite(() => this.withWriteLock(fn), { ...policy, ...this.controlWriteRetryPacing });
+    lockedWithRetry(fn, policy = {}, label) {
+        // 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, ...(label !== undefined ? { label } : {}) });
     }
     /**
      * One-statement local write, serialized by {@link withWriteLock} and retried on a
@@ -1594,10 +1703,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, params) {
+    execWrite(sql, params, label) {
         this.ensureInitialized();
-        return this.lockedWithRetry(() => this.db.exec(sql, params));
+        return this.lockedWithRetry(() => this.db.exec(sql, params), {}, label);
     }
     /**
      * Throw unless the database sits at a committed boundary — `getAutocommit()` is false
@@ -1666,7 +1778,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,
@@ -1723,7 +1836,7 @@ export class ControlDatabase {
             options.validationUrl ?? null,
             options.strandId ?? null,
             stampId,
-        ]);
+        ], 'formation-invite-insert');
         log('Formation invite inserted: %s', token);
     }
     /**
@@ -1751,50 +1864,60 @@ 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) {
         this.ensureInitialized();
         const { token, strandId, disclosure = '', peerKey, peerSignature, usageStampId, nowMs, validationKey, validationSignature, signal, totalUses, } = params;
         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 () => {
-            // 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.
-            await this.db.exec(`
+        // 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.
+                await this.db.exec(`
           insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
             with context OwnerKey = null, Signature = null
             values (?, 'o', null, ?)
         `, [strandId, strandStampId]);
-            // 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,
-                peerKey, peerSignature, nowMs: nowMs ?? Date.now(),
-                validationKey: validationKey ?? null, validationSignature: validationSignature ?? null,
+                // 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, usageStampId, disclosure, strandId, strandStampId,
+                    peerKey, peerSignature, nowMs: nowMs ?? Date.now(),
+                    validationKey: validationKey ?? null, validationSignature: validationSignature ?? null,
+                });
             });
-        }));
-        log('Redeemed invitation %s -> strand %s (use #%d)', token, strandId, useNumber);
-        return { useNumber, usageStampId };
+        }, {}, 'formation-usage');
+        log('Redeemed invitation %s -> strand %s (stamp %s)', token, strandId, usageStampId);
+        return { usageStampId };
     }
     /**
      * Record a `FormationUsage` against an **already-existing** `Strand` (no strand
      * 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.
@@ -1808,108 +1931,47 @@ 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) {
         this.ensureInitialized();
         const { token, strandId, disclosure = '', peerKey, peerSignature, usageStampId, nowMs, validationKey, validationSignature, signal, 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,
-            peerKey, peerSignature, nowMs: nowMs ?? Date.now(),
-            validationKey: validationKey ?? null, validationSignature: validationSignature ?? null,
-        }));
-        log('Recorded formation usage: token=%s strand=%s (use #%d)', token, strandId, useNumber);
-        return { useNumber, 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.
-     */
-    async withUseNumberRetry(token, operation, signal, knownTotalUses, write) {
-        let lastError;
-        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;
-                });
+        // 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');
             }
-            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;
+            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 (stamp %s)', token, strandId, usageStampId);
+        return { usageStampId };
     }
     /**
-     * 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,
@@ -1919,9 +1981,9 @@ 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.
      */
-    async assertSeatRemains(token, useNumber, knownTotalUses) {
+    async assertSeatRemains(token, knownTotalUses) {
         // A missing invite is left to `Authorized` — it is not an exhaustion, and the CHECK's
         // rejection is already the right, non-retryable answer for it. That fallback is also what
         // makes this read's failure mode safe: it is a full-primary-key point lookup
@@ -1929,11 +1991,19 @@ 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. */
@@ -1948,12 +2018,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,
         ]);
     }
@@ -1961,10 +2031,15 @@ 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) {
+    async queryFormationInvite(token, retry = true) {
         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,
                 sAppId: row.sAppId,
@@ -1978,10 +2053,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) {
+    async countFormationUsage(token, retry = true) {
         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 ?? 0;
         }
         return 0;
@@ -2012,7 +2109,7 @@ export class ControlDatabase {
         // prune redeemed/expired rows.
         const metered = [];
         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);
             if (expiresAtMs !== null && expiresAtMs <= nowMs) {
                 continue;
@@ -2028,6 +2125,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;
@@ -2035,19 +2138,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.
-     */
-    async nextUseNumber(token) {
-        for await (const row of this.db.eval('select coalesce(max(UseNumber), 0) as MaxUse from CadreControl.FormationUsage where Token = ?', [token])) {
-            return row.MaxUse + 1;
-        }
-        return 1;
-    }
     /**
      * Close the database and cleanup resources.
      *