@serfab/cadre-core 0.9.0 → 0.11.0

package/src/control-database.ts

@@ -1,948 +1,2406 @@
-import debug from 'debug';
-import { toString as uint8ArrayToString } from 'uint8arrays';
-import { Database, registerPlugin } from '@quereus/quereus';
-import type { VTablePluginInfo, FunctionPluginInfo } 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';
-import type { Libp2p } from '@libp2p/interface';
-import type { IRepo } from '@optimystic/db-core';
-import type { StrandRow, PeerAddressRecord, DeviceTokenRecord, PushPlatform } from './types.js';
-import { CONTROL_SCHEMA } from './control-schema.js';
-import { canonicalDatetime } from './canonical-datetime.js';
-
-const log = debug('sereus:cadre:control-db');
-const timing = debug('sereus:cadre:timing');
-
-/**
- * Generate a unique stamp ID for transaction authorization.
- * Format: 32 bytes base64url encoded
- * - First 16 bytes: SHA-256 hash of peer ID (for distributed uniqueness)
- * - Last 16 bytes: Random bytes (for collision resistance)
- */
-export function generateStampId(peerId: string): string {
-  // Hash the peer ID and get first 16 bytes (128 bits). A purely local ID
-  // generator: never signed/verified against SQL, so the framed single-field
-  // digest is fine (the changed framing is not cross-checked anywhere).
-  const peerIdHash = digest([peerId], 'sha256', 'bytes') as Uint8Array;
-  const peerIdHashPart = peerIdHash.slice(0, 16);
-
-  // Generate 16 random bytes
-  const randomPart = randomBytes(128, 'bytes') as Uint8Array;
-
-  // Combine peer ID hash and random bytes
-  const combined = new Uint8Array(32);
-  combined.set(peerIdHashPart, 0);
-  combined.set(randomPart, 16);
-
-  // Convert to base64url
-  return uint8ArrayToString(combined, 'base64url');
-}
-
-/**
- * Parse a stored Quereus `datetime` value into epoch milliseconds.
- *
- * Quereus canonicalises a `datetime` column to a bare UTC `PlainDateTime` string
- * (e.g. `2026-06-04T12:34:56`, no `Z`). JS `Date` reads a timezone-less
- * date-time as LOCAL, so we append `Z` when no offset/zone is present to keep the
- * value anchored to UTC. Numbers (already epoch ms) pass through.
- */
-function parseStoredDatetimeMs(value: string | number): number {
-  if (typeof value === 'number') return value;
-  const hasZone = /[zZ]$|[+-]\d\d:?\d\d$/.test(value);
-  return new Date(hasZone ? value : `${value}Z`).getTime();
-}
-
-/**
- * Build the canonical authorization message that owner signatures are bound to.
- *
- * The message is a SINGLE framed SHA-256 digest over the ordered tuple of fields (the
- * crypto plugin's injective multi-field encoding), in a fixed field order, with the
- * single-use StampId as the final field:
- *
- *   message = sha256(encodeFields([field_1, field_2, ..., StampId]))   // raw digest bytes
- *
- * ed25519 signs these raw digest bytes DIRECTLY (no second hash). The SQL constraints
- * verify the identical bytes with one variadic call
- * (`verify(digest(field_1, ..., StampId), context.Signature, A.Key, 'ed25519')`): SQL
- * `digest(...)` returns the base64url string of the same digest, which `verify`'s default
- * base64url input encoding decodes back to those raw bytes — so signer and verifier
- * operate on the same bytes. Every field is TEXT on both sides (the SQL columns are
- * `cast(... as text)` / `coalesce(...,'')`; the TS args are strings), so the per-field
- * type tags agree. This binds the signature to the row contents (not a bare stamp),
- * closing the captured-stamp replay / privilege-escalation hole. Single source of truth:
- * every signed writer (and every test/harness signer) MUST build the message through this
- * function in the schema's field order, or `verify` will reject the row.
- */
-export function buildAuthorizationMessage(fields: string[]): Uint8Array {
-  return digest([...fields], 'sha256', 'bytes') as Uint8Array;
-}
-
-/**
- * Minimal interface for the CollectionFactory returned by the optimystic plugin.
- * We only need the methods we actually use.
- */
-interface CollectionFactory {
-  registerLibp2pNode(networkName: string, node: Libp2p, coordinatedRepo: IRepo): void;
-  shutdown(): Promise<void>;
-}
-
-/** Result of registering the optimystic plugin */
-interface OptimysticPluginResult {
-  collectionFactory: CollectionFactory;
-  vtables: VTablePluginInfo[];
-  functions: FunctionPluginInfo[];
-  /**
-   * Hydrate Quereus's in-memory catalog from persisted optimystic vtab schemas.
-   * Must run BEFORE applying CONTROL_SCHEMA on a warm restart so the declarative
-   * diff sees the existing tables and skips re-emitting CREATE TABLE / CREATE INDEX
-   * for each persisted control object. Idempotent; `{ tables: 0, indexes: 0 }` on a
-   * cold/in-memory start. Mirrors the strand path's hydrate-before-apply (see
-   * compose-strand.ts).
-   */
-  hydrate: (db: Database) => Promise<{ tables: number; indexes: number }>;
-  [key: string]: unknown;
-}
-
-/**
- * Names of the CadreControl tables that {@link ControlDatabase.countRows} can
- * read. Constraining to this union keeps the dynamic `from` clause off the
- * SQL-injection surface and hands callers (e.g. the integration harness's
- * `waitForControlSync`) a typo-proof table argument.
- */
-export type ControlTable =
-  | 'OwnerKey'
-  | 'ValidationKey'
-  | 'Strand'
-  | 'CadrePeer'
-  | 'DeviceToken'
-  | 'FormationInvite'
-  | 'FormationUsage';
-
-/** Runtime guard mirroring {@link ControlTable} for the dynamic-`from` count. */
-const CONTROL_TABLES: ReadonlySet<ControlTable> = new Set<ControlTable>([
-  'OwnerKey',
-  'ValidationKey',
-  'Strand',
-  'CadrePeer',
-  'DeviceToken',
-  'FormationInvite',
-  'FormationUsage',
-]);
-
-export interface ControlDatabaseConfig {
-  /** Party ID for the control network */
-  partyId: string;
-  /**
-   * Optional path to the control schema file.
-   * If not provided, uses the embedded schema for cross-platform compatibility.
-   * Only use this if you need to override the default schema (e.g., for testing).
-   */
-  schemaPath?: string;
-  /** Libp2p node for the control network (injected) */
-  libp2pNode: Libp2p;
-  /** Coordinated repo from the libp2p node */
-  coordinatedRepo: IRepo;
-}
-
-/**
- * ControlDatabase manages the CadreControl schema using Quereus with Optimystic backend.
- * It provides typed query methods for accessing control network data.
- */
-export class ControlDatabase {
-  private db: Database | null = null;
-  private collectionFactory: CollectionFactory | null = null;
-  private readonly config: ControlDatabaseConfig;
-  private initialized = false;
-
-  constructor(config: ControlDatabaseConfig) {
-    this.config = config;
-  }
-
-  /**
-   * Initialize the database - load schema and register plugins
-   */
-  async initialize(): Promise<void> {
-    if (this.initialized) {
-      log('ControlDatabase already initialized');
-      return;
-    }
-
-    log('Initializing ControlDatabase for party: %s', this.config.partyId);
-
-    // Create database instance
-    this.db = new Database();
-
-    // Register crypto plugin (provides digest, sign, verify functions)
-    let t0 = performance.now();
-    await registerPlugin(this.db, cryptoPlugin);
-    timing('[controlDb] cryptoPlugin: %dms', Math.round(performance.now() - t0));
-    log('Registered crypto plugin');
-
-    // Register optimystic plugin with network transactor as default
-    t0 = performance.now();
-    const networkName = `control-${this.config.partyId}`;
-    const pluginResult = optimysticPlugin(this.db, {
-      default_transactor: 'network',
-      default_key_network: 'libp2p',
-      default_network_name: networkName,
-      enable_cache: true,
-    }) as unknown as OptimysticPluginResult;
-
-    // Register vtables and functions manually since we need access to collectionFactory
-    for (const vtable of pluginResult.vtables) {
-      this.db.registerModule(vtable.name, vtable.module, vtable.auxData);
-    }
-    for (const func of pluginResult.functions) {
-      this.db.registerFunction(func.schema);
-    }
-    timing('[controlDb] optimysticPlugin: %dms', Math.round(performance.now() - t0));
-
-    this.collectionFactory = pluginResult.collectionFactory;
-
-    // Inject the libp2p node into the collection factory
-    t0 = performance.now();
-    this.collectionFactory.registerLibp2pNode(
-      networkName,
-      this.config.libp2pNode,
-      this.config.coordinatedRepo
-    );
-    timing('[controlDb] registerLibp2pNode: %dms', Math.round(performance.now() - t0));
-    log('Registered libp2p node with collection factory');
-
-    // Network-back the control tables. CONTROL_SCHEMA's `declare schema CadreControl
-    // { table ... }` tables carry NO per-table `using optimystic(...)`, so storage is
-    // chosen by the database's DEFAULT vtab. Routing the default to optimystic (with
-    // the network transactor + this party's control network) is what makes a control
-    // write replicate peer-to-peer — exactly what connectToStrand does for strand
-    // tables (compose-strand.ts). Without these two calls the tables fall back to
-    // Quereus's in-memory vtab and never converge across the cadre.
-    this.db.setDefaultVtabName('optimystic');
-    this.db.setDefaultVtabArgs({
-      networkName,
-      transactor: 'network',
-      keyNetwork: 'libp2p',
-    });
-    log('Set default vtab to optimystic (networkName=%s, transactor=network)', networkName);
-
-    // Hydrate Quereus's catalog from any persisted optimystic vtab schemas BEFORE
-    // applying CONTROL_SCHEMA, so a warm restart with persistent storage diffs the
-    // control DDL against the already-present tables and re-emits nothing — the same
-    // warm-start regression connectToStrand's hydrate-before-apply guards against.
-    // No-op on a cold / in-memory start (`{ tables: 0, indexes: 0 }`).
-    t0 = performance.now();
-    const hydrated = await pluginResult.hydrate(this.db);
-    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
-    t0 = performance.now();
-    await this.loadSchema();
-    timing('[controlDb] loadSchema: %dms', Math.round(performance.now() - t0));
-
-    this.initialized = true;
-    log('ControlDatabase initialized successfully');
-  }
-
-  private async loadSchema(): Promise<void> {
-    let schemaContent: string;
-
-    if (this.config.schemaPath) {
-      // Load from file if explicitly provided (for testing or custom schemas)
-      // This only works in Node.js environments
-      log('Loading schema from file: %s', this.config.schemaPath);
-
-      // Check if we're in a Node.js environment
-      if (typeof process !== 'undefined' && process.versions?.node) {
-        try {
-          // Use require to conditionally load fs only in Node.js.
-          // This won't be bundled by React Native's Metro bundler — a dynamic
-          // import() would be statically picked up by Metro, so require is
-          // intentional here (cross-platform constraint, not lazy CommonJS).
-          // eslint-disable-next-line @typescript-eslint/no-require-imports
-          const fs = require('fs/promises');
-          schemaContent = await fs.readFile(this.config.schemaPath, 'utf-8');
-        } catch (error) {
-          throw new Error(
-            `Failed to load schema from ${this.config.schemaPath}: ${error instanceof Error ? error.message : String(error)}`,
-            { cause: error }
-          );
-        }
-      } else {
-        throw new Error(
-          'Loading schema from file is not supported in React Native. ' +
-          'Remove the schemaPath option to use the embedded schema instead.'
-        );
-      }
-    } else {
-      // Use embedded schema for cross-platform compatibility
-      log('Using embedded control schema');
-      schemaContent = CONTROL_SCHEMA;
-    }
-
-    await this.db!.exec(schemaContent);
-    log('Schema loaded and executed');
-  }
-
-  /**
-   * Query all strands from the control database
-   */
-  async queryStrands(): Promise<StrandRow[]> {
-    this.ensureInitialized();
-    const results: StrandRow[] = [];
-    for await (const row of this.db!.eval('select Id, MemberPrivateKey, Type from CadreControl.Strand')) {
-      results.push({
-        Id: row.Id as string,
-        MemberPrivateKey: row.MemberPrivateKey as string | null,
-        Type: row.Type as 'o' | 'c',
-      });
-    }
-    return results;
-  }
-
-  /**
-   * Read a single strand row by id, or null when absent. Single-row sibling of
-   * {@link queryStrands}; the responder uses it to read a host strand's
-   * `MemberPrivateKey` (the closed-strand read-gating secret) for delivery to a
-   * validated invitee during provision-then-record formation.
-   */
-  async queryStrand(strandId: string): Promise<StrandRow | null> {
-    this.ensureInitialized();
-    for await (const row of this.db!.eval(
-      'select Id, MemberPrivateKey, Type from CadreControl.Strand where Id = ?',
-      [strandId]
-    )) {
-      return {
-        Id: row.Id as string,
-        MemberPrivateKey: row.MemberPrivateKey as string | null,
-        Type: row.Type as 'o' | 'c',
-      };
-    }
-    return null;
-  }
-
-  /**
-   * Count rows in a CadreControl table as seen by THIS database instance.
-   *
-   * `table` is validated against {@link CONTROL_TABLES} before it is interpolated
-   * into the `from` clause: the names are not user input, but the check keeps the
-   * dynamic query off the injection surface and fails loudly on a typo instead of
-   * emitting a malformed statement. The count reflects only the rows this node's
-   * control DB has converged on — in the integration harness that is the owner
-   * node (one ControlDatabase per party), i.e. the authoritative control-network
-   * view, not a per-drone convergence guarantee.
-   */
-  async countRows(table: ControlTable): Promise<number> {
-    this.ensureInitialized();
-    if (!CONTROL_TABLES.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}`)) {
-      return (row.Count as number) ?? 0;
-    }
-    return 0;
-  }
-
-  /**
-   * Get the underlying database for advanced queries
-   */
-  getDatabase(): Database {
-    this.ensureInitialized();
-    return this.db!;
-  }
-
-  /**
-   * Check whether any owner key exists in the control database.
-   * Used to decide whether a fresh-party genesis insert is required.
-   */
-  async hasOwnerKey(): Promise<boolean> {
-    this.ensureInitialized();
-    for await (const row of this.db!.eval('select count(1) as Count from CadreControl.OwnerKey')) {
-      return (row.Count as number) > 0;
-    }
-    return false;
-  }
-
-  /**
-   * Idempotent genesis: insert `key` as the founding owner key only when
-   * the party has none yet. Returns true if it inserted, false if an owner
-   * key already existed (so a repeat `--owner` start is a no-op).
-   */
-  async ensureOwnerKey(key: string): Promise<boolean> {
-    this.ensureInitialized();
-    if (await this.hasOwnerKey()) {
-      log('Owner key already present; skipping genesis insert');
-      return false;
-    }
-    await this.insertOwnerKey(key);
-    return true;
-  }
-
-  /**
-   * Collect every owner key (`CadreControl.OwnerKey.Key`) as a set.
-   *
-   * This is the steady-state trust anchor for seeds: a seed's signer key is
-   * trusted only if it is already enrolled here (see `SeedTrustPolicy`). It is
-   * also the owner-identity source for `queryPeers`, decoupling owner
-   * status from the libp2p transport peer ID.
-   */
-  async getOwnerKeys(): Promise<Set<string>> {
-    this.ensureInitialized();
-    const keys = new Set<string>();
-    for await (const row of this.db!.eval('select Key from CadreControl.OwnerKey')) {
-      keys.add(row.Key as string);
-    }
-    return keys;
-  }
-
-  /**
-   * Enumerate the CadrePeer rows (cadre membership) for admin/membership reads.
-   */
-  async queryCadrePeers(): Promise<Array<{ peerId: string; multiaddr: string | null; stampId: string | null; vouchOwner: string | null; vouchSig: string | null }>> {
-    this.ensureInitialized();
-    const rows: Array<{ peerId: string; multiaddr: string | null; stampId: string | null; vouchOwner: string | null; vouchSig: string | null }> = [];
-    for await (const row of this.db!.eval('select PeerId, Multiaddr, StampId, VouchOwner, VouchSig from CadreControl.CadrePeer')) {
-      rows.push({
-        peerId: row.PeerId as string,
-        multiaddr: (row.Multiaddr as string | null) ?? null,
-        stampId: (row.StampId as string | null) ?? null,
-        vouchOwner: (row.VouchOwner as string | null) ?? null,
-        vouchSig: (row.VouchSig as string | null) ?? null,
-      });
-    }
-    return rows;
-  }
-
-  /**
-   * Read a single `CadrePeer` row's single-use `StampId` nonce (null when the row
-   * does not exist). Used by the owner delete / re-touch paths, which must bind
-   * their signature to the row's CURRENT nonce ({@link cadrePeerRemoveDigest} /
-   * {@link cadrePeerVoucherDigest}).
-   */
-  async queryCadrePeerStampId(peerId: string): Promise<string | null> {
-    this.ensureInitialized();
-    for await (const row of this.db!.eval('select StampId from CadreControl.CadrePeer where PeerId = ?', [peerId])) {
-      return (row.StampId as string | null) ?? null;
-    }
-    return null;
-  }
-
-  /**
-   * Read a single peer's address record (the full `CadrePeer` row) by PeerId.
-   *
-   * Returns null when no row exists. Missing/legacy 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
-   * the inverse of join-on-`,`), so the resolver re-verifies over the same bytes
-   * the publisher signed.
-   */
-  async queryPeerRecord(peerId: string): Promise<PeerAddressRecord | null> {
-    this.ensureInitialized();
-    for await (const row of this.db!.eval(
-      'select PeerId, PublicKey, Multiaddr, UpdatedAt, Sig from CadreControl.CadrePeer where PeerId = ?',
-      [peerId]
-    )) {
-      const multiaddr = (row.Multiaddr as string | null) ?? '';
-      return {
-        peerId: row.PeerId as string,
-        publicKey: (row.PublicKey as string | null) ?? '',
-        addrs: multiaddr.length > 0 ? multiaddr.split(',') : [],
-        updatedAt: (row.UpdatedAt as number | null) ?? 0,
-        sig: (row.Sig as string | null) ?? '',
-      };
-    }
-    return null;
-  }
-
-  /**
-   * Apply a peer's own self-signed address-record update to an existing row.
-   *
-   * Authorization is carried entirely by the record: the `Sig` column (verified
-   * by the `AuthorizedUpdate` self-branch against the stored `PublicKey`) plus
-   * the strictly-increasing `UpdatedAt`. No owner key is involved, so this
-   * is the refresh path for any member — owner or drone — once its row
-   * exists. `PublicKey` is intentionally not in the SET list (it is immutable on
-   * self-update and the constraint enforces `new.PublicKey = old.PublicKey`).
-   */
-  async updateSelfPeerRecord(record: PeerAddressRecord): Promise<void> {
-    this.ensureInitialized();
-    const multiaddr = record.addrs.join(',');
-    await this.db!.exec(`
-      update CadreControl.CadrePeer
-        with context OwnerKey = null, Signature = ?
-        set Multiaddr = ?, UpdatedAt = ?, Sig = ?
-        where PeerId = ?
-    `, [record.sig, multiaddr, record.updatedAt, record.sig, record.peerId]);
-    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
-   * 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
-   * the self-signature, which covers the platform field).
-   */
-  async queryDeviceToken(peerId: string): Promise<DeviceTokenRecord | null> {
-    this.ensureInitialized();
-    for await (const row of this.db!.eval(
-      'select PeerId, Platform, Token, UpdatedAt, Sig from CadreControl.DeviceToken where PeerId = ?',
-      [peerId]
-    )) {
-      return {
-        peerId: row.PeerId as string,
-        platform: (row.Platform as string ?? '') as PushPlatform,
-        token: (row.Token as string | null) ?? '',
-        updatedAt: (row.UpdatedAt as number | null) ?? 0,
-        sig: (row.Sig as string | null) ?? '',
-      };
-    }
-    return null;
-  }
-
-  /**
-   * Apply a peer's own self-signed device-token update to an existing row.
-   *
-   * Authorization is carried entirely by the record: the `Sig` column (verified by
-   * the `DeviceToken.AuthorizedUpdate` self-branch against the stored
-   * `CadrePeer.PublicKey`) plus the strictly-increasing `UpdatedAt`. No owner key
-   * is involved, so this is the refresh / rotation path for any member once both its
-   * `CadrePeer` row (for the PublicKey) and its `DeviceToken` row exist. `PeerId` is
-   * intentionally not in the SET list (immutable; the constraint enforces
-   * `new.PeerId = old.PeerId`). Mirrors {@link updateSelfPeerRecord}.
-   */
-  async updateSelfDeviceToken(record: DeviceTokenRecord): Promise<void> {
-    this.ensureInitialized();
-    await this.db!.exec(`
-      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]);
-    log('Self device token updated: %s (platform=%s, updatedAt=%d)', record.peerId, record.platform, record.updatedAt);
-  }
-
-  /**
-   * Insert the initial owner key (bootstrap - no existing owners required)
-   */
-  async insertOwnerKey(key: string): Promise<void> {
-    this.ensureInitialized();
-    log('Inserting owner key: %s', key);
-
-    // Bootstrap is authorized by the schema's `(select count(1) from OwnerKey) <= 1`
-    // branch, so no signature is needed. We still persist a fresh, unique StampId in the
-    // row's own column to satisfy the not-null/unique anti-replay constraint — the StampId
-    // is now a real column value, not the optimystic `StampId()` SQL function.
-    const stampId = generateStampId(this.config.libp2pNode.peerId.toString());
-    await this.db!.exec(`
-      insert into CadreControl.OwnerKey (Key, StampId)
-        with context OwnerKey = null, Signature = null
-        values (?, ?)
-    `, [key, stampId]);
-    log('Owner key inserted');
-  }
-
-  /**
-   * Insert a strand into the control database using an owner signature.
-   *
-   * The owner signs the canonical row-bound authorization message (see
-   * {@link buildAuthorizationMessage}) — NOT a bare stamp — so the signature is bound to
-   * this strand's contents and cannot be transplanted onto an attacker-chosen row. The
-   * StampId is persisted as a unique column for single-use anti-replay.
-   *
-   * @param strandId - Unique identifier for the strand
-   * @param type - Strand type: 'o' for open, 'c' for closed
-   * @param ownerKey - Public key of the authorizing owner
-   * @param signMessage - Function that ed25519-signs the raw message bytes (no pre-hash)
-   *   with the owner's private key, returning a base64url signature
-   * @param memberPrivateKey - Optional private key for membership in closed strands
-   */
-  async insertStrand(
-    strandId: string,
-    type: 'o' | 'c',
-    ownerKey: string,
-    signMessage: (message: Uint8Array) => string,
-    memberPrivateKey?: string
-  ): Promise<void> {
-    this.ensureInitialized();
-    log('Inserting strand: %s (type: %s)', strandId, type);
-
-    // Generate a unique stamp ID using the peer ID for distributed uniqueness
-    const peerId = this.config.libp2pNode.peerId.toString();
-    const stampId = generateStampId(peerId);
-
-    // Field order MUST match the schema's Strand `Authorized` verify:
-    // Id, Type, MemberPrivateKey ('' when null), StampId.
-    const message = buildAuthorizationMessage([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.db!.exec(`
-      insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
-        with context OwnerKey = ?, Signature = ?
-        values (?, ?, ?, ?)
-    `, [ownerKey, signature, strandId, type, memberPrivateKey ?? null, stampId]);
-
-    log('Strand inserted: %s', strandId);
-  }
-
-  /**
-   * Insert a validation key into the control database using an owner signature.
-   *
-   * Mirrors {@link insertStrand}: the owner signs the canonical row-bound
-   * authorization message over (Key, StampId), and the StampId is persisted as a unique
-   * column for single-use anti-replay. A `ValidationKey` authorizes verifying strand
-   * formation disclosures.
-   *
-   * @param key - The validation public key to enroll
-   * @param ownerKey - Public key of the authorizing owner
-   * @param signMessage - Function that ed25519-signs the raw message bytes (no pre-hash)
-   *   with the owner's private key, returning a base64url signature
-   */
-  async insertValidationKey(
-    key: string,
-    ownerKey: string,
-    signMessage: (message: Uint8Array) => string
-  ): Promise<void> {
-    this.ensureInitialized();
-    log('Inserting validation key: %s', key);
-
-    const peerId = this.config.libp2pNode.peerId.toString();
-    const stampId = generateStampId(peerId);
-
-    // Field order MUST match the schema's ValidationKey `Authorized` verify: Key, StampId.
-    const message = buildAuthorizationMessage([key, stampId]);
-    const signature = signMessage(message);
-
-    await this.db!.exec(`
-      insert into CadreControl.ValidationKey (Key, StampId)
-        with context OwnerKey = ?, Signature = ?
-        values (?, ?)
-    `, [ownerKey, signature, key, stampId]);
-
-    log('Validation key inserted: %s', key);
-  }
-
-  /**
-   * Insert an owner-signed `FormationInvite` (open invitation token).
-   *
-   * The invite is the on-network record that later authorizes an
-   * owner-signature-FREE `Strand` creation: an invited cadre peer redeems it
-   * by inserting a matching `FormationUsage` row (see {@link redeemInvitation}),
-   * which satisfies the consent branch of `Strand.Authorized`.
-   *
-   * Like {@link insertStrand}/{@link insertValidationKey}, the owner signs the
-   * canonical row-bound authorization message (see {@link buildAuthorizationMessage})
-   * over (Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId) — NOT a
-   * bare stamp — so the signature is bound to this invite's contents and cannot be
-   * transplanted onto an attacker-chosen row. The StampId is persisted as a unique
-   * column for single-use anti-replay. `FormationInvite.AuthorizedAddOrRemove` gates
-   * both insert and delete; its `coalesce(new, old)` verify binds the NEW row on
-   * insert and the OLD row on delete.
-   *
-   * `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.
-   * 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,
-   * because it has a subquery) CHECK sees AFTER column coercion: TotalUses becomes a
-   * decimal string (`String(totalUses)` ⇔ `cast(new.TotalUses as text)`) and ExpiresAt
-   * becomes the engine's canonical `PlainDateTime` string — sourced here from
-   * {@link canonicalDatetime} (a `select datetime(?)` round-trip) rather than a hand-rolled
-   * ISO formatter, so signer and verifier agree exactly. A null ExpiresAt / TotalUses /
-   * ValidationUrl signs as `''`, matching the schema's `coalesce(..., '')`.
-   *
-   * @param token - Invitation token (the `FormationInvite` primary key)
-   * @param sAppId - The sApp a redeemed strand will use
-   * @param ownerKey - Public key of the authorizing owner
-   * @param signMessage - ed25519-signs the raw message bytes (no pre-hash),
-   *   returning a base64url signature — the same callback shape {@link insertStrand} uses
-   * @param options - Optional `expiresAtMs` (epoch ms), `totalUses`, `validationUrl`,
-   *   `strandId` (bind to a pre-existing host strand for provision-then-record)
-   */
-  async insertFormationInvite(
-    token: string,
-    sAppId: string,
-    ownerKey: string,
-    signMessage: (message: Uint8Array) => string,
-    options: { expiresAtMs?: number; totalUses?: number; validationUrl?: string; strandId?: string } = {}
-  ): Promise<void> {
-    this.ensureInitialized();
-    log('Inserting formation invite: %s', token);
-
-    const stampId = generateStampId(this.config.libp2pNode.peerId.toString());
-
-    // Build each bound field exactly as the deferred CHECK sees it post-coercion:
-    //   - ExpiresAt: engine-canonical datetime string (or '' when absent), sourced from
-    //     the engine so it byte-matches the column's stored/coerced form.
-    //   - TotalUses: decimal string via String(...) (⇔ cast(new.TotalUses as text)), '' when absent.
-    //   - ValidationUrl: the url or '' when absent.
-    //   - StrandId: the host strand id or '' when absent (text column, no coercion).
-    const expiresAtCanonical = options.expiresAtMs == null
-      ? null
-      : await canonicalDatetime(this.db!, options.expiresAtMs);
-    const expiresAtField = expiresAtCanonical ?? '';
-    const totalUsesField = options.totalUses == null ? '' : String(options.totalUses);
-    const validationUrlField = options.validationUrl ?? '';
-    const strandIdField = options.strandId ?? '';
-
-    // Field order MUST match the schema's FormationInvite `AuthorizedAddOrRemove` verify:
-    // Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId.
-    const message = buildAuthorizationMessage([
-      token, sAppId, expiresAtField, totalUsesField, validationUrlField, strandIdField, stampId,
-    ]);
-    const signature = signMessage(message);
-
-    // 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.db!.exec(`
-      insert into CadreControl.FormationInvite (Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId)
-        with context OwnerKey = ?, Signature = ?
-        values (?, ?, ?, ?, ?, ?, ?)
-    `, [
-      ownerKey, signature,
-      token, sAppId,
-      expiresAtCanonical,
-      options.totalUses ?? null,
-      options.validationUrl ?? null,
-      options.strandId ?? null,
-      stampId,
-    ]);
-
-    log('Formation invite inserted: %s', token);
-  }
-
-  /**
-   * Redeem a `FormationInvite` by inserting the `Strand` row and a matching
-   * `FormationUsage` row **atomically, in one transaction**.
-   *
-   * The two CHECK constraints are mutually circular under immediate evaluation:
-   * `Strand.Authorized`'s consent branch requires the `FormationUsage` row, while
-   * `FormationUsage.StrandExists` requires the `Strand` row. Both CHECKs contain
-   * subqueries, so Quereus auto-defers them to transaction commit — wrapping both
-   * inserts in a single explicit `begin … commit` lets both deferred CHECKs see
-   * both rows at commit. The strand is authorised WITHOUT an owner signature
-   * (the `FormationUsage` branch of `Strand.Authorized`) but still gets a fresh,
-   * unique `StampId` column to satisfy the not-null/unique anti-replay column.
-   *
-   * `UseNumber` is computed as `max(UseNumber)+1` for the token (the `Monotonic`
-   * constraint); callers redeeming concurrently against the same token must
-   * serialise, since the next use number is read before the insert.
-   */
-  async redeemInvitation(params: {
-    token: string;
-    strandId: string;
-    type?: 'o' | 'c';
-    memberPrivateKey?: string;
-    disclosure?: string;
-    peerId?: string;
-    peerSignature?: string;
-    nowMs?: number;
-    validationKey?: string;
-    validationSignature?: string;
-  }): Promise<void> {
-    this.ensureInitialized();
-    const {
-      token, strandId, type = 'o',
-      memberPrivateKey, disclosure = '',
-      peerId, peerSignature,
-      nowMs, validationKey, validationSignature,
-    } = params;
-    log('Redeeming invitation %s -> strand %s', token, strandId);
-
-    const localPeerId = this.config.libp2pNode.peerId.toString();
-    const strandStampId = generateStampId(localPeerId);
-    const useNumber = await this.nextUseNumber(token);
-
-    await this.db!.beginTransaction();
-    try {
-      // 1. Strand row — authorised by the FormationUsage branch (no owner sig),
-      //    still carrying a fresh unique StampId for the anti-replay column.
-      await this.db!.exec(`
-        insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
-          with context OwnerKey = null, Signature = null
-          values (?, ?, ?, ?)
-      `, [strandId, type, memberPrivateKey ?? null, strandStampId]);
-
-      // 2. FormationUsage row — authorised by the matching FormationInvite.
-      await this.execFormationUsageInsert({
-        token, useNumber, disclosure, strandId,
-        peerId: peerId ?? localPeerId, peerSignature: peerSignature ?? null, nowMs: nowMs ?? Date.now(),
-        validationKey: validationKey ?? null, validationSignature: validationSignature ?? null,
-      });
-
-      await this.db!.commit();
-      log('Redeemed invitation %s -> strand %s (use #%d)', token, strandId, useNumber);
-    } catch (error) {
-      // A failed commit() already tears down the transaction, so rollback() would
-      // throw "No transaction active" and mask the real cause — swallow only that.
-      try {
-        await this.db!.rollback();
-      } catch (rollbackError) {
-        log('Rollback after redemption failure was a no-op: %s', rollbackError);
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * 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`.
-   *
-   * Use {@link redeemInvitation} instead when the strand must be created by
-   * consent atomically with the usage.
-   */
-  async recordFormationUsage(params: {
-    token: string;
-    strandId: string;
-    disclosure?: string;
-    peerId?: string;
-    peerSignature?: string;
-    nowMs?: number;
-    validationKey?: string;
-    validationSignature?: string;
-  }): Promise<number> {
-    this.ensureInitialized();
-    const {
-      token, strandId, disclosure = '',
-      peerId, peerSignature, nowMs, validationKey, validationSignature,
-    } = params;
-
-    const localPeerId = this.config.libp2pNode.peerId.toString();
-    const useNumber = await this.nextUseNumber(token);
-
-    await this.execFormationUsageInsert({
-      token, useNumber, disclosure, strandId,
-      peerId: peerId ?? localPeerId, peerSignature: peerSignature ?? null, 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;
-  }
-
-  /** Parameterised `FormationUsage` insert shared by redeem + record paths. */
-  private async execFormationUsageInsert(opts: {
-    token: string;
-    useNumber: number;
-    disclosure: string;
-    strandId: string;
-    peerId: string;
-    peerSignature: string | null;
-    nowMs: number;
-    validationKey: string | null;
-    validationSignature: string | null;
-  }): Promise<void> {
-    // Derive `context.Now` through the same `canonicalDatetime` transform that
-    // produced the stored `ExpiresAt`, so the deferred CHECK's `FI.ExpiresAt >
-    // context.Now` compares two byte-identical engine-`datetime` strings. The
-    // previous `new Date(nowMs).toISOString()` form differed only by a trailing
-    // `.000Z` (the engine `datetime()` separator is `T`, not a space), which never
-    // flipped the strict `>` against a second-granular `ExpiresAt` — so this is a
-    // 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, Disclosure, StrandId)
-        with context PeerId = ?, PeerSignature = ?, Now = ?, ValidationKey = ?, ValidationSignature = ?
-        values (?, ?, ?, ?)
-    `, [
-      opts.peerId, opts.peerSignature, nowCanonical,
-      opts.validationKey, opts.validationSignature,
-      opts.token, opts.useNumber, opts.disclosure, opts.strandId,
-    ]);
-  }
-
-  /**
-   * 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.
-   */
-  async queryFormationInvite(token: string): Promise<{
-    token: string;
-    sAppId: string;
-    expiresAtMs: number | null;
-    totalUses: number | null;
-    validationUrl: string | null;
-    strandId: string | null;
-  } | null> {
-    this.ensureInitialized();
-    for await (const row of this.db!.eval(
-      'select Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId from CadreControl.FormationInvite where Token = ?',
-      [token]
-    )) {
-      const expiresAt = row.ExpiresAt as string | number | null;
-      const expiresAtMs = expiresAt === null || expiresAt === undefined
-        ? null
-        : parseStoredDatetimeMs(expiresAt);
-      return {
-        token: row.Token as string,
-        sAppId: row.sAppId as string,
-        expiresAtMs: expiresAtMs !== null && Number.isNaN(expiresAtMs) ? null : expiresAtMs,
-        totalUses: (row.TotalUses as number | null) ?? null,
-        validationUrl: (row.ValidationUrl as string | null) ?? null,
-        strandId: (row.StrandId as string | null) ?? null,
-      };
-    }
-    return null;
-  }
-
-  /**
-   * Count `FormationUsage` rows recorded against a token (uses consumed so far).
-   */
-  async countFormationUsage(token: string): Promise<number> {
-    this.ensureInitialized();
-    for await (const row of this.db!.eval(
-      'select count(1) as Count from CadreControl.FormationUsage where Token = ?',
-      [token]
-    )) {
-      return (row.Count as number) ?? 0;
-    }
-    return 0;
-  }
-
-  /** Next `UseNumber` for a token = max(existing)+1, per the `Monotonic` constraint. */
-  private async nextUseNumber(token: string): Promise<number> {
-    for await (const row of this.db!.eval(
-      'select coalesce(max(UseNumber), 0) as MaxUse from CadreControl.FormationUsage where Token = ?',
-      [token]
-    )) {
-      return (row.MaxUse as number) + 1;
-    }
-    return 1;
-  }
-
-  /**
-   * Close the database and cleanup resources
-   */
-  async close(): Promise<void> {
-    if (this.collectionFactory) {
-      await this.collectionFactory.shutdown();
-      this.collectionFactory = null;
-    }
-    if (this.db) {
-      void this.db.close();
-      this.db = null;
-    }
-    this.initialized = false;
-    log('ControlDatabase closed');
-  }
-
-  private ensureInitialized(): void {
-    if (!this.initialized || !this.db) {
-      throw new Error('ControlDatabase not initialized. Call initialize() first.');
-    }
-  }
-}
-
+import debug from 'debug';
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { Database, registerPlugin } from '@quereus/quereus';
+import type { VTablePluginInfo, FunctionPluginInfo, SqlParameters } 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';
+import type { Libp2p } from '@libp2p/interface';
+import type { IRepo } from '@optimystic/db-core';
+import type { StrandRow, PeerAddressRecord, CadrePeerRow, RevocationRow, DeviceTokenRecord, DeviceTokenRow, PushPlatform } from './types.js';
+import { CONTROL_SCHEMA } from './control-schema.js';
+import { canonicalDatetime } from './canonical-datetime.js';
+import { controlAuthorizationFields, CONTROL_TABLES } from './control-authorization.js';
+import type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
+import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
+import { retryControlWrite, SCHEMA_INIT_RETRY_POLICY } from './control-write-retry.js';
+import type { ControlWriteRetryOptions } from './control-write-retry.js';
+
+export type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
+
+const log = debug('sereus:cadre:control-db');
+const timing = debug('sereus:cadre:timing');
+
+/**
+ * Generate a unique stamp ID for transaction authorization.
+ * Format: 32 bytes base64url encoded
+ * - First 16 bytes: SHA-256 hash of peer ID (for distributed uniqueness)
+ * - Last 16 bytes: Random bytes (for collision resistance)
+ */
+export function generateStampId(peerId: string): string {
+  // Hash the peer ID and get first 16 bytes (128 bits). A purely local ID
+  // generator: never signed/verified against SQL, so the framed single-field
+  // digest is fine (the changed framing is not cross-checked anywhere).
+  const peerIdHash = digest([peerId], 'sha256', 'bytes') as Uint8Array;
+  const peerIdHashPart = peerIdHash.slice(0, 16);
+
+  // Generate 16 random bytes
+  const randomPart = randomBytes(128, 'bytes') as Uint8Array;
+
+  // Combine peer ID hash and random bytes
+  const combined = new Uint8Array(32);
+  combined.set(peerIdHashPart, 0);
+  combined.set(randomPart, 16);
+
+  // Convert to base64url
+  return uint8ArrayToString(combined, 'base64url');
+}
+
+/**
+ * A `FormationUsage` was to be recorded against a host `Strand` row that is not
+ * present locally.
+ *
+ * Consent is bound to the strand's one-off `StampId` (see the consent branch of
+ * `Strand.AuthorizedInsert`), so the writer must read the live row before inserting.
+ * The ordinary "host strand has not converged on this responder yet" case is caught
+ * earlier and reported as `missing` by `ControlFormationUsageRecorder.resolveStrand`;
+ * reaching here means the row vanished between that check and the write, which is a
+ * genuine race and is surfaced rather than left to fail the deferred `StrandExists`
+ * CHECK at commit (which would drop the write with a far less legible error).
+ */
+export class MissingHostStrandError extends Error {
+  constructor(readonly strandId: string, readonly token: string) {
+    super(`Cannot record formation usage for token ${token}: host strand ${strandId} is not present`);
+    this.name = 'MissingHostStrandError';
+  }
+}
+
+/**
+ * A formation write was abandoned because the caller's `AbortSignal` fired BEFORE the
+ * `FormationUsage` insert was issued — the invite's single use is NOT spent.
+ *
+ * Thrown by the formation write paths ({@link ControlDatabase.recordFormationUsage},
+ * {@link ControlDatabase.redeemInvitation}) and by `ControlFormationUsageRecorder`'s
+ * pre-approval checks when the responder's provisioning budget expires while the work is
+ * still queued (e.g. behind the write lock) or still asking the approval hook. Never
+ * thrown once the insert has been issued: a half-issued write must be allowed to land,
+ * and the formation listener's settle grace then adopts it as a successful join. The
+ * manager rethrows this error instead of mapping it to a retryable conflict — the
+ * listener's timeout path owns the reply.
+ */
+export class FormationAbortedError extends Error {
+  constructor(
+    readonly token: string,
+    operation: string,
+    options?: { cause?: unknown }
+  ) {
+    super(`Formation ${operation} for token ${token} was aborted before its write was issued`, options);
+    this.name = 'FormationAbortedError';
+  }
+}
+
+/**
+ * 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 off the committed-count check ({@link ControlDatabase.assertSeatRemains}) ahead of
+ * the write, inside {@link ControlDatabase.redeemInvitation} /
+ * {@link ControlDatabase.recordFormationUsage} — and off nothing else. It exists because
+ * without it the refusal surfaces as a generic `CHECK constraint failed: Authorized` from the
+ * schema's own count-based cap clause, which the manager reports as a retryable
+ * `Formation conflict, retry` — telling the joiner to retry something that can never succeed.
+ * Two redemptions of one token racing on the SAME node serialize behind the local write
+ * queue, so the loser reads the winner's committed row and is refused here by name —
+ * `StrandFormationManager.validateToken`'s `isTokenUsed` check cannot catch that, since it
+ * ran before either redemption wrote anything.
+ */
+export class InvitationExhaustedError extends Error {
+  constructor(
+    readonly token: string,
+    readonly usesRecorded: number,
+    readonly totalUses: number,
+  ) {
+    super(
+      `Invitation ${token} is exhausted: ${usesRecorded} of ${totalUses} use(s) already recorded`
+    );
+    this.name = 'InvitationExhaustedError';
+  }
+}
+
+/**
+ * What a recorded `FormationUsage` row came out as.
+ *
+ * `usageStampId` is echoed back so a caller that obtained an approver sign-off can prove the
+ * nonce it signed over is the one that landed — the two must match or
+ * `FormationUsage.Authorized` rejects the row (see {@link formationVouchMessage}).
+ */
+export interface FormationUsageResult {
+  /** The single-use nonce written to `UsageStampId` (the row's primary key) — the caller's, or a freshly minted one. */
+  usageStampId: string;
+}
+
+/**
+ * Parse a stored Quereus `datetime` value into epoch milliseconds.
+ *
+ * Quereus canonicalises a `datetime` column to a bare UTC `PlainDateTime` string
+ * (e.g. `2026-06-04T12:34:56`, no `Z`). JS `Date` reads a timezone-less
+ * date-time as LOCAL, so we append `Z` when no offset/zone is present to keep the
+ * value anchored to UTC. Numbers (already epoch ms) pass through.
+ */
+function parseStoredDatetimeMs(value: string | number): number {
+  if (typeof value === 'number') return value;
+  const hasZone = /[zZ]$|[+-]\d\d:?\d\d$/.test(value);
+  return new Date(hasZone ? value : `${value}Z`).getTime();
+}
+
+/**
+ * Parse a nullable stored `datetime` column into epoch ms, mapping both "absent"
+ * and "unparseable" to null — i.e. "no expiry". Shared by every `ExpiresAt`
+ * reader so the NaN guard cannot drift between them.
+ */
+function parseNullableStoredDatetimeMs(value: string | number | null | undefined): number | null {
+  if (value === null || value === undefined) return null;
+  const parsed = parseStoredDatetimeMs(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+/**
+ * Build the canonical authorization message that owner signatures are bound to.
+ *
+ * The message is a SINGLE framed SHA-256 digest over the ordered field vector from
+ * {@link controlAuthorizationFields} (the crypto plugin's injective multi-field
+ * encoding): two fixed literals — the domain tag naming the table rule and the action
+ * tag — followed by the row fields in the schema's fixed order, with the single-use
+ * StampId as the final field where the table has one:
+ *
+ *   message = sha256(encodeFields([domain, action, field_1, ..., StampId]))   // raw digest bytes
+ *
+ * ed25519 signs these raw digest bytes DIRECTLY (no second hash). The SQL constraints
+ * verify the identical bytes with one variadic call
+ * (`verify(digest('CadreControl.X', 'add', field_1, ...), context.Signature, A.Key, 'ed25519')`):
+ * SQL `digest(...)` returns the base64url string of the same digest, which `verify`'s default
+ * base64url input encoding decodes back to those raw bytes — so signer and verifier
+ * operate on the same bytes. Every field is TEXT on both sides (the SQL columns are
+ * `cast(... as text)` / `coalesce(...,'')`; the TS args are strings), so the per-field
+ * type tags agree. Binding the row contents closes captured-stamp replay; the leading
+ * domain/action tags scope the signature to ONE table rule, so an approval minted for
+ * one constraint can never satisfy another (e.g. a ValidationKey enrollment can no
+ * longer double as an OwnerKey enrollment). Single source of truth: every signed writer
+ * (and every test/harness signer) MUST build the message through this function with the
+ * schema's tags and field order, or `verify` will reject the row.
+ */
+export function buildAuthorizationMessage(
+  domain: ControlDomain,
+  action: ControlAction,
+  rowFields: string[],
+): Uint8Array {
+  return digest(controlAuthorizationFields(domain, action, rowFields), 'sha256', 'bytes') as Uint8Array;
+}
+
+/**
+ * The exact bytes an outside approver signs to authorize ONE redemption of a
+ * `ValidationUrl`-bearing `FormationInvite` — the TS mirror of the `'vouch'` digest in
+ * `FormationUsage.Authorized`, in the schema's field order.
+ *
+ * The approval covers the whole redemption: the invitation (`token`), the single-use nonce
+ * the JOINING peer minted for THIS redemption (`usageStampId`), the network being joined
+ * (`strandId`), the joining peer's own ed25519 public key (`peerKey`), and the disclosure
+ * text. That makes it non-transferable — an approval cannot be re-presented for another use
+ * of the same invitation, another network, or another joiner — and the nonce's `unique`
+ * column makes a verbatim re-presentation a duplicate-row rejection. The joiner mints the
+ * nonce ({@link generateStampId}) and sends it in its contact message; sign these bytes over
+ * that same nonce, then pass BOTH the nonce and the signature to
+ * {@link ControlDatabase.redeemInvitation} / {@link ControlDatabase.recordFormationUsage}:
+ * signing one nonce and inserting another fails the CHECK.
+ */
+export function formationVouchMessage(fields: {
+  token: string;
+  usageStampId: string;
+  strandId: string;
+  peerKey: string;
+  disclosure: string;
+}): Uint8Array {
+  return buildAuthorizationMessage('CadreControl.FormationUsage', 'vouch', [
+    fields.token, fields.usageStampId, fields.strandId, fields.peerKey, fields.disclosure,
+  ]);
+}
+
+/**
+ * The exact bytes the JOINING peer signs to consent to ONE redemption of a
+ * `FormationInvite` — the TS mirror of the `'consent'` digest in the schema's
+ * `FormationUsage.PeerConsented` constraint, in its field order.
+ *
+ * A sibling of {@link formationVouchMessage}, not a replacement: the approver's vouch
+ * says the redemption may proceed, this says the joiner itself agreed to it, and the
+ * two are signed by different keys over the same nonce so neither can stand in for
+ * the other. Verify the result with `peer-authorization.ts`'s
+ * `verifyFormationConsent`, whose `formationConsentDigest` is the base64url twin of
+ * this vector — the two must stay in lockstep.
+ *
+ * `strandId` is deliberately absent, unlike its vouch sibling: the joiner cannot know
+ * the strand when it signs (a bound invite's host strand arrives only in the result
+ * frame; an unbound strand is minted by the responder). The responder cannot
+ * substitute one anyway — a bound invite is pinned to its own strand by `Authorized`,
+ * and an unbound redemption mints a fresh strand, so there is no victim to name.
+ */
+export function formationConsentMessage(fields: {
+  token: string;
+  usageStampId: string;
+  peerKey: string;
+  disclosure: string;
+}): Uint8Array {
+  return buildAuthorizationMessage('CadreControl.FormationUsage', 'consent', [
+    fields.token, fields.usageStampId, fields.peerKey, fields.disclosure,
+  ]);
+}
+
+/**
+ * Minimal interface for the CollectionFactory returned by the optimystic plugin.
+ * We only need the methods we actually use.
+ */
+interface CollectionFactory {
+  registerLibp2pNode(networkName: string, node: Libp2p, coordinatedRepo: IRepo): void;
+  shutdown(): Promise<void>;
+}
+
+/** Result of registering the optimystic plugin */
+interface OptimysticPluginResult {
+  collectionFactory: CollectionFactory;
+  vtables: VTablePluginInfo[];
+  functions: FunctionPluginInfo[];
+  /**
+   * Hydrate Quereus's in-memory catalog from persisted optimystic vtab schemas.
+   * Must run BEFORE applying CONTROL_SCHEMA on a warm restart so the declarative
+   * diff sees the existing tables and skips re-emitting CREATE TABLE / CREATE INDEX
+   * for each persisted control object. Idempotent; `{ tables: 0, indexes: 0 }` on a
+   * cold/in-memory start. Mirrors the strand path's hydrate-before-apply (see
+   * compose-strand.ts).
+   */
+  hydrate: (db: Database) => Promise<{ tables: number; indexes: number }>;
+  [key: string]: unknown;
+}
+
+/** Runtime guard for the dynamic-`from` count, over the one table list. */
+const CONTROL_TABLE_SET: ReadonlySet<ControlTable> = new Set<ControlTable>(CONTROL_TABLES);
+
+/** Primary-key column of each {@link RevocableTable}. */
+type GuardedKeyColumn = 'Key' | 'Id' | 'PeerId';
+
+/**
+ * Which column identifies one row of each guarded table — the ONLY place that mapping
+ * lives, so a stamp read and the delete that binds to it can never disagree about it.
+ * Derived rather than passed: every guarded table has exactly one primary key, so a
+ * `(table, keyColumn)` pair on a signature is a mismatch waiting to happen.
+ */
+const GUARDED_KEY_COLUMN: Readonly<Record<RevocableTable, GuardedKeyColumn>> = {
+  OwnerKey: 'Key',
+  CadrePeer: 'PeerId',
+  ValidationKey: 'Key',
+  Strand: 'Id',
+  DeviceToken: 'PeerId',
+};
+
+/**
+ * Guarded tables a node may reap locally once their tombstone has committed — the
+ * tables whose `AuthorizedDelete` carries the REAP branch (see the constraint comment on
+ * `CadrePeer.AuthorizedDelete` in the schema). `Strand` is deliberately absent: its row
+ * carries `MemberPrivateKey`, the party's own membership secret for that network, stored
+ * nowhere else (tickets/backlog/debt-strand-tombstone-reap.md owns any future change).
+ * `OwnerKey` has no production removal path and `MinOneOwner` makes an automated
+ * owner-key reap a party-bricking hazard.
+ */
+export const REAPABLE_TABLES = ['CadrePeer', 'DeviceToken', 'ValidationKey'] as const satisfies readonly RevocableTable[];
+export type ReapableTable = (typeof REAPABLE_TABLES)[number];
+
+/**
+ * Runtime membership test for {@link REAPABLE_TABLES}, narrowing a tombstone's
+ * `TableName` to the subset {@link ControlDatabase.reapRevokedRow} accepts. A tombstone
+ * naming an excluded table (`Strand`, `OwnerKey`) is skipped silently — `Strand`
+ * tombstones are the common case in a party that has unpublished a strand, so a log line
+ * per skip would be per-pass noise.
+ */
+const REAPABLE_TABLE_SET: ReadonlySet<RevocableTable> = new Set<RevocableTable>(REAPABLE_TABLES);
+const isReapableTable = (table: RevocableTable): table is ReapableTable => REAPABLE_TABLE_SET.has(table);
+
+/**
+ * Notified after a `CadreControl.CadrePeer` row write has COMMITTED.
+ *
+ * The one hook the party-membership snapshot a node admits control-DB traffic
+ * against ({@link CadreNode.refreshMembershipGate}) hangs off, so that snapshot
+ * is refreshed by the WRITE rather than by whoever remembered to ask. `reason`
+ * only labels the log line. Must not reject (the notifier swallows and logs
+ * anyway — a committed write never fails because a snapshot refresh did).
+ */
+export type MembershipChangeListener = (reason: string) => Promise<void>;
+
+/**
+ * Identity of the tombstone a committed guarded delete wrote — a
+ * {@link RevocationRow} minus its `ReissuedAt` counter, which a fresh tombstone
+ * always seats at 0 (`FreshTombstone`) and so carries no information.
+ */
+export type RevokedRowRef = Omit<RevocationRow, 'reissuedAt'>;
+
+/**
+ * Notified after a guarded-table delete — and the `CadreControl.Revocation`
+ * tombstone it writes in the same transaction — has COMMITTED.
+ *
+ * The seam the write-while-alone re-replication queue hangs off
+ * ({@link CadreNode.noteGuardedDelete}): one listener covers all four guarded
+ * tables (`CadrePeer` / `DeviceToken` / `Strand` / `ValidationKey`) because every
+ * owner delete funnels through {@link deleteGuardedRow}. Synchronous — the
+ * handler only records the tombstone's identity; it must not throw (the notifier
+ * swallows and logs anyway — a committed delete never fails because bookkeeping did).
+ */
+export type GuardedDeleteListener = (revocation: RevokedRowRef) => void;
+
+export interface ControlDatabaseConfig {
+  /** Party ID for the control network */
+  partyId: string;
+  /**
+   * Optional path to the control schema file.
+   * If not provided, uses the embedded schema for cross-platform compatibility.
+   * Only use this if you need to override the default schema (e.g., for testing).
+   */
+  schemaPath?: string;
+  /** Libp2p node for the control network (injected) */
+  libp2pNode: Libp2p;
+  /** Coordinated repo from the libp2p node */
+  coordinatedRepo: IRepo;
+}
+
+/**
+ * ControlDatabase manages the CadreControl schema using Quereus with Optimystic backend.
+ * It provides typed query methods for accessing control network data.
+ */
+export class ControlDatabase {
+  private db: Database | null = null;
+  private collectionFactory: CollectionFactory | null = null;
+  private readonly config: ControlDatabaseConfig;
+  private initialized = false;
+  private membershipListener: MembershipChangeListener | null = null;
+  private guardedDeleteListener: GuardedDeleteListener | null = null;
+  /** Tail of the local-write chain — see {@link withWriteLock}. */
+  private writeQueue: Promise<unknown> = Promise.resolve();
+  /**
+   * Pacing seams for {@link lockedWithRetry}. Production leaves this empty (real backoff,
+   * real clock); specs inject a recorded `sleep` / fake `now` so no test waits out a real
+   * backoff. Applied OVER the call site's policy, so it overrides pacing without a spec
+   * having to restate the policy's attempts or classifier.
+   */
+  private controlWriteRetryPacing: ControlWriteRetryOptions = {};
+
+  constructor(config: ControlDatabaseConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Initialize the database - load schema and register plugins
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      log('ControlDatabase already initialized');
+      return;
+    }
+
+    log('Initializing ControlDatabase for party: %s', this.config.partyId);
+
+    // Create database instance
+    this.db = new Database();
+
+    // Register crypto plugin (provides digest, sign, verify functions)
+    let t0 = performance.now();
+    await registerPlugin(this.db, cryptoPlugin);
+    timing('[controlDb] cryptoPlugin: %dms', Math.round(performance.now() - t0));
+    log('Registered crypto plugin');
+
+    // Register optimystic plugin with network transactor as default
+    t0 = performance.now();
+    const networkName = `control-${this.config.partyId}`;
+    const pluginResult = optimysticPlugin(this.db, {
+      default_transactor: 'network',
+      default_key_network: 'libp2p',
+      default_network_name: networkName,
+      enable_cache: true,
+    }) as unknown as OptimysticPluginResult;
+
+    // Register vtables and functions manually since we need access to collectionFactory
+    for (const vtable of pluginResult.vtables) {
+      this.db.registerModule(vtable.name, vtable.module, vtable.auxData);
+    }
+    for (const func of pluginResult.functions) {
+      this.db.registerFunction(func.schema);
+    }
+    timing('[controlDb] optimysticPlugin: %dms', Math.round(performance.now() - t0));
+
+    this.collectionFactory = pluginResult.collectionFactory;
+
+    // Inject the libp2p node into the collection factory
+    t0 = performance.now();
+    this.collectionFactory.registerLibp2pNode(
+      networkName,
+      this.config.libp2pNode,
+      this.config.coordinatedRepo
+    );
+    timing('[controlDb] registerLibp2pNode: %dms', Math.round(performance.now() - t0));
+    log('Registered libp2p node with collection factory');
+
+    // Network-back the control tables. CONTROL_SCHEMA's `declare schema CadreControl
+    // { table ... }` tables carry NO per-table `using optimystic(...)`, so storage is
+    // chosen by the database's DEFAULT vtab. Routing the default to optimystic (with
+    // the network transactor + this party's control network) is what makes a control
+    // write replicate peer-to-peer — exactly what connectToStrand does for strand
+    // tables (compose-strand.ts). Without these two calls the tables fall back to
+    // Quereus's in-memory vtab and never converge across the cadre.
+    this.db.setDefaultVtabName('optimystic');
+    this.db.setDefaultVtabArgs({
+      networkName,
+      transactor: 'network',
+      keyNetwork: 'libp2p',
+    });
+    log('Set default vtab to optimystic (networkName=%s, transactor=network)', networkName);
+
+    // Hydrate Quereus's catalog from any persisted optimystic vtab schemas BEFORE
+    // applying CONTROL_SCHEMA, so a warm restart with persistent storage diffs the
+    // control DDL against the already-present tables and re-emits nothing — the same
+    // warm-start regression connectToStrand's hydrate-before-apply guards against.
+    // No-op on a cold / in-memory start (`{ tables: 0, indexes: 0 }`).
+    t0 = performance.now();
+    const hydrated = await pluginResult.hydrate(this.db);
+    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));
+
+    this.initialized = true;
+    log('ControlDatabase initialized successfully');
+  }
+
+  private async loadSchema(): Promise<void> {
+    let schemaContent: string;
+
+    if (this.config.schemaPath) {
+      // Load from file if explicitly provided (for testing or custom schemas)
+      // This only works in Node.js environments
+      log('Loading schema from file: %s', this.config.schemaPath);
+
+      // Check if we're in a Node.js environment
+      if (typeof process !== 'undefined' && process.versions?.node) {
+        try {
+          // Use require to conditionally load fs only in Node.js.
+          // This won't be bundled by React Native's Metro bundler — a dynamic
+          // import() would be statically picked up by Metro, so require is
+          // intentional here (cross-platform constraint, not lazy CommonJS).
+          // eslint-disable-next-line @typescript-eslint/no-require-imports
+          const fs = require('fs/promises');
+          schemaContent = await fs.readFile(this.config.schemaPath, 'utf-8');
+        } catch (error) {
+          throw new Error(
+            `Failed to load schema from ${this.config.schemaPath}: ${error instanceof Error ? error.message : String(error)}`,
+            { cause: error }
+          );
+        }
+      } else {
+        throw new Error(
+          'Loading schema from file is not supported in React Native. ' +
+          'Remove the schemaPath option to use the embedded schema instead.'
+        );
+      }
+    } else {
+      // Use embedded schema for cross-platform compatibility
+      log('Using embedded control schema');
+      schemaContent = CONTROL_SCHEMA;
+    }
+
+    // Schema init is a DISTRIBUTED write, so it gets the same bounded transient-failure
+    // retry every other control write does ({@link lockedWithRetry}). Every CadreControl
+    // table is optimystic-backed (the default vtab was routed to optimystic just above),
+    // so each `create table` needs a super-majority of the party's peers to answer. On a
+    // node joining a party that already has two live members a single unanswered peer
+    // during any one create otherwise kills startup outright.
+    //
+    // Re-running the WHOLE `exec` after a partial failure is safe, and this is the
+    // non-obvious part:
+    //
+    //  - `apply schema` is a DIFF, not a replay. Quereus collects the live catalog, diffs
+    //    the declared schema against it, and only emits DDL for what is missing — which is
+    //    exactly why `initialize` hydrates persisted optimystic schemas BEFORE getting here.
+    //    Tables that already landed generate no statements on the second pass.
+    //  - a failed `create table` leaves the catalog CLEAN. `SchemaManager.createTable` calls
+    //    the module's `create` first and only registers the table on success, so the table
+    //    that failed is not in the catalog, and neither are the ones after it.
+    //
+    // Together: attempt 2 re-emits exactly the failed table and its successors. No
+    // `if not exists` juggling, no per-table loop, no statement splitting.
+    //
+    // Only the "cohort did not answer, nothing committed" class is retried; the classifier
+    // vetoes indeterminate commits and does not match `Missing block`, which is a durable
+    // convergence fault a retry cannot heal (tracked separately) and must keep propagating.
+    //
+    // This is the ONE call site on a non-default policy: the re-run safety argued above is
+    // 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, 'schema-init');
+    log('Schema loaded and executed');
+  }
+
+  /**
+   * Query all strands from the control database
+   */
+  async queryStrands(): Promise<StrandRow[]> {
+    this.ensureInitialized();
+    const results: StrandRow[] = [];
+    for await (const row of this.db!.eval('select Id, MemberPrivateKey, Type from CadreControl.Strand')) {
+      results.push({
+        Id: row.Id as string,
+        MemberPrivateKey: row.MemberPrivateKey as string | null,
+        Type: row.Type as 'o' | 'c',
+      });
+    }
+    return results;
+  }
+
+  /**
+   * Read a single strand row by id, or null when absent. Single-row sibling of
+   * {@link queryStrands}; the responder uses it to read a host strand's
+   * `MemberPrivateKey` (the closed-strand read-gating secret) for delivery to a
+   * validated invitee during provision-then-record formation.
+   */
+  async queryStrand(strandId: string): Promise<StrandRow | null> {
+    this.ensureInitialized();
+    for await (const row of this.db!.eval(
+      'select Id, MemberPrivateKey, Type from CadreControl.Strand where Id = ?',
+      [strandId]
+    )) {
+      return {
+        Id: row.Id as string,
+        MemberPrivateKey: row.MemberPrivateKey as string | null,
+        Type: row.Type as 'o' | 'c',
+      };
+    }
+    return null;
+  }
+
+  /**
+   * Count rows in a CadreControl table as seen by THIS database instance.
+   *
+   * `table` is validated against {@link CONTROL_TABLE_SET} before it is interpolated
+   * into the `from` clause: the names are not user input, but the check keeps the
+   * dynamic query off the injection surface and fails loudly on a typo instead of
+   * emitting a malformed statement. The count reflects only the rows this node's
+   * control DB has converged on — in the integration harness that is the owner
+   * node (one ControlDatabase per party), i.e. the authoritative control-network
+   * view, not a per-drone convergence guarantee.
+   */
+  async countRows(table: ControlTable): Promise<number> {
+    this.ensureInitialized();
+    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}`)) {
+      return (row.Count as number) ?? 0;
+    }
+    return 0;
+  }
+
+  /**
+   * Get the underlying database for advanced queries
+   */
+  getDatabase(): Database {
+    this.ensureInitialized();
+    return this.db!;
+  }
+
+  /**
+   * Check whether any owner key exists in the control database.
+   * Used to decide whether a fresh-party genesis insert is required.
+   */
+  async hasOwnerKey(): Promise<boolean> {
+    this.ensureInitialized();
+    for await (const row of this.db!.eval('select count(1) as Count from CadreControl.OwnerKey')) {
+      return (row.Count as number) > 0;
+    }
+    return false;
+  }
+
+  /**
+   * Idempotent genesis: insert `key` as the founding owner key only when
+   * the party has none yet. Returns true if it inserted, false if an owner
+   * key already existed (so a repeat `--owner` start is a no-op).
+   */
+  async ensureOwnerKey(key: string): Promise<boolean> {
+    this.ensureInitialized();
+    const trimmed = requireEd25519PublicKeyB64(key, 'owner key');
+    if (await this.hasOwnerKey()) {
+      log('Owner key already present; skipping genesis insert');
+      return false;
+    }
+    await this.insertOwnerKey(trimmed);
+    return true;
+  }
+
+  /**
+   * Collect every owner key (`CadreControl.OwnerKey.Key`) as a set.
+   *
+   * This is the steady-state trust anchor for seeds: a seed's signer key is
+   * trusted only if it is already enrolled here (see `SeedTrustPolicy`). It is
+   * also the owner-identity source for `queryPeers`, decoupling owner
+   * status from the libp2p transport peer ID.
+   */
+  async getOwnerKeys(): Promise<Set<string>> {
+    this.ensureInitialized();
+    const keys = new Set<string>();
+    for await (const row of this.db!.eval('select Key from CadreControl.OwnerKey')) {
+      keys.add(row.Key as string);
+    }
+    return keys;
+  }
+
+  /**
+   * Enumerate the CadrePeer rows (cadre membership) for admin/membership reads.
+   * Includes the persisted voucher columns, which
+   * {@link CadreNode.listAuthorizedMembers} re-checks against its node-local anchor.
+   *
+   * Rows whose `StampId` is retired in `CadreControl.Revocation` are excluded HERE, so
+   * every membership reader inherits the exclusion — a revoked peer is neither
+   * authorizable nor addressable (a replayed row planted at a retired stamp must not
+   * be RPC'd or handed out as an address). Reads the retired set through
+   * {@link queryRevokedStamps} rather than inlining the SQL, so tests can interpose on
+   * that seam to model the replicated live-row-plus-tombstone merge state.
+   *
+   * NOTE: runs a second query (the retired-stamp set) per call, and this sits on the
+   * 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(): Promise<CadrePeerRow[]> {
+    this.ensureInitialized();
+    const revoked = await this.queryRevokedStamps('CadrePeer');
+    const rows: CadrePeerRow[] = [];
+    for await (const row of this.db!.eval('select PeerId, Multiaddr, StampId, VouchOwner, VouchSig from CadreControl.CadrePeer')) {
+      const stampId = (row.StampId as string | null) ?? null;
+      if (stampId !== null && revoked.has(stampId)) {
+        continue;
+      }
+      rows.push({
+        peerId: row.PeerId as string,
+        multiaddr: (row.Multiaddr as string | null) ?? null,
+        stampId,
+        vouchOwner: (row.VouchOwner as string | null) ?? null,
+        vouchSig: (row.VouchSig as string | null) ?? null,
+      });
+    }
+    return rows;
+  }
+
+  /**
+   * Every approver public key currently enrolled in `CadreControl.ValidationKey` — the
+   * set a `ValidationUrl` redemption's approval signature must be signed by (see
+   * {@link ControlFormationUsageRecorder}, which checks one key at a time via
+   * {@link queryValidationKeyStampId}).
+   *
+   * Sorted in TypeScript rather than SQL so the order is stable regardless of storage
+   * order; the enrolled set is a handful of keys, so the sort is free.
+   */
+  async queryValidationKeys(): Promise<string[]> {
+    this.ensureInitialized();
+    const keys: string[] = [];
+    for await (const row of this.db!.eval('select Key from CadreControl.ValidationKey')) {
+      keys.push(row.Key as string);
+    }
+    return keys.sort();
+  }
+
+  /**
+   * Read one guarded row's single-use `StampId` nonce (null when the row does not
+   * exist). Every owner-signed delete / re-touch path must bind its signature to the
+   * row's CURRENT nonce, so they all read through here first.
+   *
+   * Deliberately RAW — no `Revocation` filtering (unlike {@link queryCadrePeers} /
+   * {@link queryPeerRecord}): {@link deleteGuardedRow} and the insert-if-absent guard
+   * in the `CadrePeer` upsert need to see a physically present row. Filtering here
+   * would make an insert-if-absent guard read "absent" for a row that exists and
+   * collide on the primary key.
+   *
+   * `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).
+   */
+  private async queryStampId(
+    table: RevocableTable,
+    keyValue: string
+  ): Promise<string | null> {
+    this.ensureInitialized();
+    const sql = `select StampId from CadreControl.${table} where ${GUARDED_KEY_COLUMN[table]} = ?`;
+    for await (const row of this.db!.eval(sql, [keyValue])) {
+      return (row.StampId as string | null) ?? null;
+    }
+    return null;
+  }
+
+  /**
+   * `CadrePeer` stamp nonce — read by {@link SeedBootstrapService.removePeer} as its
+   * row-present gate before it delegates to {@link deleteCadrePeer}. The in-class
+   * `CadrePeer` writers ({@link insertCadrePeer}, {@link reauthorizeCadrePeer}) go
+   * straight to {@link queryStampId}.
+   */
+  queryCadrePeerStampId(peerId: string): Promise<string | null> {
+    return this.queryStampId('CadrePeer', peerId);
+  }
+
+  /**
+   * `DeviceToken` stamp nonce. {@link deleteDeviceToken} reads the stamp itself, so this
+   * is the reader for callers that need to observe a live row's nonce — asserting a token
+   * was seated, or that a removal retired the stamp it named.
+   */
+  queryDeviceTokenStampId(peerId: string): Promise<string | null> {
+    return this.queryStampId('DeviceToken', peerId);
+  }
+
+  /** `Strand` stamp nonce — bound into {@link deleteStrand}'s remove digest. */
+  queryStrandStampId(strandId: string): Promise<string | null> {
+    return this.queryStampId('Strand', strandId);
+  }
+
+  /** `ValidationKey` stamp nonce — bound into {@link deleteValidationKey}'s remove digest. */
+  queryValidationKeyStampId(key: string): Promise<string | null> {
+    return this.queryStampId('ValidationKey', key);
+  }
+
+  /**
+   * Collect the retired `StampId` nonces recorded in `CadreControl.Revocation` for one
+   * {@link RevocableTable}. A stamp
+   * lands here when its row is removed ({@link SeedBootstrapService.removePeer},
+   * {@link deleteValidationKey}, {@link deleteStrand}), and retirement is permanent —
+   * rows are never deleted (only their `ReissuedAt` counter moves, via
+   * {@link reissueRevocations}). Read-side mitigation for the write-time race: the
+   * schema's `NotRevoked` CHECK only sees locally visible tombstones, so a node that
+   * converged on a resurrected row before its tombstone can hold both; readers
+   * ({@link queryCadrePeers}, {@link queryPeerRecord},
+   * {@link CadreNode.resolveDeviceToken}) drop any row whose stamp appears here.
+   *
+   * 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.
+   */
+  async queryRevokedStamps(tableName: RevocableTable): Promise<Set<string>> {
+    this.ensureInitialized();
+    const stamps = new Set<string>();
+    for await (const row of this.db!.eval('select StampId from CadreControl.Revocation where TableName = ?', [tableName])) {
+      stamps.add(row.StampId as string);
+    }
+    return stamps;
+  }
+
+  /**
+   * Every locally-held `CadreControl.Revocation` tombstone — identity triple plus its
+   * `ReissuedAt` counter. Consumed by the cohort-growth re-issue sweep, which
+   * enumerates what this node holds before {@link reissueRevocations} re-broadcasts
+   * it. Plain scan with no `where`, so the composite-primary-key point-lookup hazard
+   * (see the statement comment in {@link reissueRevocations}) does not arise. Unlocked,
+   * like every other read.
+   */
+  async queryRevocations(): Promise<RevocationRow[]> {
+    this.ensureInitialized();
+    const rows: RevocationRow[] = [];
+    for await (const row of this.db!.eval('select TableName, RowKey, StampId, ReissuedAt from CadreControl.Revocation')) {
+      rows.push({
+        tableName: row.TableName as RevocableTable,
+        rowKey: row.RowKey as string,
+        stampId: row.StampId as string,
+        reissuedAt: (row.ReissuedAt as number | null) ?? 0,
+      });
+    }
+    return rows;
+  }
+
+  /**
+   * Read a single peer's address record (the full `CadrePeer` row) by PeerId.
+   *
+   * Returns null when no row exists, or when the row's `StampId` is retired in
+   * `CadreControl.Revocation` — a revoked peer reads as absent, so the resolver
+   * ({@link CadreNode.resolvePeerAddrs}) never hands out a revoked peer's addresses.
+   * The stamp is read for that check only and then dropped; the returned
+   * {@link PeerAddressRecord} shape is unchanged. Reads the retired set through
+   * {@link queryRevokedStamps} rather than inlining the SQL, so tests can interpose on
+   * that seam (see {@link queryCadrePeers}).
+   *
+   * Missing/legacy 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
+   * the inverse of join-on-`,`), so the resolver re-verifies over the same bytes
+   * the publisher signed.
+   */
+  async queryPeerRecord(peerId: string): Promise<PeerAddressRecord | null> {
+    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]
+    )) {
+      const stampId = (row.StampId as string | null) ?? null;
+      if (stampId !== null && revoked.has(stampId)) {
+        return null;
+      }
+      const multiaddr = (row.Multiaddr as string | null) ?? '';
+      return {
+        peerId: row.PeerId as string,
+        publicKey: (row.PublicKey as string | null) ?? '',
+        addrs: multiaddr.length > 0 ? multiaddr.split(',') : [],
+        updatedAt: (row.UpdatedAt as number | null) ?? 0,
+        sig: (row.Sig as string | null) ?? '',
+      };
+    }
+    return null;
+  }
+
+  /**
+   * Apply a peer's own self-signed address-record update to an existing row.
+   *
+   * Authorization is carried entirely by the record: the `Sig` column (verified
+   * by the `AuthorizedUpdate` self-branch against the stored `PublicKey`) plus
+   * the strictly-increasing `UpdatedAt`. No owner key is involved, so this
+   * is the refresh path for any member — owner or drone — once its row
+   * exists. `PublicKey` is intentionally not in the SET list (it is immutable on
+   * self-update and the constraint enforces `new.PublicKey = old.PublicKey`).
+   *
+   * Deliberately NOT wrapped in {@link mutateCadrePeer}, the one `CadrePeer` mutator that
+   * is not: it only ever touches THIS node's own row (sole caller
+   * `CadreNode.publishSelfRecord`), and `CadreNode.listAuthorizedMembers` filters self out
+   * of the membership snapshot, so it cannot change that snapshot. It also runs on the
+   * periodic self-registration refresh, where a notify would add a recurring membership
+   * read for nothing.
+   *
+   * Its INSERT counterpart (`SeedBootstrapService.insertSelfPeerRecord`) does notify. Not an
+   * inconsistency: it shares the one owner-signed insert path with every other member's
+   * row, and a self insert happens once at startup, so the wasted refresh is a single read
+   * — cheaper than a conditional carve-out inside the shared writer. Only the repeating
+   * path is worth exempting.
+   */
+  async updateSelfPeerRecord(record: PeerAddressRecord): Promise<void> {
+    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], '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
+   * 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
+   * the self-signature, which covers the platform field).
+   *
+   * `stampId` rides along ({@link DeviceTokenRow}) because the resolver must drop a
+   * row whose stamp is retired in `CadreControl.Revocation`; it is NOT part of
+   * {@link DeviceTokenRecord}, which is the self-signed shape the peer's `Sig` covers.
+   */
+  async queryDeviceToken(peerId: string): Promise<DeviceTokenRow | null> {
+    this.ensureInitialized();
+    for await (const row of this.db!.eval(
+      'select PeerId, Platform, Token, UpdatedAt, Sig, StampId from CadreControl.DeviceToken where PeerId = ?',
+      [peerId]
+    )) {
+      return {
+        peerId: row.PeerId as string,
+        platform: (row.Platform as string ?? '') as PushPlatform,
+        token: (row.Token as string | null) ?? '',
+        updatedAt: (row.UpdatedAt as number | null) ?? 0,
+        sig: (row.Sig as string | null) ?? '',
+        stampId: (row.StampId as string | null) ?? '',
+      };
+    }
+    return null;
+  }
+
+  /**
+   * Apply a peer's own self-signed device-token update to an existing row.
+   *
+   * Authorization is carried entirely by the record: the `Sig` column (verified by
+   * the `DeviceToken.AuthorizedUpdate` self-branch against the stored
+   * `CadrePeer.PublicKey`) plus the strictly-increasing `UpdatedAt`. No owner key
+   * is involved, so this is the refresh / rotation path for any member once both its
+   * `CadrePeer` row (for the PublicKey) and its `DeviceToken` row exist. `PeerId` is
+   * intentionally not in the SET list (immutable; the constraint enforces
+   * `new.PeerId = old.PeerId`). Mirrors {@link updateSelfPeerRecord}.
+   */
+  async updateSelfDeviceToken(record: DeviceTokenRecord): Promise<void> {
+    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], 'device-token-update');
+    log('Self device token updated: %s (platform=%s, updatedAt=%d)', record.peerId, record.platform, record.updatedAt);
+  }
+
+  /**
+   * Insert the initial owner key (bootstrap - no existing owners required)
+   */
+  async insertOwnerKey(key: string): Promise<void> {
+    this.ensureInitialized();
+    log('Inserting owner key: %s', key);
+
+    // Bootstrap is authorized by the schema's genesis branch — `(select count(1) from
+    // committed.OwnerKey) = 0`, i.e. the party had no owner before this transaction — so no
+    // signature is needed. Every other branch of `OwnerKey.Authorized` requires a signature
+    // from a PRE-EXISTING owner, so this method only ever succeeds on a fresh party; seating
+    // a second owner (or removing one) has no writer here and must sign the digests
+    // documented on the schema's `Authorized` constraint. We still persist a fresh, unique
+    // 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], 'owner-key-insert');
+    log('Owner key inserted');
+  }
+
+  /**
+   * Insert a strand into the control database using an owner signature.
+   *
+   * The owner signs the canonical row-bound authorization message (see
+   * {@link buildAuthorizationMessage}) — NOT a bare stamp — so the signature is bound to
+   * this strand's contents and cannot be transplanted onto an attacker-chosen row. The
+   * StampId is persisted as a unique column for single-use anti-replay.
+   *
+   * @param strandId - Unique identifier for the strand
+   * @param type - Strand type: 'o' for open, 'c' for closed
+   * @param ownerKey - Public key of the authorizing owner
+   * @param signMessage - Function that ed25519-signs the raw message bytes (no pre-hash)
+   *   with the owner's private key, returning a base64url signature
+   * @param memberPrivateKey - Optional private key for membership in closed strands
+   */
+  async insertStrand(
+    strandId: string,
+    type: 'o' | 'c',
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string,
+    memberPrivateKey?: string
+  ): Promise<void> {
+    this.ensureInitialized();
+    log('Inserting strand: %s (type: %s)', strandId, type);
+
+    // Generate a unique stamp ID using the peer ID for distributed uniqueness
+    const peerId = this.config.libp2pNode.peerId.toString();
+    const stampId = generateStampId(peerId);
+
+    // Field order MUST match the schema's Strand `AuthorizedInsert` verify:
+    // Id, Type, MemberPrivateKey ('' when null), StampId.
+    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], 'strand-insert');
+
+    log('Strand inserted: %s', strandId);
+  }
+
+  /**
+   * Delete a strand from the control database using an owner signature.
+   *
+   * Mirrors {@link insertStrand}'s row-bound approach for the delete half: the owner
+   * signs the canonical `'remove'`-tagged authorization message over (Id, StampId) — the
+   * schema's `Strand.AuthorizedDelete` verifies this DISTINCT digest, so the insert
+   * approval (which never expires) can never be replayed as a removal. The delete and
+   * the `Revocation` tombstone retiring the row's StampId commit in ONE transaction —
+   * `Strand.RevocationRecorded` refuses a bare delete, and without the tombstone the
+   * stamp would free up and the original formation approval could re-seat the strand.
+   * Body shared with every other guarded delete via {@link deleteGuardedRow}.
+   *
+   * The remove digest binds only (Id, StampId) — not Type/MemberPrivateKey — so this
+   * works identically for open and closed strands.
+   *
+   * A no-op (no throw, no tombstone) when the row does not exist — `false` then, `true`
+   * when a row was actually removed.
+   */
+  deleteStrand(
+    strandId: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    return this.lockedWithRetry(() => this.deleteGuardedRow('Strand', strandId, ownerKey, signMessage), {}, 'strand-delete');
+  }
+
+  /**
+   * Insert a validation key into the control database using an owner signature.
+   *
+   * Mirrors {@link insertStrand}: the owner signs the canonical row-bound
+   * authorization message over (Key, StampId), and the StampId is persisted as a unique
+   * column for single-use anti-replay. A `ValidationKey` authorizes verifying strand
+   * formation disclosures.
+   *
+   * @param key - The validation public key to enroll
+   * @param ownerKey - Public key of the authorizing owner
+   * @param signMessage - Function that ed25519-signs the raw message bytes (no pre-hash)
+   *   with the owner's private key, returning a base64url signature
+   */
+  async insertValidationKey(
+    key: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<void> {
+    this.ensureInitialized();
+    log('Inserting validation key: %s', key);
+
+    const peerId = this.config.libp2pNode.peerId.toString();
+    const stampId = generateStampId(peerId);
+
+    // 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], 'validation-key-insert');
+
+    log('Validation key inserted: %s', key);
+  }
+
+  /**
+   * Delete a validation key from the control database using an owner signature.
+   *
+   * Mirrors {@link insertValidationKey}'s row-bound approach for the delete half: the
+   * owner signs the canonical `'remove'`-tagged authorization message over (Key,
+   * StampId) — the schema's `ValidationKey.AuthorizedDelete` verifies this DISTINCT
+   * digest, so the enrollment approval (which never expires) can never be replayed as a
+   * removal. The delete and the `Revocation` tombstone retiring the row's StampId commit
+   * in ONE transaction — `ValidationKey.RevocationRecorded` refuses a bare delete, and
+   * without the tombstone the stamp would free up and the original enrollment approval
+   * could re-seat the key. Body shared with every other guarded delete via
+   * {@link deleteGuardedRow}.
+   *
+   * A no-op (no throw, no tombstone) when the row does not exist — `false` then, `true`
+   * when a row was actually removed.
+   */
+  deleteValidationKey(
+    key: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    return this.lockedWithRetry(() => this.deleteGuardedRow('ValidationKey', key, ownerKey, signMessage), {}, 'validation-key-delete');
+  }
+
+  /**
+   * Owner-vouched INSERT of one `CadrePeer` membership row, notifying the membership
+   * listener once it has committed.
+   *
+   * Mints a fresh single-use `StampId` and signs the `'vouch'`-tagged authorization
+   * message over (PeerId, StampId) — see {@link buildAuthorizationMessage} — satisfying
+   * the schema's `CadrePeer.AuthorizedInsert`. Binding the peer id to the nonce means a
+   * captured insert approval cannot be replayed (live rows are blocked by the unique
+   * `StampId` column, removed rows by `Revocation` retirement via `CadrePeer.NotRevoked`)
+   * and cannot be repurposed as a delete (which signs a distinct `'remove'`-tagged digest).
+   *
+   * The owner signature does NOT cover the address columns — those are vouched only as far
+   * as the owner asserts them, and a peer's own `Sig` (when present) is what makes the row
+   * resolvable.
+   *
+   * The {@link mutateCadrePeer} wrapper lives here rather than in the caller so no
+   * `CadrePeer` inserter can forget it — the write itself is what lets the admitted peer's
+   * traffic in.
+   *
+   * Idempotent on an already-present row: two writers can legitimately race the SAME peer's
+   * first row — the node's own background self-publish ({@link CadreNode.registerSelf})
+   * against a foreground {@link SeedBootstrapService.authorizePeer} of that node's id — and
+   * the write lock only serializes them; the loser would hit the `CadrePeer.PeerId` UNIQUE
+   * constraint. The existence check runs INSIDE the locked body, so it sees the winner's
+   * committed row (a pre-lock check would re-open the read-then-insert window). The existing
+   * row — voucher, addresses, self-`Sig` — is left untouched; re-touching a live row is
+   * {@link reauthorizeCadrePeer}'s job.
+   *
+   * @param row - the membership row's columns; `multiaddr` is the comma-joined address list.
+   * @param ownerKey - public key of the vouching owner, persisted into `VouchOwner`.
+   * @param signMessage - ed25519-signs the raw message bytes (no pre-hash) with that owner's
+   *   private key, returning a base64url signature.
+   * @returns `true` when this call performed the INSERT, `false` when the in-lock existence
+   *   check found the row already seated. The loser needs to know: an authorize seats a row
+   *   with a null `Sig`, so a self-publish that lost the race must fall through to a
+   *   self-update or its record never lands.
+   */
+  async insertCadrePeer(
+    row: {
+      peerId: string;
+      publicKey: string | null;
+      multiaddr: string;
+      updatedAt: number;
+      sig: string | null;
+    },
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    this.ensureInitialized();
+    // Stamp is minted from the ADMITTED peer's id, not this node's — the nonce names the
+    // row it vouches.
+    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) {
+        log('CadrePeer row already present for %s; insert skipped (already a member)', row.peerId);
+        return false;
+      }
+      // Bare `exec`: already inside the write lock, which is NOT re-entrant (see the NOTE
+      // on withWriteLock — re-entry via execWrite hangs silently and permanently).
+      //
+      // 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 (?, ?, ?, ?, ?, ?, ?, ?)
+      `, [ownerKey, signature, row.peerId, row.publicKey, row.multiaddr, row.updatedAt, row.sig, stampId, ownerKey, signature]);
+      return true;
+    });
+  }
+
+  /**
+   * Owner "re-touch" of an existing `CadrePeer` membership row: bump `UpdatedAt` and
+   * rewrite `VouchOwner`/`VouchSig` under the owner branch of `CadrePeer.AuthorizedUpdate`
+   * (a signature over the SAME `'vouch'`-tagged digest {@link insertCadrePeer} builds), so
+   * the row is re-emitted as a fresh, broadcasting transaction.
+   *
+   * This is the write-while-alone re-replication primitive: a membership row that committed
+   * local-only (its block's cluster ≤1 at insert) is pushed to the cohort once it grows, by
+   * re-issuing this monotonic bump. It is an UPDATE (not the original INSERT) because the row
+   * already exists locally; a re-INSERT would hit the `PeerId` PK. Only the freshness stamp
+   * and voucher change — `PublicKey` / `Multiaddr` / `Sig` are left intact — so it is safe
+   * over a row whose peer has not self-published (`Sig` null); the caller must skip a row
+   * that already carries a self-`Sig` (that row is the owning peer's to refresh, and bumping
+   * `UpdatedAt` without re-signing would invalidate its self-signature).
+   *
+   * Signs over the row's CURRENT `StampId` (unchanged by the re-touch), read BEFORE the lock
+   * is taken. An absent row returns `false` WITHOUT notifying: nothing was written, so the
+   * membership snapshot cannot have changed.
+   *
+   * NOTE: that stamp read is outside the lock, same as {@link deleteGuardedRow}'s. A writer
+   * that removes the row in between makes the `update` match nothing, and this still returns
+   * `true` and notifies — harmless today (the sole caller, the write-while-alone drain, only
+   * logs the result, and a spurious notify just re-reads the member set), and a remove-then-
+   * re-add in the same window fails loudly instead, since the signature binds the retired
+   * stamp. If a caller ever acts on `true` as proof the row was written, fold the stamp read
+   * into the locked body.
+   *
+   * Notifies like the insert/remove paths even though this is "only" a re-touch: it rewrites
+   * VouchOwner/VouchSig, which the authorized-membership predicate judges on, so it CAN
+   * change the member set. Keeping the rule uniform ("every CadrePeer mutator notifies")
+   * beats a per-method exception the next reader has to relearn.
+   *
+   * NOTE: this rebinds VouchOwner to the CALLING owner's key, and the authorized-membership
+   * predicate (`CadreNode.listAuthorizedMembers`) now judges rows by that column against each
+   * reader's node-local anchor. Benign today because the only caller — the write-while-alone
+   * drain — re-touches solely rows this node itself authored (`pendingPeerWrites`), so the
+   * voucher is rewritten to the key that already signed it. If a future path ever lets one
+   * owner re-touch a row a DIFFERENT owner vouched, the voucher silently flips: readers that
+   * anchor the original owner but not this one would drop a legitimate member. Such a path
+   * must re-vouch deliberately (or preserve the existing VouchOwner/VouchSig) rather than
+   * inherit this rebinding.
+   *
+   * @param peerId - the membership row to re-touch.
+   * @param updatedAt - the strictly-increasing freshness stamp to write.
+   * @param ownerKey - public key of the re-vouching owner, rewritten into `VouchOwner`.
+   * @param signMessage - ed25519-signs the raw message bytes with that owner's private key.
+   * @returns `true` when the row was re-touched, `false` when no row exists (no notify).
+   */
+  async reauthorizeCadrePeer(
+    peerId: string,
+    updatedAt: number,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    this.ensureInitialized();
+    const stampId = await this.queryStampId('CadrePeer', peerId);
+    if (stampId === null) {
+      log('reauthorizeCadrePeer: no CadrePeer row for %s (nothing to re-touch)', peerId);
+      return false;
+    }
+    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 = ?
+      `, [ownerKey, signature, updatedAt, ownerKey, signature, peerId]);
+    });
+    return true;
+  }
+
+  /**
+   * Owner-signed removal of one `CadrePeer` membership row, notifying the membership
+   * listener once it has committed.
+   *
+   * Mirrors {@link deleteStrand} for the membership table: the owner signs the DISTINCT
+   * `'remove'`-tagged digest over (PeerId, StampId), so the row's stored `VouchSig` can
+   * never be replayed to delete it, and the `Revocation` tombstone retiring the stamp
+   * lands in the SAME transaction — `CadrePeer.RevocationRecorded` refuses a bare delete,
+   * and without the tombstone the never-expiring admission approval (which the removed
+   * peer holds a copy of) could re-seat the row.
+   *
+   * The {@link mutateCadrePeer} wrapper lives here rather than in the caller so no
+   * `CadrePeer` remover can forget it. It notifies whenever the body resolves, including
+   * the absent-row no-op below — a caller that must not notify for an already-absent peer
+   * gates on {@link queryCadrePeerStampId} first (see
+   * {@link SeedBootstrapService.removePeer}).
+   *
+   * A no-op (no throw, no tombstone) when the row does not exist — `false` then, `true`
+   * when a row was actually removed.
+   */
+  deleteCadrePeer(
+    peerId: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    return this.mutateCadrePeer('peer-remove', () =>
+      this.deleteGuardedRow('CadrePeer', peerId, ownerKey, signMessage));
+  }
+
+  /**
+   * Owner-signed removal of one peer's `DeviceToken` row (logout / token invalidation).
+   *
+   * Mirrors {@link deleteStrand}: the owner signs the DISTINCT `'remove'`-tagged digest
+   * over (PeerId, StampId), so the insert approval can never be replayed to clear a token,
+   * and the `Revocation` tombstone retiring the stamp lands in the SAME transaction —
+   * `DeviceToken.RevocationRecorded` refuses a bare delete, and without the tombstone the
+   * never-expiring insert approval (which the cleared device holds a copy of) could
+   * re-seat the token.
+   *
+   * A no-op (no throw, no tombstone) when the row does not exist — `false` then, `true`
+   * when a row was actually removed.
+   */
+  deleteDeviceToken(
+    peerId: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    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
+   * stamp, in ONE transaction. The single body behind EVERY guarded delete —
+   * {@link deleteStrand}, {@link deleteValidationKey}, {@link deleteCadrePeer},
+   * {@link deleteDeviceToken}; see any of them for the per-table security rationale. Each
+   * of those is a thin named wrapper, so callers never pass a table name and this
+   * generic shape stays off the public surface.
+   *
+   * `OwnerKey` is excluded from `table` only because no owner-key removal path exists in
+   * production yet — the schema has the `'remove'` branch (`OwnerKey.Authorized`, which
+   * requires a DIFFERENT owner as signer) and `control-revocation-replay.spec.ts` drives
+   * it with hand-rolled SQL. Widen this and add a wrapper when that path lands; the body
+   * needs no change.
+   *
+   * The row's CURRENT stamp is read first and signed over, so the remove digest binds to
+   * this exact row instance. A no-op (no throw, no tombstone) when the row is absent —
+   * reported as `false` so a caller can tell "removed" from "was never there" without a
+   * second read (e.g. {@link CadreNode.unpublishStrand}'s committed-while-alone warning,
+   * which must not fire for a no-op).
+   *
+   * NOTE: the stamp read is outside the transaction. A concurrent writer that removes
+   * the row in between makes the signature bind a stamp that is no longer live; the
+   * delete then matches nothing and the tombstone insert collides with the other
+   * writer's on `Revocation`'s (TableName, StampId) primary key, so the transaction
+   * fails rather than silently half-applying. If concurrent owner-device removals ever
+   * become routine, fold the stamp read into the transaction instead.
+   *
+   * Deliberately NOT wrapped in {@link withWriteLock}: every public entry point already
+   * holds the (non-re-entrant) lock, so taking it again here would self-deadlock.
+   *
+   * `table` and its {@link GUARDED_KEY_COLUMN} column are interpolated into the SQL; both
+   * come from closed literal unions — no caller-supplied string reaches the statement.
+   */
+  private async deleteGuardedRow(
+    table: Exclude<RevocableTable, 'OwnerKey'>,
+    keyValue: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    this.ensureInitialized();
+    const stampId = await this.queryStampId(table, keyValue);
+    if (stampId === null) {
+      log('delete %s: no row for %s (already absent)', table, keyValue);
+      return false;
+    }
+
+    const message = buildAuthorizationMessage(`CadreControl.${table}`, 'remove', [keyValue, stampId]);
+    const signature = signMessage(message);
+    // The tombstone carries its OWN owner signature (`Revocation.Authorized`): retiring a
+    // stamp is permanent and party-wide, so the delete's signature deliberately does not
+    // 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]} = ?
+      `, [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)
+      `, [ownerKey, revocationSignature, table, keyValue, stampId]);
+    });
+
+    log('%s deleted: %s (stamp retired)', table, keyValue);
+    if (this.guardedDeleteListener) {
+      try {
+        this.guardedDeleteListener({ tableName: table, rowKey: keyValue, stampId });
+      } catch (error) {
+        log('guarded-delete listener threw (committed delete unaffected): %o', error);
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Delete one guarded row that an ALREADY-COMMITTED `Revocation` tombstone retires —
+   * the local catch-up for a node that converged on a removal's tombstone while still
+   * holding the removed row. That live-row-plus-tombstone state is reachable only by
+   * replication merge (local writes cannot build it: `Revocation.RowIsGone` refuses a
+   * tombstone while the row is live), and replication cannot carry the delete itself —
+   * replaying a delete of a row that is already gone locally is a no-op — so without
+   * this the stale row is permanent garbage on every node that held it at revocation
+   * time. Authorized by the REAP branch of the table's `AuthorizedDelete`: the
+   * tombstone is itself owner-signed (`Revocation.Authorized`), so no owner key is
+   * needed HERE — any node holding row + tombstone may reap, drones included.
+   *
+   * Returns whether a row was removed: `false` without writing when the row is absent
+   * locally (the common case on most nodes), or when its live stamp is not `stampId`
+   * (a fresh incarnation the owner re-seated, which the old tombstone must not touch).
+   *
+   * The delete's WHERE clause binds `StampId` too — required, not belt-and-braces: an
+   * owner may re-seat the row (fresh stamp) between the stamp read below and the
+   * statement, and without the clause the reap would delete the owner's brand-new row.
+   * With it the statement matches nothing and the reap is a silent no-op (the schema
+   * branch would also refuse that delete, but as a constraint error thrown into a
+   * background sweep — matched-nothing is the better failure mode). Like
+   * {@link reauthorizeCadrePeer}, a race lost AFTER the guard still returns `true`;
+   * harmless — nothing was deleted, and the next sweep re-reads.
+   *
+   * Writes NOTHING to `Revocation`: `RevocationRecorded` is satisfied by the same
+   * committed tombstone that authorizes the reap, so a reap files no second tombstone.
+   * It therefore does NOT fire the guarded-delete listener either — that seam exists to
+   * queue a tombstone for re-issue when it committed while alone, and a reap has no
+   * tombstone of its own to re-issue. A reap that commits while alone needs no
+   * re-replication at all: every OTHER node either already lacks the row, or holds the
+   * same committed tombstone and reaps its own copy.
+   *
+   * NOTE: the reap delete is keyed on the primary key; the `StampId` predicate is applied
+   * where the statement runs. If a reap on one node ever has to be reconciled against an
+   * owner re-seat of the same key that landed on another node, whether the delete or the
+   * re-seat wins is decided by the collection's merge order, not by this clause — the same
+   * ordering question the owner-signed delete path already carries
+   * (`tickets/blocked/forked-control-collection-sync-livelocks.md`). Only matters once a
+   * sweep drives this automatically on connected nodes; if that reconcile ever drops a
+   * freshly re-seated row, this is the site.
+   *
+   * `table` and its {@link GUARDED_KEY_COLUMN} column come from closed literal unions —
+   * no caller-supplied string reaches the statement (same injection-surface discipline
+   * as {@link deleteGuardedRow}). The `with context` clause is PRESENT and bound to
+   * nulls, never omitted: Quereus cannot resolve `context.OwnerKey` at plan time when
+   * the clause is absent while a constraint references `context.*` (nulls through a
+   * present clause are the shape {@link redeemInvitation}'s consent-branch insert ships).
+   *
+   * Driven automatically by {@link reapRevokedRows}, which the periodic control-cohort
+   * reconcile pass runs while the node has at least one control connection.
+   */
+  async reapRevokedRow(table: ReapableTable, rowKey: string, stampId: string): Promise<boolean> {
+    this.ensureInitialized();
+    const liveStamp = await this.queryStampId(table, rowKey);
+    if (liveStamp === null) {
+      log('reap %s: no row for %s (nothing to reap)', table, rowKey);
+      return false;
+    }
+    if (liveStamp !== stampId) {
+      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 = ?
+    `;
+    if (table === 'CadrePeer') {
+      // Through mutateCadrePeer so the "EVERY CadrePeer writer goes through here"
+      // invariant keeps holding with no new documented exception. The membership
+      // snapshot cannot actually change — queryCadrePeers already dropped this row via
+      // the retired-stamp gate — so the notify is a redundant refresh. Bare exec:
+      // already inside the non-re-entrant write lock (see insertCadrePeer).
+      //
+      // NOTE: reapRevokedRows calls this in a loop, so a sweep that clears K CadrePeer
+      // rows fires K redundant gate refreshes (two table scans each), awaited serially.
+      // Harmless today — K is the backlog of unreaped rows, which a party burns down to
+      // 0 on its first connected tick and holds there. If a party ever reaps many rows
+      // in one pass, hoist the notify to one refresh after the sweep instead.
+      await this.mutateCadrePeer('peer-reap', () => this.db!.exec(sql, [rowKey, stampId]));
+    } else {
+      await this.execWrite(sql, [rowKey, stampId], `reap-${table}`);
+    }
+    // A row leaving the control plane without an owner signature at the write site
+    // should be visible in a log.
+    log('REAPED %s row %s (stamp %s): committed tombstone authorized local removal, no owner signature', table, rowKey, stampId);
+    return true;
+  }
+
+  /**
+   * Sweep every locally-held `Revocation` tombstone and {@link reapRevokedRow} the guarded
+   * row each one retires, returning how many rows were actually removed.
+   *
+   * This is the enumeration half of the reap: replication carries the tombstone but cannot
+   * carry the delete (replaying a delete of an already-absent row is a no-op), so a node
+   * that converged on a removal while holding the removed row keeps that row as inert
+   * garbage until something walks the tombstones and drops it. `CadreNode`'s periodic
+   * control-cohort reconcile pass is that something, gated on the node having at least one
+   * control connection (a reap is a write, and a write committed alone is local-only).
+   *
+   * Enumerated UNLOCKED, deleted per-row LOCKED: {@link reapRevokedRow} takes the write
+   * lock itself (via {@link mutateCadrePeer} / {@link execWrite}) and the lock is not
+   * re-entrant, so this loop must not hold it. Same structure as
+   * `CadreNode.reissueAuthoredMembershipRows`.
+   *
+   * Two rows are deliberately left alone:
+   *
+   * - **Tables outside {@link REAPABLE_TABLES}** (`Strand`, `OwnerKey`) — no reap branch
+   *   exists on their `AuthorizedDelete`, so the delete would throw rather than no-op.
+   * - **This node's OWN `CadrePeer` / `DeviceToken` row** (`selfPeerId`). Reaping it would
+   *   fight this node's own re-registration: `registerSelf` / `retouchSelfDeviceToken` run
+   *   on the heartbeat and the growth drain, and after a self-reap their insert-if-absent
+   *   guard takes the INSERT path — which needs an owner signature `NotRevoked` refuses for
+   *   a retired stamp, and which a revoked drone cannot produce at all. The trade is
+   *   recurring failure noise every cycle against removing the one stale row nobody else
+   *   reads from this node (every other node already filters it by tombstone). A revoked
+   *   node therefore keeps its own copy of its own row; "a node that learns it has been
+   *   revoked should shut itself down" is a distinct behaviour and its own ticket.
+   *   `ValidationKey` has no self notion and is not special-cased.
+   *
+   * A per-row failure is logged and skipped rather than aborting the sweep: an abort would
+   * starve every tombstone after the failing one on every subsequent pass, and each row is
+   * independent. Returns the count so far if the database is closed mid-sweep.
+   *
+   * `selfPeerId` is a parameter rather than read from the injected libp2p node so the
+   * skip-self rule is exercisable without one.
+   *
+   * NOTE: cost is O(tombstones), not O(live rows) — one {@link queryRevocations} scan plus
+   * one {@link queryStampId} point lookup per tombstone, and the empty-table early return
+   * makes the common case (a party that has never revoked anyone) a single scan per pass.
+   * But `Revocation` is append-only and unbounded, so this is O(all tombstones ever) point
+   * lookups on every reconcile tick. Fine while revocations stay rare for a cadre-sized
+   * party; if the table ever grows, persist a node-local high-water mark of what has
+   * already been reaped instead of re-scanning everything (the same bound the sweep in
+   * `CadreNode.drainPendingRevocations` wants).
+   */
+  async reapRevokedRows(selfPeerId: string): Promise<number> {
+    this.ensureInitialized();
+    const held = await this.queryRevocations();
+    if (held.length === 0) {
+      return 0;
+    }
+    let reaped = 0;
+    for (const tombstone of held) {
+      // Teardown guard, per row: close() can land mid-sweep (the reconcile pass that
+      // drives this outlives no node, but it does not hold the node's lifecycle either).
+      if (!this.initialized || !this.db) {
+        return reaped;
+      }
+      if (!isReapableTable(tombstone.tableName)) {
+        continue;
+      }
+      if (tombstone.rowKey === selfPeerId
+        && (tombstone.tableName === 'CadrePeer' || tombstone.tableName === 'DeviceToken')) {
+        continue;
+      }
+      try {
+        if (await this.reapRevokedRow(tombstone.tableName, tombstone.rowKey, tombstone.stampId)) {
+          reaped++;
+        }
+      } catch (error) {
+        log('reap sweep: %s row %s (stamp %s) failed (continuing): %o',
+          tombstone.tableName, tombstone.rowKey, tombstone.stampId, error);
+      }
+    }
+    return reaped;
+  }
+
+  /**
+   * Owner-signed re-issue of a batch of `Revocation` tombstones: bump each row's
+   * `ReissuedAt` to `reissuedAt` in ONE transaction. Re-writing the row is what makes
+   * the storage layer re-broadcast it — a tombstone that committed while the node was
+   * alone is local-only, and unlike an insert a delete cannot be replayed (the guarded
+   * row is already gone locally), so the tombstone is the half of a removal that can
+   * still carry it to the rest of the party.
+   *
+   * One transaction, not one per row: a sweep may cover every tombstone in the table,
+   * and each separate commit is a separate round of network work. One owner signature
+   * per row: `AuthorizedReissue`'s digest binds (TableName, RowKey, StampId,
+   * ReissuedAt). `reissuedAt` must be STRICTLY above every affected row's current
+   * value (`ReissueOnly`); callers derive it as `Math.max(Date.now(), max(existing) + 1)`,
+   * mirroring {@link CadreNode.reissuePeerAuthorize}'s monotonic bump. Re-issuing a
+   * tombstone whose guarded row was never present locally is the normal case (a node
+   * that converged on the tombstone but never held the row) — a re-issue files no
+   * delete, so `RowIsGone` / `RevocationRecorded` are not involved.
+   *
+   * A constraint failure on any row rolls the WHOLE batch back and propagates —
+   * {@link lockedWithRetry}'s classifier only re-presents transient cluster failures,
+   * so a real refusal (non-owner signer, or a stale counter when two owner devices
+   * sweep concurrently and the loser's `ReissueOnly` CHECK fails) surfaces to the
+   * caller, which retries with a fresh counter on its next sweep. A row whose
+   * `StampId` matches nothing locally is a silent no-op statement; callers enumerate
+   * via {@link queryRevocations} first, so they only name stamps they hold.
+   *
+   * Returns how many UPDATE statements ran (`rows.length` on success).
+   */
+  reissueRevocations(
+    rows: readonly RevocationRow[],
+    reissuedAt: number,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<number> {
+    this.ensureInitialized();
+    // Signatures minted OUTSIDE the locked body: a retried attempt must re-present the
+    // exact signed message, never re-mint (the contract on withWriteLock). ReissuedAt
+    // rides in the digest as a string — SQL-side it is cast(new.ReissuedAt as text),
+    // and every digest field is TEXT on both sides (see buildAuthorizationMessage).
+    const signed = rows.map((row) => ({
+      row,
+      signature: signMessage(buildAuthorizationMessage(
+        'CadreControl.Revocation', 'reissue',
+        [row.tableName, row.rowKey, row.stampId, String(reissuedAt)]
+      )),
+    }));
+    return this.lockedWithRetry(async () => {
+      // Counter lives INSIDE the locked body so a lockedWithRetry re-run (which
+      // re-executes the whole body) starts from zero instead of double-counting.
+      let executed = 0;
+      await this.inTransaction('reissue revocations', async () => {
+        for (const { row, signature } of signed) {
+          // Keyed on StampId ALONE, deliberately. Equality on every column of the
+          // composite primary key (TableName, StampId) makes the optimystic vtab claim
+          // the predicate as a point lookup with no engine-side re-check, and that
+          // descent has been observed returning zero rows for a row that provably
+          // exists (tickets/backlog/debt-composite-pk-point-lookup-unreliable-untracked).
+          // A re-issue that silently matched nothing would report success and
+          // replicate nothing — the exact failure this path exists to remove. StampId
+          // alone is a non-leading subset of the key, which the module declines, so
+          // the read is a scan the engine filters; a StampId is 128 bits of CSPRNG
+          // 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 = ?
+          `, [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.
+   *
+   * A failed `commit()` has already torn the transaction down, so the `rollback()` in
+   * the failure path would itself throw "No transaction active" and mask the real
+   * cause — that secondary throw is logged and swallowed, and the original error always
+   * propagates.
+   *
+   * It opens a transaction unconditionally (Quereus hard-throws on a nested
+   * `beginTransaction`), so a caller already inside one must not call it. A `CadrePeer`
+   * write nests this INSIDE {@link mutateCadrePeer}, never the reverse — see
+   * {@link assertCommitBoundary}.
+   *
+   * Private: every multi-statement control write lives in this class (the owner-signed
+   * delete/tombstone pairs all go through {@link deleteGuardedRow}), so needing to widen
+   * this is a sign the writer that wants it belongs in here too.
+   *
+   * Deliberately NOT wrapped in {@link withWriteLock}: callers already hold the
+   * (non-re-entrant) lock, so taking it again here would self-deadlock.
+   *
+   * @param label - What the transaction was doing, for the rollback log line.
+   */
+  private async inTransaction(label: string, body: () => Promise<void>): Promise<void> {
+    this.ensureInitialized();
+    await this.db!.beginTransaction();
+    try {
+      await body();
+      await this.db!.commit();
+    } catch (error) {
+      try {
+        await this.db!.rollback();
+      } catch (rollbackError) {
+        log('Rollback after %s failure was a no-op: %s', label, rollbackError);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Wire (or clear, with null) the single listener notified after every committed
+   * `CadreControl.CadrePeer` row write.
+   *
+   * At most one listener: a ControlDatabase instance belongs to exactly one
+   * {@link CadreNode}, which wires this in `start()` and clears it on teardown. A
+   * second call replaces the first rather than fanning out, so a stale node can
+   * never keep receiving notifications for a database it no longer owns.
+   */
+  setMembershipChangeListener(listener: MembershipChangeListener | null): void {
+    this.membershipListener = listener;
+  }
+
+  /**
+   * Wire (or clear, with null) the single listener notified after every committed
+   * guarded-table delete. Same ownership contract as
+   * {@link setMembershipChangeListener}: one CadreNode, one listener, a second
+   * call replaces the first.
+   */
+  setGuardedDeleteListener(listener: GuardedDeleteListener | null): void {
+    this.guardedDeleteListener = listener;
+  }
+
+  /**
+   * Run a `CadrePeer` row mutation and notify the membership listener once it has
+   * COMMITTED.
+   *
+   * EVERY `CadrePeer` writer goes through here, with one documented exception
+   * ({@link updateSelfPeerRecord}, which cannot change the snapshot) — that is what makes
+   * the party-membership snapshot refresh automatic rather than a caller obligation. A
+   * writer necessarily holds the target node's ControlDatabase (the `SeedBootstrapService`'s
+   * event callbacks are NOT a viable seam: the temp services `CadreNode.applySeed`/
+   * `dialInvite` build, and services constructed outside `CadreNode` entirely, never get
+   * callbacks wired), so this is the one point on the write path that cannot be bypassed.
+   *
+   * `body` owns its own transaction if it needs one and must COMMIT before returning, so
+   * the notification never makes the listener read uncommitted state. A throwing `body`
+   * propagates and does NOT notify: nothing changed.
+   *
+   * That contract is enforced, not merely documented — see {@link assertCommitBoundary}.
+   *
+   * Runs under {@link withWriteLock}, notification included: with the lock held through
+   * the notify, no other local writer can have a transaction open while the listener
+   * reads, so the listener always sees exactly the committed state it was told about.
+   * The listener itself only READS (it re-materializes the membership snapshot) — a
+   * listener that wrote through a locked method would deadlock.
+   *
+   * Reaches the lock through {@link lockedWithRetry}, so after a transient cluster
+   * failure the WHOLE locked body re-runs — `body` must be atomic and re-runnable (the
+   * contract on {@link withWriteLock}). The notify sits after a successful `body` inside
+   * the same attempt and a throwing attempt never reaches it, so a retried mutation
+   * still notifies exactly once: on the attempt that commits, and not at all on
+   * exhaustion.
+   *
+   * @param reason - Label for the log line only (e.g. `'peer-insert'`).
+   */
+  async mutateCadrePeer<T>(reason: string, body: () => Promise<T>): Promise<T> {
+    this.ensureInitialized();
+    return this.lockedWithRetry(async () => {
+      this.assertCommitBoundary(reason, 'on entry to');
+      const result = await body();
+      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
+   * every other local writer on this ControlDatabase.
+   *
+   * Quereus tracks transaction state per `Database` (`getAutocommit()`), and a write
+   * statement's implicit transaction stays open across the awaits inside `exec`. Two
+   * local writers interleaving mid-statement therefore either trip
+   * {@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
+   * 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
+   * assert.
+   *
+   * Reads are deliberately not locked: they take no transaction of their own, and
+   * serializing them here would let a listener that reads during a notify (see
+   * {@link mutateCadrePeer}) deadlock. The lock is NOT re-entrant — a locked writer's
+   * body must never call another locked public method; the private bodies it composes
+   * ({@link deleteGuardedRow}, {@link inTransaction}) stay bare for exactly that reason.
+   *
+   * NOTE: re-entry fails SILENTLY and PERMANENTLY. A locked body that calls another
+   * locked public method (including a {@link mutateCadrePeer} body, which runs an
+   * arbitrary caller-supplied callback) queues behind its own tail and never resolves —
+   * no error, and it strands the whole write queue, not only that call. There is no
+   * cheap fail-fast: a "held" flag cannot tell re-entry from a legitimately queued
+   * concurrent writer. Compose bare private bodies instead.
+   *
+   * A locked body must also be ATOMIC and RE-RUNNABLE: the public write surface reaches
+   * this lock through {@link lockedWithRetry}, which re-runs the WHOLE body after a
+   * transient cluster failure. Atomic holds for every body today — one statement, or
+   * wrapped in {@link inTransaction} — so a failed attempt leaves nothing half-applied;
+   * re-runnable means a retry re-runs the body's reads too, which is what makes it safe.
+   * Signatures and stamp ids minted OUTSIDE the body are deliberately NOT re-minted per
+   * attempt: a retry re-presents the exact signed message the first attempt presented.
+   */
+  async withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
+    // Chain behind the current tail regardless of how it settled, then park a
+    // swallowed copy as the new tail so one failed write never poisons the queue.
+    const run = this.writeQueue.then(fn, fn);
+    this.writeQueue = run.then(() => undefined, () => undefined);
+    return run;
+  }
+
+  /**
+   * {@link withWriteLock} plus the bounded transient-failure retry
+   * ({@link retryControlWrite}) — the wrapper the whole public write surface goes
+   * through, so a control write that failed because the cluster cohort did not answer is
+   * re-presented a moment later instead of surfacing to ~19 callers that are not
+   * uniformly written to retry.
+   *
+   * 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. 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
+   * {@link execWrite}, whose {@link ensureInitialized} would reject it. The write queue is
+   * necessarily empty at that point, so the lock is uncontended there; it is taken anyway
+   * rather than carving out a lockless path. It is also the ONLY caller that passes a
+   * `policy` — everything else takes the default, whose classifier and attempt count are
+   * unchanged by that call site existing.
+   *
+   * `label` names the operation in this loop's debug lines and nothing else
+   * ({@link ControlWriteRetryOptions.label}). Every call site in this class supplies one:
+   * several writes retry CONCURRENTLY in a real party, so an unlabelled line cannot be
+   * attributed to a write — keep new call sites labelled.
+   */
+  private lockedWithRetry<T>(fn: () => Promise<T>, policy: ControlWriteRetryOptions = {}, label?: string): Promise<T> {
+    // The label lands LAST so a call site's own name survives both the policy and the
+    // spec-injected pacing; it changes log attribution only, never behaviour.
+    return retryControlWrite(
+      () => this.withWriteLock(fn),
+      { ...policy, ...this.controlWriteRetryPacing, ...(label !== undefined ? { label } : {}) }
+    );
+  }
+
+  /**
+   * One-statement local write, serialized by {@link withWriteLock} and retried on a
+   * transient cluster failure via {@link lockedWithRetry}. Prefer this over a bare
+   * `getDatabase().exec` so a new writer cannot forget the lock — the hazard
+   * {@link assertCommitBoundary} can only catch after the fact.
+   *
+   * Public so `SeedBootstrapService`'s direct `CadrePeer`/`DeviceToken` SQL writes go
+   * through the same seam. Must NOT be called from inside an already-locked body (the
+   * lock is not re-entrant); such a caller uses a bare `getDatabase().exec` instead.
+   *
+   * `label` names the write in the retry loop's debug lines (see {@link lockedWithRetry});
+   * optional only because it is log-only, but every caller in this repo passes one.
+   */
+  execWrite(sql: string, params?: SqlParameters, label?: string): Promise<void> {
+    this.ensureInitialized();
+    return this.lockedWithRetry(() => this.db!.exec(sql, params), {}, label);
+  }
+
+  /**
+   * Throw unless the database sits at a committed boundary — `getAutocommit()` is false
+   * exactly while a transaction is open.
+   *
+   * Both ends of a {@link mutateCadrePeer} body are checked, because either open
+   * transaction would notify a listener that then reads PRE-commit state and materializes
+   * a membership snapshot silently missing the write it was told about:
+   *
+   * - open on entry: the wrapper sits INSIDE an enclosing transaction and must be moved
+   *   out to enclose that outer commit.
+   * - open on return: the body opened a transaction and never committed it.
+   *
+   * Neither is reachable from today's callers, so this is a fail-fast guard on a future
+   * mistake rather than a live code path.
+   *
+   * NOTE: `getAutocommit()` reports the whole `Database`, not this call. Local writers
+   * serialize through {@link withWriteLock}, so with every writer locked this can only
+   * trip on the two misuses above. A writer that bypasses the lock (a new method that
+   * forgets it, or raw `getDatabase().exec` outside a locked wrapper) re-opens the
+   * concurrent-writer window, and this assert is what catches it — it throws instead of
+   * silently joining the other write's transaction.
+   */
+  private assertCommitBoundary(reason: string, where: string): void {
+    if (this.db!.getAutocommit()) {
+      return;
+    }
+    throw new Error(
+      `mutateCadrePeer(${reason}): a transaction is open ${where} the mutation body — a ` +
+      'CadrePeer write must commit before the membership listener runs; move the ' +
+      'mutateCadrePeer wrapper out to enclose the commit'
+    );
+  }
+
+  /**
+   * Best-effort notify. A listener that throws is logged and swallowed: the write has
+   * already committed, and it must never be reported as failed because a downstream
+   * snapshot refresh did. A null listener (no `CadreNode` attached — e.g. the service
+   * unit tests drive a bare control DB) is a silent no-op.
+   */
+  private async notifyMembershipChanged(reason: string): Promise<void> {
+    if (!this.membershipListener) {
+      return;
+    }
+    try {
+      await this.membershipListener(reason);
+    } catch (error) {
+      log('Membership change listener failed (%s): %s', reason, error);
+    }
+  }
+
+  /**
+   * Insert an owner-signed `FormationInvite` (open invitation token).
+   *
+   * The invite is the on-network record that later authorizes an
+   * owner-signature-FREE `Strand` creation: an invited cadre peer redeems it
+   * by inserting a matching `FormationUsage` row (see {@link redeemInvitation}),
+   * which satisfies the consent branch of `Strand.AuthorizedInsert`.
+   *
+   * Like {@link insertStrand}/{@link insertValidationKey}, the owner signs the
+   * canonical row-bound authorization message (see {@link buildAuthorizationMessage})
+   * over (Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId) — NOT a
+   * bare stamp — so the signature is bound to this invite's contents and cannot be
+   * transplanted onto an attacker-chosen row. The StampId is persisted as a unique
+   * column for single-use anti-replay. `FormationInvite.AuthorizedInsert` gates insert
+   * over an `'add'`-tagged digest; deletes verify a DISTINCT `'remove'`-tagged digest
+   * (`AuthorizedDelete`), so this insert approval can never be replayed as a revocation.
+   *
+   * `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.
+   * 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,
+   * because it has a subquery) CHECK sees AFTER column coercion: TotalUses becomes a
+   * decimal string (`String(totalUses)` ⇔ `cast(new.TotalUses as text)`) and ExpiresAt
+   * becomes the engine's canonical `PlainDateTime` string — sourced here from
+   * {@link canonicalDatetime} (a `select datetime(?)` round-trip) rather than a hand-rolled
+   * ISO formatter, so signer and verifier agree exactly. A null ExpiresAt / TotalUses /
+   * ValidationUrl signs as `''`, matching the schema's `coalesce(..., '')`.
+   *
+   * @param token - Invitation token (the `FormationInvite` primary key)
+   * @param sAppId - The sApp a redeemed strand will use
+   * @param ownerKey - Public key of the authorizing owner
+   * @param signMessage - ed25519-signs the raw message bytes (no pre-hash),
+   *   returning a base64url signature — the same callback shape {@link insertStrand} uses
+   * @param options - Optional `expiresAtMs` (epoch ms), `totalUses`, `validationUrl`,
+   *   `strandId` (bind to a pre-existing host strand for provision-then-record)
+   */
+  async insertFormationInvite(
+    token: string,
+    sAppId: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string,
+    options: { expiresAtMs?: number; totalUses?: number; validationUrl?: string; strandId?: string } = {}
+  ): Promise<void> {
+    this.ensureInitialized();
+    log('Inserting formation invite: %s', token);
+
+    const stampId = generateStampId(this.config.libp2pNode.peerId.toString());
+
+    // Build each bound field exactly as the deferred CHECK sees it post-coercion:
+    //   - ExpiresAt: engine-canonical datetime string (or '' when absent), sourced from
+    //     the engine so it byte-matches the column's stored/coerced form.
+    //   - TotalUses: decimal string via String(...) (⇔ cast(new.TotalUses as text)), '' when absent.
+    //   - ValidationUrl: the url or '' when absent.
+    //   - StrandId: the host strand id or '' when absent (text column, no coercion).
+    const expiresAtCanonical = options.expiresAtMs == null
+      ? null
+      : await canonicalDatetime(this.db!, options.expiresAtMs);
+    const expiresAtField = expiresAtCanonical ?? '';
+    const totalUsesField = options.totalUses == null ? '' : String(options.totalUses);
+    const validationUrlField = options.validationUrl ?? '';
+    const strandIdField = options.strandId ?? '';
+
+    // Field order MUST match the schema's FormationInvite `AuthorizedInsert` verify:
+    // Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId.
+    const message = buildAuthorizationMessage('CadreControl.FormationInvite', 'add', [
+      token, sAppId, expiresAtField, totalUsesField, validationUrlField, strandIdField, stampId,
+    ]);
+    const signature = signMessage(message);
+
+    // 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 (?, ?, ?, ?, ?, ?, ?)
+    `, [
+      ownerKey, signature,
+      token, sAppId,
+      expiresAtCanonical,
+      options.totalUses ?? null,
+      options.validationUrl ?? null,
+      options.strandId ?? null,
+      stampId,
+    ], 'formation-invite-insert');
+
+    log('Formation invite inserted: %s', token);
+  }
+
+  /**
+   * Redeem a `FormationInvite` by inserting the `Strand` row and a matching
+   * `FormationUsage` row **atomically, in one transaction**.
+   *
+   * The two CHECK constraints are mutually circular under immediate evaluation:
+   * `Strand.AuthorizedInsert`'s consent branch requires a `FormationUsage` row naming
+   * this strand's `(Id, StampId)`, while `FormationUsage.StrandExists` requires a
+   * `Strand` row matching that same pair — the ONE freshly-minted `strandStampId` below
+   * satisfies both, which is what binds the consent record to this specific strand ROW
+   * (so a later owner-signed, tombstoned removal cannot be undone by re-inserting the
+   * id with a fresh stamp). Both CHECKs contain
+   * subqueries, so Quereus auto-defers them to transaction commit — wrapping both
+   * inserts in a single explicit `begin … commit` lets both deferred CHECKs see
+   * both rows at commit. The strand is authorised WITHOUT an owner signature
+   * (the `FormationUsage` branch of `Strand.AuthorizedInsert`) but still gets a fresh,
+   * unique `StampId` column to satisfy the not-null/unique anti-replay column.
+   *
+   * The seated strand is always open (`'o'`) and keyless — the consent branch of
+   * `Strand.AuthorizedInsert` accepts nothing else, the invite must be UNBOUND
+   * (`FormationInvite.StrandId` null; a bound invite's host strand is owner-provisioned
+   * and only ever record-only, see {@link recordFormationUsage}), and a given strand id
+   * may be consent-seated once, EVER: after an owner-signed removal, re-joining that id
+   * takes an owner re-seat ({@link insertStrand}) plus a bound invite, never another
+   * redemption.
+   *
+   * The usage row is keyed by the joiner's own nonce (`UsageStampId` is the primary key), so
+   * concurrent redemptions of one token never contend for a shared row key — there is no
+   * lost race to retry and no second trip through the approval hook. The invite's seat
+   * budget is checked by COUNT ({@link assertSeatRemains}) inside the write lock, ahead of
+   * the write, so a spent invite is refused by name (`InvitationExhaustedError`) instead of
+   * as the schema cap clause's generic `Authorized` CHECK failure.
+   */
+  async redeemInvitation(params: {
+    token: string;
+    strandId: string;
+    /** The joining peer's own ed25519 public key. Required: it is inside BOTH signed digests (see {@link formationVouchMessage} / {@link formationConsentMessage}). */
+    peerKey: string;
+    disclosure?: string;
+    /** Single-use nonce for this redemption, minted by the JOINER; both signed digests cover it. */
+    usageStampId: string;
+    /** The joiner's signature over the `'consent'` digest — verified by the `PeerConsented` CHECK. */
+    peerSignature: string;
+    nowMs?: number;
+    validationKey?: string;
+    validationSignature?: string;
+    /**
+     * Aborted when the caller has given up. Checked once PER ATTEMPT, inside the write lock,
+     * before that attempt's transaction is opened — never between the two inserts — throwing
+     * {@link FormationAbortedError} with the invite unspent.
+     */
+    signal?: AbortSignal;
+    /**
+     * The invite's seat budget, when the caller already has it in hand (e.g. it already read
+     * the `FormationInvite` row to get here). Passed through to {@link assertSeatRemains} so
+     * the seat check needs no extra read. `undefined` falls back to a fresh
+     * {@link queryFormationInvite} read; `null` means "no invite row" / unlimited.
+     */
+    totalUses?: number | null;
+  }): Promise<FormationUsageResult> {
+    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();
+    // 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);
+
+    // 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, usageStampId, disclosure, strandId, strandStampId,
+          peerKey, peerSignature, nowMs: nowMs ?? Date.now(),
+          validationKey: validationKey ?? null, validationSignature: validationSignature ?? null,
+        });
+      });
+    }, {}, '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. 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.
+   *
+   * The strand's live `StampId` is read first and written onto the usage row:
+   * `FormationUsage.StrandExists` matches the (id, stamp) PAIR, and
+   * `Strand.AuthorizedInsert`'s consent branch reads the same pair back, so a consent
+   * record authorizes exactly the strand ROW it was recorded against. A missing strand
+   * THROWS here rather than being left to the deferred `StrandExists` CHECK — the
+   * ordinary "host strand has not converged yet" case is already reported as `missing`
+   * by {@link ControlFormationUsageRecorder.resolveStrand}, so an absent row at this
+   * point is a genuine race and deserves a named error, not a silent rollback.
+   *
+   * The row is keyed by the joiner's own nonce (`UsageStampId` is the primary key), so this
+   * path — the one production actually races on (a bound invite published by `cadre-web` /
+   * `cadre-phone` is always record-only) — never contends with another redemption for a
+   * shared row key: there is no lost race to retry and no second trip through the approval
+   * hook. The invite's seat budget is checked by COUNT ({@link assertSeatRemains}) inside
+   * the write lock, ahead of the write.
+   */
+  async recordFormationUsage(params: {
+    token: string;
+    strandId: string;
+    /** The joining peer's own ed25519 public key. Required: it is inside BOTH signed digests (see {@link formationVouchMessage} / {@link formationConsentMessage}). */
+    peerKey: string;
+    disclosure?: string;
+    /** Single-use nonce for this redemption, minted by the JOINER; both signed digests cover it. */
+    usageStampId: string;
+    /** The joiner's signature over the `'consent'` digest — verified by the `PeerConsented` CHECK. */
+    peerSignature: string;
+    nowMs?: number;
+    validationKey?: string;
+    validationSignature?: string;
+    /**
+     * Aborted when the caller has given up. Checked inside the write lock, before the insert
+     * is issued, throwing {@link FormationAbortedError} with the invite unspent. Never
+     * checked once the insert has been issued.
+     */
+    signal?: AbortSignal;
+    /**
+     * The invite's seat budget, when the caller already has it in hand (e.g. it already read
+     * the `FormationInvite` row to get here). Passed through to {@link assertSeatRemains} so
+     * the seat check needs no extra read. `undefined` falls back to a fresh
+     * {@link queryFormationInvite} read; `null` means "no invite row" / unlimited.
+     */
+    totalUses?: number | null;
+  }): Promise<FormationUsageResult> {
+    this.ensureInitialized();
+    const {
+      token, strandId, disclosure = '',
+      peerKey, peerSignature, usageStampId, nowMs, validationKey, validationSignature, signal,
+      totalUses,
+    } = params;
+
+    // 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);
+    }
+
+    // Ordering inside the locked body is contractual — abort check, seat check, write — see
+    // the matching note in redeemInvitation.
+    await this.lockedWithRetry(async () => {
+      if (signal?.aborted) {
+        throw new FormationAbortedError(token, 'usage recording');
+      }
+      await this.assertSeatRemains(token, totalUses);
+      await this.execFormationUsageInsert({
+        token, usageStampId, disclosure, strandId, strandStampId,
+        peerKey, peerSignature, nowMs: nowMs ?? Date.now(),
+        validationKey: validationKey ?? null, validationSignature: validationSignature ?? null,
+      });
+    }, {}, 'formation-usage');
+
+    log('Recorded formation usage: token=%s strand=%s (stamp %s)', token, strandId, usageStampId);
+    return { usageStampId };
+  }
+
+  /**
+   * Refuse a redemption that would consume a seat the invite does not have.
+   *
+   * 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,
+   * non-racing path. `undefined` falls back to a fresh read here.
+   *
+   * NOTE: a passed-in budget is a value read BEFORE the write lock (and, for a validating
+   * 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 instead.
+   */
+  private async assertSeatRemains(
+    token: string,
+    knownTotalUses: number | null | undefined,
+  ): Promise<void> {
+    // 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
+    // (`FormationInvite where Token = ?`), the shape whose reliability on a networked strand
+    // 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.
+    const totalUses = knownTotalUses !== undefined
+      ? knownTotalUses
+      : (await this.queryFormationInvite(token))?.totalUses ?? null;
+    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. */
+  private async execFormationUsageInsert(opts: {
+    token: string;
+    /** Single-use nonce bound into the approver's signed digest; the row's primary key, so one approval spends once. */
+    usageStampId: string;
+    disclosure: string;
+    strandId: string;
+    /** The live `Strand.StampId` this consent record authorizes (`StrandExists` matches the pair). */
+    strandStampId: string;
+    peerKey: string;
+    peerSignature: string;
+    nowMs: number;
+    validationKey: string | null;
+    validationSignature: string | null;
+  }): Promise<void> {
+    // Derive `context.Now` through the same `canonicalDatetime` transform that
+    // produced the stored `ExpiresAt`, so the deferred CHECK's `FI.ExpiresAt >
+    // context.Now` compares two byte-identical engine-`datetime` strings. The
+    // previous `new Date(nowMs).toISOString()` form differed only by a trailing
+    // `.000Z` (the engine `datetime()` separator is `T`, not a space), which never
+    // flipped the strict `>` against a second-granular `ExpiresAt` — so this is a
+    // 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 (?, ?, ?, ?, ?, ?, ?)
+    `, [
+      nowCanonical, opts.validationKey, opts.validationSignature,
+      opts.token, opts.usageStampId, opts.peerKey,
+      opts.peerSignature, opts.disclosure, opts.strandId, opts.strandStampId,
+    ]);
+  }
+
+  /**
+   * 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.
+   */
+  async queryFormationInvite(token: string): Promise<{
+    token: string;
+    sAppId: string;
+    expiresAtMs: number | null;
+    totalUses: number | null;
+    validationUrl: string | null;
+    strandId: string | null;
+  } | null> {
+    this.ensureInitialized();
+    for await (const row of this.db!.eval(
+      'select Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId from CadreControl.FormationInvite where Token = ?',
+      [token]
+    )) {
+      return {
+        token: row.Token as string,
+        sAppId: row.sAppId as string,
+        expiresAtMs: parseNullableStoredDatetimeMs(row.ExpiresAt as string | number | null),
+        totalUses: (row.TotalUses as number | null) ?? null,
+        validationUrl: (row.ValidationUrl as string | null) ?? null,
+        strandId: (row.StrandId as string | null) ?? null,
+      };
+    }
+    return null;
+  }
+
+  /**
+   * 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: string): Promise<number> {
+    this.ensureInitialized();
+    for await (const row of this.db!.eval(
+      'select count(1) as Count from CadreControl.FormationUsage where Token = ?',
+      [token]
+    )) {
+      return (row.Count as number) ?? 0;
+    }
+    return 0;
+  }
+
+  /**
+   * Is any `FormationInvite` row still redeemable — unexpired AND with usage
+   * below its `TotalUses`? A null `ExpiresAt` never expires and a null
+   * `TotalUses` is unlimited, matching {@link ControlFormationUsageRecorder}'s
+   * per-token semantics (`isTokenValid` / `isTokenUsed`).
+   *
+   * Answers the control-network connection gate's coarse "does this node expect
+   * a stranger?" question, which has no token to ask about. The expiry
+   * comparison is `expiresAtMs <= now` — identical to `isTokenValid`'s — so an
+   * invite the formation handler would reject can never hold the gate open.
+   *
+   * The scan is deliberately not pushed into SQL: nothing else here compares a
+   * stored `datetime` with an inequality, so the parse stays in JS via the
+   * shared {@link parseNullableStoredDatetimeMs}. Only invites that are
+   * unexpired AND use-metered cost a {@link countFormationUsage} read, and an
+   * unlimited-use invite anywhere in the scan short-circuits all of them.
+   */
+  async hasOutstandingFormationInvite(nowMs: number = Date.now()): Promise<boolean> {
+    this.ensureInitialized();
+    // NOTE: scans every FormationInvite row (expired ones included) on the
+    // stranger path of an inbound connection. Cadre-scale invite counts make
+    // that free today; if a long-lived cadre accumulates thousands of expired
+    // invites and inbound upgrades slow down, add an expiry-ordered index or
+    // prune redeemed/expired rows.
+    const metered: Array<{ token: string; totalUses: number }> = [];
+    let unlimitedOutstanding = false;
+    for await (const row of this.db!.eval(
+      'select Token, ExpiresAt, TotalUses from CadreControl.FormationInvite'
+    )) {
+      const expiresAtMs = parseNullableStoredDatetimeMs(row.ExpiresAt as string | number | null);
+      if (expiresAtMs !== null && expiresAtMs <= nowMs) {
+        continue;
+      }
+      const totalUses = (row.TotalUses as number | null) ?? null;
+      if (totalUses === null) {
+        unlimitedOutstanding = true;
+      } else {
+        metered.push({ token: row.Token as string, totalUses });
+      }
+    }
+    if (unlimitedOutstanding) {
+      return true;
+    }
+    for (const invite of metered) {
+      if (await this.countFormationUsage(invite.token) < invite.totalUses) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Close the database and cleanup resources.
+   *
+   * Drains the local-write chain first: {@link withWriteLock} can park a write behind
+   * others across an await, and a queued closure evaluates `this.db!` only when it
+   * finally runs — so nulling the handle out from under it would throw a TypeError on a
+   * null handle instead of committing. The tail never rejects (it swallows both
+   * outcomes), so the bare await is safe.
+   *
+   * NOTE: this makes `close()` wait on a stuck write. Acceptable today — every locked
+   * body is a bounded local `exec` — but revisit (bounded drain, or abandon after a
+   * deadline) if a write can ever hang.
+   */
+  async close(): Promise<void> {
+    await this.writeQueue;
+    if (this.collectionFactory) {
+      await this.collectionFactory.shutdown();
+      this.collectionFactory = null;
+    }
+    if (this.db) {
+      void this.db.close();
+      this.db = null;
+    }
+    this.initialized = false;
+    log('ControlDatabase closed');
+  }
+
+  private ensureInitialized(): void {
+    if (!this.initialized || !this.db) {
+      throw new Error('ControlDatabase not initialized. Call initialize() first.');
+    }
+  }
+}
+