@optimystic/db-p2p 0.24.2 → 0.25.0

package/src/repo/coordinator-repo.ts

@@ -1,5 +1,5 @@
-import type { PendRequest, ActionBlocks, IRepo, MessageOptions, CommitResult, GetBlockResults, PendResult, StaleFailure, BlockGets, CommitRequest, RepoMessage, IKeyNetwork, ICluster, ClusterConsensusConfig, BlockId, ActionRev, ActionContext, ClusterRecord, BlockUnavailableReason } from "@optimystic/db-core";
-import { LruMap, blockIdsForTransforms, highestStaleAt, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
+import type { PendRequest, ActionBlocks, IRepo, MessageOptions, CommitResult, GetBlockResults, PendResult, StaleFailure, BlockGets, CommitRequest, RepoMessage, IKeyNetwork, ICluster, ClusterConsensusConfig, BlockId, ActionId, ActionRev, ActionContext, ClusterRecord, BlockUnavailableReason, ActionPending } from "@optimystic/db-core";
+import { LruMap, blockIdsForTransforms, highestStaleAt, isConflictFailure, isOwnRevision, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
 import { ClusterCoordinator, ConflictRaceLostError, ValidatorRejectionError } from "./cluster-coordinator.js";
 import type { PeerId } from "@libp2p/interface";
 import { peerIdFromString } from "@libp2p/peer-id";
@@ -8,11 +8,13 @@ import { createLogger } from '../logger.js';
 import type { IPeerReputation } from "../reputation/types.js";
 import { PenaltyReason } from "../reputation/types.js";
 import type { ITransactionStateStore } from "../cluster/i-transaction-state-store.js";
-import { quorumSize, corroboratorCapacity, selectQuorumRev, type RevClaim, type QuorumRev } from "../cluster/quorum-restore.js";
+import { quorumSize, corroboratorCapacity, selectQuorumRev, certifiedEquivocation, CORROBORATION_FLOOR, type RevClaim, type QuorumRev } from "../cluster/quorum-restore.js";
+import { certifyClaim, isAttributableProofFailure, proofThresholds, type ProofAnchoring } from "../cluster/certified-claims.js";
 import { DEFAULT_CLUSTER_SIZE } from "../cluster/cluster-policy.js";
 import { RECONCILE_TIMEOUT_MS } from "../cluster/reconcile-block.js";
-import { isMissingBaseRevisionFailure, MISSING_BASE_REVISION_REASON } from "../storage/storage-repo.js";
+import { isMissingBaseRevisionFailure, MISSING_BASE_REVISION_REASON, type IRevisionActionReader } from "../storage/storage-repo.js";
 import type { ReconcileBlockCallback } from "../cluster/cluster-repo.js";
+import type { CertifiedActionRev } from "../storage/block-archive.js";
 
 /**
  * Acquire a block's content for a cohort-corroborated revision, from the cohort, and persist it.
@@ -58,8 +60,13 @@ function withDeadline<T>(promise: Promise<T>, ms: number, label: string): Promis
 interface ClusterLatestQuery {
 	/** Highest `(rev, actionId)` corroborated by peers other than this node, if any. */
 	corroborated?: ActionRev;
-	/** This node's own latest for the block, as answered by the callback's self short-circuit. */
-	local?: ActionRev;
+	/**
+	 * This node's own latest for the block, as answered by the callback's self short-circuit.
+	 * Typed as a {@link CertifiedActionRev} because that short-circuit reads the local proof too —
+	 * of no use to this node (it trusts its own storage), but the type stays honest about what the
+	 * value carries rather than silently erasing it.
+	 */
+	local?: CertifiedActionRev;
 	/**
 	 * Cohort peers (self excluded) that never answered the consult — the callback rejected
 	 * (dial failure, protocol error) or blew the per-peer deadline. Silence, not evidence:
@@ -89,6 +96,96 @@ interface ClusterLatestQuery {
 	answered: number;
 }
 
+/**
+ * What earlier repair passes left unresolved for one block. Two independent facts share one entry
+ * — and one map — on purpose: both are "what the last repair pass could not finish", both are
+ * cleared by the same event (the block converging), and `CoordinatorRepo` already keeps more
+ * per-block maps than anyone can hold in their head (backlog
+ * `debt-freshness-state-scattered-across-coordinator-repo`).
+ *
+ * An entry exists exactly while at least one of the two is set; both clear together in
+ * {@link CoordinatorRepo.flagUnconfirmedCurrency} once this node reaches the claimed revision.
+ */
+interface AheadClaimState {
+	/**
+	 * The cohort-claimed revision the last freshness consult could not settle — the doubt
+	 * {@link CoordinatorRepo.flagUnconfirmedCurrency} stamps onto reads served below it. Absent once a
+	 * consult finds nothing ahead of what this node holds.
+	 */
+	rev?: number;
+	/**
+	 * Which `cluster-fetch:repair-deadlock` reasons have already been said for this block (see
+	 * {@link CoordinatorRepo.reportRepairDeadlock}). Neither reason is about any one revision — one is
+	 * about the cohort's size, the other about how many of its peers hold the block — so both survive
+	 * {@link CoordinatorRepo.recordAheadClaim} clearing `rev`: without that, a block whose cohort
+	 * claims nothing *ahead* of the reader would re-announce the same permanent condition on every
+	 * single pass, the noise this line exists to replace.
+	 *
+	 * Tracked per REASON rather than as one flag: the two diagnose different faults and send the
+	 * operator to different places, so an episode that starts as `cohort-too-small` and becomes
+	 * `sole-holder` (the operator added machines, which is what that reason told them to do) has to be
+	 * able to say the second thing. Bounded at two entries by the reason union itself.
+	 */
+	deadlocksReported?: readonly DeadlockReason[];
+}
+
+/**
+ * Why a corroboration decline is provably permanent — see {@link CoordinatorRepo.reportRepairDeadlock}
+ * for what makes each provable and which remedy each sends the operator to.
+ */
+type DeadlockReason = 'cohort-too-small' | 'sole-holder';
+
+/** The `cohort-too-small` wording: the cohort cannot field the quorum however healthy its peers are. */
+function cohortTooSmallMessage(
+	cohortPeers: number,
+	claimants: number,
+	requiredEvenIfAllAnswered: number,
+	repairCorroborationClusterSize: number
+): string {
+	return `Block repair cannot converge for this block and the condition is PERMANENT, not transient: ` +
+		`this node's cohort has ${cohortPeers} peer(s) besides itself, all of them answered ` +
+		`(${claimants} hold the block), but accepting a revision would need ${requiredEvenIfAllAnswered} ` +
+		`agreeing peers even if every one of those ${cohortPeers} answered and agreed. No later pass can reach ` +
+		`that, however healthy every peer is, so this node's copy of the block stays as it is. Repair needs ` +
+		`${CORROBORATION_FLOOR} cohort peers BESIDES the reader to answer and agree, relaxed to 1 only for a ` +
+		`cohort that DECLARES it is smaller; repairCorroborationClusterSize currently resolves to ` +
+		`${repairCorroborationClusterSize}. Two things produce this, and this node cannot tell them ` +
+		`apart: (1) the deployment really does run this few machines — set clusterPolicy.assumedClusterSize ` +
+		`to the number you actually run (it does not lower clusterSize / the replication factor), or set an ` +
+		`honest clusterSize, and run at least ${CORROBORATION_FLOOR + 2} machines for any tolerance of one ` +
+		`unreachable peer; or (2) this node's view of the cohort has shrunk below the real deployment — a ` +
+		`partition or a routing problem, which configuration will not fix. Check the peer count above ` +
+		`against the machines you run before changing anything.`;
+}
+
+/**
+ * The `sole-holder` wording: the cohort is big enough, but only one of its peers holds the block.
+ *
+ * Every claim here is scoped to THIS NODE'S COHORT PEERS, which is the whole of what the pass
+ * observed. It deliberately does not say "only one machine in the deployment holds this block": this
+ * node's own copy is excluded from the claim set (it cannot corroborate the revision it is trying to
+ * repair), so a reader that holds the block itself would make that reading false — and a scary
+ * all-caps line an operator can disprove by looking at their own disks is worth less than no line.
+ * For the same reason the remedy is "another COHORT PEER holding it" rather than "a second copy":
+ * with the reader holding one, a second copy already exists and is still not enough.
+ */
+function soleHolderMessage(cohortPeers: number): string {
+	return `Block repair cannot converge for this block and the condition is PERMANENT, not transient: ` +
+		`ONLY ONE COHORT PEER HOLDS THIS BLOCK. Of this node's ${cohortPeers} cohort peers, 1 reports holding ` +
+		`it and the other ${cohortPeers - 1} answered that they hold NOTHING — an answer, not silence, so this ` +
+		`is the whole picture and not a slow pass. Repair adopts a revision only when ${CORROBORATION_FLOOR} ` +
+		`peers BESIDES this node agree on it, and a lone holder cannot second itself, so every later pass ` +
+		`declines identically. This node's own copy, if it has one, is the copy being repaired and does not ` +
+		`count toward that number. MORE MACHINES DO NOT FIX THIS, and neither does any cluster-size setting — ` +
+		`what is missing is ANOTHER COHORT PEER HOLDING THE BLOCK. The usual cause is data written while the ` +
+		`deployment (or this block's cohort) was smaller: a block that had one holder then still has one holder ` +
+		`now, because the two paths that would replicate it — read-repair and reconcile — both decline on this ` +
+		`same rule. Committing any new revision of the block writes it to the current cohort and clears this. ` +
+		`(A lone holder whose answer carries a valid cohort commit proof for its revision IS adopted without a ` +
+		`second voter — reaching this message means the one holder attached no such proof, or one that did not ` +
+		`verify.)`;
+}
+
 /**
  * What one repair pass established about a block that is still MISSING locally after it.
  * Ordered by how firmly the block is ruled out; `get` consults it only on the missing path.
@@ -116,11 +213,23 @@ type AbsenceVerdict =
  */
 interface LocalClusterWithExecutionTracking extends ICluster {
 	wasTransactionExecuted?(messageHash: string): boolean;
+	/** Local storage's verdict for a pend applied during consensus; see ClusterMember.getExecutedPendResult. */
+	getExecutedPendResult?(messageHash: string): PendResult | undefined;
+	/** Local storage's verdict for a commit applied during consensus; see ClusterMember.getExecutedCommitResult. */
+	getExecutedCommitResult?(messageHash: string): CommitResult | undefined;
 }
 
+/**
+ * A cohort peer's answer to the latest-revision consult. Defined with the archive shape it is
+ * projected from (`storage/block-archive.ts`) and re-exported here so it reads next to the callback
+ * that returns it; see {@link CertifiedActionRev} there for what the optional proof does and does
+ * not mean.
+ */
+export type { CertifiedActionRev } from "../storage/block-archive.js";
+
 /**
  * Callback to query a cluster peer for their latest revision of a block. Three-way contract:
- *  - resolves an `ActionRev` — the peer answered and holds the block at that revision;
+ *  - resolves a `CertifiedActionRev` — the peer answered and holds the block at that revision;
  *  - resolves `undefined` — the peer answered and holds NOTHING (an absent claim);
  *  - REJECTS — the peer could not be asked at all (dial failure, protocol error).
  *
@@ -132,7 +241,7 @@ interface LocalClusterWithExecutionTracking extends ICluster {
  * harness's `silentPeers` failure knob). Slowness needs no handling here — the caller deadlines
  * each query and treats expiry as silence.
  */
-export type ClusterLatestCallback = (peerId: PeerId, blockId: BlockId, context?: ActionContext) => Promise<ActionRev | undefined>;
+export type ClusterLatestCallback = (peerId: PeerId, blockId: BlockId, context?: ActionContext) => Promise<CertifiedActionRev | undefined>;
 
 interface CoordinatorRepoComponents {
 	storageRepo: IRepo;
@@ -150,6 +259,14 @@ interface CoordinatorRepoComponents {
 	 * holds the corroborated action as a promotable pending. See {@link AcquireBlockCallback}.
 	 */
 	acquireBlockFromCohort?: AcquireBlockCallback;
+	/**
+	 * Optional layer-2 anchoring for the cohort commit proofs the latest-revision consult verifies
+	 * (`cluster/certified-claims.ts`): re-derive the block's cohort and LOG the overlap with the
+	 * proof's signers, plus surface proofs accepted without that comparison. Purely observational —
+	 * never a gate — and absent in production wiring today; `certifyClaim` logs unanchored
+	 * acceptance internally regardless.
+	 */
+	proofAnchoring?: ProofAnchoring;
 }
 
 /**
@@ -183,7 +300,8 @@ export function coordinatorRepo(
 		components.clusterLatestCallback,
 		reputation,
 		stateStore,
-		components.acquireBlockFromCohort
+		components.acquireBlockFromCohort,
+		components.proofAnchoring
 	);
 }
 
@@ -195,13 +313,13 @@ export class CoordinatorRepo implements IRepo {
 	private readonly responsibilityCache = new LruMap<string, { inCluster: boolean, expires: number }>(1000);
 	private static readonly RESPONSIBILITY_TTL_MS = 60_000;
 	private readonly lastSeenCommitMs = new LruMap<string, number>(1000);
-	/** Per block, the cohort-claimed revision the last freshness consult could not settle — the
-	 *  doubt {@link flagUnconfirmedCurrency} stamps onto reads served below it. Outlives the
-	 *  consult on purpose: the read-repair window skips consults for blocks checked recently, and
-	 *  a doubt dropped there is a stale answer served as confirmed again.
+	/** Per block, what earlier repair passes left unresolved — see {@link AheadClaimState}.
+	 *  Outlives the consult on purpose: the read-repair window skips consults for blocks checked
+	 *  recently, and a doubt dropped there is a stale answer served as confirmed again.
 	 *  NOTE: LRU-bounded like `lastSeenCommitMs`; an eviction under >1000 doubted blocks loses the
-	 *  doubt until the next consult re-derives it (one read-repair window later, at worst). */
-	private readonly unsettledAheadClaims = new LruMap<string, number>(1000);
+	 *  doubt until the next consult re-derives it (one read-repair window later, at worst) and lets
+	 *  {@link reportRepairDeadlock} say its piece a second time. */
+	private readonly unsettledAheadClaims = new LruMap<string, AheadClaimState>(1000);
 	private readonly readRepairMode: 'off' | 'lazy' | 'paranoid';
 	private readonly readRepairWindowMs: number;
 	private readonly readRepairSampleRate: number;
@@ -235,7 +353,8 @@ export class CoordinatorRepo implements IRepo {
 		private readonly clusterLatestCallback?: ClusterLatestCallback,
 		reputation?: IPeerReputation,
 		stateStore?: ITransactionStateStore,
-		private readonly acquireBlockFromCohort?: AcquireBlockCallback
+		private readonly acquireBlockFromCohort?: AcquireBlockCallback,
+		private readonly proofAnchoring?: ProofAnchoring
 	) {
 		this.localPeerId = localPeerId;
 		this.log = createLogger('coordinator-repo', localPeerId?.toString());
@@ -282,7 +401,9 @@ export class CoordinatorRepo implements IRepo {
 		const localClusterRef = localCluster && localPeerId ? {
 			update: localCluster.update.bind(localCluster),
 			peerId: localPeerId,
-			wasTransactionExecuted: localCluster.wasTransactionExecuted?.bind(localCluster)
+			wasTransactionExecuted: localCluster.wasTransactionExecuted?.bind(localCluster),
+			getExecutedPendResult: localCluster.getExecutedPendResult?.bind(localCluster),
+			getExecutedCommitResult: localCluster.getExecutedCommitResult?.bind(localCluster)
 		} : undefined;
 		this.coordinator = new ClusterCoordinator(keyNetwork, createClusterClient, policy, localClusterRef, fretService, reputation, stateStore);
 	}
@@ -512,8 +633,20 @@ export class CoordinatorRepo implements IRepo {
 	 * claimed revision (see {@link flagUnconfirmedCurrency}), which is what bounds the map.
 	 */
 	private recordAheadClaim(blockId: BlockId, claimedRev: number | undefined): void {
-		if (claimedRev === undefined) this.unsettledAheadClaims.delete(blockId);
-		else this.unsettledAheadClaims.set(blockId, claimedRev);
+		const prior = this.unsettledAheadClaims.get(blockId);
+		if (claimedRev === undefined) {
+			// The consult is the authority on the CLAIM, and only on the claim. A recorded deadlock is
+			// not about any revision — it is about how many machines this deployment can field, or how
+			// many of them hold the block — so it outlives the claim that first exposed it and is
+			// dropped only when the block converges (see {@link flagUnconfirmedCurrency}).
+			if (prior?.deadlocksReported) this.unsettledAheadClaims.set(blockId, { deadlocksReported: prior.deadlocksReported });
+			else this.unsettledAheadClaims.delete(blockId);
+			return;
+		}
+		this.unsettledAheadClaims.set(blockId, {
+			rev: claimedRev,
+			...(prior?.deadlocksReported ? { deadlocksReported: prior.deadlocksReported } : {})
+		});
 	}
 
 	/**
@@ -541,18 +674,20 @@ export class CoordinatorRepo implements IRepo {
 	 * from the tail block's `latest.rev`, and `syncInternal` commits every block of an action at
 	 * `context.rev + 1` — so `context.rev >= claimedRev` is a well-defined comparison. `state.latest`
 	 * is this node's newest revision for the block even on a pinned read (StorageRepo reports the
-	 * content's own revision separately as `materializedRev`), which is exactly the number "is this
+	 * content's own revision separately as `materialized`), which is exactly the number "is this
 	 * node behind the claim?" asks about.
 	 */
 	private flagUnconfirmedCurrency(results: GetBlockResults, blockId: BlockId, context?: ActionContext): void {
-		const claimedRev = this.unsettledAheadClaims.get(blockId);
+		const claimedRev = this.unsettledAheadClaims.get(blockId)?.rev;
 		if (claimedRev === undefined) return;
 		const entry = results[blockId];
 		if (!entry || entry.unavailable !== undefined) return;
 		const servedRev = entry.state?.latest?.rev;
 		if (typeof servedRev !== 'number') return;
 		if (servedRev >= claimedRev) {
-			// Caught up — by this pass's repair or by a commit that landed since. Nothing to doubt.
+			// Caught up — by this pass's repair or by a commit that landed since. Nothing to doubt, and
+			// nothing deadlocked either: repair demonstrably converged for this block, so a later
+			// non-convergence is a new episode and gets to say so again.
 			this.unsettledAheadClaims.delete(blockId);
 			return;
 		}
@@ -763,7 +898,7 @@ export class CoordinatorRepo implements IRepo {
 		}
 		try {
 			// Bounded: a stalled cohort peer must not hold up the caller's read. Persisting happens
-			// inside the callback via `saveReplicatedBlock`, which takes the per-block commit latch —
+			// inside the callback via `saveReplicatedBlock`, which takes the block write latch —
 			// safe to call from here because the read path holds no latch of its own (`StorageRepo.get`
 			// acquires and releases it around the promotion above, and nothing wraps this method).
 			// NOTE: `get` walks its block ids sequentially, so the bound is per block, not per call — a
@@ -791,7 +926,8 @@ export class CoordinatorRepo implements IRepo {
 	 * the repair. Returns the local revision afterwards.
 	 *
 	 * A pending-only block (metadata seeded by `savePendingTransaction`, no committed revision) asked
-	 * for a forward revision no promotion can reach used to throw out of `BlockStorage.ensureRevision`.
+	 * for a forward revision no promotion can reach used to throw out of the restore step (now
+	 * `BlockStorage.restoreRevision`, driven by `StorageRepo.get`'s healing helper).
 	 * It no longer does: "no committed base here" is an absence, so that read comes back as a plain
 	 * unflagged `{ state: {} }` and this method simply returns `undefined` — acquisition then supplies
 	 * the revision. The `unavailable` arm below still fires for the shapes that ARE a guess (a `latest`
@@ -839,11 +975,14 @@ export class CoordinatorRepo implements IRepo {
 	 * repair. It is returned separately so the caller can compare, not vote.
 	 *
 	 * NOTE: the quorum is corroboration-of-a-claim, NOT Sybil-resistant cohort
-	 * membership — a peer minting fresh keypairs still casts a vote, and the claims
-	 * themselves are bare assertions (a `BlockArchive` carries no commit certificate, so
-	 * there is nothing here to verify a `(rev, actionId)` against). Commit-cert +
-	 * membership anchoring is deferred to backlog
-	 * `debt-read-repair-commit-cert-verification`.
+	 * membership — a peer minting fresh keypairs still casts a vote. A claim that arrives
+	 * with a cohort commit proof is additionally VERIFIED here (`certifyClaim`,
+	 * `cluster/certified-claims.ts`); when the proof holds, the claim is certified and
+	 * {@link selectQuorumRev} accepts it without a second voter — the cohort's signature set
+	 * is its corroboration. What a passing proof does NOT prove is that its signers are the
+	 * block's responsible cohort (anyone controlling N keys can sign their own N-peer
+	 * proof); anchoring the signer set to topology is the optional, observational-only
+	 * {@link ProofAnchoring} layer, unwired in production today.
 	 */
 	private async queryClusterForLatest(peerIds: string[], blockId: BlockId, context?: ActionContext): Promise<ClusterLatestQuery> {
 		// Query peers in parallel for their latest revision. Each query is DEADLINED (rejects), not
@@ -876,7 +1015,7 @@ export class CoordinatorRepo implements IRepo {
 		// reads as `answered === 0` and reports isolation ('cohort-unreachable') rather than a local
 		// fault. Same fix if it ever matters — require `localPeerId`.
 		const selfId = this.localPeerId?.toString();
-		let local: ActionRev | undefined;
+		let local: CertifiedActionRev | undefined;
 		const claims: RevClaim[] = [];
 		const silent: string[] = [];
 		// `allSettled` preserves input order, so results correlate to `peerIds` by index — a
@@ -897,65 +1036,296 @@ export class CoordinatorRepo implements IRepo {
 				continue;
 			}
 			if (!value) continue; // responded, holds nothing — an absent claim, not silence
-			claims.push({ peerId: peerIdStr, rev: value.rev, actionId: value.actionId });
+			// The proof rides along here and is verified BELOW (certifyClaim) before selection reads
+			// the claim set: presence proves nothing — the peer chose what to attach — but a proof
+			// that verifies certifies the claim, and a certified claim needs no second voter.
+			claims.push({
+				peerId: peerIdStr, rev: value.rev, actionId: value.actionId,
+				...(value.proof ? { proof: value.proof } : {})
+			});
 		}
 		if (silent.length > 0) {
 			this.log('cluster-fetch:peers-silent', { blockId, silent: silent.length, consulted: peerIds.length });
 		}
 
+		// Verify every attached proof, in parallel, BEFORE selection — and penalize provable proof
+		// misbehavior HERE, at verification time, independent of what selection later does with the
+		// claim. Only attributable failures (isAttributableProofFailure) are penalized: a failure
+		// whose signer identities were never proven — unknown/non-ed25519 signer, malformed
+		// signature or proof, a legacy record, the oversized-cohort cap — could have been authored
+		// by anyone in the chain, and penalizing on it would let an attacker frame a peer (the same
+		// discipline as VerifyOutcome.penalize in cluster-repo.ts). A claim whose proof fails stays
+		// in the claim set UNCERTIFIED: it still corroborates by distinct-peer count exactly as a
+		// proof-less claim does — a peer that could fabricate a bad proof could equally have sent no
+		// proof, so dropping the vote would buy nothing.
+		// NOTE: cost is one verification pass per proof-carrying answer per consult, each bounded by
+		// MAX_PROOF_SIGNERS (256) signature checks. In `lazy` mode consults are rate-limited by the
+		// read-repair window; in `paranoid` mode every read of every block pays cohort-width
+		// verifications. Fine at deployment cohort sizes (~10) — if paranoid readers ever show CPU
+		// time in `certifyClaim`, cache verdicts per (blockId, rev, actionId, proof hash) rather than
+		// skipping verification.
+		await Promise.all(claims.map(async claim => {
+			if (!claim.proof) return;
+			const verdict = await certifyClaim(
+				claim.proof,
+				{ blockId, rev: claim.rev, actionId: claim.actionId },
+				// Shared with the reconcile path, so the two cannot drift on what the members actually
+				// enforced — see `proofThresholds` for why the simple-majority term is not
+				// this.simpleMajorityThreshold.
+				proofThresholds(this.superMajorityThreshold),
+				this.proofAnchoring
+			);
+			if (verdict.certified) {
+				claim.certified = true;
+				return;
+			}
+			this.log('cluster-fetch:proof-uncertified', {
+				blockId, peerId: claim.peerId, rev: claim.rev, failure: verdict.failure
+			});
+			if (isAttributableProofFailure(verdict.failure)) {
+				this.penalizeProofService(claim.peerId, blockId);
+			}
+		}));
+
 		const nonSelfCount = peerIds.filter(id => id !== selfId).length;
 		const answered = nonSelfCount - silent.length;
 		const capacity = corroboratorCapacity(nonSelfCount, this.repairCorroborationClusterSize);
+		const required = quorumSize(claims.length, this.simpleMajorityThreshold, capacity);
 		const selected = selectQuorumRev(claims, this.simpleMajorityThreshold, capacity);
 		if (!selected) {
+			// A decline can be the certified path REFUSING to pick a side: two distinct actions each
+			// carrying a verified cohort proof for the same top revision. Name that apart from the
+			// routine no-quorum — the cohort (or whoever holds its keys) provably signed both sides,
+			// an incident rather than a shortage of answers. Neither claimant is penalized: both
+			// proofs verified, so which side is "wrong" is exactly what this node cannot know.
+			const equivocation = certifiedEquivocation(claims);
+			if (equivocation) {
+				this.log('cluster-fetch:certified-equivocation', {
+					blockId, rev: equivocation.rev, actionIds: equivocation.actionIds
+				});
+			}
+			// The three populations are reported SEPARATELY, never rolled into one "responders" count:
+			// "1 of 2 responded" and "1 holder, 1 confirmed non-holder, 0 silent" call for completely
+			// different operator actions — the first says wait or fix reachability, the second says the
+			// block has only one copy and no amount of waiting produces a second.
 			this.log('cluster-fetch:no-quorum', {
 				blockId,
-				responders: claims.length,
-				required: quorumSize(claims.length, this.simpleMajorityThreshold, capacity),
+				cohortPeers: nonSelfCount,
+				holders: claims.length,
+				absent: answered - claims.length,
+				silent: silent.length,
+				required,
 				repairCorroborationClusterSize: this.repairCorroborationClusterSize
 			});
+			// ...and, when this decline is provably permanent rather than transient, say THAT once,
+			// in words. The `no-quorum` line above fires on every pass and cannot tell the two apart.
+			this.reportRepairDeadlock({
+				blockId, claims, silentCount: silent.length, cohortPeers: nonSelfCount, answered, required, capacity
+			});
 			// The claims themselves must not drive restoration — but their existence is
 			// evidence the caller needs: an answer served below the highest claim cannot be
 			// confirmed current (see ClusterLatestQuery.uncorroboratedRev).
-			// NOTE: ONE claim is enough to raise that doubt, and a claim is a bare assertion
-			// (no commit certificate to verify it against). So a single lying cohort peer can
-			// deny unpinned reads of a block by claiming a revision nobody else holds — an
-			// availability lever it did not have while uncorroborated claims were discarded.
-			// Deliberate for now: the alternative is the silent stale serve this marker exists
-			// to end, and the same liar can already force a silent-treated absence by staying
-			// quiet. Revisit if claims become attestable (backlog
-			// `debt-read-repair-commit-cert-verification`) — then gate the stamp on a verified
-			// certificate rather than on the bare claim.
+			// NOTE: ONE claim is enough to raise that doubt, and the claims reaching this branch
+			// are unverified assertions — a certified claim converges above instead of declining
+			// (the only certified shape that lands here is the equivocation decline). So a single
+			// lying cohort peer can deny unpinned reads of a block by claiming a revision nobody
+			// else holds — an availability lever it did not have while uncorroborated claims were
+			// discarded. Deliberate for now: the alternative is the silent stale serve this marker
+			// exists to end, and the same liar can already force a silent-treated absence by
+			// staying quiet. If the lever is ever exercised, gate the stamp on a certified claim
+			// (the verification machinery now exists) rather than on the bare assertion — at the
+			// cost of re-opening the stale-serve window for the proof-less honest majority.
 			const uncorroboratedRev = claims.length > 0 ? Math.max(...claims.map(c => c.rev)) : undefined;
 			return { local, silent, answered, ...(uncorroboratedRev !== undefined ? { uncorroboratedRev } : {}) };
 		}
 
-		// Best-effort: penalize peers whose claim contradicts the corroborated pair
-		// (an inflated rev the quorum outvoted, or conflicting content at the agreed
-		// rev). A lower rev is just lag, never penalized. Never let this throw.
+		if (selected.certified) {
+			// Which rule won matters when reading a repair log: a certified selection may rest on a
+			// SINGLE claimant whose corroboration is the cohort's signature set, not other voters.
+			this.log('cluster-fetch:certified-selected', {
+				blockId, rev: selected.rev, claimants: selected.supporters.length
+			});
+		}
+
+		// Best-effort: penalize peers whose claim contradicts a CORROBORATED selection — a different
+		// action at the very same revision. A higher rev may be honest leadership and a lower rev is
+		// just lag; neither is penalized, nor is anything contradicting a certified-only selection
+		// (an unanchored proof must not be able to convict the honest cohort). Never let this throw.
 		this.penalizeContradictingRevClaims(claims, selected, blockId);
 
 		return { corroborated: { actionId: selected.actionId, rev: selected.rev }, local, silent, answered };
 	}
 
 	/**
-	 * Report peers whose reported latest contradicts the quorum-corroborated pair. Best-effort.
+	 * Say ONCE per block, in words, when a corroboration decline is provably PERMANENT rather than a
+	 * transient shortage of answers. There are exactly TWO permanent shapes, and they send the operator
+	 * to different places, so each gets its own `reason` and its own wording:
+	 *
+	 *  - `cohort-too-small` — this node's cohort has fewer peers than the quorum would demand even if
+	 *    every one of them answered and agreed. The remedy is machines or an honest declared size.
+	 *  - `sole-holder` — the cohort is big enough, but exactly ONE of its peers holds the block at all
+	 *    and every other peer answered that it holds nothing. The remedy is another cohort peer
+	 *    holding the block; machines and configuration are both irrelevant. Note the scope: this node's
+	 *    own copy is excluded from the claim set, so a reader that holds the block itself still sees
+	 *    `sole-holder` — the message says "cohort peer", never "machine in the deployment".
+	 *
+	 * **What makes `cohort-too-small` provable.** Not "this pass fell short" — a pass falls short
+	 * whenever some peer simply does not hold the block *yet*. The decisive question is whether the
+	 * cohort could supply the quorum AT ALL: ask what would be required if every cohort peer answered
+	 * and agreed — the best case any later pass can reach without new machines — and compare it to how
+	 * many peers the cohort has. Short of that best case the shortfall is not the machine count, and
+	 * saying PERMANENT would send the operator to change a number that was never the problem. Twelve
+	 * days of log archaeology went into re-deriving the real condition from a thousand identical
+	 * `cluster-fetch:no-quorum` lines; the node knows it at the moment of each decline.
+	 *
+	 * **What makes `sole-holder` provable.** Note it is only reachable for a lone UNCERTIFIED holder:
+	 * a lone holder whose cohort commit proof verified is selected by the certified path and converges
+	 * before any decline — so the wording's "a lone holder cannot second itself" stays accurate for
+	 * every claim that gets here. "That peer will hold it later" is an assumption, and for a
+	 * peer that ANSWERED "I hold nothing" it is false: the only two mechanisms that would turn a
+	 * non-holder into a holder — `queryClusterForLatest` (read-repair) and `createReconcileBlock`
+	 * (reconcile) — consume this very decision, so they decline for exactly the same reason on that
+	 * peer. Every peer answered, one holds the block, the rest hold nothing, and no later pass changes
+	 * any of that. What DOES change it is a new copy: a commit that writes the block again pushes it to
+	 * the current cohort. (Sibling work `replicate-owned-blocks-when-the-cohort-grows` makes that
+	 * automatic; until it lands the operator has to cause the write.)
 	 *
-	 * NOTE: the `rev > selected.rev` branch is NOT provable misbehavior — an honest
-	 * peer legitimately ahead of the sampled quorum (an in-flight commit it durably
-	 * stored, or other honest holders dropped from the sample by the 1s per-peer
-	 * timeout) reports a higher rev and gets penalized (weight 30 → immediate
-	 * deprioritize at threshold 20). Distinguishing a liar from an honest leader
-	 * needs the commit-cert verification tracked in backlog
-	 * `debt-read-repair-penalty-provable-only` / `debt-read-repair-commit-cert-verification`.
+	 * **What is deliberately NOT reported.** A cohort that answers unanimously "I hold nothing" — an
+	 * agreed absence is an answer, not a failed repair. A pass with any silent peer: silence cannot
+	 * change the arithmetic (`cohortPeers` counts silent peers too), but it does mean this node saw less
+	 * than the whole picture, and the next clean pass says the same thing at no cost. Note there is
+	 * deliberately NO "the claims disagreed" exemption for `cohort-too-small`: a cohort too small to
+	 * reach quorum stays too small whether its peers agree or not, so disagreement would suppress a line
+	 * that is still true. Two or more disagreeing holders DO suppress `sole-holder`, because that is a
+	 * cohort with two copies whose peers have not settled yet — a later pass can settle it.
+	 *
+	 * **Never a lever.** This only classifies and logs; it never relaxes a floor. Which is also why the
+	 * `cohort-too-small` message names *two* readings of the same numbers — a deployment that genuinely
+	 * runs this few machines, or a cohort view shrunk below the real deployment by a partition or by an
+	 * attacker with routing influence. `corroboratorCapacity` keeps the shrunken view out of the relaxed
+	 * branch, but this node cannot tell the two apart from the inside, and an operator sent to fix the
+	 * wrong one is the failure this line exists to end.
+	 *
+	 * NOTE: the reader is still told only "this may be stale" — `BlockPossiblyStaleError` implies a
+	 * retry might help, which is wrong advice for a block whose repair is deadlocked as configured.
+	 * Carrying this condition into the error needs a new field on `GetBlockResult` plus a change to
+	 * that error's documented contract; deliberately out of scope here (see the ticket
+	 * `repair-deadlock-is-never-named`, *Not this ticket*).
+	 */
+	private reportRepairDeadlock(pass: {
+		blockId: BlockId;
+		claims: RevClaim[];
+		silentCount: number;
+		/** Cohort peers besides this node, from the cohort view — whether they answered or not. */
+		cohortPeers: number;
+		answered: number;
+		/** The quorum THIS pass demanded, computed from the peers that actually claimed. */
+		required: number;
+		/** `corroboratorCapacity` for this pass — a function of the view and the resolved size, not of who answered. */
+		capacity: number;
+	}): void {
+		const { blockId, claims, silentCount, cohortPeers, answered, required, capacity } = pass;
+		// An incomplete picture proves nothing about the deployment; the next clean pass says it.
+		if (silentCount > 0) return;
+		// Nobody claimed anything: the cohort agrees the block is absent, which is an answer, not a
+		// deadlock.
+		if (claims.length === 0) return;
+		// The decisive test for the first shape. `requiredEvenIfAllAnswered` is the quorum this cohort
+		// would face with every one of its peers answering and agreeing — the best case reachable
+		// without adding machines. A cohort that can meet it is not too small.
+		const requiredEvenIfAllAnswered = quorumSize(cohortPeers, this.simpleMajorityThreshold, capacity);
+		const cohortTooSmall = cohortPeers < requiredEvenIfAllAnswered;
+		// The second shape: exactly one cohort peer holds the block AT ALL, and — since a claim is one
+		// peer's latest, so a single claim is a single distinct (rev, actionId) group with a single
+		// supporter — every other cohort peer answered that it holds nothing. `answered === cohortPeers`
+		// is already implied by the silence guard above; it is stated because the two counts arrive as
+		// independent parameters and "everybody answered" is half of what makes this provable.
+		//
+		// NOTE: there is a narrow window where `sole-holder` is true of the instant but not of the
+		// deployment — a commit that has landed on one cohort member and has not yet been pushed to the
+		// rest presents exactly this shape. Calling it PERMANENT is defensible even there (repair
+		// genuinely cannot converge until the push lands, and the once-per-episode flag clears the
+		// moment the block converges, so the line does not repeat), and widening the window is what the
+		// push path's own threat model decides — see
+		// `tickets/blocked/repair-floor-defends-a-door-the-push-path-leaves-open`. If commit-to-push
+		// latency ever grows enough that operators see `sole-holder` on blocks that heal moments later,
+		// gate the line on the block having been quiet for longer than that latency rather than
+		// softening the wording.
+		const soleHolder = claims.length === 1 && answered === cohortPeers;
+		if (!cohortTooSmall && !soleHolder) return;
+
+		// Both shapes can hold at once (an undeclared two-machine deployment whose single peer holds the
+		// block is both). `cohort-too-small` is reported in preference because its remedy is the one
+		// that actually works there: declaring the real size makes the floor reachable, after which the
+		// lone peer's claim IS adopted — so calling it a sole-holder problem would send the operator
+		// looking for a copy they do not need.
+		const reason: DeadlockReason = cohortTooSmall ? 'cohort-too-small' : 'sole-holder';
+		const state = this.unsettledAheadClaims.get(blockId);
+		const alreadySaid = state?.deadlocksReported ?? [];
+		// Suppressed per REASON, not once outright: an episode that starts as `cohort-too-small` and
+		// becomes `sole-holder` — the operator added the machines that reason asked for, and the block
+		// is still stuck — has a second thing to say, and a silent log there is the failure this line
+		// exists to end. Neither reason repeats within an episode.
+		if (alreadySaid.includes(reason)) return;
+
+		this.log('cluster-fetch:repair-deadlock', {
+			blockId,
+			reason,
+			cohortPeers,
+			answered,
+			claimants: claims.length,
+			required,
+			requiredEvenIfAllAnswered,
+			repairCorroborationClusterSize: this.repairCorroborationClusterSize,
+			message: cohortTooSmall
+				? cohortTooSmallMessage(cohortPeers, claims.length, requiredEvenIfAllAnswered, this.repairCorroborationClusterSize)
+				: soleHolderMessage(cohortPeers)
+		});
+		// Hung off the existing per-block freshness entry rather than a fourth per-block map. The entry
+		// survives `recordAheadClaim` clearing its `rev`, and is dropped wholesale once the block
+		// converges — so each reason is said once per non-convergence episode, not once per pass.
+		// NOTE: per BLOCK, though the condition is a property of the cohort, not of any block — so a node
+		// in this state that reads N distinct blocks emits N lines. Deliberate: the operator wants to
+		// know which blocks are stuck, and N is bounded by blocks actually read (1821 lines for a single
+		// block was the defect). If a deployment in this state ever makes this the noisy line again, add
+		// a node-level once-flag keyed on (cohortPeers, requiredEvenIfAllAnswered) and let the per-block
+		// entry only suppress repeats.
+		this.unsettledAheadClaims.set(blockId, { ...(state ?? {}), deadlocksReported: [...alreadySaid, reason] });
+	}
+
+	/**
+	 * Report peers whose reported latest PROVABLY contradicts a CORROBORATED selection: the same
+	 * revision under a different actionId. Two actions cannot both be the commit at one revision,
+	 * and the pair a quorum of distinct peers agreed on is the one this node can stand behind, so
+	 * the disagreeing claimant is wrong. Best-effort.
+	 *
+	 * A CERTIFIED selection is deliberately excluded — no claim is penalized against it. A passing
+	 * proof shows the cohort it names signed the commit, never that those signers are the block's
+	 * responsible cohort: anyone holding N keys can mint a proof that verifies (see caller
+	 * obligation #1 in `cluster/commit-proof.ts`, and the unwired {@link ProofAnchoring} layer).
+	 * Penalizing here would therefore hand one forged proof a lever it must not have — every honest
+	 * peer holding the real action at that revision reported for InvalidRestoration (weight 30,
+	 * above the deprioritize threshold of 20), on every consult. Losing the selection to the proof
+	 * is already the accepted cost of the certified path; deprioritizing the honest cohort on top of
+	 * it is not. Revisit when certification is anchored to the block's derived cohort
+	 * (`feat-cluster-membership-threshold-cert-anchoring`): a gated proof makes the contradiction
+	 * provable again.
+	 *
+	 * A claim at a HIGHER rev than the selection is deliberately NOT penalized: a peer can honestly
+	 * be ahead of the sampled quorum — an in-flight commit it durably stored before the rest of the
+	 * cohort, or other honest holders dropped from the sample by the 1s per-peer consult deadline —
+	 * and the InvalidRestoration weight (30) sits above the deprioritize threshold (20), so a single
+	 * false hit used to deprioritize an honest, up-to-date peer. Declining to RESTORE from the
+	 * uncorroborated higher claim already happens in selection; the affirmative penalty on that
+	 * ambiguous evidence is what this method no longer applies. Provably-bad proof SERVICE is
+	 * penalized at verification time instead (the certifyClaim pass in
+	 * {@link queryClusterForLatest}).
 	 */
 	private penalizeContradictingRevClaims(claims: RevClaim[], selected: QuorumRev, blockId: BlockId): void {
-		if (!this.reputation) return;
+		if (!this.reputation || selected.certified) return;
 		try {
 			for (const c of claims) {
-				const contradicts = c.rev > selected.rev
-					|| (c.rev === selected.rev && c.actionId !== selected.actionId);
-				if (contradicts) {
+				if (c.rev === selected.rev && c.actionId !== selected.actionId) {
 					this.reputation.reportPeer(c.peerId, PenaltyReason.InvalidRestoration, `read-repair:${blockId}`);
 				}
 			}
@@ -964,6 +1334,21 @@ export class CoordinatorRepo implements IRepo {
 		}
 	}
 
+	/**
+	 * Best-effort penalty for a peer whose SERVED PROOF provably lies or provably does not cover the
+	 * claim it was attached to (see the attributability classification in
+	 * `cluster/certified-claims.ts`). Never throws — mirrors
+	 * {@link penalizeContradictingRevClaims}.
+	 */
+	private penalizeProofService(peerId: string, blockId: BlockId): void {
+		if (!this.reputation) return;
+		try {
+			this.reputation.reportPeer(peerId, PenaltyReason.InvalidRestoration, `read-repair:${blockId}`);
+		} catch (err) {
+			this.log('cluster-fetch:penalize-error', { blockId, error: (err as Error).message });
+		}
+	}
+
 	async pend(request: PendRequest, options?: MessageOptions): Promise<PendResult> {
 		const allBlockIds = blockIdsForTransforms(request.transforms);
 		await this.verifyResponsibility(allBlockIds);
@@ -981,10 +1366,13 @@ export class CoordinatorRepo implements IRepo {
 		};
 
 		try {
-			const { localExecuted } = await this.coordinator.executeClusterTransaction(coordinatingBlockIds[0]!, message, options);
+			const { localExecuted, localPendResult } = await this.coordinator.executeClusterTransaction(coordinatingBlockIds[0]!, message, options);
 			this.log('coordinator-repo:pend-cluster-complete', {
 				actionId: request.actionId,
-				localExecuted
+				localExecuted,
+				localVerdict: localPendResult === undefined ? 'none'
+					: localPendResult.success ? 'success'
+						: isConflictFailure(localPendResult) ? 'conflict' : 'fault'
 			});
 			// Only call storageRepo if local cluster didn't already execute during consensus
 			if (!localExecuted) {
@@ -997,7 +1385,29 @@ export class CoordinatorRepo implements IRepo {
 				});
 				return result;
 			}
-			// Local cluster already executed - return success
+			// Local cluster already executed during consensus — return storage's own verdict rather
+			// than fabricating a success (the peerCount <= 1 path above returns storage's real result
+			// verbatim; the cluster path must never answer differently). Pend-consensus confers no
+			// durability: a refusal carrying `pending` (a rival's unresolved action holds the blocks)
+			// or `missing` (the requested revision is already committed) is the optimistic-concurrency
+			// verdict — the same scan every member runs, not a local fault — and must reach the writer
+			// as a retryable conflict so NetworkTransactor.pendPhase cancels the partial pend and the
+			// writer rebases. This deliberately differs from `commit`'s divergence split below: a
+			// commit that reached commit-consensus IS the authoritative commit (Theorem 9), whereas a
+			// pend that reached pend-consensus may still have been stored by nobody.
+			if (localPendResult !== undefined) {
+				if (localPendResult.success || isConflictFailure(localPendResult)) {
+					return localPendResult;
+				}
+				// A bare-reason refusal (no pending/missing — e.g. a local validation-hook fault)
+				// stays tolerated local divergence: consensus is authoritative and the pend may well
+				// have landed on the rest of the cohort.
+				this.log('coordinator-repo:pend-local-fault-tolerated', {
+					actionId: request.actionId,
+					reason: localPendResult.reason
+				});
+			}
+			// No verdict retained (member predates retention, restart, or TTL): the prior shape.
 			return {
 				success: true,
 				pending: [],
@@ -1015,10 +1425,28 @@ export class CoordinatorRepo implements IRepo {
 			// has no field for it and the retry loop only needs "retryable". If a caller ever needs to
 			// know WHICH transaction won (e.g. to wait on it rather than re-race it), add a typed field
 			// for it; never recover it by parsing `reason`.
+			//
+			// NOTE: with three or more contenders the members can split so that EVERY contender is
+			// told it lost the race — an all-lose round where nobody wins and each writer retries.
+			// The cause is `ClusterMember.resolveRace`'s approvals-first rule, not its tie-break:
+			// each member compares the rivals as IT holds them, so a member that already approved X
+			// keeps X while a member that approved Y first keeps Y, and no rival reaches a promise
+			// supermajority. (The hash tie-break is already symmetric — it cannot be the fix.)
+			// Fine as it stands: since the torn-action fixes landed, an all-lose round costs one
+			// retry cycle rather than wedging, and the contenders are separated next round by the
+			// jittered backoff plus the aged retry priority carried on the re-pend
+			// (`clampPriority(consecutiveFailures)` in `Collection.syncInternal`), which out-ranks
+			// fresh priority-0 rivals at EQUAL approval counts — priority sits below the approval
+			// count in `resolveRace`, so it does not displace a more-progressed rival. If a
+			// high-contention workload ever shows syncs exhausting `maxAttempts` on repeated
+			// all-lose rounds, the fix is reserve/defer at pend time (backlog
+			// `feat-occ-priority-reservation`, which `resolveRace`'s own residual-fairness NOTE
+			// already points at) rather than raising maxAttempts.
 			if (error instanceof ConflictRaceLostError) {
 				return { success: false, conflict: true, reason: error.message };
 			}
-			const stale = await this.classifyStaleRejection(error, request, allBlockIds);
+			const stale = await this.classifyStaleRejection(error, request, allBlockIds)
+				?? await this.classifyPendingConflictRejection(error, request, allBlockIds);
 			if (stale) return stale;
 			throw error;
 		}
@@ -1062,7 +1490,16 @@ export class CoordinatorRepo implements IRepo {
 		// number and the reason prose name that block, so they never disagree.
 		const staleAt = highestStaleAt(blockIds.map(blockId => {
 			const latest = results[blockId]?.state.latest;
-			return latest && latest.rev >= requestedRev ? { blockId, rev: latest.rev } : undefined;
+			if (!latest || latest.rev < requestedRev) return undefined;
+			// Per-block self-exclusion (see {@link isOwnRevision}): our own durable half of a torn
+			// action is not a confirmed loss. Deliberately per-block, NOT the bail-entirely
+			// 'own-durable' shape of confirmCommitRivalAgainstLocal — a confirmed rival on ANOTHER
+			// block still confirms, and when none is confirmed anywhere the rejection stays a throw
+			// exactly as before. With the two pend-tier sites upstream fixed (StorageRepo.pend and
+			// ClusterMember.validatePendOperations) this shape should not reach here; mirrored so
+			// all three pend-tier checks agree.
+			if (isOwnRevision(latest, requestedRev, request.actionId)) return undefined;
+			return { blockId, rev: latest.rev };
 		}));
 		if (staleAt) {
 			this.log('coordinator-repo:pend-stale-classified', {
@@ -1089,6 +1526,53 @@ export class CoordinatorRepo implements IRepo {
 		return undefined;
 	}
 
+	/**
+	 * Sibling of {@link classifyStaleRejection} for the OTHER optimistic-concurrency refusal shape:
+	 * the promise-phase pending-conflict vote (`validatePendOperations` rejecting a pend whose
+	 * blocks are held by a different unresolved pending action). That vote surfaces here as a
+	 * {@link ValidatorRejectionError}, and without classification it would escape as a throw —
+	 * splitting multi-tree pends mid-batch instead of taking the retry path a lost race deserves.
+	 *
+	 * Same confirmation discipline as the stale classifier: purely local. Re-read the affected
+	 * blocks from our own storage and require some block's `state.pendings` to carry a rival
+	 * actionId; the signed reject text is never consulted. A confirmed rival returns a
+	 * {@link StaleFailure} with `conflict: true` and the rivals as `pending` (`ActionPending`
+	 * without `transform` — the type allows it, and no consumer rebases from it). Unconfirmed —
+	 * including read errors during confirmation — stays a throw, preserving fail-fast for genuine
+	 * validation faults. Checked after `classifyStaleRejection` so a confirmed committed loss
+	 * (which carries the sharper `staleAt`) wins when both hold.
+	 */
+	private async classifyPendingConflictRejection(error: unknown, request: PendRequest, blockIds: BlockId[]): Promise<StaleFailure | undefined> {
+		if (!(error instanceof ValidatorRejectionError)) return undefined;
+		let results: GetBlockResults;
+		try {
+			results = await this.storageRepo.get({ blockIds });
+		} catch (readError) {
+			this.log('coordinator-repo:pend-conflict-classify-read-error', {
+				actionId: request.actionId,
+				error: (readError as Error).message
+			});
+			return undefined;
+		}
+		const pending: ActionPending[] = [];
+		for (const blockId of blockIds) {
+			for (const actionId of results[blockId]?.state?.pendings ?? []) {
+				if (actionId !== request.actionId) pending.push({ blockId, actionId });
+			}
+		}
+		if (pending.length === 0) return undefined;
+		this.log('coordinator-repo:pend-conflict-classified', {
+			actionId: request.actionId,
+			rivals: pending.map(p => `${p.blockId}:${p.actionId}`)
+		});
+		return {
+			success: false,
+			conflict: true,
+			pending,
+			reason: `pending conflict: block(s) held by unresolved rival action(s) ${[...new Set(pending.map(p => p.actionId))].join(', ')}`
+		};
+	}
+
 	async cancel(actionRef: ActionBlocks, options?: MessageOptions): Promise<void> {
 		const blockIds = actionRef.blockIds;
 		await this.verifyResponsibility(blockIds);
@@ -1100,16 +1584,30 @@ export class CoordinatorRepo implements IRepo {
 		};
 
 		try {
-			// For each block ID, execute a cluster transaction
-			const clusterPromises = blockIds.map(blockId =>
-				this.coordinator.executeClusterTransaction(blockId, message, options)
-			);
-
-			// Wait for all cluster transactions to complete
-			const results = await Promise.all(clusterPromises);
+			// One cluster transaction per block ID — but a block whose cohort is just this node
+			// short-circuits to local storage, exactly as `pend` and `commit` do above. Without the
+			// short-circuit a solo cohort enters `executeTransaction`, fails `minAbsoluteClusterSize`
+			// (2), and throws `Cluster size 1 below minimum 2 and not validated` — so a single-peer
+			// deployment could pend and commit but never cancel, unless the operator had opened the
+			// `allowUnvalidatedSmallCluster` hatch. Decided per block rather than once for
+			// `blockIds[0]`, because a multi-block cancel can span cohorts of different sizes.
+			//
+			// NOTE: `getClusterSize` is a second `findCluster` for the same key that
+			// `executeClusterTransaction` is about to look up again, so a cancel over N blocks now
+			// costs 2N cohort lookups instead of N. Same shape `pend` and `commit` already pay, but
+			// they pay it once (they only ever consult `blockIds[0]`) where this scales with N. Fine
+			// while cancels span a handful of blocks; if wide multi-block cancels ever show up hot,
+			// have `executeClusterTransaction` return the cohort it already fetched (or own the
+			// short-circuit itself) rather than adding a cache here.
+			const results = await Promise.all(blockIds.map(async blockId => {
+				const peerCount = await this.coordinator.getClusterSize(blockId);
+				if (peerCount <= 1) return false;
+				const { localExecuted } = await this.coordinator.executeClusterTransaction(blockId, message, options);
+				return localExecuted;
+			}));
 
 			// Only call storageRepo if local cluster didn't already execute during consensus
-			const anyLocalExecuted = results.some(r => r.localExecuted);
+			const anyLocalExecuted = results.some(Boolean);
 			if (!anyLocalExecuted) {
 				await this.storageRepo.cancel(actionRef, options);
 			}
@@ -1136,8 +1634,40 @@ export class CoordinatorRepo implements IRepo {
 		};
 
 		try {
-			const { record, localExecuted } = await this.coordinator.executeClusterTransaction(blockIds[0]!, message, options);
+			const { record, localExecuted, localCommitResult } = await this.coordinator.executeClusterTransaction(blockIds[0]!, message, options);
 			if (localExecuted) {
+				// Our own member applied this commit during consensus. Its retained storage verdict is
+				// the one honest signal we have about durability: the member-side apply tolerates an
+				// "ahead" refusal as divergence (see the NOTE in ClusterMember.applyConsensusOperation),
+				// which is correct for a redelivered or lagging commit — but when the refusal's real
+				// cause is a RIVAL action holding the requested revision, that tolerance turns a commit
+				// no member durably stored into a fabricated success. This is the
+				// signed-but-not-yet-applied window: two commits for one revision can BOTH assemble
+				// consensus when every member signs the second after signing (but before applying) the
+				// first, because signing drops the member's reservation. Confirm the rival against local
+				// storage (never the verdict's prose) and answer the writer with a retryable conflict so
+				// it re-drives at a fresh revision. Own-action or unconfirmed refusals keep the
+				// prior fabricated-success shape: consensus is authoritative and this member converges
+				// via replication.
+				//
+				// NOTE: a CONFIRMED rival is trusted over the consensus outcome here. That is right in
+				// the window this closes (the cohort refused the loser too), but it inverts if the two
+				// ever disagree — a local rival at the requested revision while a super-majority
+				// approved OUR commit means this node is on a forked lineage, and refusing then tells a
+				// writer whose write did land to re-drive it (a duplicate entry). Members holding the
+				// rival reject at the promise round, so consensus and a local rival can only disagree
+				// after a fork; that is partition-healing scope (docs/partition-healing.md). If forks
+				// are ever observed here, weigh the retained verdict against the cohort's votes instead
+				// of trusting the local re-read alone.
+				if (localCommitResult !== undefined && !localCommitResult.success) {
+					const rival = await this.confirmCommitRivalAgainstLocal(request);
+					if (typeof rival === 'object') return rival;
+					this.log('coordinator-repo:commit-local-refusal-tolerated', {
+						actionId: request.actionId,
+						confirmation: rival ?? 'unconfirmed',
+						reason: localCommitResult.reason
+					});
+				}
 				this.markBlocksSeen(blockIds);
 				return { success: true };
 			}
@@ -1172,10 +1702,138 @@ export class CoordinatorRepo implements IRepo {
 			}
 		} catch (error) {
 			this.log('coordinator-repo:commit-error', { actionId: request.actionId, error: (error as Error).message });
+			// A lost commit-consensus race is an optimistic-concurrency loss, not a fault — mirror
+			// `pend`'s conversion above. At the moment this is thrown, zero members approved and the
+			// members hold the winner: nothing of the loser landed, so a retryable-conflict answer is
+			// truthful. Returning it (rather than rethrowing) matters more here than on the pend path:
+			// db-core's `commitCollection` retries a THROWN commit error verbatim up to 3 times, and by
+			// the retry the members have applied the winner and cleared its reservation — the re-driven
+			// commit can then assemble a consensus no member will durably store (the writer's append
+			// fulfills, the entry exists on no node). A RETURNED `success:false` is instead surfaced
+			// immediately as a stale loss; the writer cancels the pend, re-reads, and re-drives the
+			// whole pend+commit at a fresh revision. `staleAt` stays absent for the same reason as
+			// pend's: it is confirmed-only, and a lost race is a rival commit racing the same revision,
+			// not a locally-confirmed revision claim.
+			if (error instanceof ConflictRaceLostError) {
+				return { success: false, conflict: true, reason: error.message };
+			}
+			// A promise-phase stale-commit reject (`ClusterMember.validateCommitRevisions` — a member
+			// holds the requested revision under a different action) surfaces here as a
+			// ValidatorRejectionError; classify it against local storage the way `pend` does, so the
+			// writer gets a clean retryable conflict instead of three verbatim re-drives and a hard
+			// failure.
+			const stale = await this.classifyCommitStaleRejection(error, request);
+			if (stale) return stale;
 			throw error;
 		}
 	}
 
+	/**
+	 * Commit-shaped sibling of {@link classifyStaleRejection}: decide whether a cluster validator
+	 * rejection of a COMMIT was an optimistic-concurrency loss — the requested revision is already
+	 * committed under a different action — rather than a genuine validation fault. A confirmed loss
+	 * returns a {@link StaleFailure} with `conflict: true` so db-core's `commitCollection` surfaces
+	 * it immediately as a stale loss (no verbatim retry) and the writer re-drives at a fresh
+	 * revision.
+	 *
+	 * Same confirmation discipline as the pend classifiers: purely local re-read; the signed reject
+	 * text is never consulted. One commit-specific delta — confirmation must EXCLUDE the
+	 * own-action-at-rev case: a block whose requested revision is held by THIS action is already
+	 * durable, and answering `conflict` for it would make the writer rebase and re-append an
+	 * already-committed action at a new revision — a duplicate entry. So:
+	 *  - `latest.rev === request.rev` → compare `latest.actionId`: ours ⇒ bail (stays a throw),
+	 *    a rival's ⇒ confirmed loss;
+	 *  - `latest.rev > request.rev` → ask the {@link IRevisionActionReader} capability who holds
+	 *    `request.rev`: ours ⇒ bail, a rival's ⇒ confirmed loss, unknown/absent/fault ⇒ unconfirmed;
+	 *  - anything unconfirmed (including read errors) stays a throw — fail-fast for genuine faults.
+	 */
+	private async classifyCommitStaleRejection(error: unknown, request: CommitRequest): Promise<StaleFailure | undefined> {
+		if (!(error instanceof ValidatorRejectionError)) return undefined;
+		const rival = await this.confirmCommitRivalAgainstLocal(request);
+		// 'own-durable' and unconfirmed both stay a throw here: fail-fast for genuine faults, and a
+		// commit already durable under this action must never be answered `conflict` (the writer
+		// would rebase and re-append it — a duplicate entry).
+		return typeof rival === 'object' ? rival : undefined;
+	}
+
+	/**
+	 * Shared confirmation core for the two commit-tier conversion sites ({@link classifyCommitStaleRejection}
+	 * and the locally-executed refusal check in {@link commit}): decide, from LOCAL storage only, who
+	 * holds the requested revision.
+	 *  - a confirmed RIVAL → the {@link StaleFailure} conflict answer (with `staleAt` = highest
+	 *    confirmed holder);
+	 *  - our OWN action durable at the requested revision → `'own-durable'` (callers must not answer
+	 *    `conflict` — the writer would rebase an already-landed action into a duplicate entry);
+	 *  - anything else (behind, truncated history, read faults, capability absent) → `undefined`,
+	 *    unconfirmed.
+	 * The signed reject text / retained verdict prose is never consulted.
+	 */
+	private async confirmCommitRivalAgainstLocal(request: CommitRequest): Promise<StaleFailure | 'own-durable' | undefined> {
+		const blockIds = request.blockIds;
+		let results: GetBlockResults;
+		try {
+			results = await this.storageRepo.get({ blockIds });
+		} catch (readError) {
+			this.log('coordinator-repo:commit-stale-classify-read-error', {
+				actionId: request.actionId,
+				error: (readError as Error).message
+			});
+			return undefined;
+		}
+		const reader = this.storageRepo as IRepo & Partial<IRevisionActionReader>;
+		// Scan EVERY block (same rule as the pend classifier): report the highest confirmed rival
+		// revision, but bail the moment any block shows OUR action durable at the requested revision.
+		const rivalStales: ({ blockId: BlockId; rev: number } | undefined)[] = [];
+		for (const blockId of blockIds) {
+			const latest = results[blockId]?.state?.latest;
+			if (!latest || latest.rev < request.rev) continue;
+			if (latest.rev === request.rev) {
+				if (latest.actionId === request.actionId) {
+					this.log('coordinator-repo:commit-stale-classify-own-action', {
+						actionId: request.actionId, blockId, rev: request.rev
+					});
+					return 'own-durable';
+				}
+				rivalStales.push({ blockId, rev: latest.rev });
+				continue;
+			}
+			// latest.rev > request.rev — latest can no longer name who took request.rev.
+			if (typeof reader.getRevisionAction !== 'function') continue;
+			let takenBy: ActionId | undefined;
+			try {
+				takenBy = await reader.getRevisionAction(blockId, request.rev);
+			} catch (readError) {
+				this.log('coordinator-repo:commit-stale-classify-revision-read-error', {
+					actionId: request.actionId, blockId, rev: request.rev,
+					error: (readError as Error).message
+				});
+				continue;
+			}
+			if (takenBy === request.actionId) {
+				this.log('coordinator-repo:commit-stale-classify-own-action', {
+					actionId: request.actionId, blockId, rev: request.rev, latestRev: latest.rev
+				});
+				return 'own-durable';
+			}
+			if (takenBy !== undefined) rivalStales.push({ blockId, rev: latest.rev });
+			// takenBy undefined (truncated history): unconfirmed for this block.
+		}
+		const staleAt = highestStaleAt(rivalStales);
+		if (!staleAt) return undefined;
+		this.log('coordinator-repo:commit-stale-classified', {
+			actionId: request.actionId,
+			blockId: staleAt.blockId,
+			latestRev: staleAt.rev,
+			requestedRev: request.rev
+		});
+		return {
+			success: false,
+			conflict: true,
+			reason: `stale commit: block ${staleAt.blockId} at rev ${staleAt.rev}, requested rev ${request.rev}`,
+			staleAt
+		};
+	}
+
 	/**
 	 * Report success for a commit the cluster carried but this peer could not apply locally. The
 	 * blocks are marked seen so the read path treats them as freshness-checked; convergence comes