@serfab/cadre-core 0.12.0 → 1.0.0

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

@@ -14,8 +14,19 @@ import type { ControlRetryOptions } from './control-retry.js';
  * a moment later, which the degraded-cohort-member scenario measured as safe (a failed
  * write rolls back, nothing half-commits) and effective (the next write commits in ~1 s).
  *
- * A write somebody actually REJECTED is never retried — re-presenting it would re-present
- * a spent signature against a cohort that already said no.
+ * A write somebody actually REJECTED is never retried on the strength of the rejection itself —
+ * no matcher here claims a rejection message, at any phase, because re-presenting one would
+ * re-present a spent signature against a cohort that already said no. Rejections are re-presented
+ * anyway when they arrive inside the transactor's promise-phase `[block:` aggregate, which
+ * {@link isUncommittedTransactorAggregate} claims on the WRAPPER alone, whatever the cause inside
+ * says. Safe because nothing has committed at that phase, and deliberately kept — one of the
+ * remaining promise-phase rejections is exactly the kind a re-presentation fixes. See the
+ * accepted-tradeoff `NOTE:` there for which, and why no blanket rejection veto is wanted.
+ *
+ * A failure that says some of the write may be STORED is a different matter, and never
+ * re-presented whatever text it carries: {@link reportsPossiblyStoredWrite} vetoes it by type
+ * before any matcher runs. The one half-landed write that IS re-presented is a torn write the
+ * library marks final — not saved and unable to land ({@link isFinalTornWrite}).
  *
  * TWO policies ship from here, and the split is deliberate: the default
  * ({@link isRetriableControlWriteFailure}, {@link CONTROL_WRITE_ATTEMPTS}) sits under every
@@ -63,6 +74,17 @@ export declare const SCHEMA_INIT_ATTEMPTS = 5;
  * attempts, measured in `control-write-degraded-cohort-member.integration.ts`), which
  * already exceeds this budget when attempt 1 returns — so that case is surfaced immediately
  * and retry adds ZERO latency to the case where it cannot help.
