@serfab/cadre-core 1.18.0 → 1.19.1

package/dist/control-read-retry.d.ts

@@ -17,16 +17,14 @@ import type { ControlRetryOptions } from './control-retry.js';
  * 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
+ * read policy. A block-unavailability failure is matched by TYPE: `OptimysticVirtualTable`
+ * rethrows a scan failure 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.
+ * (`quereus/src/runtime/emit/scan.ts`). The transactor's aggregate is matched by TEXT, since
+ * upstream raises it as a plain `Error`. Every matcher fails CLOSED — an upstream rewording or
+ * a lost `cause` stops the retry engaging, it never makes it unsafe.
  */
 /**
  * Attempts allowed per control read: the first, plus two retries. Attempts are cheap here —
@@ -92,11 +90,13 @@ export type ControlReadRetryOptions = ControlRetryOptions;
  *   `[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).
+ * - a block read the cohort could not answer ({@link reportsUnreachableCohort}, the
+ *   predicate the write classifier shares — see it for the reasons and 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.
+ * The aggregate is matched by message at any depth of the `cause` chain (`chainMessages`),
+ * the unavailability by type on the same chain. Anything that is not an `Error` is never
+ * retried, and anything unmatched is not retried either.
  */
 export declare function isRetriableControlReadFailure(error: unknown): boolean;
 /**
@@ -109,9 +109,12 @@ export declare function isRetriableControlReadFailure(error: unknown): boolean;
  * 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.
+ * `peers-unreachable` means part of the cohort answered (or no coordinator did), and
+ * `claimed-elsewhere` / `unmaterializable` mean the block is known to exist, so an empty
+ * answer could hide a real revocation. NOTE: narrower than upstream's same-named
+ * `isCohortUnreachableRead` (`@optimystic/db-core`), which also matches `peers-unreachable`
+ * and is what the retry classifiers use ({@link reportsUnreachableCohort}); do not swap one
+ * for the other.
  *
  * 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

package/dist/control-read-retry.js

@@ -1,5 +1,5 @@
 import { BlockUnavailableError } from '@optimystic/db-core';
-import { causeChain, chainMessages, retryControlOperation } from './control-retry.js';
+import { causeChain, chainMessages, reportsUnreachableCohort, retryControlOperation } from './control-retry.js';
 import { isUncommittedTransactorAggregate } from './control-write-retry.js';
 /**
  * Bounded retry for TRANSIENT control-read failures — the classifier and policy behind
@@ -19,16 +19,14 @@ import { isUncommittedTransactorAggregate } from './control-write-retry.js';
  * 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
+ * read policy. A block-unavailability failure is matched by TYPE: `OptimysticVirtualTable`
+ * rethrows a scan failure 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.
+ * (`quereus/src/runtime/emit/scan.ts`). The transactor's aggregate is matched by TEXT, since
+ * upstream raises it as a plain `Error`. Every matcher fails CLOSED — an upstream rewording or
+ * a lost `cause` stops the retry engaging, it never makes it unsafe.
  */
 /**
  * Attempts allowed per control read: the first, plus two retries. Attempts are cheap here —
@@ -77,42 +75,6 @@ export const CONTROL_READ_RETRY_DELAYS_MS = [100, 400];
  */
 // eslint-disable-next-line no-restricted-syntax -- cuts off by design: a slow attempt is not retried, because the admission gate this budget is sized for has already failed open by then; see docs/cadre-consistency.md → "Deadlines Over Optimystic's Reads and Commits"
 export const CONTROL_READ_RETRY_BUDGET_MS = 1500;
