@serfab/cadre-core 1.3.0 → 1.5.0

package/src/control-database.ts

@@ -627,17 +627,35 @@ export class ControlDatabase {
     //  - `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.
+    //    A table the live catalog already lists generates no statements at all, which is what
+    //    makes an apply over an already-complete schema (a warm start) a no-op.
+    //  - a failed apply is taken back WHOLE (Quereus 4.20.0). The migration loop keeps an
+    //    undo journal; when a step fails it runs that journal in reverse, re-renders the
+    //    catalog, compares it against a fingerprint taken BEFORE the apply, and only then
+    //    rethrows the step's own error. So attempt 2 does not resume where attempt 1 died —
+    //    it re-emits the whole schema, because the catalog is back where the apply started.
     //
-    // Together: attempt 2 re-emits exactly the failed table and its successors. No
-    // `if not exists` juggling, no per-table loop, no statement splitting.
+    // Together: attempt 2 emits exactly the DDL the live catalog is missing, whatever
+    // attempt 1 reached. No `if not exists` juggling, no per-table loop, no statement
+    // splitting.
+    //
+    // That second bullet carries a dependency the pre-4.20.0 argument did not have. The
+    // unwind Quereus performs is the CATALOG's; whether STORAGE follows it is the optimystic
+    // plugin's doing. Quereus runs the forward steps, the undo steps and the verification
+    // all inside the module's `beginSchemaBatch`/`endSchemaBatch` pair, and the plugin puts
+    // each undo statement (`drop table`, `drop index if exists`) through its ordinary hooks
+    // in that one write batch, then commits the restored state. On a plugin build WITHOUT
+    // those batch hooks storage would be left holding objects the catalog no longer lists,
+    // and the re-run would diff against a catalog that disagrees with the blocks. So this
+    // argument is a statement about the pair, not about Quereus alone — pinned by
+    // `test/control-schema-apply-unwind.spec.ts`.
     //
     // 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.
+    // The cases the unwind cannot cover — a failed undo statement, a post-unwind catalog
+    // that does not match its fingerprint, an irreversible step — are retried deliberately
+    // rather than vetoed; why, on `RETRIABLE_SCHEMA_INIT_MATCHERS`.
     //
     // 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
@@ -2977,16 +2995,30 @@ export class ControlDatabase {
    * 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.
+   * This read is NOT the seat cap. The authoritative cap is the deferred `Authorized` CHECK
+   * in `schemas/control.qsql` — `FI.TotalUses > (select count(1) from
+   * committed.FormationUsage U where U.Token = new.Token)` — evaluated by the validating
+   * cohort against the committed snapshot at commit time. Every caller of this method is a
+   * permissive PRE-check that runs ahead of it, and a transiently short read costs each of
+   * them only a worse outcome for the ATTEMPT, never a seat the invitation did not pay for:
+   * {@link assertSeatRemains} loses its named exhaustion error and falls back to the CHECK's
+   * generic refusal; `ControlFormationUsageRecorder.isTokenUsed` reports not-used and lets
+   * the redemption proceed to the CHECK, which decides; {@link hasOutstandingFormationInvite}
+   * holds the stranger-admission door open slightly longer.
+   *
+   * NOTE: index convergence still gates the cap — just at the CHECK, not here, since the
+   * CHECK's own count is served by the same `FormationUsageByToken` index. That convergence
+   * failed 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. A failure on ONE view is
+   * NOT automatically that scenario being slow: one-way convergence lag, and the 2026-08 defect
+   * itself, both present that way whenever only the sibling node wrote the rows. What separates
+   * them is the failure message, which prints both nodes' rows and counts — a sibling holding
+   * rows the failing view is missing is a convergence problem, not a slow 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

package/src/control-formation-recorder.ts

@@ -1,6 +1,6 @@
 import debug from 'debug';
-import { randomBytes } from '@optimystic/quereus-plugin-crypto';
 import { FormationAbortedError, type ControlDatabase } from './control-database.js';
+import { mintStrandId } from './strand-id.js';
 import {
   createHttpFormationApprover,
   verifyFormationApproval,
@@ -252,10 +252,10 @@ export class ControlFormationUsageRecorder implements FormationUsageRecorder {
    * Provision a NEW strand for an UNBOUND invite and record consent against it in ONE
    * transaction (the responder-provisions fallback, now single-use-enforced).
    *
-   * Mints a fresh, globally-unique strand id from {@link randomBytes} — the same
-   * cross-platform CSPRNG `control-database`'s `generateStampId` uses, NOT
-   * `crypto.randomUUID` / `Date.now` / `Math.random` (not uniformly available across
-   * node/browser/RN) — then delegates to {@link ControlDatabase.redeemInvitation}, whose
+   * Mints a fresh, globally-unique strand id with {@link mintStrandId} — an
+   * unguessable CSPRNG id, and one `strand-id.ts` has already checked is usable as a
+   * storage scope key and network name — then delegates to
+   * {@link ControlDatabase.redeemInvitation}, whose
    * single `begin … commit` inserts the consent-authorized `Strand` row AND the matching
    * `FormationUsage` row together (both deferred CHECKs see both rows at commit). That one
    * `FormationUsage` row makes the unbound redemption single-use exactly like the bound
@@ -289,7 +289,7 @@ export class ControlFormationUsageRecorder implements FormationUsageRecorder {
     if (signal?.aborted) {
       throw new FormationAbortedError(token, 'redemption');
     }
-    const strandId = `strand-${randomBytes(128, 'hex') as string}`;
+    const strandId = mintStrandId();
     const invite = await this.controlDatabase.queryFormationInvite(token);
     const approval = await this.obtainApproval({
       token, usageStampId, strandId, peerKey, disclosure,

package/src/control-read-retry.ts

@@ -1,202 +1,214 @@
-import { BlockUnavailableError } from '@optimystic/db-core';
-import { causeChain, chainMessages, retryControlOperation } from './control-retry.js';
-import type { ControlRetryOptions } from './control-retry.js';
-import { isUncommittedTransactorAggregate } from './control-write-retry.js';
-
-/**
- * Bounded retry for TRANSIENT control-read failures — the classifier and policy behind
- * `ControlDatabase.readRows`, the single funnel every control read passes through.
- *
- * Why this exists: control WRITES have absorbed transient cluster failures since
- * `control-write-retry.ts` landed, but a read had no second chance — one stream reset
- * during a scan ended the read outright (measured: a rigged single `eval` failure killed
- * `queryRevokedStamps` after exactly one attempt while the same injection against `exec`
- * was absorbed). This module gives reads the same bounded re-presentation with a SHORTER
- * deadline and a NARROWER failure set, because the tightest caller deadline over a control
- * read is the inbound admission gate's 2 s fail-open timeout
- * (`ADMISSION_DECISION_TIMEOUT_MS`, `membership-connection-gater.ts`) — a read budget that
- * does not fit inside it with headroom spends its retries after the gate has already
- * admitted.
- *
- * This is deliberately NOT "the write classifier minus its commit veto" — the retriable
- * set differs in both directions (see {@link isRetriableControlReadFailure}). The loop
- * lives in `control-retry.ts`, shared with the write policy; this module owns only the
- * read policy. And like the write side, the retry classifies by TEXT. That was forced when
- * it was written — optimystic's scan path used to rethrow `new Error('Query failed: ' +
- * message)` with no `cause` — and is no longer: `OptimysticVirtualTable` now rethrows
- * through `rewrapAsQueryError` (`quereus-plugin-optimystic/src/optimystic-module.ts`),
- * which keeps the typed `BlockUnavailableError` on `cause`, and Quereus wraps that as
- * `Error during query on table '<T>': …`, again preserving `cause`
- * (`quereus/src/runtime/emit/scan.ts`). The text matchers still work because every wrap
- * embeds the inner message. Every matcher fails CLOSED — an upstream rewording stops the
- * retry engaging, it never makes it unsafe. {@link isCohortUnreachableRead}, which is not a
- * retry classifier, matches by type.
- */
-
-/**
- * Attempts allowed per control read: the first, plus two retries. Attempts are cheap here —
- * the observed transient failure (the transactor's read-phase aggregate off a stream still
- * forming) surfaces in ~25 ms — and {@link CONTROL_READ_RETRY_BUDGET_MS} is what terminates
- * the loop when an attempt is slow instead.
- */
-export const CONTROL_READ_ATTEMPTS = 3;
-
-/**
- * Backoff before read retry N, jittered ±50% and capped at the largest base by the shared
- * loop — so worst case 150 ms + 400 ms = 550 ms of total sleep (the second delay's
- * upside jitter is clipped by the cap). Much shorter than the write list because the
- * whole loop must fit under {@link CONTROL_READ_RETRY_BUDGET_MS}; the spec pins that
- * relationship rather than the number.
- */
-export const CONTROL_READ_RETRY_DELAYS_MS: readonly number[] = [100, 400];
-
-/**
- * Elapsed-time ceiling on the whole read-retry loop, checked after a failed attempt BEFORE
- * sleeping — so one slow attempt (e.g. a `cohort-unreachable` read that burned the
- * transactor's own deadline) terminates the loop rather than compounding.
- *
- * 1500 ms, sized against `ADMISSION_DECISION_TIMEOUT_MS` (2000 ms): the inbound admission
- * gate reads the control DB and is FAIL-OPEN on both throw and timeout, so a read that
- * outlives the gate's deadline spends its retries after the gate has already admitted an
- * unplaced peer. Under the deadline, a read that succeeds on its second attempt lets the
- * gate make the real decision instead. `control-read-retry.spec.ts` asserts the
- * relationship so a future edit to either constant reddens instead of silently
- * reintroducing the fail-open admit. NOTE: `queryCadrePeers` / `queryPeerRecord` each
- * issue TWO network reads (the revoked-stamp filter plus the row scan) and the budget is
- * per read, so a membership read can spend up to two budgets back to back — still inside
- * 2 s only because each stays well under it. Do not raise these numbers without
- * re-checking against `ADMISSION_DECISION_TIMEOUT_MS`.
- */
-export const CONTROL_READ_RETRY_BUDGET_MS = 1_500;
-
-/**
- * The block-unavailability reasons a repeat read can actually improve on, matched against
- * upstream's exact template `Block <id> is unavailable (<reason>): …`
- * (`BlockUnavailableError`, `db-core/src/network/struct.ts`):
- *
- * - **`peers-unreachable`** — part of the cohort answered and part could not be asked, and
- *   OTHER coordinators are reachable, so asking one of them can still settle it. Upstream's
- *   own definition invites the second attempt.
- * - **`cohort-unreachable`** — the marginal member of the set. Upstream says the answer
- *   will not improve until this node's connectivity does — but during bring-up connectivity
- *   DOES improve within a second (the boot-time failure shape recorded in
- *   `tickets/blocked/control-read-over-fresh-edge-stream-resets`), and the cost of being
- *   wrong is bounded by {@link CONTROL_READ_RETRY_BUDGET_MS}, which is the whole reason it
- *   is safe to include.
- *
- * Deliberately NOT matched:
- *
- * - **`claimed-elsewhere`** — a cohort peer positively claims the block exists and nobody
- *   could corroborate or acquire it. MEASURED not to clear: reissuing the same call every
- *   second for 60 s returned the identical error every time (2026-08-20, recorded in the
- *   fix ticket). Retrying spends the whole budget and fails anyway. The measured cause (a
- *   block only one machine held) was fixed upstream by the solo-commit proof in
- *   `@optimystic/db-p2p` 0.28.0 (`tickets/complete/block-held-by-only-one-machine-is-unreadable`),
- *   so a `claimed-elsewhere` that surfaces now is a new defect — this retry must not hide it.
- * - **`unmaterializable`** — records are held locally but cannot be reassembled. A local
- *   data problem; a second read reads the same records.
- * - **`Block <id> may be stale`** (`BlockPossiblyStaleError`) — about currency, not
- *   existence: a cohort claim no reachable coordinator could confirm or refute will not
- *   resolve inside a few hundred milliseconds of backoff.
- * - Anything unmatched. The default is no retry.
- */
-const RETRIABLE_BLOCK_UNAVAILABLE =
-	/Block \S+ is unavailable \((?:peers-unreachable|cohort-unreachable)\)/;
-
-/** A block-unavailable read failure whose reason a repeat read can improve on. */
-function isRetriableBlockUnavailable(message: string): boolean {
-	return RETRIABLE_BLOCK_UNAVAILABLE.test(message);
-}
-
-/**
- * Pacing overrides for {@link retryControlRead} — the read twin of
- * `ControlWriteRetryOptions`. Every field defaults to the shipped read policy
- * ({@link CONTROL_READ_ATTEMPTS}, {@link CONTROL_READ_RETRY_DELAYS_MS},
- * {@link isRetriableControlReadFailure}); field shapes and semantics live on the shared
- * {@link ControlRetryOptions}.
- */
-export type ControlReadRetryOptions = ControlRetryOptions;
-
-/**
- * Did this control read fail in a way a repeat read can improve on?
- *
- * Two classes, both meaning "the cluster could not be ASKED properly just now":
- *
- * - the transactor's read-phase aggregate (`Some peers did not complete: …[block:…]`),
- *   reused verbatim from the write classifier — a `get` batch formats the single-block
- *   `[block:` token, and a read can never produce the commit-phase `[blocks:` token, so
- *   the write side's indeterminate-commit veto has nothing to veto here (a read commits
- *   nothing and re-running it is always safe);
- * - the block-unavailability reasons in {@link RETRIABLE_BLOCK_UNAVAILABLE} (and only
- *   those — see its comment for the measured exclusions).
- *
- * Classifies by MESSAGE, walking the `cause` chain with the shared `chainMessages` (why
- * text, in the module comment). Anything that is not an `Error` is never retried.
- */
-export function isRetriableControlReadFailure(error: unknown): boolean {
-	if (!(error instanceof Error)) {
-		return false;
-	}
-	return chainMessages(error).some(message =>
-		isUncommittedTransactorAggregate(message) || isRetriableBlockUnavailable(message));
-}
-
-/**
- * Did this control read fail because no cohort member other than the answering node could
- * be asked about a block nobody here holds — a `BlockUnavailableError` with reason
- * `cohort-unreachable` anywhere on the `cause` chain?
- *
- * Not a retry classifier. It answers "is there a better answer to wait for?", and is used
- * by exactly one reader, `ControlDatabase.queryRevokedStamps`, to read an isolated node's
- * never-received `Revocation` block as "no revocations known" (the reasoning is in the NOTE
- * there). Upstream names this the one reason a caller may treat permissively
- * (`db-core/src/transactor/network-transactor.ts`). The other reasons do NOT match:
- * `peers-unreachable` means part of the cohort answered, and `claimed-elsewhere` /
- * `unmaterializable` mean the block is known to exist, so an empty answer could hide a
- * real revocation.
- *
- * Matched by TYPE, since the typed error survives upstream's rewraps (module comment).
- * Fails CLOSED: a non-`Error`, a text-only copy of the message, and an error built by a
- * second loaded copy of `@optimystic/db-core` (which `instanceof` cannot recognise) all
- * answer false, and the reader throws as it did before this existed.
- */
-export function isCohortUnreachableRead(error: unknown): boolean {
-	return causeChain(error).some(link =>
-		link instanceof BlockUnavailableError && link.reason === 'cohort-unreachable');
-}
-
-/**
- * Run `attempt` — a full drain of one control read — up to
- * {@link CONTROL_READ_ATTEMPTS} times, retrying only failures
- * {@link isRetriableControlReadFailure} calls transient, and only while
- * {@link CONTROL_READ_RETRY_BUDGET_MS} has not elapsed.
- *
- * Reads are idempotent, so `attempt` needs no atomicity contract — but it must be a
- * COLLECTING drain, not a live iterator: a half-consumed iterator cannot be retried
- * without re-yielding rows the caller already saw, which is why
- * `ControlDatabase.readRows` materializes before this loop ever sees a failure.
- *
- * On exhaustion the LAST error is rethrown unchanged. Log lines carry the
- * `Control read [<label>] …` prefix so a read's retries can be attributed among the
- * several reads in flight concurrently in a real party.
- *
- * No reader passes an `onAbandon` observer, deliberately, though the shared options type
- * offers one ({@link ControlRetryOptions.onAbandon}) and the loop would honour it. That hook
- * exists because an abandoned WRITE can have no caller at all — the background self-record
- * republish is `void`-ed with a `debug`-only catch, so giving up on it is invisible. Every
- * control read is awaited by the caller that issued it, so an abandoned read surfaces as that
- * caller's rejection; there is nothing here to lose silently. A fire-and-forget read would be
- * the reason to start passing one.
- */
-export function retryControlRead<T>(
-	attempt: () => Promise<T>,
-	options: ControlReadRetryOptions = {}
-): Promise<T> {
-	return retryControlOperation(attempt, {
-		attempts: CONTROL_READ_ATTEMPTS,
-		delaysMs: CONTROL_READ_RETRY_DELAYS_MS,
-		budgetMs: CONTROL_READ_RETRY_BUDGET_MS,
-		isRetriable: isRetriableControlReadFailure,
-		logPrefix: 'Control read',
-	}, options);
-}
+import { BlockUnavailableError } from '@optimystic/db-core';
+import { causeChain, chainMessages, retryControlOperation } from './control-retry.js';
+import type { ControlRetryOptions } from './control-retry.js';
+import { isUncommittedTransactorAggregate } from './control-write-retry.js';
+
+/**
+ * Bounded retry for TRANSIENT control-read failures — the classifier and policy behind
+ * `ControlDatabase.readRows`, the single funnel every control read passes through.
+ *
+ * Why this exists: control WRITES have absorbed transient cluster failures since
+ * `control-write-retry.ts` landed, but a read had no second chance — one stream reset
+ * during a scan ended the read outright (measured: a rigged single `eval` failure killed
+ * `queryRevokedStamps` after exactly one attempt while the same injection against `exec`
+ * was absorbed). This module gives reads the same bounded re-presentation with a SHORTER
+ * deadline and a NARROWER failure set, because the tightest caller deadline over a control
+ * read is the inbound admission gate's 2 s fail-open timeout
+ * (`ADMISSION_DECISION_TIMEOUT_MS`, `membership-connection-gater.ts`) — a read budget that
+ * does not fit inside it with headroom spends its retries after the gate has already
+ * admitted.
+ *
+ * This is deliberately NOT "the write classifier minus its commit veto" — the retriable
+ * set differs in both directions (see {@link isRetriableControlReadFailure}). The loop
+ * lives in `control-retry.ts`, shared with the write policy; this module owns only the
+ * read policy. And like the write side, the retry classifies by TEXT. That was forced when
+ * it was written — optimystic's scan path used to rethrow `new Error('Query failed: ' +
+ * message)` with no `cause` — and is no longer: `OptimysticVirtualTable` now rethrows
+ * through `rewrapAsQueryError` (`quereus-plugin-optimystic/src/optimystic-module.ts`),
+ * which keeps the typed `BlockUnavailableError` on `cause`, and Quereus wraps that as
+ * `Error during query on table '<T>': …`, again preserving `cause`
+ * (`quereus/src/runtime/emit/scan.ts`). The text matchers still work because every wrap
+ * embeds the inner message. Every matcher fails CLOSED — an upstream rewording stops the
+ * retry engaging, it never makes it unsafe. {@link isCohortUnreachableRead}, which is not a
+ * retry classifier, matches by type.
+ */
+
+/**
+ * Attempts allowed per control read: the first, plus two retries. Attempts are cheap here —
+ * the observed transient failure (the transactor's read-phase aggregate off a stream still
+ * forming) surfaces in ~25 ms — and {@link CONTROL_READ_RETRY_BUDGET_MS} is what terminates
+ * the loop when an attempt is slow instead.
+ */
+export const CONTROL_READ_ATTEMPTS = 3;
+
+/**
+ * Backoff before read retry N, jittered ±50% and capped at the largest base by the shared
+ * loop — so worst case 150 ms + 400 ms = 550 ms of total sleep (the second delay's
+ * upside jitter is clipped by the cap). Much shorter than the write list because the
+ * whole loop must fit under {@link CONTROL_READ_RETRY_BUDGET_MS}; the spec pins that
+ * relationship rather than the number.
+ */
+export const CONTROL_READ_RETRY_DELAYS_MS: readonly number[] = [100, 400];
+
+/**
+ * Elapsed-time ceiling on the whole read-retry loop, checked after a failed attempt BEFORE
+ * sleeping — so one slow attempt (e.g. a `cohort-unreachable` read that burned the
+ * transactor's own deadline) terminates the loop rather than compounding.
+ *
+ * 1500 ms, sized against `ADMISSION_DECISION_TIMEOUT_MS` (2000 ms): the inbound admission
+ * gate reads the control DB and is FAIL-OPEN on both throw and timeout, so a read that
+ * outlives the gate's deadline spends its retries after the gate has already admitted an
+ * unplaced peer. Under the deadline, a read that succeeds on its second attempt lets the
+ * gate make the real decision instead. `control-read-retry.spec.ts` asserts the
+ * relationship so a future edit to either constant reddens instead of silently
+ * reintroducing the fail-open admit. NOTE: `queryCadrePeers` / `queryPeerRecord` each
+ * issue TWO network reads (the revoked-stamp filter plus the row scan) and the budget is
+ * per read, so a membership read can spend up to two budgets back to back — still inside
+ * 2 s only because each stays well under it. Do not raise these numbers without
+ * re-checking against `ADMISSION_DECISION_TIMEOUT_MS`.
+ *
+ * NOTE: the obligation runs the other way too, and the number that dominates this budget is
+ * declared in another package. One attempt whose cohort consult finds a silent peer costs
+ * `clusterPolicy.cohortQueryTimeoutMs`, which sereus declares at 5000 ms
+ * (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`) for relayed phone
+ * links — more than three times this budget, so such an attempt is never retried and the
+ * admission gate above it has already fail-opened. That is a widened cost of a deliberate
+ * choice, not a hole (the stream gates still decide), and the whole ladder of cadre-core
+ * deadlines against Optimystic's is audited by
+ * `backlog/debt-cadre-deadlines-sized-against-old-optimystic-bounds`. What this budget still
+ * buys is the failure it was built for: the ~25 ms transactor read-phase aggregate off a
+ * stream still forming, which retries twice well inside 1500 ms.
+ */
+export const CONTROL_READ_RETRY_BUDGET_MS = 1_500;
+
+/**
+ * The block-unavailability reasons a repeat read can actually improve on, matched against
+ * upstream's exact template `Block <id> is unavailable (<reason>): …`
+ * (`BlockUnavailableError`, `db-core/src/network/struct.ts`):
+ *
+ * - **`peers-unreachable`** — part of the cohort answered and part could not be asked, and
+ *   OTHER coordinators are reachable, so asking one of them can still settle it. Upstream's
+ *   own definition invites the second attempt.
+ * - **`cohort-unreachable`** — the marginal member of the set. Upstream says the answer
+ *   will not improve until this node's connectivity does — but during bring-up connectivity
+ *   DOES improve within a second (the boot-time failure shape recorded in
+ *   `tickets/blocked/control-read-over-fresh-edge-stream-resets`), and the cost of being
+ *   wrong is bounded by {@link CONTROL_READ_RETRY_BUDGET_MS}, which is the whole reason it
+ *   is safe to include.
+ *
+ * Deliberately NOT matched:
+ *
+ * - **`claimed-elsewhere`** — a cohort peer positively claims the block exists and nobody
+ *   could corroborate or acquire it. MEASURED not to clear: reissuing the same call every
+ *   second for 60 s returned the identical error every time (2026-08-20, recorded in the
+ *   fix ticket). Retrying spends the whole budget and fails anyway. The measured cause (a
+ *   block only one machine held) was fixed upstream by the solo-commit proof in
+ *   `@optimystic/db-p2p` 0.28.0 (`tickets/complete/block-held-by-only-one-machine-is-unreadable`),
+ *   so a `claimed-elsewhere` that surfaces now is a new defect — this retry must not hide it.
+ * - **`unmaterializable`** — records are held locally but cannot be reassembled. A local
+ *   data problem; a second read reads the same records.
+ * - **`Block <id> may be stale`** (`BlockPossiblyStaleError`) — about currency, not
+ *   existence: a cohort claim no reachable coordinator could confirm or refute will not
+ *   resolve inside a few hundred milliseconds of backoff.
+ * - Anything unmatched. The default is no retry.
+ */
+const RETRIABLE_BLOCK_UNAVAILABLE =
+	/Block \S+ is unavailable \((?:peers-unreachable|cohort-unreachable)\)/;
+
+/** A block-unavailable read failure whose reason a repeat read can improve on. */
+function isRetriableBlockUnavailable(message: string): boolean {
+	return RETRIABLE_BLOCK_UNAVAILABLE.test(message);
+}
+
+/**
+ * Pacing overrides for {@link retryControlRead} — the read twin of
+ * `ControlWriteRetryOptions`. Every field defaults to the shipped read policy
+ * ({@link CONTROL_READ_ATTEMPTS}, {@link CONTROL_READ_RETRY_DELAYS_MS},
+ * {@link isRetriableControlReadFailure}); field shapes and semantics live on the shared
+ * {@link ControlRetryOptions}.
+ */
+export type ControlReadRetryOptions = ControlRetryOptions;
+
+/**
+ * Did this control read fail in a way a repeat read can improve on?
+ *
+ * Two classes, both meaning "the cluster could not be ASKED properly just now":
+ *
+ * - the transactor's read-phase aggregate (`Some peers did not complete: …[block:…]`),
+ *   reused verbatim from the write classifier — a `get` batch formats the single-block
+ *   `[block:` token, and a read can never produce the commit-phase `[blocks:` token, so
+ *   the write side's indeterminate-commit veto has nothing to veto here (a read commits
+ *   nothing and re-running it is always safe);
+ * - the block-unavailability reasons in {@link RETRIABLE_BLOCK_UNAVAILABLE} (and only
+ *   those — see its comment for the measured exclusions).
+ *
+ * Classifies by MESSAGE, walking the `cause` chain with the shared `chainMessages` (why
+ * text, in the module comment). Anything that is not an `Error` is never retried.
+ */
+export function isRetriableControlReadFailure(error: unknown): boolean {
+	if (!(error instanceof Error)) {
+		return false;
+	}
+	return chainMessages(error).some(message =>
+		isUncommittedTransactorAggregate(message) || isRetriableBlockUnavailable(message));
+}
+
+/**
+ * Did this control read fail because no cohort member other than the answering node could
+ * be asked about a block nobody here holds — a `BlockUnavailableError` with reason
+ * `cohort-unreachable` anywhere on the `cause` chain?
+ *
+ * Not a retry classifier. It answers "is there a better answer to wait for?", and is used
+ * by exactly one reader, `ControlDatabase.queryRevokedStamps`, to read an isolated node's
+ * never-received `Revocation` block as "no revocations known" (the reasoning is in the NOTE
+ * there). Upstream names this the one reason a caller may treat permissively
+ * (`db-core/src/transactor/network-transactor.ts`). The other reasons do NOT match:
+ * `peers-unreachable` means part of the cohort answered, and `claimed-elsewhere` /
+ * `unmaterializable` mean the block is known to exist, so an empty answer could hide a
+ * real revocation.
+ *
+ * Matched by TYPE, since the typed error survives upstream's rewraps (module comment).
+ * Fails CLOSED: a non-`Error`, a text-only copy of the message, and an error built by a
+ * second loaded copy of `@optimystic/db-core` (which `instanceof` cannot recognise) all
+ * answer false, and the reader throws as it did before this existed.
+ */
+export function isCohortUnreachableRead(error: unknown): boolean {
+	return causeChain(error).some(link =>
+		link instanceof BlockUnavailableError && link.reason === 'cohort-unreachable');
+}
+
+/**
+ * Run `attempt` — a full drain of one control read — up to
+ * {@link CONTROL_READ_ATTEMPTS} times, retrying only failures
+ * {@link isRetriableControlReadFailure} calls transient, and only while
+ * {@link CONTROL_READ_RETRY_BUDGET_MS} has not elapsed.
+ *
+ * Reads are idempotent, so `attempt` needs no atomicity contract — but it must be a
+ * COLLECTING drain, not a live iterator: a half-consumed iterator cannot be retried
+ * without re-yielding rows the caller already saw, which is why
+ * `ControlDatabase.readRows` materializes before this loop ever sees a failure.
+ *
+ * On exhaustion the LAST error is rethrown unchanged. Log lines carry the
+ * `Control read [<label>] …` prefix so a read's retries can be attributed among the
+ * several reads in flight concurrently in a real party.
+ *
+ * No reader passes an `onAbandon` observer, deliberately, though the shared options type
+ * offers one ({@link ControlRetryOptions.onAbandon}) and the loop would honour it. That hook
+ * exists because an abandoned WRITE can have no caller at all — the background self-record
+ * republish is `void`-ed with a `debug`-only catch, so giving up on it is invisible. Every
+ * control read is awaited by the caller that issued it, so an abandoned read surfaces as that
+ * caller's rejection; there is nothing here to lose silently. A fire-and-forget read would be
+ * the reason to start passing one.
+ */
+export function retryControlRead<T>(
+	attempt: () => Promise<T>,
+	options: ControlReadRetryOptions = {}
+): Promise<T> {
+	return retryControlOperation(attempt, {
+		attempts: CONTROL_READ_ATTEMPTS,
+		delaysMs: CONTROL_READ_RETRY_DELAYS_MS,
+		budgetMs: CONTROL_READ_RETRY_BUDGET_MS,
+		isRetriable: isRetriableControlReadFailure,
+		logPrefix: 'Control read',
+	}, options);
+}

package/src/control-write-retry.ts

@@ -384,9 +384,25 @@ const RETRIABLE_CONTROL_WRITE_MATCHERS: readonly ((message: string) => boolean)[
  * that landed is exactly the `UNIQUE constraint failed: CadrePeer.PeerId` failure that veto exists
  * to prevent.
  *
- * Schema init does not have that problem: `apply schema` is a diff rather than a replay and a
- * failed `create table` leaves the catalog clean, so a re-run emits only the tables that did not
- * land (the full argument is at the `loadSchema` call site in `control-database.ts`).
+ * Schema init does not have that problem: `apply schema` is a diff rather than a replay, and a
+ * failed apply is taken back whole — Quereus unwinds every step it ran and verifies the catalog
+ * against a pre-apply fingerprint — so a re-run emits exactly the DDL the live catalog is missing.
+ * The full argument, including the plugin-side dependency that unwind carries, is at the
+ * `loadSchema` call site in `control-database.ts`.
+ *
+ * RETRIED DELIBERATELY, not by oversight: the failures Quereus cannot take back. When the unwind
+ * does not complete — an undo statement threw, the post-unwind catalog did not match the pre-apply
+ * fingerprint, that catalog could not be re-collected to check, or a step the differ marks
+ * irreversible because it discards data (dropping a table or a column, narrowing a column's type —
+ * none of which a `CadreControl` diff generates today) poisoned the journal before it ran, leaving
+ * nothing unwound — Quereus keeps the failing step's own message, APPENDS the reason the
+ * schema could not be restored, and carries the original as `cause`. So a transient cause
+ * underneath still matches here, and neither veto ({@link reportsPossiblyStoredWrite},
+ * {@link reportsIndeterminateCommit}) looks for that reason text. Retrying over a partially migrated
+ * schema is safe for the same reason the ordinary re-run is: the plugin commits whatever its write
+ * batch holds, so storage and the catalog are left in step either way, and the next apply diffs
+ * against what is really there. Vetoing it instead would turn a healable transient outage into a
+ * dead start.
  */
 const RETRIABLE_SCHEMA_INIT_MATCHERS: readonly ((message: string) => boolean)[] = [
 	...RETRIABLE_CONTROL_WRITE_MATCHERS,
@@ -482,10 +498,11 @@ export type ControlWriteRetryOptions = ControlRetryOptions;
  * {@link CONTROL_WRITE_RETRY_BUDGET_MS}.
  *
  * NOTE: exactly one call site opts in today, and the re-run safety this policy assumes is that
- * site's, not a general property — `apply schema` is a diff and a failed `create table` leaves the
- * catalog clean. A second opt-in must re-derive that argument for its own write body first; if this
- * policy ever grows a third consumer, rename it for what the callers share rather than widening it
- * by default.
+ * site's, not a general property — `apply schema` is a diff, and a failed apply is unwound whole
+ * and verified against the pre-apply catalog (full argument at the `loadSchema` call site in
+ * `control-database.ts`). A second opt-in must re-derive that argument for its own write body
+ * first; if this policy ever grows a third consumer, rename it for what the callers share rather
+ * than widening it by default.
  */
 export const SCHEMA_INIT_RETRY_POLICY: Readonly<ControlWriteRetryOptions> = {
 	attempts: SCHEMA_INIT_ATTEMPTS,