@serfab/cadre-core 0.11.0 → 0.12.0

package/dist/control-database.js

@@ -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');
 /**
@@ -248,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;
     }
     /**
@@ -396,13 +404,126 @@ export class ControlDatabase {
         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,
@@ -419,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,
@@ -444,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;
@@ -462,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;
@@ -493,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;
@@ -522,12 +643,21 @@ export class ControlDatabase {
      * 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;
@@ -554,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();
@@ -573,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;
@@ -622,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;
@@ -642,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,
@@ -663,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
@@ -673,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;
@@ -715,18 +858,18 @@ 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 = ?
+        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);
     }
     /**
      * 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
@@ -738,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 ?? ''),
@@ -763,11 +906,11 @@ 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 = ?
+        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);
     }
@@ -786,10 +929,10 @@ 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 (?, ?)
+        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');
     }
@@ -819,10 +962,10 @@ 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 (?, ?, ?, ?)
+        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);
     }
@@ -868,10 +1011,10 @@ 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 (?, ?)
+        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);
     }
@@ -938,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;
             }
@@ -948,10 +1092,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;
         });
@@ -1014,11 +1158,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;
@@ -1097,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;
@@ -1109,18 +1254,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);
@@ -1197,10 +1342,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"
@@ -1358,11 +1503,11 @@ 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++;
                 }
@@ -1484,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
@@ -1632,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,
@@ -1677,10 +1824,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,
@@ -1747,10 +1894,10 @@ export class ControlDatabase {
                 // 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, ?)
+                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.
@@ -1844,13 +1991,17 @@ 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;
+            : (await this.queryFormationInvite(token, false))?.totalUses ?? null;
         if (totalUses == null) {
             return;
         }
-        const used = await this.countFormationUsage(token);
+        const used = await this.countFormationUsage(token, false);
         if (used >= totalUses) {
             throw new InvitationExhaustedError(token, used, totalUses);
         }
@@ -1866,10 +2017,10 @@ 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, 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.usageStampId, opts.peerKey,
@@ -1880,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,
@@ -1898,25 +2054,31 @@ 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.
+     * 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;
@@ -1947,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;
@@ -1963,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;