-/**
- * 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) {
-    return RETRIABLE_BLOCK_UNAVAILABLE.test(message);
-}
 /**
  * Did this control read fail in a way a repeat read can improve on?
  *
@@ -123,17 +85,20 @@ function isRetriableBlockUnavailable(message) {
  *   `[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).
+ * - a block read the cohort could not answer ({@link reportsUnreachableCohort}, the
+ *   predicate the write classifier shares — see it for the reasons and 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.
+ * The aggregate is matched by message at any depth of the `cause` chain (`chainMessages`),
+ * the unavailability by type on the same chain. Anything that is not an `Error` is never
+ * retried, and anything unmatched is not retried either.
  */
 export function isRetriableControlReadFailure(error) {
     if (!(error instanceof Error)) {
         return false;
     }
-    return chainMessages(error).some(message => isUncommittedTransactorAggregate(message) || isRetriableBlockUnavailable(message));
+    return reportsUnreachableCohort(causeChain(error))
+        || chainMessages(error).some(isUncommittedTransactorAggregate);
 }
 /**
  * Did this control read fail because no cohort member other than the answering node could
@@ -145,9 +110,12 @@ export function isRetriableControlReadFailure(error) {
  * 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.
+ * `peers-unreachable` means part of the cohort answered (or no coordinator did), and
+ * `claimed-elsewhere` / `unmaterializable` mean the block is known to exist, so an empty
+ * answer could hide a real revocation. NOTE: narrower than upstream's same-named
+ * `isCohortUnreachableRead` (`@optimystic/db-core`), which also matches `peers-unreachable`
+ * and is what the retry classifiers use ({@link reportsUnreachableCohort}); do not swap one
+ * for the other.
  *
  * 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

package/dist/control-read-retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-read-retry.js","sourceRoot":"","sources":["../src/control-read-retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEtF,OAAO,EAAE,gCAAgC,EAAE,MAAM,0BAA0B,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,2QAA2Q;AAC3Q,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAK,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,2BAA2B,GAChC,uEAAuE,CAAC;AAEzE,kFAAkF;AAClF,SAAS,2BAA2B,CAAC,OAAe;IACnD,OAAO,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClD,CAAC;AAWD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAAc;IAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAC1C,gCAAgC,CAAC,OAAO,CAAC,IAAI,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACrD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpC,IAAI,YAAY,qBAAqB,IAAI,IAAI,CAAC,MAAM,KAAK,oBAAoB,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAC/B,OAAyB,EACzB,UAAmC,EAAE;IAErC,OAAO,qBAAqB,CAAC,OAAO,EAAE;QACrC,QAAQ,EAAE,qBAAqB;QAC/B,QAAQ,EAAE,4BAA4B;QACtC,QAAQ,EAAE,4BAA4B;QACtC,WAAW,EAAE,6BAA6B;QAC1C,SAAS,EAAE,cAAc;KACzB,EAAE,OAAO,CAAC,CAAC;AACb,CAAC"}
+{"version":3,"file":"control-read-retry.js","sourceRoot":"","sources":["../src/control-read-retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhH,OAAO,EAAE,gCAAgC,EAAE,MAAM,0BAA0B,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,2QAA2Q;AAC3Q,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAK,CAAC;AAWlD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAAc;IAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,wBAAwB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;WAC9C,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACrD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpC,IAAI,YAAY,qBAAqB,IAAI,IAAI,CAAC,MAAM,KAAK,oBAAoB,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAC/B,OAAyB,EACzB,UAAmC,EAAE;IAErC,OAAO,qBAAqB,CAAC,OAAO,EAAE;QACrC,QAAQ,EAAE,qBAAqB;QAC/B,QAAQ,EAAE,4BAA4B;QACtC,QAAQ,EAAE,4BAA4B;QACtC,WAAW,EAAE,6BAA6B;QAC1C,SAAS,EAAE,cAAc;KACzB,EAAE,OAAO,CAAC,CAAC;AACb,CAAC"}

package/dist/control-retry.d.ts

@@ -130,10 +130,10 @@ export interface ControlRetryOptions {
  */
 export declare function retryControlOperation<T>(attempt: () => Promise<T>, policy: ControlRetryPolicy, options?: ControlRetryOptions): Promise<T>;
 /**
- * Every message in the failure's `cause` chain — the shared substrate both retry classifiers
- * match against. They match text (why, in `control-read-retry.ts`'s module comment); every
- * wrap on the way out of optimystic and Quereus embeds the inner message, so the text of
- * the deepest failure is visible at every level.
+ * Every message in the failure's `cause` chain — the substrate both retry classifiers match
+ * their text matchers against (the transactor's aggregate and the coordinator's shortfall are
+ * plain `Error`s, recognisable only by text); every wrap on the way out of optimystic and
+ * Quereus embeds the inner message, so the text of the deepest failure is visible at every level.
  *
  * `unwrapError` declares its `message` as `string`, but it follows `.cause` without checking
  * what that holds — a chain link that is not an `Error` (a stream rejected with a bare string
@@ -149,8 +149,52 @@ export declare function retryControlOperation<T>(attempt: () => Promise<T>, poli
 export declare function chainMessages(error: Error): string[];
 /**
  * `error` and every `cause` below it, outermost first — the substrate for the classifiers that
- * match by TYPE rather than text (the read side's cohort-unreachable check, the write side's
- * possibly-stored veto). Stops at a non-`Error` link (it can carry no further `cause` worth
+ * match by TYPE rather than text ({@link reportsUnreachableCohort}, the read side's isolated-node
+ * check, the write side's possibly-stored veto). Stops at a non-`Error` link (it can carry no further `cause` worth
  * trusting) and at a repeat, so a cyclic chain terminates.
  */
 export declare function causeChain(error: unknown): Error[];
