@serfab/cadre-core 1.17.0 → 1.19.0

package/src/control-protocol-guard.ts

@@ -135,6 +135,21 @@ export function controlNetworkName(partyId: string): string {
 	return `control-${partyId}`;
 }
 
+/** The control database's two storage protocols, `repo` and `cluster`. */
+function controlDatabaseProtocols(partyId: string): readonly string[] {
+	const prefix = `/optimystic/${controlNetworkName(partyId)}`;
+	return [`${prefix}/repo/1.0.0`, `${prefix}/cluster/1.0.0`];
+}
+
+/**
+ * Whether a peer whose protocol list is `protocols` serves the control database. Optimystic
+ * counts a peer into a control block's cohort by the same test (`servesThisNetwork` in db-p2p's
+ * `libp2p-key-network.ts`), before its membership check.
+ */
+export function servesControlDatabase(partyId: string, protocols: readonly string[]): boolean {
+	return controlDatabaseProtocols(partyId).some((protocol) => protocols.includes(protocol));
+}
+
 /**
  * The class of every protocol a control node serves, by exact protocol id: the single
  * declaration the guard enforces. See the module doc for what each class admits and why each
@@ -152,8 +167,7 @@ export function controlProtocolClasses(partyId: string): ReadonlyMap<string, Con
 		[WAKE_PROTOCOL, 'members'],
 		[STRAND_ADDR_PROTOCOL, 'members'],
 
-		[`${prefix}/repo/1.0.0`, 'members-snapshot'],
-		[`${prefix}/cluster/1.0.0`, 'members-snapshot'],
+		...controlDatabaseProtocols(partyId).map((protocol): [string, ControlProtocolClass] => [protocol, 'members-snapshot']),
 		[`${prefix}/db-p2p/sync/1.0.0`, 'members-snapshot'],
 		[`${prefix}/db-p2p/block-transfer/1.0.0`, 'members-snapshot'],
 		[`${fret}/neighbors`, 'members-snapshot'],

package/src/control-schema-version.ts

@@ -3,40 +3,53 @@
  * store after declaring the control schema and before applying it.
  *
  * `apply schema CadreControl` runs whatever DDL makes the hydrated catalog equal the declared
- * schema. Against a store written by another release that DDL is either refused by the
- * optimystic module part-way through (`alter table … drop constraint`, `add column`,
- * `drop column`), which fails the start with a message naming whichever step came first, or
- * runs and destroys rows (`drop table`). This module decides from the pending DDL and the
- * stored schema version, before any of it runs, and throws one typed error instead.
+ * schema, and that apply is how a store written under an older control schema version is
+ * migrated in place: between consecutive versions the difference is limited to statements the
+ * optimystic module applies to a table's catalog record without rewriting a row, so running the
+ * diff from a store at version K to this build's declaration runs each version's changes from
+ * K+1 up to the build's, in order. This module decides, from the stored version and the pending
+ * DDL and before any of it runs, whether the apply may go ahead, and throws one typed error
+ * naming the reason when it may not.
  *
  * The same change classifier ({@link classifyControlSchemaChange}) is what
  * `control-schema-versions.spec.ts` runs over each pair of consecutive control schema versions,
  * so a schema edit that no store could be migrated across fails when it is made. Where the
  * version lives, when it changes and what a new version may change: docs/architecture.md →
- * "Control schema changes and incompatible stores".
+ * "Control schema versions and migrations".
  *
- * NOTE: the stored tag is the version the store's `OwnerKey` table was CREATED under. The
- * optimystic plugin does not persist `alter table … set tags` (Quereus applies a tag change to
- * its catalog without calling the module, and the plugin follows it in memory only), so the
- * `set tags` an additive upgrade runs raises the version for that process alone. The check stays
- * safe regardless, because it lets through only DDL that adds, so an older build's diff against
- * an upgraded store lists the drop and is refused on that ground. Migrating a store in place
- * (control-store-migrates-on-start) needs the version a store was upgraded to, so it needs that
- * persisted upstream (optimystic-catalog-only-alter-table).
+ * The stored tag is the version of the last start that applied the schema to the store: the
+ * apply's `alter table OwnerKey set tags (…)` persists since Optimystic 1.16.0, so after a
+ * migrating start the store records this build's version. A store additively upgraded by a build
+ * from before that still reads the version it was created under, which is harmless: the diff is
+ * computed from the catalog, not from the number, and the number only has to tell a store that
+ * a newer release migrated from one this build can migrate.
  */
 
 import { Parser, type Database, type SchemaManager, type SqlValue, type TableSchema } from '@quereus/quereus';
 import type { AlterTableStmt, ColumnDef, Statement } from '@quereus/quereus/parser';