+ *
+ * NOTE: a failed commit attempt now also pays a cancel discharge before its error returns
+ * (optimystic `TransactorSource.transact`'s catch, added by upstream
+ * `1-a-failed-attempt-must-discharge-its-own-pend`) — bounded by six rounds and
+ * `abortOrCancelTimeoutMs`, which every collection this repo opens sets to 5 s
+ * (`../optimystic/packages/quereus-plugin-optimystic/src/optimystic-adapter/collection-factory.ts`).
+ * Two failed attempts whose cancels each run their full budget would consume this whole 10 s
+ * ceiling and cut the three-attempt policy to two. Not observed — every measured round of the
+ * transient-reset case committed on attempt 3 of 3 — so this is a condition to watch, not work
+ * to do: if that case ever starts failing with `failed after 2/3 attempt(s)`, the cancel
+ * discharge is where the time went.
  */
 export declare const CONTROL_WRITE_RETRY_BUDGET_MS = 10000;
 /**
@@ -101,6 +123,42 @@ export declare const CONTROL_WRITE_RETRY_BUDGET_MS = 10000;
  * token on the live aggregate; if it reddens there, an upstream reformat is the first thing to
  * check.
  *
+ * 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
+ * one further place — a third formatter, outside the aggregate's three sites — `dischargeCancel`
+ * (`Cancel of action <id> did not discharge <n> block(s): …`), which does not raise the
+ * `Some peers did not complete:` prefix; only the conjunction keeps a cancel fault from
+ * classifying as a retriable get/pend (checked against optimystic `c56c2bd4`, 2026-09-16).
+ *
+ * NOTE: accepted tradeoff — a REJECTION raised while promises are still being collected reaches
+ * this repo wrapped in this same aggregate, and this matcher claims it on the wrapper alone,
+ * whatever the cause inside says. That re-presents such a rejection up to two more times inside
+ * the 10 s budget. Kept deliberately, and re-decided on 2026-09-17 against the current upstream
+ * behaviour rather than inherited:
+ *
+ *  - Contention is no longer a rejection at all. "Another write holds this block right now"
+ *    (`pending conflict`) is now a `held` verdict that counts toward neither approvals nor
+ *    rejections (`validatePendOperations`,
+ *    `../optimystic/packages/db-p2p/src/cluster/cluster-repo.ts`), so the rejection this tradeoff
+ *    was originally written about does not arrive any more. It reaches this funnel as
+ *    `SyncRetryExhaustedError` instead, which {@link reportsPossiblyStoredWrite} declines by type
+ *    — upstream documents resubmitting after it as unsafe (the attempt that spent the budget may
+ *    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
+ *    (`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.
+ *
+ * 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
+ * cheap — or when upstream offers a typed refusal surface to classify on instead of this text
+ * (`../optimystic/tickets/backlog/debt-a-downstream-repo-classifies-retries-by-parsing-our-error-text`).
+ * Contention is no longer the reason to revisit.
+ *
  * An aggregate whose details came out EMPTY (possible when `formatBatchStatuses` has no
  * batches to format) carries neither token, matches nothing here, and is not retried — an
  * unattributable failure is not a proven non-commit.
@@ -114,16 +172,18 @@ export declare function isUncommittedTransactorAggregate(message: string): boole
  * Did this control write fail because the cluster cohort did not ANSWER — i.e. is
  * re-presenting the SAME signed write a moment later the right response?
  *
- * Classifies by MESSAGE, walking the `cause` chain with the shared {@link chainMessages}
- * (Quereus' own `unwrapError` underneath) —
- * the failure surface is not recognisable by type. The transactor and the coordinator both throw bare `Error`s, and by
- * the time one reaches `ControlDatabase` it is wrapped in a `QuereusError` (the real chain
- * is `QuereusError` → `Error` → `Error`), so the match must work at any depth. Anything
- * that is not an `Error` is never retried.
+ * Classifies the transient cases by MESSAGE, walking the `cause` chain with the shared
+ * {@link chainMessages} (Quereus' own `unwrapError` underneath) — the transactor and the
+ * coordinator both throw bare `Error`s, not recognisable by type. By the time one reaches
+ * `ControlDatabase` it is wrapped in a `QuereusError` (the real chain is `QuereusError` → `Error`
+ * → `Error`), so the match must work at any depth. Anything that is not an `Error` is never
+ * retried.
  *
- * {@link reportsIndeterminateCommit} vetoes the whole chain before any matcher runs, so a
- * failure that reports a commit-phase batch anywhere is never retried on the strength of some
- * other level looking transient.
+ * 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}).
  *
  * 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
@@ -181,5 +241,14 @@ export declare const SCHEMA_INIT_RETRY_POLICY: Readonly<ControlWriteRetryOptions
  * On exhaustion (attempts or budget) the LAST error is rethrown unchanged — never wrapped,
  * so the exact messages downstream code and the degraded-cohort-member scenario assert on
  * survive. A non-retriable failure propagates from the attempt that raised it.
+ *
+ * Either way — declined or exhausted — an `options.onAbandon` observer is notified exactly
+ * once before the rethrow (a `ControlRetryAbandonment`). Only WRITES pass one: an abandoned
+ * read throws to a caller that is awaiting it, so nothing is lost silently there
+ * (`control-read-retry.ts` says so at its own seam), while an abandoned write may have no
+ * caller at all — a background self-record republish is `void`-ed with a `debug` catch, so
+ * its failure reaches nobody unless something is listening here.
+ * `ControlDatabase.setControlWriteAbandonedListener` is the only thing that passes one in
+ * production; `retryControlWrite` itself neither supplies nor requires an observer.
  */
 export declare function retryControlWrite<T>(attempt: () => Promise<T>, options?: ControlWriteRetryOptions): Promise<T>;

package/dist/control-write-retry.js