+/**
+ * Does any link of the `cause` chain report a block read that failed because the cohort could not
+ * be asked — a `BlockUnavailableError` whose reason is `peers-unreachable` or `cohort-unreachable`?
+ * The one block-unavailability test both retry classifiers share, so the read and write policies
+ * cannot disagree on which reasons a repeat can improve on:
+ *
+ * - **`peers-unreachable`** — part of the cohort answered and part could not be asked, or no
+ *   coordinator answered the read at all (`NetworkTransactor.get` flags such a block rather than
+ *   failing the whole read). Another attempt can reach one that answers; 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 each policy's elapsed budget
+ *   bounds the cost of being wrong, 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 — a 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.
+ * - **`BlockPossiblyStaleError`** (`Block <id> may be stale`) — about currency, not existence: a
+ *   cohort claim no reachable coordinator could confirm or refute will not resolve inside a few
+ *   hundred milliseconds of backoff.
+ *
+ * The reason set is upstream's (`isCohortUnreachableRead`, `db-core/src/transaction/commit-failure-class.ts`),
+ * the rule its commit-failure sort and the plugin's offline reads use for "the cohort could not be
+ * reached". NOTE: a reason upstream adds to that set is therefore retried here with no change in
+ * this repo — the right default for a set defined as unreachability; if it ever grows, re-check it
+ * against the exclusions above.
+ *
+ * Matched by TYPE. Upstream builds this error only on the node doing the read, from the
+ * `unavailable` flag a get result carries (`TransactorSource.tryGet`, `NetworkTransactor.getStatus`),
+ * never from a peer's error, and every rewrap on the way to either funnel keeps `cause`. NOTE: an
+ * error built by a second loaded copy of `@optimystic/db-core`, or one rebuilt as a plain `Error`
+ * from its text, fails `instanceof` and is not retried — the safe side.
+ */
+export declare function reportsUnreachableCohort(links: readonly Error[]): boolean;

package/dist/control-retry.js

@@ -1,4 +1,5 @@
 import debug from 'debug';
+import { isCohortUnreachableRead } from '@optimystic/db-core';
 import { unwrapError } from '@quereus/quereus';
 const log = debug('sereus:cadre:control-db');
 /**
@@ -100,10 +101,10 @@ function notifyAbandoned(listener, prefix, tag, abandonment) {
     }
 }
 /**
- * Every message in the failure's `cause` chain — the shared substrate both retry classifiers
- * match against. They match text (why, in `control-read-retry.ts`'s module comment); every
- * wrap on the way out of optimystic and Quereus embeds the inner message, so the text of
- * the deepest failure is visible at every level.
+ * Every message in the failure's `cause` chain — the substrate both retry classifiers match
+ * their text matchers against (the transactor's aggregate and the coordinator's shortfall are
+ * plain `Error`s, recognisable only by text); every wrap on the way out of optimystic and
+ * Quereus embeds the inner message, so the text of the deepest failure is visible at every level.
  *
  * `unwrapError` declares its `message` as `string`, but it follows `.cause` without checking
  * what that holds — a chain link that is not an `Error` (a stream rejected with a bare string
@@ -123,8 +124,8 @@ export function chainMessages(error) {
 }
 /**
  * `error` and every `cause` below it, outermost first — the substrate for the classifiers that
- * match by TYPE rather than text (the read side's cohort-unreachable check, the write side's
- * possibly-stored veto). Stops at a non-`Error` link (it can carry no further `cause` worth
+ * match by TYPE rather than text ({@link reportsUnreachableCohort}, the read side's isolated-node
+ * check, the write side's possibly-stored veto). Stops at a non-`Error` link (it can carry no further `cause` worth
  * trusting) and at a repeat, so a cyclic chain terminates.
  */
 export function causeChain(error) {
@@ -136,6 +137,52 @@ export function causeChain(error) {
     }
     return links;
 }
