@serfab/cadre-core 0.12.0 → 1.0.0

package/dist/control-cohort.d.ts

@@ -33,32 +33,6 @@ export declare const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15000;
  * count against this cap.
  */
 export declare const DEFAULT_CONTROL_COHORT_TARGET_DEGREE = 6;
-/**
- * Default per-sibling budget for one proactive control-cohort dial, in ms.
- *
- * `libp2p.dial(addrs)` is handed EVERY address a sibling resolved to, and each
- * one carries its own attempt timeout (js-libp2p's default is ~10 s, and
- * `@optimystic/db-p2p` does not override it). Some addresses cost more than one
- * attempt on their own: a `…/p2p-circuit/webrtc/…` address makes
- * `@libp2p/webrtc` dial the signalling leg to the relay hop FIRST and only then
- * the peer, so a two-address WebRTC sibling can block the sequential dial loop
- * for four attempt timeouts. Against unroutable addresses none of those attempts
- * ever answers, so an offline sibling's cost is address fan-out × relay hops ×
- * ~10 s — a number nothing in this package chose or bounds.
- *
- * This budget makes the SIBLING the unit instead of the address: one pass costs
- * at most (dialed siblings) × this, whatever each sibling's addresses look like.
- * Deliberately wider than one attempt timeout so a reachable sibling whose first
- * address is stale still gets a genuine try at its later ones; a sibling that
- * needs longer than this is simply retried next pass (every
- * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}), which is what the dial loop's
- * best-effort contract already does with any other dial failure.
- *
- * Override per node with `network.controlCohort.dialTimeoutMs` — tests that
- * drive dead addresses on purpose set it low so a pass's duration is a chosen
- * number rather than a transitive libp2p default stretched by machine load.
- */
-export declare const DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS = 20000;
 /** Outcome of {@link selectControlCohortDials}: who to dial + what the cap dropped. */
 export interface ControlCohortSelection {
     /**
@@ -71,6 +45,19 @@ export interface ControlCohortSelection {
     /** Non-owner members dropped by the `targetDegree` cap (0 when none). */
     cappedNonOwner: number;
 }
+/** What one {@link CadreNode.reconcileControlCohort} pass did. */
+export interface ControlCohortReconcileResult {
+    /**
+     * Peer ids this pass dialled and whose dial resolved, in dial order: selected
+     * siblings on the steady-state pass, retained bootstrap peers on the cold-start
+     * pass (the pass takes one branch or the other, never both). A peer already
+     * connected when the pass began is never listed — the pass skips it. A resolved
+     * dial can still be refused moments later by the remote's membership gate, so
+     * an entry means "this pass opened a connection", not "that connection is still
+     * open".
+     */
+    dialed: string[];
+}
 /**
  * Backbone-preferential, bounded-out-degree selection of control-cohort siblings
  * to dial.

package/dist/control-cohort.js

@@ -33,32 +33,6 @@ export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15000;
  * count against this cap.
  */
 export const DEFAULT_CONTROL_COHORT_TARGET_DEGREE = 6;