@@ -1,4 +1,6 @@
-import { chainMessages, retryControlOperation } from './control-retry.js';
+import { CoordinatorPartialCommitError, SyncRetryExhaustedError, TornActionError } from '@optimystic/db-core';
+import { PartialCommitError } from '@optimystic/quereus-plugin-optimystic';
+import { causeChain, chainMessages, 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
@@ -14,8 +16,19 @@ import { chainMessages, retryControlOperation } from './control-retry.js';
  * a moment later, which the degraded-cohort-member scenario measured as safe (a failed
  * write rolls back, nothing half-commits) and effective (the next write commits in ~1 s).
  *
- * A write somebody actually REJECTED is never retried — re-presenting it would re-present
- * a spent signature against a cohort that already said no.
+ * A write somebody actually REJECTED is never retried on the strength of the rejection itself —
+ * no matcher here claims a rejection message, at any phase, because re-presenting one would
+ * re-present a spent signature against a cohort that already said no. Rejections are re-presented
+ * anyway when they arrive inside the transactor's promise-phase `[block:` aggregate, which
+ * {@link isUncommittedTransactorAggregate} claims on the WRAPPER alone, whatever the cause inside
+ * says. Safe because nothing has committed at that phase, and deliberately kept — one of the
+ * remaining promise-phase rejections is exactly the kind a re-presentation fixes. See the
+ * accepted-tradeoff `NOTE:` there for which, and why no blanket rejection veto is wanted.
+ *
+ * A failure that says some of the write may be STORED is a different matter, and never
+ * re-presented whatever text it carries: {@link reportsPossiblyStoredWrite} vetoes it by type
+ * before any matcher runs. The one half-landed write that IS re-presented is a torn write the
+ * library marks final — not saved and unable to land ({@link isFinalTornWrite}).
  *
  * TWO policies ship from here, and the split is deliberate: the default
  * ({@link isRetriableControlWriteFailure}, {@link CONTROL_WRITE_ATTEMPTS}) sits under every
@@ -63,6 +76,17 @@ export const SCHEMA_INIT_ATTEMPTS = 5;
  * attempts, measured in `control-write-degraded-cohort-member.integration.ts`), which
  * already exceeds this budget when attempt 1 returns — so that case is surfaced immediately
  * and retry adds ZERO latency to the case where it cannot help.