+/**
+ * Does any link of the `cause` chain report a block read that failed because the cohort could not
+ * be asked — a `BlockUnavailableError` whose reason is `peers-unreachable` or `cohort-unreachable`?
+ * The one block-unavailability test both retry classifiers share, so the read and write policies
+ * cannot disagree on which reasons a repeat can improve on:
+ *
+ * - **`peers-unreachable`** — part of the cohort answered and part could not be asked, or no
+ *   coordinator answered the read at all (`NetworkTransactor.get` flags such a block rather than
+ *   failing the whole read). Another attempt can reach one that answers; 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 each policy's elapsed budget
+ *   bounds the cost of being wrong, 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 — a 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.
+ * - **`BlockPossiblyStaleError`** (`Block <id> may be stale`) — about currency, not existence: a
+ *   cohort claim no reachable coordinator could confirm or refute will not resolve inside a few
+ *   hundred milliseconds of backoff.
+ *
+ * The reason set is upstream's (`isCohortUnreachableRead`, `db-core/src/transaction/commit-failure-class.ts`),
+ * the rule its commit-failure sort and the plugin's offline reads use for "the cohort could not be
+ * reached". NOTE: a reason upstream adds to that set is therefore retried here with no change in
+ * this repo — the right default for a set defined as unreachability; if it ever grows, re-check it
+ * against the exclusions above.
+ *
+ * Matched by TYPE. Upstream builds this error only on the node doing the read, from the
+ * `unavailable` flag a get result carries (`TransactorSource.tryGet`, `NetworkTransactor.getStatus`),
+ * never from a peer's error, and every rewrap on the way to either funnel keeps `cause`. NOTE: an
+ * error built by a second loaded copy of `@optimystic/db-core`, or one rebuilt as a plain `Error`
+ * from its text, fails `instanceof` and is not retried — the safe side.
+ */
+export function reportsUnreachableCohort(links) {
+    return links.some(link => isCohortUnreachableRead(link));
+}
 /**
  * Backoff for the retry that follows attempt `attemptNumber`: the matching base delay
  * (last entry repeats), jittered ±50%, then capped at the list's largest base so no single

package/dist/control-retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-retry.js","sourceRoot":"","sources":["../src/control-retry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"control-retry.js","sourceRoot":"","sources":["../src/control-retry.ts"],"names":[],"mappings":"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"}

package/dist/control-write-retry.d.ts

@@ -112,7 +112,9 @@ export declare const CONTROL_WRITE_RETRY_BUDGET_MS = 10000;
  * re-present:
  *
  * - `get` (a block read, which a write body also performs) and `pend` (phase 1) fail before
- *   anything commits, so the write is known not to have landed;
+ *   anything commits, so the write is known not to have landed. `get` raises it only when a
+ *   coordinator answered and left a block out; a block nobody answered for fails typed
+ *   instead, which {@link matchesRetriableFailure} claims ({@link reportsUnreachableCohort});
  * - `commitBlocks` (phase 2) is REACHABLE here and NOT safe. `commitBlock` throws the
  *   aggregate when a header/tail commit got NO response at all — precisely the transient
  *   class this retry targets — and that escapes `commit()`, survives `TransactorSource`'s
@@ -135,10 +137,12 @@ export declare const CONTROL_WRITE_RETRY_BUDGET_MS = 10000;
  * NOTE: the discriminator is a formatting detail of another repo. If Optimystic ever reformats
  * those per-batch details, this fails CLOSED — the aggregate stops matching and control writes
  * simply stop being retried, silently losing the absorption rather than doing anything unsafe.
- * The guard against that is live: `control-write-degraded-cohort-member.integration.ts` asserts
- * this classifier against the real degraded-cohort failure object and asserts the `[block:`
- * token on the live aggregate; if it reddens there, an upstream reformat is the first thing to
- * check.
+ * The guard is `control-write-degraded-cohort-member.integration.ts`, which asserts the `[block:`
+ * token on any live aggregate a degraded case produces; if it reddens there, an upstream reformat
+ * is the first thing to check. NOTE: on Optimystic 1.20.0 none of its cases produced this form
+ * (2026-10-28: the injected reset failed the write's read typed, and a pend's shortfall arrives on
+ * its own), so the guard can pass without seeing it; if the form is ever needed live again, inject
+ * the reset at the pend's batch rather than the read's.
  *
  * NOTE: the discriminator is the prefix AND the token within ONE message — never relax it to
  * "contains `[block:`". Beyond the `get` and `pend` sites above, Optimystic renders `[block:` in
@@ -163,12 +167,14 @@ export declare const CONTROL_WRITE_RETRY_BUDGET_MS = 10000;
  *    have left its log entry standing), and its collection sync has already spent ten retries on
  *    the race. The torn-write rule beside it: a `TornActionError` is re-presented only when
  *    `final` is true; any other torn write is declined.
- *  - What remains rejectable at the promise phase is stale revision, block-unavailable,
- *    membership-not-admitted, and a configured validator's refusal. Only the first is worth a
- *    retry — and it is worth one: this loop re-runs the WHOLE write body, reads included
+ *  - What remains rejectable at the promise phase is stale revision, membership-not-admitted, an
+ *    expired transaction, and a configured validator's refusal (`ClusterMember.evaluatePromise`).
+ *    A block whose revision a member cannot establish is approved, not refused: the member logs
+ *    `validation-block-unavailable` and votes on (`judgeStaleRevisions`). Stale revision is worth
+ *    a retry: this loop re-runs the WHOLE write body, reads included
  *    (`ControlDatabase.withWriteLock`'s contract), so attempt 2 presents a pend against the
  *    revision that made attempt 1 stale. A blanket "decline any chain reporting a validator
- *    rejection" rule would remove that retry to save two wasted attempts on the other three.
+ *    rejection" rule would remove that retry to save two wasted attempts on the others.
  *
  * Revisit if a re-presentation ever becomes expensive relative to what it buys — a rejection class
  * that costs a full cohort round-trip to re-present, or a write body whose reads are no longer
@@ -199,16 +205,18 @@ export declare function isUncommittedTransactorAggregate(message: string): boole
  * Two vetoes run over the whole chain before any matcher: {@link reportsPossiblyStoredWrite}
  * (by type — a spent sync budget, a non-final torn write, a partial commit) and
  * {@link reportsIndeterminateCommit} (by text — a commit-phase batch). A chain either veto flags,
- * at any level, is never retried on the strength of some other level looking transient. The one
- * typed failure claimed as retriable is a final torn write ({@link isFinalTornWrite}).
+ * at any level, is never retried on the strength of some other level looking transient. Two typed
+ * failures are claimed as retriable: a block read the cohort could not answer
+ * ({@link reportsUnreachableCohort}, shared with the read classifier) and a final torn write
+ * ({@link isFinalTornWrite}).
  *
  * NOTE: this depends on engine/transactor error TEXT. The messages producible without a
  * network are driven from the REAL engine in `control-formation-seat-budget.spec.ts`, so
- * a rewording reddens a spec rather than silently disabling the retry. The two RETRIABLE
- * messages need a real multi-node cluster to produce; the degraded-cohort scenario
- * (`control-write-degraded-cohort-member.integration.ts`) asserts this classifier against
- * both LIVE — the super-majority shortfall from a real silent member, and the transactor
- * aggregate from a real stream reset, which the retry there absorbs end to end.
+ * a rewording reddens a spec rather than silently disabling the retry. The RETRIABLE failures
+ * need a real multi-node cluster to produce; the degraded-cohort scenario
+ * (`control-write-degraded-cohort-member.integration.ts`) asserts this classifier against the
+ * super-majority shortfall from a real silent member, and absorbs a real stream reset end to end
+ * (on Optimystic 1.20.0 the reset fails the write's read as an unanswered block, claimed by type).
  */
 export declare function isRetriableControlWriteFailure(error: unknown): boolean;
 /**

package/dist/control-write-retry.js

@@ -1,6 +1,6 @@
 import { CoordinatorPartialCommitError, SyncRetryExhaustedError, TornActionError } from '@optimystic/db-core';
 import { ConcurrentModificationError, PartialCommitError } from '@optimystic/quereus-plugin-optimystic';
-import { causeChain, chainMessages, retryControlOperation } from './control-retry.js';
+import { causeChain, chainMessages, reportsUnreachableCohort, retryControlOperation } from './control-retry.js';
 /**
  * Bounded retry for TRANSIENT control-write failures — the classifier and loop behind
  * `ControlDatabase.lockedWithRetry`, the single funnel every local control write passes
@@ -148,11 +148,17 @@ const SINGLE_BLOCK_BATCH_TOKEN = '[block:';
  */
 const COMMIT_BATCH_TOKEN = '[blocks:';
 /**
- * The cluster coordinator's super-majority shortfall (`db-p2p/src/repo/cluster-coordinator.ts`),
- * matched ONLY with a ZERO rejection count. The same message with a non-zero count means a
- * member actually voted no (that branch carries `membership-not-admitted` rejections), and
- * retrying it would re-present a spent signature to a cohort that already refused it. This one
- * is raised while collecting PROMISES, before any commit, so re-presenting it is safe.
+ * The cluster coordinator's super-majority shortfall (`PromiseShortfallError`, db-core), matched
+ * ONLY with a ZERO rejection count. The same message with a non-zero count means a member actually
+ * voted no (that branch carries `membership-not-admitted` rejections), and retrying it would
+ * re-present a spent signature to a cohort that already refused it. A pend's shortfall reaches this
+ * funnel as that error on its own, before any commit, so re-presenting it is safe; a commit's
+ * arrives inside the `[blocks:` aggregate, which {@link reportsIndeterminateCommit} vetoes (both
+ * seen live in `control-write-degraded-cohort-member`).
+ *
+ * NOTE: matched by TEXT although the error is typed. Upstream keeps this sentence byte for byte as a
+ * downstream contract, so the regex is stable; moving to `instanceof PromiseShortfallError` with
+ * `rejections === 0` is backlog `debt-control-write-retry-matches-the-shortfall-by-type`.
  *
  * This regex itself never matches a decisive rejection (`ValidatorRejectionError`, `Transaction
  * rejected by validators`) — that text carries no `Failed to get super-majority:` prefix. But the
@@ -170,7 +176,9 @@ const SUPER_MAJORITY_SHORTFALL_UNANSWERED = /Failed to get super-majority: \d+\/
  * re-present:
  *
  * - `get` (a block read, which a write body also performs) and `pend` (phase 1) fail before
- *   anything commits, so the write is known not to have landed;
+ *   anything commits, so the write is known not to have landed. `get` raises it only when a
+ *   coordinator answered and left a block out; a block nobody answered for fails typed
+ *   instead, which {@link matchesRetriableFailure} claims ({@link reportsUnreachableCohort});
  * - `commitBlocks` (phase 2) is REACHABLE here and NOT safe. `commitBlock` throws the
  *   aggregate when a header/tail commit got NO response at all — precisely the transient
  *   class this retry targets — and that escapes `commit()`, survives `TransactorSource`'s
@@ -193,10 +201,12 @@ const SUPER_MAJORITY_SHORTFALL_UNANSWERED = /Failed to get super-majority: \d+\/
  * NOTE: the discriminator is a formatting detail of another repo. If Optimystic ever reformats
  * those per-batch details, this fails CLOSED — the aggregate stops matching and control writes
  * simply stop being retried, silently losing the absorption rather than doing anything unsafe.
- * The guard against that is live: `control-write-degraded-cohort-member.integration.ts` asserts
- * this classifier against the real degraded-cohort failure object and asserts the `[block:`
- * token on the live aggregate; if it reddens there, an upstream reformat is the first thing to
- * check.
+ * The guard is `control-write-degraded-cohort-member.integration.ts`, which asserts the `[block:`
+ * token on any live aggregate a degraded case produces; if it reddens there, an upstream reformat
+ * is the first thing to check. NOTE: on Optimystic 1.20.0 none of its cases produced this form
+ * (2026-10-28: the injected reset failed the write's read typed, and a pend's shortfall arrives on
+ * its own), so the guard can pass without seeing it; if the form is ever needed live again, inject
+ * the reset at the pend's batch rather than the read's.
  *
  * NOTE: the discriminator is the prefix AND the token within ONE message — never relax it to
  * "contains `[block:`". Beyond the `get` and `pend` sites above, Optimystic renders `[block:` in
@@ -221,12 +231,14 @@ const SUPER_MAJORITY_SHORTFALL_UNANSWERED = /Failed to get super-majority: \d+\/
  *    have left its log entry standing), and its collection sync has already spent ten retries on
  *    the race. The torn-write rule beside it: a `TornActionError` is re-presented only when
  *    `final` is true; any other torn write is declined.
- *  - What remains rejectable at the promise phase is stale revision, block-unavailable,
- *    membership-not-admitted, and a configured validator's refusal. Only the first is worth a
- *    retry — and it is worth one: this loop re-runs the WHOLE write body, reads included
+ *  - What remains rejectable at the promise phase is stale revision, membership-not-admitted, an
+ *    expired transaction, and a configured validator's refusal (`ClusterMember.evaluatePromise`).
+ *    A block whose revision a member cannot establish is approved, not refused: the member logs
+ *    `validation-block-unavailable` and votes on (`judgeStaleRevisions`). Stale revision is worth
+ *    a retry: this loop re-runs the WHOLE write body, reads included
  *    (`ControlDatabase.withWriteLock`'s contract), so attempt 2 presents a pend against the
  *    revision that made attempt 1 stale. A blanket "decline any chain reporting a validator
- *    rejection" rule would remove that retry to save two wasted attempts on the other three.
+ *    rejection" rule would remove that retry to save two wasted attempts on the others.
  *
  * Revisit if a re-presentation ever becomes expensive relative to what it buys — a rejection class
  * that costs a full cohort round-trip to re-present, or a write body whose reads are no longer
@@ -381,7 +393,9 @@ function isSelfCoordinationGraceRefusal(message) {
 /**
  * The error messages that mean "the cohort did not answer AND nothing committed", and nothing
  * else. The observed one-shot failure was `registerSelf()` racing a connection still forming:
- * a read/pend-phase transactor aggregate with `cause=The stream has been reset`.
+ * a read/pend-phase transactor aggregate with `cause=The stream has been reset`. When none of
+ * the cohort answers the read at all, that failure arrives typed instead, and is claimed by
+ * type in {@link matchesRetriableFailure} ({@link reportsUnreachableCohort}), not here.
  *
  * Deliberately NOT matched: every constraint / authorization failure
  * (`CHECK constraint failed:`, `UNIQUE constraint failed:`) — those reach the same funnel
@@ -446,16 +460,18 @@ const RETRIABLE_SCHEMA_INIT_MATCHERS = [
  * Two vetoes run over the whole chain before any matcher: {@link reportsPossiblyStoredWrite}
  * (by type — a spent sync budget, a non-final torn write, a partial commit) and
  * {@link reportsIndeterminateCommit} (by text — a commit-phase batch). A chain either veto flags,
- * at any level, is never retried on the strength of some other level looking transient. The one
- * typed failure claimed as retriable is a final torn write ({@link isFinalTornWrite}).
+ * at any level, is never retried on the strength of some other level looking transient. Two typed
+ * failures are claimed as retriable: a block read the cohort could not answer
+ * ({@link reportsUnreachableCohort}, shared with the read classifier) and a final torn write
+ * ({@link isFinalTornWrite}).
  *
  * NOTE: this depends on engine/transactor error TEXT. The messages producible without a
  * network are driven from the REAL engine in `control-formation-seat-budget.spec.ts`, so
- * a rewording reddens a spec rather than silently disabling the retry. The two RETRIABLE
- * messages need a real multi-node cluster to produce; the degraded-cohort scenario
- * (`control-write-degraded-cohort-member.integration.ts`) asserts this classifier against
- * both LIVE — the super-majority shortfall from a real silent member, and the transactor
- * aggregate from a real stream reset, which the retry there absorbs end to end.
+ * a rewording reddens a spec rather than silently disabling the retry. The RETRIABLE failures
+ * need a real multi-node cluster to produce; the degraded-cohort scenario
+ * (`control-write-degraded-cohort-member.integration.ts`) asserts this classifier against the
+ * super-majority shortfall from a real silent member, and absorbs a real stream reset end to end
+ * (on Optimystic 1.20.0 the reset fails the write's read as an unanswered block, claimed by type).
  */
 export function isRetriableControlWriteFailure(error) {
     return matchesRetriableFailure(error, RETRIABLE_CONTROL_WRITE_MATCHERS);
@@ -483,12 +499,13 @@ export function isRetriableLostUpdateFailure(error) {
 /**
  * Shared body of the three classifiers: walk the `cause` chain, let
  * {@link reportsPossiblyStoredWrite} and then {@link reportsIndeterminateCommit} veto it, then claim
- * a final torn write ({@link isFinalTornWrite}) or any link `claimsLink` names, then ask `matchers`.
- * The vetoes run BEFORE any claim for every policy — a chain reporting a possibly-stored write or a
- * commit-phase batch is never retried, however transient some other level looks, and a final torn
- * write or a lost update carried by a partial commit is still declined because a sibling collection
- * landed. `claimsLink` is the one typed claim a policy may add; it sits here beside the torn-write
- * claim so the vetoes stay in one place above both.
+ * a block read the cohort could not answer ({@link reportsUnreachableCohort}), a final torn write
+ * ({@link isFinalTornWrite}) or any link `claimsLink` names, then ask `matchers`. The vetoes run
+ * BEFORE any claim for every policy — a chain reporting a possibly-stored write or a commit-phase
+ * batch is never retried, however transient some other level looks, and a final torn write or a
+ * lost update carried by a partial commit is still declined because a sibling collection landed.
+ * `claimsLink` is the one typed claim a policy may add; it sits here beside the shared typed claims
+ * so the vetoes stay in one place above all of them.
  */
 function matchesRetriableFailure(error, matchers, claimsLink) {
     if (!(error instanceof Error)) {
@@ -502,7 +519,18 @@ function matchesRetriableFailure(error, matchers, claimsLink) {
     if (reportsIndeterminateCommit(messages)) {
         return false;
     }
-    if (links.some(link => isFinalTornWrite(link) || claimsLink?.(link) === true)) {
+    // NOTE: an unanswered read can fail AFTER this write's log entry is stored: the refresh between
+    // commit attempts reads the collection's log ends, and finishing the write's own entry
+    // (`Collection.completeOwnEntry`) asks `getStatus` when no attempt is retained at the entry's
+    // revision (a forked lineage — both commit paths retain the failed attempt before refreshing).
+    // Either throw escapes the refresh loop unwrapped. Claimed anyway, because the `[block:`
+    // aggregate those same reads raise is already claimed by the text matcher, so the typed form
+    // adds no new case: the re-run is a new transaction whose body re-reads the blocks, so it diffs
+    // to nothing or fails on `UNIQUE` where the earlier write landed, and writes it once where it did
+    // not. A refresh that already saved a sibling collection arrives as
+    // `CoordinatorPartialCommitError`, which the veto above declines.
+    if (reportsUnreachableCohort(links)
+        || links.some(link => isFinalTornWrite(link) || claimsLink?.(link) === true)) {
         return true;
     }
     return messages.some(message => matchers.some(matches => matches(message)));