-import { CONTROL_SCHEMA_NAME, CONTROL_SCHEMA_VERSION_TAG } from './control-schema.js';
+import { CONTROL_SCHEMA_BASELINE_VERSION, CONTROL_SCHEMA_NAME, CONTROL_SCHEMA_VERSION_TAG } from './control-schema.js';
 import { controlStorageScope } from './storage-scope.js';
 
 /** The control table whose tags carry {@link CONTROL_SCHEMA_VERSION_TAG}. */
 const VERSION_TABLE = 'OwnerKey';
 
-/** A warm control store this build cannot apply its control schema to without destroying data. */
+/**
+ * Why a warm control store is refused, in the order the check decides them:
+ *  - `newer-release`: the store records a version above this build's, so a newer release has
+ *    migrated it (this machine before a downgrade, or another machine sharing its catalog
+ *    lineage); this machine is the one to update.
+ *  - `before-migrations`: the store records a version below {@link CONTROL_SCHEMA_BASELINE_VERSION}
+ *    (written by 1.16.0 or earlier); it cannot be migrated and must be recreated.
+ *  - `not-migratable`: a pending statement would rewrite or discard rows. Reachable only from a
+ *    development or hand-made store, since the edit-time check refuses such a version.
+ */
+export type ControlStoreIncompatibility = 'newer-release' | 'before-migrations' | 'not-migratable';
+
+/** A warm control store this build cannot apply its control schema to. */
 export class ControlStoreIncompatibleError extends Error {
+	readonly reason: ControlStoreIncompatibility;
 	readonly partyId: string;
-	/** The version the store records: the one it was created under; 0 = before versions were recorded. */
+	/** The version the store records: the one its last migrating start declared; 0 = before versions were recorded. */
 	readonly storeVersion: number;
 	/** The version this build declares. */
 	readonly buildVersion: number;
@@ -45,16 +58,17 @@ export class ControlStoreIncompatibleError extends Error {
 	/** `controlStorageScope(partyId)`: the storage the embedder deletes to recreate (docs/architecture.md). */
 	readonly storageScope: string;
 
-	constructor(partyId: string, storeVersion: number, buildVersion: number, pendingDdl: readonly string[]) {
+	constructor(
+		reason: ControlStoreIncompatibility,
+		partyId: string,
+		storeVersion: number,
+		buildVersion: number,
+		pendingDdl: readonly string[]
+	) {
 		const storageScope = controlStorageScope(partyId);
-		super(
-			`The control store for party ${JSON.stringify(partyId)} ${provenance(storeVersion, buildVersion)} ` +
-			`(it records control schema version ${storeVersion}; this build declares ${buildVersion}), and this build ` +
-			'cannot apply its control schema to it without losing data. Run a release whose control schema ' +
-			`matches the store, or recreate the control store (storage scope ${storageScope}) as ` +
-			'docs/architecture.md describes.'
-		);
+		super(refusalMessage(reason, partyId, storeVersion, buildVersion, storageScope));
 		this.name = 'ControlStoreIncompatibleError';
+		this.reason = reason;
 		this.partyId = partyId;
 		this.storeVersion = storeVersion;
 		this.buildVersion = buildVersion;
@@ -64,33 +78,55 @@ export class ControlStoreIncompatibleError extends Error {
 }
 
 /**
- * Which release created the store, relative to this build, for the error message. Created, not
- * last written: the stored version does not move on an additive upgrade (module NOTE).
+ * The message for each {@link ControlStoreIncompatibility}. Only the two recreate cases advise
+ * recreating: a store a newer release migrated holds rows written since, and recreating it
+ * would throw them away.
  */
-function provenance(storeVersion: number, buildVersion: number): string {
-	if (storeVersion > buildVersion) {
-		return 'was created by a newer release';
+function refusalMessage(
+	reason: ControlStoreIncompatibility,
+	partyId: string,
+	storeVersion: number,
+	buildVersion: number,
+	storageScope: string
+): string {
+	const store = `The control store for party ${JSON.stringify(partyId)}`;
+	const versions = `it records control schema version ${storeVersion}; this build declares ${buildVersion}`;
+	const recreate = 'Run a release whose control schema matches the store, or recreate the control store ' +
+		`(storage scope ${storageScope}) as docs/architecture.md describes.`;
+	switch (reason) {
+		case 'newer-release':
+			return `${store} was migrated by a newer release (${versions}). Update this app or node to that ` +
+				'release or a later one; the store and its rows are intact.';
+		case 'before-migrations':
+			return `${store} was written before control schema migrations (${versions}; migrations start at ` +
+				`version ${CONTROL_SCHEMA_BASELINE_VERSION}, and docs/architecture.md says why earlier stores are not ` +
+				`migrated), so this build cannot upgrade it in place. ${recreate}`;
+		case 'not-migratable':
+			return `${store} cannot be migrated to this build's control schema (${versions}): applying it would ` +
+				`rewrite or discard stored rows. ${recreate}`;
 	}
-	return storeVersion < buildVersion
-		? 'was created by an older release'
-		: 'was created under the same control schema version';
 }
 
 /**
- * Throw {@link ControlStoreIncompatibleError} when applying the declared control schema to the
- * hydrated store would destroy data; return having run nothing otherwise. Needs
- * `declare schema CadreControl` to have run, and runs only `diff schema`, which executes no DDL.
+ * Throw {@link ControlStoreIncompatibleError} when the declared control schema must not be applied
+ * to the hydrated store; return having run nothing otherwise, and the apply then migrates the
+ * store. Needs `declare schema CadreControl` to have run, and runs only `diff schema`, which
+ * executes no DDL.
  *
  * A cold store (the hydrated catalog lists no control table) passes without a diff: the apply
- * creates everything. A warm store is refused when either
- *  - any pending statement is not `additive` ({@link classifyControlSchemaChange}): every other
- *    change to an existing control table is refused by the optimystic module or discards rows; or
- *  - its version is above the build's: a newer release created it, so even a diff that only adds
- *    (the newer release no longer declares something this build does) would put back what that
- *    release removed, and the newer release would then refuse its own store.
+ * creates everything. A warm store is refused for the first of these that holds
+ * ({@link ControlStoreIncompatibility}):
+ *  - its version is above the build's: even a diff that only adds (the newer release no longer
+ *    declares something this build does) would put back what that release removed, and the newer
+ *    release would then refuse its own store;
+ *  - its version is below the baseline, whatever the diff: a store written by 1.16.0 or earlier,
+ *    which the baseline paragraph of docs/architecture.md explains cannot be migrated;
+ *  - any pending statement is `unmigratable` ({@link classifyControlSchemaChange}).
  *
- * So a store from an older release still warm-starts when the only change since is a new table
- * or index.
+ * Every `additive` and `catalog-only` change passes, so a store from an older migratable
+ * release warm-starts and the apply brings it to this build's version. A store that is both
+ * older than the baseline and not migratable reports `before-migrations`, whose message gives the
+ * recreate advice and points at the explanation.
  */
 export async function refuseIncompatibleControlStore(db: Database, partyId: string): Promise<void> {
 	if (!isWarmControlStore(db)) {
@@ -99,11 +135,25 @@ export async function refuseIncompatibleControlStore(db: Database, partyId: stri
 	const storeVersion = schemaVersionOf(db.schemaManager.getTable(CONTROL_SCHEMA_NAME, VERSION_TABLE)?.tags);
 	const buildVersion = declaredSchemaVersion(db);
 	const pending = await pendingControlSchemaChanges(db);
-	// `catalog-only` changes stay refused until the optimystic module applies them
-	// (optimystic-catalog-only-alter-table); control-store-migrates-on-start widens this then.
-	if (storeVersion > buildVersion || pending.some((change) => change.kind !== 'additive')) {
-		throw new ControlStoreIncompatibleError(partyId, storeVersion, buildVersion, pending.map((change) => change.ddl));
+	const reason = incompatibilityOf(storeVersion, buildVersion, pending);
+	if (reason !== undefined) {
+		throw new ControlStoreIncompatibleError(reason, partyId, storeVersion, buildVersion, pending.map((change) => change.ddl));
+	}
+}
+
+/** The first {@link ControlStoreIncompatibility} that holds for a warm store, or undefined when the apply may migrate it. */
+function incompatibilityOf(
+	storeVersion: number,
+	buildVersion: number,
+	pending: readonly PendingControlSchemaChange[]
+): ControlStoreIncompatibility | undefined {
+	if (storeVersion > buildVersion) {
+		return 'newer-release';
+	}
+	if (storeVersion < CONTROL_SCHEMA_BASELINE_VERSION) {
+		return 'before-migrations';
 	}
+	return pending.some((change) => change.kind === 'unmigratable') ? 'not-migratable' : undefined;
 }
 
 /** Whether the hydrated catalog lists at least one control table, i.e. the store was written before. */
@@ -139,11 +189,11 @@ function schemaVersionOf(tags: Readonly<Record<string, SqlValue>> | undefined):
 
 /**
  * How applying one `diff schema` statement to a warm store treats its rows, from most to least
- * migratable (docs/architecture.md → "Control schema changes and incompatible stores"):
+ * migratable (docs/architecture.md → "Control schema versions and migrations"):
  *  - `additive`: a new table, a new index, or a table tag change, which the optimystic module
- *    applies today without touching a row;
+ *    applies without touching a row;
  *  - `catalog-only`: a change the optimystic module applies to the table's catalog record without
- *    rewriting a row, once optimystic-catalog-only-alter-table ships;
+ *    rewriting a row (since Optimystic 1.16.0);
  *  - `unmigratable`: everything else, which rewrites or discards rows.
  */
 export type ControlSchemaChangeKind = 'additive' | 'catalog-only' | 'unmigratable';

package/src/control-schema.ts

@@ -3,20 +3,20 @@ import { Parser } from '@quereus/quereus';
 /**
  * The version of the declared control schema, carried in the schema text as the
  * {@link CONTROL_SCHEMA_VERSION_TAG} tag on the `OwnerKey` table. A warm start compares
- * it with the version the store records before applying anything
- * (`control-schema-version.ts`, which also says why that is the version the store was
- * created under).
+ * it with the version the store records before applying anything, and the apply then
+ * migrates the store to this version and records it (`control-schema-version.ts`).
  *
  * When it changes, what a new version may change, and the fixture each version keeps:
- * docs/architecture.md → "Control schema changes and incompatible stores", enforced by
+ * docs/architecture.md → "Control schema versions and migrations", enforced by
  * `control-schema-versions.spec.ts`.
  */
 export const CONTROL_SCHEMA_VERSION = 3;
 
 /**
  * The first control schema version whose fixture is kept, and the oldest a store can be
- * migrated from. Stores that record no version (written by 1.16.0 and earlier) are not
- * migrated; docs/architecture.md says why.
+ * migrated from. A store that records a version below it (written by 1.16.0 and earlier,
+ * which recorded none) is refused with reason `before-migrations`; docs/architecture.md
+ * says why it is not migrated.
  */
 export const CONTROL_SCHEMA_BASELINE_VERSION = 3;
 
@@ -667,7 +667,7 @@ declare schema CadreControl {
     ) with context (Now datetime, ValidationKey text null, ValidationSignature text null);
 
     -- Serves the per-token reads (the cap count above; cadre-core's countFormationUsage,
-    -- isTokenUsed and hasOutstandingFormationInvite) on an append-only table. Its cross-machine
+    -- readToken and hasOutstandingFormationInvite) on an append-only table. Its cross-machine
     -- convergence is guarded by the integration scenario strand-formation-concurrent-redemption.
     index FormationUsageByToken on FormationUsage (Token);
 
@@ -903,16 +903,15 @@ declare schema CadreControl {
 
     -- Append-only retirement record for the stamps of removed rows of every guarded table, with
     -- the removed row's key. Every append is owner-signed, so the growth surface is the owner
-    -- keys. One singleton marker row, ('Revocation', 'ledger', 'opened'), retires nothing: an
-    -- owner's connected reconcile pass files it (ControlDatabase.openRevocationLedger) so this
-    -- table is never a never-written block, which the storage layer would consult the cohort
-    -- for on every guarded insert and membership lookup. Readers filter on their own guarded
+    -- keys. A party founded before genesis created every control collection may hold one marker
+    -- row, ('Revocation', 'ledger', 'opened'), which retires nothing: an owner filed it so this
+    -- table had a collection. Nothing files it now. Readers filter on their own guarded
     -- TableName, and queryRevocations skips it. A 'CadreInvite' or 'OwnerGrant' row withdraws
     -- an invitation or a grant whose row stays (the table comments).
     table Revocation (
         TableName text,             -- 'OwnerKey' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'JoinedStrand' |
                                     -- 'JoinRequest' | 'CadrePeer' | 'DeviceToken' | 'CadreInvite' | 'OwnerGrant', or
-                                    -- 'Revocation' for the marker
+                                    -- 'Revocation' for an older party's marker
         RowKey text,                -- primary key of the removed row
         StampId text,               -- the retired stamp
         ReissuedAt integer default 0,   -- bumped by an owner-signed re-issue so a tombstone committed while the
@@ -942,7 +941,9 @@ declare schema CadreControl {
         -- never existed is harmless: stamps carry 128 random bits (generateStampId). For
         -- 'CadreInvite' and 'OwnerGrant' there is no row-gone test: a tombstone there is a
         -- withdrawal, and the row stays (the table comments). The last branch admits the marker
-        -- row and nothing else under 'Revocation'.
+        -- row an older party may hold, and nothing else under 'Revocation'; nothing files it now.
+        -- NOTE: drop this branch, REVOCATION_LEDGER_MARKER and the readers' skip together with the
+        -- next CONTROL_SCHEMA_VERSION change that already needs a migration.
         constraint RowIsGone check on insert (
             (new.TableName = 'OwnerKey' and not exists (select 1 from OwnerKey K where K.StampId = new.StampId))
                 or (new.TableName = 'CadrePeer' and not exists (select 1 from CadrePeer P where P.StampId = new.StampId))
@@ -961,9 +962,8 @@ declare schema CadreControl {
         -- writer could evict a peer party-wide and block its re-admission. RowKey is not checked
         -- against the retired row here (that would reject a tombstone re-issued later, or filed on
         -- a node that never held the row); each guarded table's RevocationRecorded binds it
-        -- instead. Reads live OwnerKey like the sibling tables. The marker is signed under this
-        -- rule too, over ('Revocation', 'ledger', 'opened'). The stored signer pair must be the
-        -- pair verified here.
+        -- instead. Reads live OwnerKey like the sibling tables. An older party's marker was signed
+        -- under this rule too. The stored signer pair must be the pair verified here.
         constraint Authorized check on insert (
             exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = A.StampId) and verify(digest('CadreControl.Revocation', 'remove', party_id(), new.TableName, new.RowKey, new.StampId), context.Signature, A.Key, 'ed25519'))
                 and coalesce(new.SignerKey, '') = context.OwnerKey

package/src/control-write-retry.ts

@@ -1,5 +1,5 @@
 import { CoordinatorPartialCommitError, SyncRetryExhaustedError, TornActionError } from '@optimystic/db-core';
-import { PartialCommitError } from '@optimystic/quereus-plugin-optimystic';
+import { ConcurrentModificationError, PartialCommitError } from '@optimystic/quereus-plugin-optimystic';
 import { causeChain, chainMessages, retryControlOperation } from './control-retry.js';
 import type { ControlRetryOptions } from './control-retry.js';
 
@@ -32,12 +32,13 @@ import type { ControlRetryOptions } from './control-retry.js';
  * 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
+ * THREE policies ship from here, and the split is deliberate: the default
  * ({@link isRetriableControlWriteFailure}, {@link CONTROL_WRITE_ATTEMPTS}) sits under every
- * control write, and {@link SCHEMA_INIT_RETRY_POLICY} is opted into by
- * `ControlDatabase.applyControlSchema` alone. The widened one absorbs one extra failure class whose
- * re-run safety holds for schema DDL and NOT for writes in general; anything added to the default
- * list must be safe for all ~19 callers.
+ * control write; {@link SCHEMA_INIT_RETRY_POLICY} is opted into by
+ * `ControlDatabase.applyControlSchema` alone; {@link LOST_UPDATE_RETRY_POLICY} is opted into by
+ * the `CadrePeer` writers whose bodies re-read the row and decide again. Each widened one absorbs
+ * one extra failure class whose re-run safety holds for its opted-in bodies and NOT for writes in
+ * general; anything added to the default list must be safe for all ~19 callers.
  *
  * Lives outside `control-database.ts` so a spec can drive the classifier against real engine
  * errors without importing the whole database class. The loop itself lives in
@@ -343,6 +344,34 @@ function isUnansweredSuperMajorityShortfall(message: string): boolean {
 	return SUPER_MAJORITY_SHORTFALL_UNANSWERED.test(message);
 }
 
+/**
+ * A LOST UPDATE: the optimystic bridge refusing a commit because another writer changed or
+ * removed a row this statement read (`TransactionBridge.mapCommitRefusal` over a
+ * `TreeEntryChangedError`, `quereus-plugin-optimystic/src/optimystic-adapter/txn-bridge.ts`).
+ * Claimed by TYPE for {@link LOST_UPDATE_RETRY_POLICY} only.
+ *
+ * Why it is a proven non-commit: the refusal is raised inside the action's atomic handler, so
+ * none of that action's entries land. A refusal after a sibling tree or collection of the same
+ * transaction already synced is not delivered bare — the per-tree sweep wraps it in
+ * `PartialCommitError`, the coordinator path in `CoordinatorPartialCommitError` — and
+ * {@link reportsPossiblyStoredWrite} vetoes both by type before this predicate runs. A bare chain
+ * carrying this class therefore means nothing of the write is durable.
+ *
+ * Why it is not in the default list: the rejection is of the write's READ SET, not of its
+ * signature, so re-presenting the same statement is only right when the body re-reads the row and
+ * decides again over what it finds. That is a property of each opted-in body (see the policy's
+ * `NOTE:`), not of control writes in general.
+ *
+ * Not matched by text: `ConcurrentModificationError` is exported from both the plugin's root and
+ * `/plugin` entries over one shared chunk, as `PartialCommitError` is, so the one `instanceof`
+ * covers both (the `NOTE:` on {@link reportsPossiblyStoredWrite} applies to it too). A second
+ * loaded copy of the plugin would fail the `instanceof` and the lost update would then simply not
+ * be retried — the safe side.
+ */
+function isLostUpdate(link: Error): boolean {
+	return link instanceof ConcurrentModificationError;
+}
+
 /**
  * Optimystic refusing to let a node elect ITSELF coordinator because its last connection dropped
  * less than the guard's grace period ago (`Libp2pKeyPeerNetwork.shouldAllowSelfCoordination` →
@@ -411,9 +440,9 @@ const RETRIABLE_CONTROL_WRITE_MATCHERS: readonly ((message: string) => boolean)[
  * 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 reaches a `CadreControl` apply: a cold store's diff is all creates, and
- * `refuseIncompatibleControlStore` in `control-schema-version.ts` refuses a warm store whose diff
- * holds anything but creates and tag changes before the apply runs) poisoned the journal before it
+ * of which only dropping a column reaches a `CadreControl` apply, as the catalog-only migration
+ * step `refuseIncompatibleControlStore` in `control-schema-version.ts` lets through; it discards
+ * nothing there, since rows keep the field) 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},
@@ -469,16 +498,30 @@ export function isRetriableSchemaInitFailure(error: unknown): boolean {
 }
 
 /**
- * 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.
+ * {@link isRetriableControlWriteFailure} widened by exactly one class — a lost update
+ * ({@link isLostUpdate}), claimed by type — for the `CadrePeer` writers that re-read the row inside
+ * their locked body. Opt-in per call site, via {@link LOST_UPDATE_RETRY_POLICY}; both vetoes still
+ * run first, so a lost update carried inside a partial commit, a spent sync budget or a non-final
+ * torn write stays declined.
+ */
+export function isRetriableLostUpdateFailure(error: unknown): boolean {
+	return matchesRetriableFailure(error, RETRIABLE_CONTROL_WRITE_MATCHERS, isLostUpdate);
+}
+
+/**
+ * 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.
  */
 function matchesRetriableFailure(
 	error: unknown,
-	matchers: readonly ((message: string) => boolean)[]
+	matchers: readonly ((message: string) => boolean)[],
+	claimsLink?: (link: Error) => boolean
 ): boolean {
 	if (!(error instanceof Error)) {
 		return false;
@@ -491,7 +534,7 @@ function matchesRetriableFailure(
 	if (reportsIndeterminateCommit(messages)) {
 		return false;
 	}
-	if (links.some(isFinalTornWrite)) {
+	if (links.some(link => isFinalTornWrite(link) || claimsLink?.(link) === true)) {
 		return true;
 	}
 	return messages.some(message => matchers.some(matches => matches(message)));
@@ -510,7 +553,7 @@ function matchesRetriableFailure(
 export type ControlWriteRetryOptions = ControlRetryOptions;
 
 /**
- * The one non-default retry policy: `ControlDatabase.applyControlSchema`'s distributed DDL, which
+ * The schema-init policy: `ControlDatabase.applyControlSchema`'s distributed DDL, which
  * additionally absorbs optimystic's self-coordination grace refusal and gets more attempts over a
  * longer backoff to do it (see {@link SCHEMA_INIT_ATTEMPTS} and
  * {@link SCHEMA_INIT_RETRY_DELAYS_MS}). Still bounded by the shared
@@ -521,7 +564,8 @@ export type ControlWriteRetryOptions = ControlRetryOptions;
  * and verified against the pre-apply catalog (full argument at the `applyControlSchema` 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.
+ * than widening it by default. {@link LOST_UPDATE_RETRY_POLICY} is a separate policy for a
+ * separate class, not a second consumer of this one.
  */
 export const SCHEMA_INIT_RETRY_POLICY: Readonly<ControlWriteRetryOptions> = {
 	attempts: SCHEMA_INIT_ATTEMPTS,
@@ -529,6 +573,34 @@ export const SCHEMA_INIT_RETRY_POLICY: Readonly<ControlWriteRetryOptions> = {
 	isRetriable: isRetriableSchemaInitFailure,
 };
 
+/**
+ * The lost-update policy: the default classifier plus a lost update claimed by type
+ * ({@link isRetriableLostUpdateFailure}), over the default attempts, backoff and budget. A re-run
+ * here is a RE-DECISION, not a re-presentation: the body reads the row again under the lock and
+ * signs over what it finds, so the write that lost to a rival is replaced by one made over the
+ * rival's result. The budget bounds it as it bounds every write — a losing attempt whose read
+ * phase waited out one per-peer read deadline (~7.5 s measured in the degraded-cohort scenario's
+ * trio boot) gets exactly one retry, which is the ceiling to expect; one that waited out two
+ * (14.7 s, measured once in 18 of that scenario's boots, on the member that cannot reach one
+ * sibling) gets none and is abandoned on the budget, and the lost publish is then the reconcile
+ * pass's or the heartbeat's to redo, as every abandoned self-publish is.
+ *
+ * NOTE: the re-run safety this policy assumes is each opted-in body's, not a general property. A
+ * body may opt in only when its read of the row, its decision and its signature ALL run inside
+ * the locked body, so that the re-run presents a write made over the row as it now stands rather
+ * than the first attempt's signed record (which the rival may have stamped past, or which may
+ * overwrite what the rival wrote). Three `CadrePeer` writers opt in, through
+ * `ControlDatabase.mutateCadrePeer`'s policy parameter or `lockedWithRetry` directly:
+ * `updateSelfPeerRecord` (re-reads and re-signs the node's own record), `reauthorizeCadrePeer`
+ * (re-reads the stamp and decides again whether the row is still the owner's to re-touch) and
+ * the two removals `deleteCadrePeer` / `removeMachine` (stamp read and signature already inside
+ * the body, and a self-publish never changes the stamp the `'remove'` digest binds). A new opt-in
+ * must re-derive that argument for its own body first.
+ */
+export const LOST_UPDATE_RETRY_POLICY: Readonly<ControlWriteRetryOptions> = {
+	isRetriable: isRetriableLostUpdateFailure,
+};
+
 /**
  * Run `attempt` up to {@link CONTROL_WRITE_ATTEMPTS} times (or `options.attempts`), retrying only
  * failures the policy's classifier — {@link isRetriableControlWriteFailure} by default —