@serfab/cadre-core 0.13.0 → 1.0.0

package/src/control-database.ts

@@ -7,7 +7,7 @@ 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 type { StrandRow, PeerAddressRecord, CadrePeerRow, RevocationRow, RevocationLedgerOpenResult, 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';
@@ -15,9 +15,10 @@ import type { ControlTable, RevocableTable, ControlDomain, ControlAction } from
 import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
 import { retryControlWrite, SCHEMA_INIT_RETRY_POLICY } from './control-write-retry.js';
 import type { ControlWriteRetryOptions } from './control-write-retry.js';
-import { retryControlRead } from './control-read-retry.js';
+import { isCohortUnreachableRead, retryControlRead } from './control-read-retry.js';
 import type { ControlReadRetryOptions } from './control-read-retry.js';
 import { chainMessages } from './control-retry.js';
+import type { ControlRetryAbandonment } from './control-retry.js';
 
 export type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
 
@@ -291,6 +292,7 @@ const GUARDED_KEY_COLUMN: Readonly<Record<RevocableTable, GuardedKeyColumn>> = {
   CadrePeer: 'PeerId',
   ValidationKey: 'Key',
   Strand: 'Id',
+  StrandPartyKey: 'Id',
   DeviceToken: 'PeerId',
 };
 
@@ -320,20 +322,48 @@ const STRAND_ID_CONFLICT = /UNIQUE constraint failed: Strand\.Id\b/i;
  * reword reddens there.
  */
 export function isStrandIdConflict(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
-  }
-  return chainMessages(error).some(message => STRAND_ID_CONFLICT.test(message));
+  return errorChainMatches(error, STRAND_ID_CONFLICT);
+}
+
+/**
+ * The one `CadreControl.Revocation` row that retires nothing, filed once by an owner
+ * ({@link ControlDatabase.openRevocationLedger}) so the table is never a never-written
+ * block. The schema's table comment says why that matters and why the row can never read
+ * as a retirement; `RowIsGone` pins this exact triple.
+ */
+export const REVOCATION_LEDGER_MARKER = {
+  tableName: 'Revocation',
+  rowKey: 'ledger',
+  stampId: 'opened',
+} as const;
+
+/**
+ * The rejection a second insert of the ledger marker produces: the optimystic vtab's
+ * primary-key wording (see {@link STRAND_ID_CONFLICT}), naming both columns of
+ * `Revocation`'s composite key. Applied only to the marker's own insert, whose key
+ * ('Revocation', 'opened') no row but the marker can hold (`RowIsGone`), and `Revocation`
+ * has no other unique constraint.
+ */
+const REVOCATION_LEDGER_CONFLICT = /UNIQUE constraint failed: Revocation\.TableName, Revocation\.StampId\b/i;
+
+/** Did the ledger marker's insert fail because the marker is already filed? Text-matched, failing closed, like {@link isStrandIdConflict}. */
+function isRevocationLedgerConflict(error: unknown): boolean {
+  return errorChainMatches(error, REVOCATION_LEDGER_CONFLICT);
+}
+
+/** Whether any message in `error`'s cause chain matches `pattern`; false for a non-`Error`. */
+function errorChainMatches(error: unknown, pattern: RegExp): boolean {
+  return error instanceof Error && chainMessages(error).some(message => pattern.test(message));
 }
 
 /**
  * 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.
+ * `CadrePeer.AuthorizedDelete` in the schema). `Strand` and `StrandPartyKey` are
+ * deliberately absent: their rows carry `MemberPrivateKey` / `PrivateKey` — party
+ * secrets 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];
@@ -379,6 +409,20 @@ export type RevokedRowRef = Omit<RevocationRow, 'reissuedAt'>;
  */
 export type GuardedDeleteListener = (revocation: RevokedRowRef) => void;
 