+ *
+ * NOTE: a failed commit attempt now also pays a cancel discharge before its error returns
+ * (optimystic `TransactorSource.transact`'s catch, added by upstream
+ * `1-a-failed-attempt-must-discharge-its-own-pend`) — bounded by six rounds and
+ * `abortOrCancelTimeoutMs`, which every collection this repo opens sets to 5 s
+ * (`../optimystic/packages/quereus-plugin-optimystic/src/optimystic-adapter/collection-factory.ts`).
+ * Two failed attempts whose cancels each run their full budget would consume this whole 10 s
+ * ceiling and cut the three-attempt policy to two. Not observed — every measured round of the
+ * transient-reset case committed on attempt 3 of 3 — so this is a condition to watch, not work
+ * to do: if that case ever starts failing with `failed after 2/3 attempt(s)`, the cancel
+ * discharge is where the time went.
  */
 export const CONTROL_WRITE_RETRY_BUDGET_MS = 10000;
 /**
@@ -110,9 +134,14 @@ const COMMIT_BATCH_TOKEN = '[blocks:';
  * 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. A
- * decisive rejection is a different error entirely (`ValidatorRejectionError`,
- * `Transaction rejected by validators`), which this classifier also never matches.
+ * is raised while collecting PROMISES, before any commit, so re-presenting it is safe.
+ *
+ * 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
+ * composite classifier is not this matcher alone: a rejection raised while promises are still
+ * being collected reaches this repo wrapped in the transactor's `Some peers did not complete:
+ * …[block:…]` aggregate, and {@link isUncommittedTransactorAggregate} matches that wrapper on its
+ * own, whatever the cause inside it says — see the accepted-tradeoff `NOTE:` there.
  */
 const SUPER_MAJORITY_SHORTFALL_UNANSWERED = /Failed to get super-majority: \d+\/\d+ approvals \(needed \d+, 0 rejections\)/;
 /**
@@ -151,6 +180,42 @@ const SUPER_MAJORITY_SHORTFALL_UNANSWERED = /Failed to get super-majority: \d+\/
  * token on the live aggregate; if it reddens there, an upstream reformat is the first thing to
  * check.
  *
+ * 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
+ * one further place — a third formatter, outside the aggregate's three sites — `dischargeCancel`
+ * (`Cancel of action <id> did not discharge <n> block(s): …`), which does not raise the
+ * `Some peers did not complete:` prefix; only the conjunction keeps a cancel fault from
+ * classifying as a retriable get/pend (checked against optimystic `c56c2bd4`, 2026-09-16).
+ *
+ * NOTE: accepted tradeoff — a REJECTION raised while promises are still being collected reaches
+ * this repo wrapped in this same aggregate, and this matcher claims it on the wrapper alone,
+ * whatever the cause inside says. That re-presents such a rejection up to two more times inside
+ * the 10 s budget. Kept deliberately, and re-decided on 2026-09-17 against the current upstream
+ * behaviour rather than inherited:
+ *
+ *  - Contention is no longer a rejection at all. "Another write holds this block right now"
+ *    (`pending conflict`) is now a `held` verdict that counts toward neither approvals nor
+ *    rejections (`validatePendOperations`,
+ *    `../optimystic/packages/db-p2p/src/cluster/cluster-repo.ts`), so the rejection this tradeoff
+ *    was originally written about does not arrive any more. It reaches this funnel as
+ *    `SyncRetryExhaustedError` instead, which {@link reportsPossiblyStoredWrite} declines by type
+ *    — upstream documents resubmitting after it as unsafe (the attempt that spent the budget may
+ *    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
+ *    (`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.
+ *
+ * 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
+ * cheap — or when upstream offers a typed refusal surface to classify on instead of this text
+ * (`../optimystic/tickets/backlog/debt-a-downstream-repo-classifies-retries-by-parsing-our-error-text`).
+ * Contention is no longer the reason to revisit.
+ *
  * An aggregate whose details came out EMPTY (possible when `formatBatchStatuses` has no
  * batches to format) carries neither token, matches nothing here, and is not retried — an
  * unattributable failure is not a proven non-commit.
@@ -177,6 +242,59 @@ export function isUncommittedTransactorAggregate(message) {
 function reportsIndeterminateCommit(messages) {
     return messages.some(message => message.includes(COMMIT_BATCH_TOKEN));
 }
+/**
+ * Does any link of the `cause` chain say some of this write may be stored, or may still be?
+ * Such a failure is never re-presented — a re-run could store the write twice.
+ *
+ * - `SyncRetryExhaustedError` (and its `SyncRevisionStalledError` subclass): upstream documents
+ *   resubmitting as unsafe, because the attempt that spent the budget may have left its log
+ *   entry standing.
+ * - `TornActionError` without `final: true`: the write's log entry is stored and nobody could
+ *   establish that the rest can never land — it may be saved already, or land later.
+ * - `CoordinatorPartialCommitError` / `PartialCommitError`: another collection or tree of the
+ *   same transaction is already durable, and re-running the whole body would apply it twice.
+ *
+ * Every one of these embeds text from elsewhere in its message (a responder's refusal, the
+ * underlying failure), which can carry the pend-phase aggregate's prefix and `[block:` token —
+ * so this veto runs before any text matcher.
+ *
+ * Matched by TYPE: each survives the bridge's and Quereus' rewraps on `cause`. An error built by a
+ * second loaded copy of `@optimystic/db-core` (or of the plugin, for `PartialCommitError`) fails
+ * `instanceof`, and then this veto does not fire — falling back to the text classifiers, which is
+ * how these failures were classified before the veto existed. The asymmetry with
+ * {@link isFinalTornWrite} is deliberate: there, a missed `instanceof` means no retry, which is the
+ * safe side. No text fallback parses `TornActionError`'s closing sentence, since upstream says its
+ * wording is for log lines only.
+ *
+ * NOTE: the plugin is registered through its `/plugin` entry (`control-database.ts`) but
+ * `PartialCommitError` is imported from its root entry; the two are one class only because the
+ * plugin's build emits both entries over one shared chunk. If upstream ever bundles the entries
+ * separately, this `instanceof` stops matching with every spec still green — import the class from
+ * the entry the plugin is registered through.
+ */
+function reportsPossiblyStoredWrite(links) {
+    return links.some(link => link instanceof SyncRetryExhaustedError
+        || (link instanceof TornActionError && link.final !== true)
+        || link instanceof CoordinatorPartialCommitError
+        || link instanceof PartialCommitError);
+}
+/**
+ * A torn write the library marks FINAL: not saved, unable to land, its pending records confirmed
+ * cancelled — so submitting it again stores it once.
+ *
+ * Worth re-presenting, not merely safe to: upstream raises it mostly when a rival holds the
+ * revision this write's log entry claimed, which is contention, and the loop re-runs the write
+ * body's reads, so the next attempt builds on the rival's revision — the same argument that keeps
+ * stale-revision rejections retried (the accepted-tradeoff `NOTE:` on
+ * {@link isUncommittedTransactorAggregate}).
+ *
+ * NOTE: `CoordinatorStaleLossError` (db-core; "nothing durably committed, safe to re-drive") is not
+ * claimed, so it falls to the text matchers; it escapes only after the coordinator's own retry budget
+ * ran out. If control writes are seen abandoned on it, claim it here by type beside this one.
+ */
+function isFinalTornWrite(link) {
+    return link instanceof TornActionError && link.final === true;
+}
 /** The coordinator's shortfall, raised pre-commit, with nobody having voted no. */
 function isUnansweredSuperMajorityShortfall(message) {
     return SUPER_MAJORITY_SHORTFALL_UNANSWERED.test(message);
@@ -193,13 +311,14 @@ function isUnansweredSuperMajorityShortfall(message) {
  * one connection again, which a cold-starting node dialling its bootstrap peers is actively
  * working on.
  *
- * NOTE: matched by TEXT, not by type, and that is forced rather than chosen.
- * `FindCoordinatorError` (`code: 'SELF_COORDINATION_BLOCKED'`) is exported from `@optimystic/db-p2p`
- * and this package depends on it, but the error OBJECT does not survive the trip:
- * `OptimysticVirtualTable.initialize` catches and rethrows as `new Error(message)` with no `cause`
- * (`quereus-plugin-optimystic/src/optimystic-module.ts`), so only the text reaches this repo. Like
- * every matcher here this fails CLOSED — a rewording upstream stops the retry engaging, it never
- * makes it unsafe.
+ * NOTE: matched by TEXT, not by type. `FindCoordinatorError` (`code: 'SELF_COORDINATION_BLOCKED'`)
+ * is exported from `@optimystic/db-p2p`, and when this matcher was written the error OBJECT did not
+ * survive the trip: `OptimysticVirtualTable.initialize` rethrew as `new Error(message)` with no
+ * `cause`. It now rethrows through `rewrapAsQueryError`, which keeps `cause`
+ * (`quereus-plugin-optimystic/src/optimystic-module.ts`); whether every Quereus wrapper above it on
+ * the schema-init path keeps it too has not been checked, and the text still arrives either way.
+ * Like every matcher here this fails CLOSED — a rewording upstream stops the retry engaging, it
+ * never makes it unsafe.
  */
 const SELF_COORDINATION_GRACE_REFUSAL = /Self-coordination blocked: grace-period-not-elapsed\. No coordinator available for key\./;
 /** Self-coordination refused because the node's last connection dropped moments ago. */
@@ -246,16 +365,18 @@ const RETRIABLE_SCHEMA_INIT_MATCHERS = [
  * Did this control write fail because the cluster cohort did not ANSWER — i.e. is
  * re-presenting the SAME signed write a moment later the right response?
  *
- * Classifies by MESSAGE, walking the `cause` chain with the shared {@link chainMessages}
- * (Quereus' own `unwrapError` underneath) —
- * the failure surface is not recognisable by type. The transactor and the coordinator both throw bare `Error`s, and by
- * the time one reaches `ControlDatabase` it is wrapped in a `QuereusError` (the real chain
- * is `QuereusError` → `Error` → `Error`), so the match must work at any depth. Anything
- * that is not an `Error` is never retried.
+ * Classifies the transient cases by MESSAGE, walking the `cause` chain with the shared
+ * {@link chainMessages} (Quereus' own `unwrapError` underneath) — the transactor and the
+ * coordinator both throw bare `Error`s, not recognisable by type. By the time one reaches
+ * `ControlDatabase` it is wrapped in a `QuereusError` (the real chain is `QuereusError` → `Error`
+ * → `Error`), so the match must work at any depth. Anything that is not an `Error` is never
+ * retried.
  *
- * {@link reportsIndeterminateCommit} vetoes the whole chain before any matcher runs, so a
- * failure that reports a commit-phase batch anywhere is never retried on the strength of some
- * other level looking transient.
+ * 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}).
  *
  * 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
@@ -266,7 +387,7 @@ const RETRIABLE_SCHEMA_INIT_MATCHERS = [
  * aggregate from a real stream reset, which the retry there absorbs end to end.
  */
 export function isRetriableControlWriteFailure(error) {
-    return matchesRetriableMessage(error, RETRIABLE_CONTROL_WRITE_MATCHERS);
+    return matchesRetriableFailure(error, RETRIABLE_CONTROL_WRITE_MATCHERS);
 }
 /**
  * {@link isRetriableControlWriteFailure} widened by exactly one class — the self-coordination
@@ -276,22 +397,31 @@ export function isRetriableControlWriteFailure(error) {
  * default classifier untouched.
  */
 export function isRetriableSchemaInitFailure(error) {
-    return matchesRetriableMessage(error, RETRIABLE_SCHEMA_INIT_MATCHERS);
+    return matchesRetriableFailure(error, RETRIABLE_SCHEMA_INIT_MATCHERS);
 }
 /**
- * Shared body of both classifiers: walk the `cause` chain, let
- * {@link reportsIndeterminateCommit} veto it, then ask `matchers`. The veto runs BEFORE any
- * matcher for every policy — a chain reporting a commit-phase batch is never retried, however
- * transient some other level looks.
+ * Shared body of both classifiers: walk the `cause` chain, let {@link reportsPossiblyStoredWrite}
+ * and then {@link reportsIndeterminateCommit} veto it, then claim a final torn write
+ * ({@link isFinalTornWrite}), then ask `matchers`. The vetoes run BEFORE any matcher 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 carried by a partial commit is
+ * still declined because a sibling collection landed.
  */
-function matchesRetriableMessage(error, matchers) {
+function matchesRetriableFailure(error, matchers) {
     if (!(error instanceof Error)) {
         return false;
     }
+    const links = causeChain(error);
+    if (reportsPossiblyStoredWrite(links)) {
+        return false;
+    }
     const messages = chainMessages(error);
     if (reportsIndeterminateCommit(messages)) {
         return false;
     }
+    if (links.some(isFinalTornWrite)) {
+        return true;
+    }
     return messages.some(message => matchers.some(matches => matches(message)));
 }
 /**
@@ -326,6 +456,15 @@ export const SCHEMA_INIT_RETRY_POLICY = {
  * On exhaustion (attempts or budget) the LAST error is rethrown unchanged — never wrapped,
  * so the exact messages downstream code and the degraded-cohort-member scenario assert on
  * survive. A non-retriable failure propagates from the attempt that raised it.
+ *
+ * Either way — declined or exhausted — an `options.onAbandon` observer is notified exactly
+ * once before the rethrow (a `ControlRetryAbandonment`). Only WRITES pass one: an abandoned
+ * read throws to a caller that is awaiting it, so nothing is lost silently there
+ * (`control-read-retry.ts` says so at its own seam), while an abandoned write may have no
+ * caller at all — a background self-record republish is `void`-ed with a `debug` catch, so
+ * its failure reaches nobody unless something is listening here.
+ * `ControlDatabase.setControlWriteAbandonedListener` is the only thing that passes one in
+ * production; `retryControlWrite` itself neither supplies nor requires an observer.
  */
 export function retryControlWrite(attempt, options = {}) {
     return retryControlOperation(attempt, {

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

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

package/dist/enrolled-machine-store-file.d.ts

@@ -0,0 +1,13 @@
+import type { EnrolledMachineStore } from './enrolled-machine-store.js';
+/**
+ * File-backed {@link EnrolledMachineStore}. Open via {@link open}, which loads the
+ * existing file and returns the cross-platform store over it. An absent, corrupt,
+ * wrong-party, junk-valued **or unreadable** file is a cold start (`count()` is
+ * `undefined`, the node declares no repair yardstick and runs at the base control
+ * policy) — `open` never rejects, unlike the sibling stores' file backends. That
+ * divergence and its reasoning live on `enrolled-machine-store.ts`.
+ */
+export declare const FileEnrolledMachineStore: {
+    /** Load (or cold-start) the party's last recorded machine count from a file in `dir`. */
+    open(dir: string, partyId: string): Promise<EnrolledMachineStore>;
+};

package/dist/enrolled-machine-store-file.js

@@ -0,0 +1,41 @@
+/**
+ * Node-only file-backed {@link EnrolledMachineStore}: one JSON file per party under
+ * a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated count of
+ * machines this party had enrolled the last time this node looked.
+ *
+ * Nothing but the file itself lives here: the envelope, the cold-start-on-anything
+ * load policy (deliberately NOT the throw-on-unreadable policy its two sibling
+ * records use — see the `enrolled-machine-store.ts` module comment) and the
+ * serialised writes are cross-platform in `PersistentEnrolledMachineStore`, and the
+ * file is a `FileDurableSlot`. This module exists only so the `node:fs` edge stays
+ * out of the package's cross-platform default entry (`./index.js`) — import it from
+ * the dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileEnrolledMachineStore } from '@serfab/cadre-core/enrolled-machine-store-file';
+ * ```
+ *
+ * A React Native / browser entry graph never resolves this path, so the `node:fs`
+ * edge never reaches a bundler that cannot satisfy it (same isolation pattern as
+ * `bootstrap-peer-store-file.ts` / `trusted-owner-store-file.ts` / `key-store-file.ts`).
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentEnrolledMachineStore } from './enrolled-machine-store.js';
+/** Base name of the store file: `<dir>/enrolled-machines.<encoded partyId>.json`. */
+const SLOT_NAME = 'enrolled-machines';
+/**
+ * File-backed {@link EnrolledMachineStore}. Open via {@link open}, which loads the
+ * existing file and returns the cross-platform store over it. An absent, corrupt,
+ * wrong-party, junk-valued **or unreadable** file is a cold start (`count()` is
+ * `undefined`, the node declares no repair yardstick and runs at the base control
+ * policy) — `open` never rejects, unlike the sibling stores' file backends. That
+ * divergence and its reasoning live on `enrolled-machine-store.ts`.
+ */
+export const FileEnrolledMachineStore = {
+    /** Load (or cold-start) the party's last recorded machine count from a file in `dir`. */
+    async open(dir, partyId) {
+        return PersistentEnrolledMachineStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+    }
+};
+//# sourceMappingURL=enrolled-machine-store-file.js.map

package/dist/enrolled-machine-store-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrolled-machine-store-file.js","sourceRoot":"","sources":["../src/enrolled-machine-store-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAG7E,qFAAqF;AACrF,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACvC,yFAAyF;IACzF,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,OAAe;QACtC,OAAO,8BAA8B,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IACnG,CAAC;CACD,CAAC"}

package/dist/enrolled-machine-store.d.ts

@@ -0,0 +1,81 @@
+import type { DurableSlot } from './node-local-snapshot.js';
+export interface EnrolledMachineStore {
+    /** Party this store is scoped to. */
+    readonly partyId: string;
+    /**
+     * Machines last recorded for this party, or `undefined` when nothing usable was
+     * ever recorded — a brand-new node, or a slot that could not be read. Callers
+     * pass this straight to `controlClusterPolicy`, whose `undefined` branch returns
+     * the frozen base policy unchanged, so "this node does not know" and "this node
+     * has never run" are the same declaration: none.
+     */
+    count(): number | undefined;
+    /**
+     * Record the current count. Reflected by {@link count} SYNCHRONOUSLY; the
+     * returned promise resolves once the persist attempt has settled.
+     *
+     * **Never rejects.** Its sole caller is
+     * `CadreNode.refreshAuthorizedControlPeers`, whose contract is never-rejects and
+     * which leaves the promise un-awaited (`void`) — so a rejection here would
+     * surface as an unhandled rejection in the embedder's process, over a hint that
+     * re-lands on the next refresh anyway. A failed persist is LOGGED, and the
+     * in-memory count stays correct for this session.
+     *
+     * A count that is not a positive integer is a caller bug: it is logged and
+     * IGNORED rather than persisted, so a degenerate value can never reach the slot
+     * and be read back as a declaration nobody chose.
+     */
+    record(count: number): Promise<void>;
+}
+/**
+ * Ephemeral in-memory store — the default when no store is injected via
+ * `CadreNodeConfig.enrolledMachines`. A node using this cold-starts on every
+ * launch: `count()` is `undefined` at `start()`, so its control node declares
+ * nothing and runs at today's behaviour, exactly as before this record existed.
+ */
+export declare class MemoryEnrolledMachineStore implements EnrolledMachineStore {
+    readonly partyId: string;
+    private current;
+    constructor(partyId: string);
+    count(): number | undefined;
+    record(count: number): Promise<void>;
+}
+/**
+ * Durable {@link EnrolledMachineStore} over an app-supplied {@link DurableSlot} —
+ * the cross-platform half of every persistent backend (the Node
+ * `FileEnrolledMachineStore` is this class over a file slot).
+ *
+ * Construct via {@link open}. Load policy is the module comment's: every failure
+ * mode cold-starts, and `open` never rejects.
+ */
+export declare class PersistentEnrolledMachineStore implements EnrolledMachineStore {
+    private readonly slot;
+    readonly partyId: string;
+    /** Serialises persists so the last count recorded is the last one written. */
+    private writeChain;
+    /** Last count accepted, whether or not it has reached the slot yet. */
+    private current;
+    /** Last count believed to BE in the slot; drives the unchanged-write skip. */
+    private persisted;
+    private constructor();
+    /** Load (or cold-start) the party's last recorded machine count from `slot`. */
+    static open(slot: DurableSlot, partyId: string): Promise<PersistentEnrolledMachineStore>;
+    count(): number | undefined;
+    /**
+     * Record the count: visible via {@link count} synchronously, then persisted.
+     *
+     * Writes are SKIPPED when the slot already holds this number, because the sole
+     * caller runs on every committed membership write *and* every timed reconcile
+     * pass — a party whose membership is stable would otherwise rewrite the same
+     * integer forever. The skip is keyed off {@link persisted} rather than
+     * {@link current}, so a write that FAILED is retried by the next refresh instead
+     * of being suppressed as "unchanged".
+     */
+    record(count: number): Promise<void>;
+    /**
+     * Write whatever {@link current} holds when this link of the chain runs — so a
+     * burst of records collapses into one write of the latest value — and never
+     * throw (see {@link EnrolledMachineStore.record}).
+     */
+    private persistCurrent;
+}