-/**
- * Default per-sibling budget for one proactive control-cohort dial, in ms.
- *
- * `libp2p.dial(addrs)` is handed EVERY address a sibling resolved to, and each
- * one carries its own attempt timeout (js-libp2p's default is ~10 s, and
- * `@optimystic/db-p2p` does not override it). Some addresses cost more than one
- * attempt on their own: a `…/p2p-circuit/webrtc/…` address makes
- * `@libp2p/webrtc` dial the signalling leg to the relay hop FIRST and only then
- * the peer, so a two-address WebRTC sibling can block the sequential dial loop
- * for four attempt timeouts. Against unroutable addresses none of those attempts
- * ever answers, so an offline sibling's cost is address fan-out × relay hops ×
- * ~10 s — a number nothing in this package chose or bounds.
- *
- * This budget makes the SIBLING the unit instead of the address: one pass costs
- * at most (dialed siblings) × this, whatever each sibling's addresses look like.
- * Deliberately wider than one attempt timeout so a reachable sibling whose first
- * address is stale still gets a genuine try at its later ones; a sibling that
- * needs longer than this is simply retried next pass (every
- * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}), which is what the dial loop's
- * best-effort contract already does with any other dial failure.
- *
- * Override per node with `network.controlCohort.dialTimeoutMs` — tests that
- * drive dead addresses on purpose set it low so a pass's duration is a chosen
- * number rather than a transitive libp2p default stretched by machine load.
- */
-export const DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS = 20000;
 /** Stable peerId ordering so the bounded fill is identical across passes/nodes. */
 function byPeerId(a, b) {
     if (a.peerId < b.peerId)

package/dist/control-cohort.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-cohort.js","sourceRoot":"","sources":["../src/control-cohort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAGpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,KAAM,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,KAAM,CAAC;AAe7D,mFAAmF;AACnF,SAAS,QAAQ,CAAC,CAAgB,EAAE,CAAgB;IAClD,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAyB,EACzB,SAA8B,EAC9B,YAAoB;IAEpB,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,MAAM,IAAI,GAAoB,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,6BAA6B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1D,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAEhC,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;QAC7B,cAAc,EAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;KAC1C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"control-cohort.js","sourceRoot":"","sources":["../src/control-cohort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAGpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,KAAM,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC;AAkCtD,mFAAmF;AACnF,SAAS,QAAQ,CAAC,CAAgB,EAAE,CAAgB;IAClD,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAyB,EACzB,SAA8B,EAC9B,YAAoB;IAEpB,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,MAAM,IAAI,GAAoB,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,6BAA6B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1D,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAEhC,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;QAC7B,cAAc,EAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;KAC1C,CAAC;AACJ,CAAC"}

package/dist/control-database.d.ts

@@ -2,8 +2,9 @@ import { Database } from '@quereus/quereus';
 import type { SqlParameters } from '@quereus/quereus';
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
-import type { StrandRow, PeerAddressRecord, CadrePeerRow, RevocationRow, DeviceTokenRecord, DeviceTokenRow } from './types.js';
+import type { StrandRow, PeerAddressRecord, CadrePeerRow, RevocationRow, RevocationLedgerOpenResult, DeviceTokenRecord, DeviceTokenRow } from './types.js';
 import type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
+import type { ControlRetryAbandonment } from './control-retry.js';
 export type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
 /**
  * Generate a unique stamp ID for transaction authorization.
@@ -154,14 +155,40 @@ export declare function formationConsentMessage(fields: {
     peerKey: string;
     disclosure: string;
 }): Uint8Array;
+/**
+ * Did this write fail because the strand id is already seated?
+ *
+ * {@link CadreNode.publishStrand} uses this to tell "my own earlier publish already
+ * landed" (re-read, and no-op when the row matches) apart from every other rejection —
+ * an unauthorized signer, a retired stamp — which must keep surfacing.
+ *
+ * Matched by TEXT, not by type: the typed engine error does not survive the trip out of
+ * optimystic (same constraint the retry classifiers in `control-write-retry.ts` document).
+ * Fails CLOSED — a rewording upstream turns the idempotent branch back into the raw
+ * uniqueness error the caller saw before, never into a silent overwrite. The
+ * `publish-strand.spec.ts` repeat-publish cases assert against the live engine error, so a
+ * reword reddens there.
+ */
+export declare function isStrandIdConflict(error: unknown): boolean;
+/**
+ * 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 declare const REVOCATION_LEDGER_MARKER: {
+    readonly tableName: "Revocation";
+    readonly rowKey: "ledger";
+    readonly stampId: "opened";
+};
 /**
  * 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 declare const REAPABLE_TABLES: readonly ["CadrePeer", "DeviceToken", "ValidationKey"];
 export type ReapableTable = (typeof REAPABLE_TABLES)[number];
@@ -193,6 +220,19 @@ export type RevokedRowRef = Omit<RevocationRow, 'reissuedAt'>;
  * swallows and logs anyway — a committed delete never fails because bookkeeping did).
  */
 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;
@@ -218,8 +258,16 @@ export declare class ControlDatabase {
     private initialized;
     private membershipListener;
     private guardedDeleteListener;
+    private controlWriteAbandonedListener;
     /** Tail of the local-write chain — see {@link withWriteLock}. */
     private writeQueue;
+    /**
+     * 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;
     /**
      * 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
@@ -274,11 +322,33 @@ export declare 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
@@ -286,8 +356,24 @@ export declare 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 readRowsOnce;
+    /**
+     * 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;
     /**
      * {@link readRowsOnce} plus the bounded transient-failure retry
      * ({@link retryControlRead}) — the funnel every UNLOCKED control read goes through, so a
@@ -303,8 +389,8 @@ export declare 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
@@ -391,10 +477,12 @@ export declare 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`),
@@ -465,6 +553,16 @@ export declare class ControlDatabase {
     queryDeviceTokenStampId(peerId: string): Promise<string | null>;
     /** `Strand` stamp nonce — bound into {@link deleteStrand}'s remove digest. */
     queryStrandStampId(strandId: string): Promise<string | null>;
+    /** `StrandPartyKey` stamp nonce — bound into {@link deleteStrandPartyKey}'s remove digest. */
+    queryStrandPartyKeyStampId(strandId: string): Promise<string | null>;
+    /**
+     * 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.
+     */
+    queryStrandPartyKey(strandId: string): Promise<string | null>;
     /** `ValidationKey` stamp nonce — bound into {@link deleteValidationKey}'s remove digest. */
     queryValidationKeyStampId(key: string): Promise<string | null>;
     /**
@@ -479,21 +577,69 @@ export declare 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.
      */
     queryRevokedStamps(tableName: RevocableTable, retry?: boolean): Promise<Set<string>>;
+    /**
+     * 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 readRevokedStampRows;
     /**
      * 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'`.
      */
     queryRevocations(): Promise<RevocationRow[]>;
     /**
@@ -572,6 +718,10 @@ export declare class ControlDatabase {
     /**
      * Insert a strand into the control database using an owner signature.
      *
+     * Fails with a `Strand.Id` uniqueness violation when the id is already seated — the
+     * caller decides whether that is a duplicate of its own earlier write (idempotent) or a
+     * genuine conflict; see {@link isStrandIdConflict} and `CadreNode.publishStrand`.
+     *
      * 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
@@ -600,10 +750,65 @@ export declare 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.
      */
     deleteStrand(strandId: string, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<boolean>;
+    /**
+     * 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 deleteStrandAndPartyKey;
+    /**
+     * 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.
+     */
+    insertStrandPartyKey(strandId: string, privateKey: string, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<void>;
+    /**
+     * 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>;
     /**
      * Insert a validation key into the control database using an owner signature.
      *
@@ -797,6 +1002,13 @@ export declare class ControlDatabase {
      * come from closed literal unions — no caller-supplied string reaches the statement.
      */
     private deleteGuardedRow;
+    /**
+     * 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;
     /**
      * 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
@@ -868,8 +1080,9 @@ export declare 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
@@ -889,8 +1102,11 @@ export declare 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
@@ -927,6 +1143,44 @@ export declare class ControlDatabase {
      * Returns how many UPDATE statements ran (`rows.length` on success).
      */
     reissueRevocations(rows: readonly RevocationRow[], reissuedAt: number, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<number>;
+    /**
+     * 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.
+     */
+    openRevocationLedger(ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<RevocationLedgerOpenResult>;
+    /**
+     * 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 revocationLedgerFiled;
     /**
      * Run `body` between `beginTransaction` and `commit`, rolling back on failure.
      *
@@ -967,6 +1221,17 @@ export declare class ControlDatabase {
      * call replaces the first.
      */
     setGuardedDeleteListener(listener: GuardedDeleteListener | null): void;
+    /**
+     * 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;
     /**
      * Run a `CadrePeer` row mutation and notify the membership listener once it has
      * COMMITTED.
@@ -1040,6 +1305,13 @@ export declare class ControlDatabase {
      * attempt: a retry re-presents the exact signed message the first attempt presented.
      */
     withWriteLock<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 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 runWriteBody;
     /**
      * {@link withWriteLock} plus the bounded transient-failure retry
      * ({@link retryControlWrite}) — the wrapper the whole public write surface goes
@@ -1063,7 +1335,12 @@ export declare 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;
     /**
@@ -1312,22 +1589,19 @@ export declare 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