+/**
+ * Notified when the control-write retry funnel GIVES UP on a local control write — the
+ * classifier declined the failure as non-transient, or every attempt / the elapsed budget
+ * ran out. Carries the operation label, how far it got and the error
+ * ({@link ControlRetryAbandonment}).
+ *
+ * The seam that stops an abandoned BACKGROUND write from disappearing: those are `void`-ed
+ * with a `debug`-only catch, and that namespace is off unless somebody set `DEBUG=`, so
+ * without this the write, the operator and the embedding app all learn nothing. Synchronous
+ * and must not throw — the retry loop swallows and logs if it does, because the write's own
+ * failure is what has to reach the caller.
+ */
+export type ControlWriteAbandonedListener = (abandonment: ControlRetryAbandonment) => void;
+
 export interface ControlDatabaseConfig {
   /** Party ID for the control network */
   partyId: string;
@@ -405,8 +449,16 @@ export class ControlDatabase {
   private initialized = false;
   private membershipListener: MembershipChangeListener | null = null;
   private guardedDeleteListener: GuardedDeleteListener | null = null;
+  private controlWriteAbandonedListener: ControlWriteAbandonedListener | null = null;
   /** Tail of the local-write chain — see {@link withWriteLock}. */
   private writeQueue: Promise<unknown> = Promise.resolve();
+  /**
+   * Locked write bodies currently running (see {@link runWriteBody}); what
+   * {@link readRowsOnce} consults to route an unlocked read around a write that has
+   * started but not yet opened its transaction. At most 1 while every writer takes the
+   * lock — a count rather than a flag so it stays truthful if that ever stops holding.
+   */
+  private runningWriteBodies = 0;
   /**
    * 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
@@ -507,8 +559,8 @@ export class ControlDatabase {
     // 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
+    // start now reaches the backend 45 times (9 tables + 1 index, 20 distinct blocks
+    // — dominated by its genuine writes), a warm restart 13, 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
@@ -629,11 +681,33 @@ export class ControlDatabase {
    * opted in, `control-write-degraded-cohort-member` could no longer observe a sibling
    * publishing its own `CadrePeer` row and failed at suite setup on two runs out of two.
    *
-   * `getAutocommit()` reports the whole `Database` rather than this call (the same
-   * property {@link assertCommitBoundary} leans on), which is exactly what is wanted:
-   * false means some writer's transaction is open, which is the only situation where a
-   * read would have blocked. The check races that writer harmlessly in both directions
-   * — losing it either reads normally (today's behaviour) or reads committed state.
+   * "A write is in flight" is {@link writeInFlight}, and it needs TWO signals because a
+   * write is invisible to `getAutocommit()` for part of its life. `Database.exec` takes
+   * the exec mutex first; the implicit transaction — the moment `getAutocommit()` turns
+   * false — opens only after the write has acquired the mutex, planned the statement,
+   * and awaited `begin()` on every connection. While the write WAITS for the mutex (a
+   * serialized read holds it, say) it still reports autocommit, so a read routed on
+   * `getAutocommit()` alone queued behind the write and answered only after its whole
+   * commit — tens of seconds against a slow cohort member, which is what timed out the
+   * degraded-cohort scenario's `isMember` read (verified against the engine directly;
+   * `complete/control-read-queues-behind-a-write-waiting-for-the-database`). So an
+   * UNLOCKED read also takes the committed path while any locked write body is running
+   * ({@link runningWriteBodies}), which covers that queued window and everything else a
+   * body does before its transaction opens. A read issued INSIDE a locked body
+   * (`underWriteLock`) must not: that body is the one being counted, and its guard reads
+   * need the refreshing path — so it keeps the transaction-only test.
+   *
+   * Both signals are sampled synchronously just before `eval`, which claims its place
+   * on the mutex in that same tick, so the only race left is a body starting or ending
+   * in between: a body that starts after the sample queues its statements BEHIND this
+   * read, and one that ended before it has nothing left to queue behind.
+   *
+   * Residual gaps, both of which still queue a read behind a write:
+   * - an EXPLICIT transaction ({@link inTransaction}) disqualifies the committed path in
+   *   Quereus itself, so a read overlapping such a body's `COMMIT` falls back to the
+   *   serialized path and waits for it;
+   * - a writer that bypasses {@link withWriteLock} is not counted (in this repo only
+   *   `reference-app-web`'s deliberately-rejected diagnostics insert does).
    *
    * What a committed read gives up is observing a write that has not finished
    * committing, and that is safe for every caller here: an AWAITED write is committed by
@@ -641,14 +715,23 @@ export class ControlDatabase {
    * open explicit transaction and stays serialized, so it still sees its own
    * transaction's rows. A read after an UNAWAITED write on this database would be wrong
    * — no such caller exists, and {@link withWriteLock} is what keeps it that way.
+   *
+   * NOTE: counting whole bodies widens the stale (non-refreshing) window from "a
+   * transaction is open" to "a locked body is running", which adds a body's pre-transaction
+   * work and its post-commit tail (a `CadrePeer` write's membership-listener read). The
+   * slow part of a write against a degraded cohort is its commit, already inside the old
+   * window, so the added time is short; if a poller for replicated rows ever starves
+   * behind back-to-back local writes, narrow the count to the span from a body's first
+   * statement to its transaction opening.
    */
-  private async readRowsOnce(sql: string, params?: SqlParameters): Promise<Record<string, SqlValue>[]> {
+  private async readRowsOnce(sql: string, params: SqlParameters | undefined, underWriteLock: boolean): Promise<Record<string, SqlValue>[]> {
     let iterator: AsyncIterableIterator<Record<string, SqlValue>>;
-    if (this.db!.getAutocommit()) {
-      iterator = this.db!.eval(sql, params);
-    } else {
-      log('read-eval: a write is in flight, asking for a committed read: %s', sql);
+    if (this.writeInFlight(underWriteLock)) {
+      log('read-eval: a write is in flight (%s), asking for a committed read: %s',
+        this.db!.getAutocommit() ? 'locked body running, no transaction open yet' : 'transaction open', sql);
       iterator = this.db!.eval(sql, params, { readConcurrency: 'committed' });
+    } else {
+      iterator = this.db!.eval(sql, params);
     }
     const rows: Record<string, SqlValue>[] = [];
     for await (const row of iterator) {
@@ -657,6 +740,20 @@ export class ControlDatabase {
     return rows;
   }
 
+  /**
+   * Whether a control read should ask for a committed read — see {@link readRowsOnce}.
+   * `getAutocommit()` reports the whole `Database` (the property
+   * {@link assertCommitBoundary} leans on), so false means some writer's transaction is
+   * open. An unlocked read also counts a running locked body that has not opened its
+   * transaction yet; a read inside such a body does not, since it is that body.
+   */
+  private writeInFlight(underWriteLock: boolean): boolean {
+    if (!this.db!.getAutocommit()) {
+      return true;
+    }
+    return !underWriteLock && this.runningWriteBodies > 0;
+  }
+
   /**
    * {@link readRowsOnce} plus the bounded transient-failure retry
    * ({@link retryControlRead}) — the funnel every UNLOCKED control read goes through, so a
@@ -672,8 +769,8 @@ export class ControlDatabase {
    * primary-key lookup or a `count(1)`); nothing streams.
    *
    * Each ATTEMPT is a fresh {@link readRowsOnce} call, so the committed-read opt-in
-   * (`getAutocommit()`) is re-evaluated per attempt — a write can finish between attempts
-   * and change the right answer.
+   * ({@link writeInFlight}) is re-evaluated per attempt — a write can finish between
+   * attempts and change the right answer.
    *
    * The retry's budget ({@link CONTROL_READ_RETRY_BUDGET_MS}, 1.5 s) is deliberately far
    * under the write funnel's: the tightest caller deadline over a control read is the
@@ -706,13 +803,20 @@ export class ControlDatabase {
     label: string,
     retry = true
   ): Promise<Record<string, SqlValue>[]> {
+    // `retry: false` marks the reads that may run inside a locked write body, which is
+    // also what readRowsOnce's committed-read routing must know (see writeInFlight).
+    // NOTE: the membership-gate refresh passes it on EVERY trigger, including the
+    // unlocked ones (start, reconcile, seed-applied), so those keep the transaction-only
+    // routing and can still queue behind a write waiting for the exec mutex (as before this
+    // routing existed). Tolerable while its awaiting callers (reconcile, applySeed) carry no
+    // tight deadline; if one ever does, pass the locked/unlocked distinction through instead.
     if (!retry) {
-      return this.readRowsOnce(sql, params);
+      return this.readRowsOnce(sql, params, true);
     }
     // The label lands LAST so the call site's name survives the spec-injected pacing —
     // it changes log attribution only, never behaviour (same layering as lockedWithRetry).
     return retryControlRead(
-      () => this.readRowsOnce(sql, params),
+      () => this.readRowsOnce(sql, params, false),
       { ...this.controlReadRetryPacing, label }
     );
   }
@@ -844,10 +948,12 @@ export class ControlDatabase {
    * {@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: runs a second query (the retired-stamp set) per call, on the membership-gate
+   * refresh path. Its cost is storage consults, not rows (see {@link queryRevokedStamps}):
+   * while `Revocation` has never been written every call consults the cohort about it, and
+   * the ledger marker ({@link openRevocationLedger}) is what makes it a held block. Folding
+   * the exclusion into one statement would not help (it reads the same block), and caching
+   * the set would hide a tombstone arriving by replication.
    *
    * 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`),
@@ -966,6 +1072,30 @@ export class ControlDatabase {
     return this.queryStampId('Strand', strandId);
   }
 
+  /** `StrandPartyKey` stamp nonce — bound into {@link deleteStrandPartyKey}'s remove digest. */
+  queryStrandPartyKeyStampId(strandId: string): Promise<string | null> {
+    return this.queryStampId('StrandPartyKey', strandId);
+  }
+
+  /**
+   * Read THIS party's own strand membership private key (base64 protobuf; decode with
+   * `strandMemberKeyPair`) for one strand, or null when no `StrandPartyKey` row exists.
+   * The identity source the closed-strand founder bootstrap derives its `Member.Key` /
+   * `Manager.MemberKey` from — deliberately NOT `Strand.MemberPrivateKey`, the
+   * strand-wide read secret every joining party receives.
+   */
+  async queryStrandPartyKey(strandId: string): Promise<string | null> {
+    this.ensureInitialized();
+    for (const row of await this.readRows(
+      'select PrivateKey from CadreControl.StrandPartyKey where Id = ?',
+      [strandId],
+      'strand-party-key'
+    )) {
+      return (row.PrivateKey as string | null) ?? null;
+    }
+    return null;
+  }
+
   /** `ValidationKey` stamp nonce — bound into {@link deleteValidationKey}'s remove digest. */
   queryValidationKeyStampId(key: string): Promise<string | null> {
     return this.queryStampId('ValidationKey', key);
@@ -983,9 +1113,18 @@ export class ControlDatabase {
    * ({@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.
+   * NOTE: the per-call cost that matters is the storage layer's, not the row count. While
+   * `Revocation` has never been written, this node does not hold its block, and Optimystic
+   * consults a block's cohort on every read of a block it does not hold: 1 consult per
+   * call (measured), each a round trip to every other member on a multi-machine party. The
+   * ledger marker ({@link openRevocationLedger}) ends that — a held block is re-consulted
+   * at most once per read-repair window (10 s). Do not cache the set instead: a cache
+   * cannot see a tombstone arriving by replication, so it would delay a revocation. The
+   * row count only grows (append-only) but stays small while removals are rare; revisit if
+   * removals become routine and the scan itself shows up in a profile.
+   *
+   * An isolated node that has never received the `Revocation` block reads it as holding no
+   * revocations instead of throwing — see {@link readRevokedStampRows}.
    *
    * `retry: false` is forwarded by {@link queryCadrePeers} for the one caller that reads
    * under the write lock — see that method's note.
@@ -993,24 +1132,77 @@ export class ControlDatabase {
   async queryRevokedStamps(tableName: RevocableTable, retry = true): Promise<Set<string>> {
     this.ensureInitialized();
     const stamps = new Set<string>();
-    for (const row of await this.readRows('select StampId from CadreControl.Revocation where TableName = ?', [tableName], 'revoked-stamps', retry)) {
+    for (const row of await this.readRevokedStampRows(tableName, retry)) {
       stamps.add(row.StampId as string);
     }
     return stamps;
   }
 
+  /**
+   * The `Revocation` scan behind {@link queryRevokedStamps}, answering NO ROWS when the read
+   * fails `cohort-unreachable` ({@link isCohortUnreachableRead}): this node does not hold
+   * the block and could ask no other cohort member about it. Every other failure rethrows.
+   * The retry in {@link readRows} runs first, so a node whose connectivity returns within
+   * the read budget still gets the real answer.
+   *
+   * Without this, a machine cut off from every other machine in its party before it ever
+   * received the block — the block does not exist anywhere until the owner files the
+   * ledger marker ({@link openRevocationLedger}) on a connected reconcile pass — cannot
+   * answer ANY membership, peer-record or device-token lookup, although it holds those
+   * rows locally.
+   *
+   * NOTE: accepted tradeoff — `cohort-unreachable` on THIS read, and only this read, is
+   * treated as "no revocations known". It adds no fail-open that does not already exist:
+   * an isolated node holding a stale `Revocation` block is served it silently (the consult
+   * reaches nobody, so no doubt is raised), and a revocation authored elsewhere is invisible
+   * to it either way until connectivity returns. The other reasons still throw:
+   * `peers-unreachable` means part of the cohort answered, and `claimed-elsewhere` /
+   * `unmaterializable` mean the block exists, so an empty answer could admit a revoked
+   * member. Do not move this into {@link readRows}: an empty answer is known-safe only for
+   * a table whose empty state is its never-written state; decide any other table in its
+   * own reader. Revisit if optimystic starts reporting a held-but-stale block distinctly
+   * (the equivalence above then breaks), or if revocation enforcement must fail closed
+   * under partition.
+   *
+   * NOTE: an isolated node pays the whole read retry (up to
+   * `CONTROL_READ_RETRY_BUDGET_MS`, plus the slow attempt that exhausted it) before this
+   * answers, and {@link queryPeerRecord} then issues its row scan on top. If an isolated
+   * node's lookups are seen exceeding the admission gate's 2 s deadline
+   * (`ADMISSION_DECISION_TIMEOUT_MS`), skip the retry for this read when the first attempt
+   * fails `cohort-unreachable`.
+   */
+  private async readRevokedStampRows(tableName: RevocableTable, retry: boolean): Promise<Record<string, SqlValue>[]> {
+    try {
+      return await this.readRows('select StampId from CadreControl.Revocation where TableName = ?', [tableName], 'revoked-stamps', retry);
+    } catch (error) {
+      if (!isCohortUnreachableRead(error)) {
+        throw error;
+      }
+      log('revoked-stamps(%s): no cohort member reachable and the Revocation block is not held here; reading as no revocations known: %s', tableName, error);
+      return [];
+    }
+  }
+
   /**
    * 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.
+   * it, and by the reap sweep ({@link reapRevokedRows}). 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.
+   *
+   * Skips the ledger marker ({@link REVOCATION_LEDGER_MARKER}): it retires nothing, so
+   * neither sweep may reap or re-sign it, and skipping it keeps `RevocationRow.tableName`
+   * a {@link RevocableTable}. Filtered on `TableName` alone, in TypeScript: `RowIsGone`
+   * admits no other row under `'Revocation'`.
    */
   async queryRevocations(): Promise<RevocationRow[]> {
     this.ensureInitialized();
     const rows: RevocationRow[] = [];
     for (const row of await this.readRows('select TableName, RowKey, StampId, ReissuedAt from CadreControl.Revocation', undefined, 'revocations')) {
+      if (row.TableName === REVOCATION_LEDGER_MARKER.tableName) {
+        continue;
+      }
       rows.push({
         tableName: row.TableName as RevocableTable,
         rowKey: row.RowKey as string,
@@ -1242,6 +1434,15 @@ export class ControlDatabase {
    * The remove digest binds only (Id, StampId) — not Type/MemberPrivateKey — so this
    * works identically for open and closed strands.
    *
+   * When the strand has a `StrandPartyKey` row (this party's own membership identity for
+   * the strand — minted at publish for closed strands), it is deleted IN THE SAME
+   * transaction, with its own `'remove'`-tagged signature and its own `Revocation`
+   * tombstone, so a re-published strand always mints fresh identity and no crash window
+   * can orphan the key row. The party-key delete happens ONLY alongside an actual strand
+   * row delete: a `StrandPartyKey` row with no local `Strand` row is a JOINER's identity
+   * (the joiner never holds the strand row) and is not this method's to destroy — that
+   * is {@link deleteStrandPartyKey}'s.
+   *
    * A no-op (no throw, no tombstone) when the row does not exist — `false` then, `true`
    * when a row was actually removed.
    */
@@ -1250,7 +1451,141 @@ export class ControlDatabase {
     ownerKey: string,
     signMessage: (message: Uint8Array) => string
   ): Promise<boolean> {
-    return this.lockedWithRetry(() => this.deleteGuardedRow('Strand', strandId, ownerKey, signMessage), {}, 'strand-delete');
+    return this.lockedWithRetry(() => this.deleteStrandAndPartyKey(strandId, ownerKey, signMessage), {}, 'strand-delete');
+  }
+
+  /**
+   * The locked body of {@link deleteStrand}: the `Strand` delete + tombstone, plus — when
+   * one exists — the strand's `StrandPartyKey` delete + tombstone, all in ONE
+   * transaction. A two-table sibling of {@link deleteGuardedRow} (see that method for the
+   * per-clause security rationale: stamp read inside the locked body, `'remove'`-tagged
+   * digests, mandatory same-transaction tombstones); kept separate rather than
+   * generalizing the shared body because no other guarded table has a companion row.
+   *
+   * NOTE: that duplication is a drift risk, not a correctness one — a future tightening of
+   * {@link deleteGuardedRow}'s discipline (an extra precondition, a different digest shape)
+   * will NOT reach this body. Grep for both when you change either; if a second guarded
+   * table ever gains a companion row, generalize instead of copying this a third time.
+   *
+   * Not wrapped in {@link withWriteLock} — the caller holds the (non-re-entrant) lock.
+   */
+  private async deleteStrandAndPartyKey(
+    strandId: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    this.ensureInitialized();
+    // retry: false — these reads run inside the locked write body (see queryStampId's NOTE).
+    const strandStamp = await this.queryStampId('Strand', strandId, false);
+    if (strandStamp === null) {
+      log('delete Strand: no row for %s (already absent)', strandId);
+      return false;
+    }
+    const partyKeyStamp = await this.queryStampId('StrandPartyKey', strandId, false);
+
+    const strandSignature = signMessage(
+      buildAuthorizationMessage('CadreControl.Strand', 'remove', [strandId, strandStamp]));
+    const strandRevocationSignature = signMessage(
+      buildAuthorizationMessage('CadreControl.Revocation', 'remove', ['Strand', strandId, strandStamp]));
+    const partyKeySignature = partyKeyStamp === null ? null : signMessage(
+      buildAuthorizationMessage('CadreControl.StrandPartyKey', 'remove', [strandId, partyKeyStamp]));
+    const partyKeyRevocationSignature = partyKeyStamp === null ? null : signMessage(
+      buildAuthorizationMessage('CadreControl.Revocation', 'remove', ['StrandPartyKey', strandId, partyKeyStamp]));
+
+    await this.inTransaction('delete Strand', async () => {
+      await this.db!.exec(`
+        delete from CadreControl.Strand
+          with context OwnerKey = ?, Signature = ?
+          where Id = ?
+      `, [ownerKey, strandSignature, strandId]);
+      await this.db!.exec(`
+        insert into CadreControl.Revocation (TableName, RowKey, StampId, ReissuedAt)
+          with context OwnerKey = ?, Signature = ?
+          values ('Strand', ?, ?, 0)
+      `, [ownerKey, strandRevocationSignature, strandId, strandStamp]);
+      if (partyKeyStamp !== null) {
+        await this.db!.exec(`
+          delete from CadreControl.StrandPartyKey
+            with context OwnerKey = ?, Signature = ?
+            where Id = ?
+        `, [ownerKey, partyKeySignature, strandId]);
+        await this.db!.exec(`
+          insert into CadreControl.Revocation (TableName, RowKey, StampId, ReissuedAt)
+            with context OwnerKey = ?, Signature = ?
+            values ('StrandPartyKey', ?, ?, 0)
+        `, [ownerKey, partyKeyRevocationSignature, strandId, partyKeyStamp]);
+      }
+    });
+
+    log('Strand deleted: %s (stamp retired%s)', strandId,
+      partyKeyStamp === null ? '' : '; party key deleted, stamp retired');
+    this.notifyGuardedDelete({ tableName: 'Strand', rowKey: strandId, stampId: strandStamp });
+    if (partyKeyStamp !== null) {
+      this.notifyGuardedDelete({ tableName: 'StrandPartyKey', rowKey: strandId, stampId: partyKeyStamp });
+    }
+    return true;
+  }
+
+  /**
+   * Insert this party's own strand membership identity key (`StrandPartyKey` row) using
+   * an owner signature.
+   *
+   * Mirrors {@link insertStrand}: the owner signs the canonical row-bound authorization
+   * message over (Id, PrivateKey, StampId) — binding the key material means a captured
+   * approval can only ever reproduce the exact key it approved — and the StampId is
+   * persisted as a unique column for single-use anti-replay.
+   *
+   * @param strandId - The strand this key is the party's identity for.
+   * @param privateKey - The party's ed25519 strand member private key, base64 protobuf
+   *   (same encoding as `Strand.MemberPrivateKey`; mint with `generateStrandMemberKey`).
+   * @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 insertStrandPartyKey(
+    strandId: string,
+    privateKey: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<void> {
+    this.ensureInitialized();
+    log('Inserting strand party key for strand: %s', strandId);
+
+    const peerId = this.config.libp2pNode.peerId.toString();
+    const stampId = generateStampId(peerId);
+
+    // Field order MUST match the schema's StrandPartyKey `AuthorizedInsert` verify:
+    // Id, PrivateKey, StampId.
+    const message = buildAuthorizationMessage('CadreControl.StrandPartyKey', 'add', [strandId, privateKey, stampId]);
+    const signature = signMessage(message);
+
+    await this.execWrite(`
+      insert into CadreControl.StrandPartyKey (Id, PrivateKey, StampId)
+        with context OwnerKey = ?, Signature = ?
+        values (?, ?, ?)
+    `, [ownerKey, signature, strandId, privateKey, stampId], 'strand-party-key-insert');
+
+    log('Strand party key inserted for strand: %s', strandId);
+  }
+
+  /**
+   * Owner-signed removal of one `StrandPartyKey` row — the party's own membership
+   * identity for that strand, stored nowhere else, so this is as destructive as
+   * {@link deleteStrand} on a closed strand. {@link deleteStrand} already removes the
+   * founder's row alongside the `Strand` row in one transaction; this standalone form
+   * exists for a party-key row with NO local `Strand` row (a joiner's identity — the
+   * shape the formation tickets build on).
+   *
+   * Mirrors {@link deleteValidationKey}: `'remove'`-tagged digest over (Id, StampId),
+   * `Revocation` tombstone in the same transaction. A no-op (no throw, no tombstone)
+   * when the row does not exist — `false` then, `true` when a row was actually removed.
+   */
+  deleteStrandPartyKey(
+    strandId: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    return this.lockedWithRetry(() => this.deleteGuardedRow('StrandPartyKey', strandId, ownerKey, signMessage), {}, 'strand-party-key-delete');
   }
 
   /**
@@ -1588,16 +1923,27 @@ export class ControlDatabase {
     });
 
     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);
-      }
-    }
+    this.notifyGuardedDelete({ tableName: table, rowKey: keyValue, stampId });
     return true;
   }
 
+  /**
+   * Fire the guarded-delete listener for one committed tombstone, swallowing (and
+   * logging) a listener throw — a committed delete never fails because bookkeeping did.
+   * Shared by {@link deleteGuardedRow} and {@link deleteStrandAndPartyKey} (which files
+   * up to two tombstones per transaction).
+   */
+  private notifyGuardedDelete(revocation: RevokedRowRef): void {
+    if (!this.guardedDeleteListener) {
+      return;
+    }
+    try {
+      this.guardedDeleteListener(revocation);
+    } catch (error) {
+      log('guarded-delete listener threw (committed delete unaffected): %o', error);
+    }
+  }
+
   /**
    * 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
@@ -1706,8 +2052,9 @@ export class ControlDatabase {
    *
    * 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.
+   * - **Tables outside {@link REAPABLE_TABLES}** (`Strand`, `StrandPartyKey`, `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
@@ -1727,8 +2074,11 @@ export class ControlDatabase {
    * 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.
+   * one {@link queryStampId} point lookup per tombstone, and the empty early return makes
+   * the common case (a party that has never revoked anyone; {@link queryRevocations} skips
+   * the ledger marker) a single scan per pass. That scan consults the cohort on every pass
+   * only while `Revocation` has never been written; the ledger marker
+   * ({@link openRevocationLedger}), filed by the same connected pass, makes it a held block.
    * 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
@@ -1845,6 +2195,85 @@ export class ControlDatabase {
     }, {}, 'revocation-reissue');
   }
 
+  /**
+   * Owner-signed filing of the singleton `Revocation` ledger marker
+   * ({@link REVOCATION_LEDGER_MARKER}), the one row in that table that retires nothing.
+   *
+   * Why it exists: while `Revocation` has never been written, this node does not hold its
+   * block, and Optimystic consults a block's cohort on EVERY read of a block it does not
+   * hold — and every membership lookup, and every guarded insert's `NotRevoked` check,
+   * reads this table. Once any row exists the block is held and re-checked at most once per
+   * read-repair window, like every other populated table. The schema's table comment says
+   * why the row can never read as a retirement.
+   *
+   * Insert-if-absent, shaped like {@link reissueRevocations}: the signature is minted
+   * OUTSIDE the locked body so a retried attempt re-presents the same one, and the guard
+   * runs INSIDE it so it sees a concurrent local writer's committed row. The guard scans
+   * the `'Revocation'` rows and compares the stamp in TypeScript rather than seeking the
+   * full composite primary key, which is served as a point lookup that can miss an existing
+   * row on a networked database (tickets/backlog/debt-composite-pk-point-lookup-unreliable-untracked).
+   *
+   * Two owners filing at once: the loser either sees the marker in its guard or is refused
+   * on the primary key, and both answer `'already-open'`.
+   *
+   * The caller decides WHEN. A marker committed while the node is alone is local-only and
+   * can fork the collection, so {@link CadreNode} files it only while connected; this
+   * method does not look at connectivity.
+   *
+   * @param ownerKey - owner public key for the write context (`Revocation.Authorized`).
+   * @param signMessage - ed25519-signs the raw message bytes (no pre-hash) with that owner's
+   *   private key, returning a base64url signature.
+   * @returns `'opened'` when this call filed the marker, `'already-open'` when it was
+   *   already there.
+   */
+  async openRevocationLedger(
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<RevocationLedgerOpenResult> {
+    this.ensureInitialized();
+    const { tableName, rowKey, stampId } = REVOCATION_LEDGER_MARKER;
+    const signature = signMessage(buildAuthorizationMessage(
+      'CadreControl.Revocation', 'remove', [tableName, rowKey, stampId]
+    ));
+    try {
+      return await this.lockedWithRetry<RevocationLedgerOpenResult>(async () => {
+        if (await this.revocationLedgerFiled()) {
+          return 'already-open';
+        }
+        // Bare `exec`: already inside the write lock, which is NOT re-entrant.
+        await this.db!.exec(`
+          insert into CadreControl.Revocation (TableName, RowKey, StampId)
+            with context OwnerKey = ?, Signature = ?
+            values (?, ?, ?)
+        `, [ownerKey, signature, tableName, rowKey, stampId]);
+        log('Revocation ledger marker filed');
+        return 'opened';
+      }, {}, 'revocation-ledger-open');
+    } catch (error) {
+      if (!isRevocationLedgerConflict(error)) {
+        throw error;
+      }
+      log('Revocation ledger marker already filed (refused on the primary key, most likely by another owner filing first): %s', error);
+      return 'already-open';
+    }
+  }
+
+  /**
+   * Whether the ledger marker is present locally: a scan of the `'Revocation'` rows with the
+   * stamp compared in TypeScript (see {@link openRevocationLedger} for why not a seek).
+   * Called only inside the locked write body, so never retried (see queryStampId's NOTE).
+   */
+  private async revocationLedgerFiled(): Promise<boolean> {
+    const { tableName, stampId } = REVOCATION_LEDGER_MARKER;
+    const rows = await this.readRows(
+      'select StampId from CadreControl.Revocation where TableName = ?',
+      [tableName],
+      'revocation-ledger',
+      false
+    );
+    return rows.some(row => row.StampId === stampId);
+  }
+
   /**
    * Run `body` between `beginTransaction` and `commit`, rolling back on failure.
    *
@@ -1906,6 +2335,20 @@ export class ControlDatabase {
     this.guardedDeleteListener = listener;
   }
 
+  /**
+   * Wire (or clear, with null) the single listener notified when {@link lockedWithRetry}
+   * ABANDONS a control write. Same ownership contract as
+   * {@link setMembershipChangeListener}: one CadreNode, wired in `start()` and cleared on
+   * teardown, and a second call replaces the first rather than fanning out.
+   *
+   * Covers every write that reaches the funnel, foreground and background alike. A
+   * foreground caller also sees the rethrown error; a background one often does not, which
+   * is the whole reason this exists.
+   */
+  setControlWriteAbandonedListener(listener: ControlWriteAbandonedListener | null): void {
+    this.controlWriteAbandonedListener = listener;
+  }
+
   /**
    * Run a `CadrePeer` row mutation and notify the membership listener once it has
    * COMMITTED.
@@ -1991,11 +2434,27 @@ export class ControlDatabase {
   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);
+    const body = () => this.runWriteBody(fn);
+    const run = this.writeQueue.then(body, body);
     this.writeQueue = run.then(() => undefined, () => undefined);
     return run;
   }
 
+  /**
+   * Run one locked body, counted in {@link runningWriteBodies} from the moment it takes
+   * the lock until it settles — so an unlocked read routes around it even while its
+   * first statement is still waiting for the database's exec mutex, before
+   * `getAutocommit()` can show it (see {@link readRowsOnce}).
+   */
+  private async runWriteBody<T>(fn: () => Promise<T>): Promise<T> {
+    this.runningWriteBodies++;
+    try {
+      return await fn();
+    } finally {
+      this.runningWriteBodies--;
+    }
+  }
+
   /**
    * {@link withWriteLock} plus the bounded transient-failure retry
    * ({@link retryControlWrite}) — the wrapper the whole public write surface goes
@@ -2019,14 +2478,26 @@ export class ControlDatabase {
    * `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.
+   * attributed to a write — keep new call sites labelled. It is also the only thing that
+   * attributes an abandonment reported through {@link setControlWriteAbandonedListener}.
+   *
+   * The abandonment observer lands LAST, after both the policy and the spec-injected
+   * pacing, so this class's single listener is the one seam for it — a caller that
+   * smuggled its own in through `policy` would be displaced here rather than fanning out.
    */
   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 } : {}) }
+      {
+        ...policy,
+        ...this.controlWriteRetryPacing,
+        ...(label !== undefined ? { label } : {}),
+        // Read through the field, not captured: a listener wired (or cleared) while a write
+        // is already in backoff still governs that write's abandonment.
+        onAbandon: (abandonment) => this.controlWriteAbandonedListener?.(abandonment)
+      }
     );
   }
 
@@ -2503,22 +2974,19 @@ export class ControlDatabase {
   /**
    * Count `FormationUsage` rows recorded against a token (uses consumed so far).
    *
-   * This count IS the seat cap (`enforceFormationUseCap`), so an under-report admits a seat
-   * the invitation never paid for. It is served by a table SCAN, deliberately: a bare
-   * equality on a non-key column is a shape the optimystic vtab declines to claim, so the
-   * engine applies the filter itself over a full read of the table.
-   *
-   * NOTE: it was briefly an index seek, and that is what the scan is protecting against.
-   * `formation-unique-token-redesign` took `Token` out of the primary key and declared
-   * `FormationUsageByToken` purely to spare this scan, recording as a tripwire that an
-   * under-reporting descent would admit an unpaid-for seat — "a failure mode a scan could
-   * not produce". The tripwire fired. Across machines a secondary-index descent returns only
-   * the rows the READING machine wrote, so this count under-reported without bound on a
-   * multi-machine party and the cap over-admitted. The index was removed 2026-08-25; the
-   * measurement is recorded in the block comment at the `FormationUsage` declaration in
-   * `schemas/control.qsql`, and the engine defect in
-   * `blocked/secondary-index-seek-blind-to-sibling-rows`. Do NOT re-declare the index to
-   * speed this up while that ticket is open.
+   * Served by a seek through the `FormationUsageByToken` index rather than a full scan of
+   * the table, which is append-only and grows for the life of the party.
+   *
+   * NOTE: this count IS the seat cap (`enforceFormationUseCap`), so an under-report admits a
+   * seat the invitation never paid for — and reading it through a secondary index makes the
+   * cap depend on that index converging across machines. It did not, from 2026-08-04 to
+   * 2026-08-25: a descent on a second machine returned only the rows that machine had
+   * written, and the index was removed until the engine was fixed upstream (re-measured
+   * 2026-09-17, `complete/restore-formation-usage-token-index`). The live guard is the
+   * integration-tests scenario `strand-formation-concurrent-redemption`, which asserts both
+   * machines' views of a raced redemption. If it fails on BOTH views again, index
+   * convergence has regressed — fix the engine or take this read off the index, and do not
+   * weaken that scenario's assertions to get a green run.
    *
    * `retry: false` is passed only by {@link assertSeatRemains}, which runs INSIDE a
    * locked write body — same per-call opt-out, and for the same reason, as