@serfab/cadre-core 0.10.0 → 0.11.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';
@@ -73,94 +73,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.
  *
@@ -377,6 +313,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,7 +393,7 @@ 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');
     }
     /**
@@ -564,6 +514,14 @@ 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.
      */
     async queryCadrePeers() {
         this.ensureInitialized();
@@ -757,12 +715,12 @@ export class ControlDatabase {
     async updateSelfPeerRecord(record) {
         this.ensureInitialized();
         const multiaddr = record.addrs.join(',');
-        await this.execWrite(`
-      update CadreControl.CadrePeer
-        with context OwnerKey = null, Signature = ?
-        set Multiaddr = ?, UpdatedAt = ?, Sig = ?
-        where PeerId = ?
-    `, [record.sig, multiaddr, record.updatedAt, record.sig, record.peerId]);
+        await this.execWrite(`
+      update CadreControl.CadrePeer
+        with context OwnerKey = null, Signature = ?
+        set Multiaddr = ?, UpdatedAt = ?, Sig = ?
+        where 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);
     }
     /**
@@ -805,12 +763,12 @@ export class ControlDatabase {
      */
     async updateSelfDeviceToken(record) {
         this.ensureInitialized();
-        await this.execWrite(`
-      update CadreControl.DeviceToken
-        with context OwnerKey = null, Signature = ?
-        set Platform = ?, Token = ?, UpdatedAt = ?, Sig = ?
-        where PeerId = ?
-    `, [record.sig, record.platform, record.token, record.updatedAt, record.sig, record.peerId]);
+        await this.execWrite(`
+      update CadreControl.DeviceToken
+        with context OwnerKey = null, Signature = ?
+        set Platform = ?, Token = ?, UpdatedAt = ?, Sig = ?
+        where 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);
     }
     /**
@@ -828,11 +786,11 @@ export class ControlDatabase {
         // StampId in the row's own column to satisfy the not-null/unique anti-replay constraint —
         // the StampId is a real column value, not the optimystic `StampId()` SQL function.
         const stampId = generateStampId(this.config.libp2pNode.peerId.toString());
-        await this.execWrite(`
-      insert into CadreControl.OwnerKey (Key, StampId)
-        with context OwnerKey = null, Signature = null
-        values (?, ?)
-    `, [key, stampId]);
+        await this.execWrite(`
+      insert into CadreControl.OwnerKey (Key, StampId)
+        with context OwnerKey = null, Signature = null
+        values (?, ?)
+    `, [key, stampId], 'owner-key-insert');
         log('Owner key inserted');
     }
     /**
@@ -861,11 +819,11 @@ export class ControlDatabase {
         const message = buildAuthorizationMessage('CadreControl.Strand', 'add', [strandId, type, memberPrivateKey ?? '', stampId]);
         const signature = signMessage(message);
         // StampId is a real, unique column (single-use anti-replay), no longer a context value.
-        await this.execWrite(`
-      insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
-        with context OwnerKey = ?, Signature = ?
-        values (?, ?, ?, ?)
-    `, [ownerKey, signature, strandId, type, memberPrivateKey ?? null, stampId]);
+        await this.execWrite(`
+      insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
+        with context OwnerKey = ?, Signature = ?
+        values (?, ?, ?, ?)
+    `, [ownerKey, signature, strandId, type, memberPrivateKey ?? null, stampId], 'strand-insert');
         log('Strand inserted: %s', strandId);
     }
     /**
@@ -887,7 +845,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.
@@ -910,11 +868,11 @@ export class ControlDatabase {
         // Field order MUST match the schema's ValidationKey `AuthorizedInsert` verify: Key, StampId.
         const message = buildAuthorizationMessage('CadreControl.ValidationKey', 'add', [key, stampId]);
         const signature = signMessage(message);
-        await this.execWrite(`
-      insert into CadreControl.ValidationKey (Key, StampId)
-        with context OwnerKey = ?, Signature = ?
-        values (?, ?)
-    `, [ownerKey, signature, key, stampId]);
+        await this.execWrite(`
+      insert into CadreControl.ValidationKey (Key, StampId)
+        with context OwnerKey = ?, Signature = ?
+        values (?, ?)
+    `, [ownerKey, signature, key, stampId], 'validation-key-insert');
         log('Validation key inserted: %s', key);
     }
     /**
@@ -934,7 +892,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
@@ -990,10 +948,10 @@ export class ControlDatabase {
             // Persist the vouching (owner, signature) onto the row (VouchOwner/VouchSig) —
             // identical to the context pair, which the AuthorizedInsert constraint binds — so a
             // reader can later re-check the voucher against its node-local trusted-owner anchor.
-            await this.db.exec(`
-        insert into CadreControl.CadrePeer (PeerId, PublicKey, Multiaddr, UpdatedAt, Sig, StampId, VouchOwner, VouchSig)
-          with context OwnerKey = ?, Signature = ?
-          values (?, ?, ?, ?, ?, ?, ?, ?)
+            await this.db.exec(`
+        insert into CadreControl.CadrePeer (PeerId, PublicKey, Multiaddr, UpdatedAt, Sig, StampId, VouchOwner, VouchSig)
+          with context OwnerKey = ?, Signature = ?
+          values (?, ?, ?, ?, ?, ?, ?, ?)
       `, [ownerKey, signature, row.peerId, row.publicKey, row.multiaddr, row.updatedAt, row.sig, stampId, ownerKey, signature]);
             return true;
         });
@@ -1056,11 +1014,11 @@ export class ControlDatabase {
         const signature = signMessage(buildAuthorizationMessage('CadreControl.CadrePeer', 'vouch', [peerId, stampId]));
         await this.mutateCadrePeer('peer-reauthorize', async () => {
             // Bare `exec` — inside the non-re-entrant write lock (see insertCadrePeer).
-            await this.db.exec(`
-        update CadreControl.CadrePeer
-          with context OwnerKey = ?, Signature = ?
-          set UpdatedAt = ?, VouchOwner = ?, VouchSig = ?
-          where PeerId = ?
+            await this.db.exec(`
+        update CadreControl.CadrePeer
+          with context OwnerKey = ?, Signature = ?
+          set UpdatedAt = ?, VouchOwner = ?, VouchSig = ?
+          where PeerId = ?
       `, [ownerKey, signature, updatedAt, ownerKey, signature, peerId]);
         });
         return true;
@@ -1102,7 +1060,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
@@ -1151,18 +1109,18 @@ export class ControlDatabase {
         // cover it — the digests are domain-separated and neither replays as the other.
         const revocationSignature = signMessage(buildAuthorizationMessage('CadreControl.Revocation', 'remove', [table, keyValue, stampId]));
         await this.inTransaction(`delete ${table}`, async () => {
-            await this.db.exec(`
-        delete from CadreControl.${table}
-          with context OwnerKey = ?, Signature = ?
-          where ${GUARDED_KEY_COLUMN[table]} = ?
+            await this.db.exec(`
+        delete from CadreControl.${table}
+          with context OwnerKey = ?, Signature = ?
+          where ${GUARDED_KEY_COLUMN[table]} = ?
       `, [ownerKey, signature, keyValue]);
             // ReissuedAt named explicitly at 0 (the only value FreshTombstone accepts) rather
             // than leaning on the column default — the seat-at-zero rule is load-bearing for
             // reissueRevocations' monotonic bump, so state it at the write site.
-            await this.db.exec(`
-        insert into CadreControl.Revocation (TableName, RowKey, StampId, ReissuedAt)
-          with context OwnerKey = ?, Signature = ?
-          values (?, ?, ?, 0)
+            await this.db.exec(`
+        insert into CadreControl.Revocation (TableName, RowKey, StampId, ReissuedAt)
+          with context OwnerKey = ?, Signature = ?
+          values (?, ?, ?, 0)
       `, [ownerKey, revocationSignature, table, keyValue, stampId]);
         });
         log('%s deleted: %s (stamp retired)', table, keyValue);
@@ -1239,10 +1197,10 @@ export class ControlDatabase {
             log('reap %s: %s holds a fresh incarnation (live stamp differs from the tombstoned one); leaving it', table, rowKey);
             return false;
         }
-        const sql = `
-      delete from CadreControl.${table}
-        with context OwnerKey = null, Signature = null
-        where ${GUARDED_KEY_COLUMN[table]} = ? and StampId = ?
+        const sql = `
+      delete from CadreControl.${table}
+        with context OwnerKey = null, Signature = null
+        where ${GUARDED_KEY_COLUMN[table]} = ? and StampId = ?
     `;
         if (table === 'CadrePeer') {
             // Through mutateCadrePeer so the "EVERY CadrePeer writer goes through here"
@@ -1259,7 +1217,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.
@@ -1400,18 +1358,18 @@ export class ControlDatabase {
                     // output minted per row incarnation (generateStampId), so it identifies one
                     // row across all TableName values. Do NOT "fix" this by adding TableName to
                     // the where clause.
-                    await this.db.exec(`
-            update CadreControl.Revocation
-              with context OwnerKey = ?, Signature = ?
-              set ReissuedAt = ?
-              where StampId = ?
+                    await this.db.exec(`
+            update CadreControl.Revocation
+              with context OwnerKey = ?, Signature = ?
+              set ReissuedAt = ?
+              where StampId = ?
           `, [ownerKey, signature, reissuedAt, row.stampId]);
                     executed++;
                 }
             });
             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 +1472,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
@@ -1569,10 +1527,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 +1537,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 +1557,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
@@ -1711,10 +1677,10 @@ export class ControlDatabase {
         // Persist the canonical ExpiresAt string (datetime parse is idempotent on it) so the
         // signed source-of-truth and the stored value are produced once. StampId is a real,
         // unique column (single-use anti-replay), no longer a context value.
-        await this.execWrite(`
-      insert into CadreControl.FormationInvite (Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId)
-        with context OwnerKey = ?, Signature = ?
-        values (?, ?, ?, ?, ?, ?, ?)
+        await this.execWrite(`
+      insert into CadreControl.FormationInvite (Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId)
+        with context OwnerKey = ?, Signature = ?
+        values (?, ?, ?, ?, ?, ?, ?)
     `, [
             ownerKey, signature,
             token, sAppId,
@@ -1723,7 +1689,7 @@ export class ControlDatabase {
             options.validationUrl ?? null,
             options.strandId ?? null,
             stampId,
-        ]);
+        ], 'formation-invite-insert');
         log('Formation invite inserted: %s', token);
     }
     /**
@@ -1751,50 +1717,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(`
-          insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
-            with context OwnerKey = null, Signature = null
-            values (?, 'o', null, ?)
+        // 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 +1784,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;
-                });
-            }
-            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);
+        // 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');
             }
-        }
-        // 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 +1834,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
@@ -1932,8 +1847,12 @@ export class ControlDatabase {
         const totalUses = knownTotalUses !== undefined
             ? knownTotalUses
             : (await this.queryFormationInvite(token))?.totalUses ?? null;
-        if (totalUses != null && useNumber > totalUses) {
-            throw new InvitationExhaustedError(token, useNumber, totalUses);
+        if (totalUses == null) {
+            return;
+        }
+        const used = await this.countFormationUsage(token);
+        if (used >= totalUses) {
+            throw new InvitationExhaustedError(token, used, totalUses);
         }
     }
     /** Parameterised `FormationUsage` insert shared by redeem + record paths. */
@@ -1947,13 +1866,13 @@ export class ControlDatabase {
         // robustness/consistency change, matching the strand layer's `consumeInvite`,
         // 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)
-        with context Now = ?, ValidationKey = ?, ValidationSignature = ?
-        values (?, ?, ?, ?, ?, ?, ?, ?)
+        await this.db.exec(`
+      insert into CadreControl.FormationUsage (Token, UsageStampId, PeerKey, PeerSig, Disclosure, StrandId, StrandStampId)
+        with context Now = ?, ValidationKey = ?, ValidationSignature = ?
+        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,
         ]);
     }
@@ -1978,6 +1897,22 @@ export class ControlDatabase {
     }
     /**
      * Count `FormationUsage` rows recorded against a token (uses consumed so far).
+     *
+     * NOTE: `Token` left the primary key in `formation-unique-token-redesign` and gained the
+     * `FormationUsageByToken` secondary index, so this filter is now served by an index SEEK
+     * (a descent through the index collection) where it used to be a leading-key partial match
+     * the optimystic vtab declined and the engine served by scan. That matters because the seat
+     * cap is this count: a descent that under-reports admits a seat the invite does not have,
+     * where a scan could not. Descent misses have been observed on a NETWORKED store (tracked
+     * by `debt-composite-pk-point-lookup-unreliable-untracked`, for full-primary-key lookups);
+     * no miss has been observed on this index on a SINGLE node. Across nodes the index is
+     * currently blind: a sibling never learns index entries for rows written elsewhere (the
+     * distributed commit drops the index update — measured 2026-08-12, tracked by
+     * `blocked/secondary-index-seek-blind-to-sibling-rows`), so on a multi-machine party this
+     * count under-reports and the cap over-admits until the upstream fix lands. If
+     * over-admission ever shows up on a converged single node — a token with more usage rows
+     * than its `TotalUses` and no concurrent redeemers to explain it — suspect this seek first
+     * and drop the index to fall back to the scan.
      */
     async countFormationUsage(token) {
         this.ensureInitialized();
@@ -2035,19 +1970,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.
      *