@optimystic/db-p2p 0.24.1 → 0.25.0

package/dist/src/repo/coordinator-repo.js

@@ -1,9 +1,10 @@
-import { LruMap, blockIdsForTransforms, highestStaleAt, DEFAULT_SUPER_MAJORITY_THRESHOLD } 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 { peerIdFromString } from "@libp2p/peer-id";
 import { createLogger } from '../logger.js';
 import { PenaltyReason } from "../reputation/types.js";
-import { quorumSize, corroboratorCapacity, selectQuorumRev } from "../cluster/quorum-restore.js";
+import { quorumSize, corroboratorCapacity, selectQuorumRev, certifiedEquivocation, CORROBORATION_FLOOR } from "../cluster/quorum-restore.js";
+import { certifyClaim, isAttributableProofFailure, proofThresholds } 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";
@@ -27,8 +28,52 @@ function withDeadline(promise, ms, label) {
             clearTimeout(timer);
     });
 }
+/** The `cohort-too-small` wording: the cohort cannot field the quorum however healthy its peers are. */
+function cohortTooSmallMessage(cohortPeers, claimants, requiredEvenIfAllAnswered, repairCorroborationClusterSize) {
+    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) {
+    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.)`;
+}
 export function coordinatorRepo(keyNetwork, createClusterClient, cfg, fretService, reputation, stateStore) {
-    return (components) => new CoordinatorRepo(keyNetwork, createClusterClient, components.storageRepo, cfg, components.localCluster, components.localPeerId, fretService, components.clusterLatestCallback, reputation, stateStore, components.acquireBlockFromCohort);
+    return (components) => new CoordinatorRepo(keyNetwork, createClusterClient, components.storageRepo, cfg, components.localCluster, components.localPeerId, fretService, components.clusterLatestCallback, reputation, stateStore, components.acquireBlockFromCohort, components.proofAnchoring);
 }
 /** Cluster coordination repo - uses local store, as well as distributes changes to other nodes using cluster consensus. */
 export class CoordinatorRepo {
@@ -37,18 +82,19 @@ export class CoordinatorRepo {
     storageRepo;
     clusterLatestCallback;
     acquireBlockFromCohort;
+    proofAnchoring;
     coordinator;
     DEFAULT_TIMEOUT = 30000; // 30 seconds default timeout
     localPeerId;
     responsibilityCache = new LruMap(1000);
     static RESPONSIBILITY_TTL_MS = 60_000;
     lastSeenCommitMs = new LruMap(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). */
+     *  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. */
     unsettledAheadClaims = new LruMap(1000);
     readRepairMode;
     readRepairWindowMs;
@@ -71,12 +117,13 @@ export class CoordinatorRepo {
     now = () => Date.now();
     /** Test seam: overridable RNG (0..1) for sample-rate gating. */
     rand = () => Math.random();
-    constructor(keyNetwork, createClusterClient, storageRepo, cfg, localCluster, localPeerId, fretService, clusterLatestCallback, reputation, stateStore, acquireBlockFromCohort) {
+    constructor(keyNetwork, createClusterClient, storageRepo, cfg, localCluster, localPeerId, fretService, clusterLatestCallback, reputation, stateStore, acquireBlockFromCohort, proofAnchoring) {
         this.keyNetwork = keyNetwork;
         this.createClusterClient = createClusterClient;
         this.storageRepo = storageRepo;
         this.clusterLatestCallback = clusterLatestCallback;
         this.acquireBlockFromCohort = acquireBlockFromCohort;
+        this.proofAnchoring = proofAnchoring;
         this.localPeerId = localPeerId;
         this.log = createLogger('coordinator-repo', localPeerId?.toString());
         const policy = {
@@ -122,7 +169,9 @@ export class CoordinatorRepo {
         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);
     }
@@ -342,10 +391,22 @@ export class CoordinatorRepo {
      * claimed revision (see {@link flagUnconfirmedCurrency}), which is what bounds the map.
      */
     recordAheadClaim(blockId, claimedRev) {
-        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 } : {})
+        });
     }
     /**
      * Stamp {@link GetBlockResult.unconfirmedAheadRev} on an entry sitting behind an unsettled
@@ -372,11 +433,11 @@ export class CoordinatorRepo {
      * 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.
      */
     flagUnconfirmedCurrency(results, blockId, context) {
-        const claimedRev = this.unsettledAheadClaims.get(blockId);
+        const claimedRev = this.unsettledAheadClaims.get(blockId)?.rev;
         if (claimedRev === undefined)
             return;
         const entry = results[blockId];
@@ -386,7 +447,9 @@ export class CoordinatorRepo {
         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;
         }
@@ -582,7 +645,7 @@ export class CoordinatorRepo {
         }
         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
@@ -606,7 +669,8 @@ export class CoordinatorRepo {
      * 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`
@@ -652,11 +716,14 @@ export class CoordinatorRepo {
      * 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.
      */
     async queryClusterForLatest(peerIds, blockId, context) {
         // Query peers in parallel for their latest revision. Each query is DEADLINED (rejects), not
@@ -705,62 +772,278 @@ export class CoordinatorRepo {
             }
             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.)
+     *
+     * **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.
      *
-     * 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`.
+     * **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*).
+     */
+    reportRepairDeadlock(pass) {
+        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 = 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}).
      */
     penalizeContradictingRevClaims(claims, selected, blockId) {
-        if (!this.reputation)
+        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}`);
                 }
             }
@@ -769,6 +1052,22 @@ export class CoordinatorRepo {
             this.log('cluster-fetch:penalize-error', { blockId, error: err.message });
         }
     }
+    /**
+     * 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}.
+     */
+    penalizeProofService(peerId, blockId) {
+        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.message });
+        }
+    }
     async pend(request, options) {
         const allBlockIds = blockIdsForTransforms(request.transforms);
         await this.verifyResponsibility(allBlockIds);
@@ -783,10 +1082,13 @@ export class CoordinatorRepo {
             coordinatingBlockIds
         };
         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) {
@@ -799,7 +1101,29 @@ export class CoordinatorRepo {
                 });
                 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: [],
@@ -818,10 +1142,28 @@ export class CoordinatorRepo {
             // 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;
@@ -867,7 +1209,18 @@ export class CoordinatorRepo {
         // 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', {
@@ -893,6 +1246,56 @@ export class CoordinatorRepo {
         // confirmed number to report, and the field's contract forbids inferring one from that text.
         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.
+     */
+    async classifyPendingConflictRejection(error, request, blockIds) {
+        if (!(error instanceof ValidatorRejectionError))
+            return undefined;
+        let results;
+        try {
+            results = await this.storageRepo.get({ blockIds });
+        }
+        catch (readError) {
+            this.log('coordinator-repo:pend-conflict-classify-read-error', {
+                actionId: request.actionId,
+                error: readError.message
+            });
+            return undefined;
+        }
+        const pending = [];
+        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, options) {
         const blockIds = actionRef.blockIds;
         await this.verifyResponsibility(blockIds);
@@ -902,12 +1305,30 @@ export class CoordinatorRepo {
             expiration: options?.expiration ?? Date.now() + this.DEFAULT_TIMEOUT
         };
         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);
             }
@@ -932,8 +1353,41 @@ export class CoordinatorRepo {
             expiration: options?.expiration ?? Date.now() + this.DEFAULT_TIMEOUT
         };
         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 };
             }
@@ -970,9 +1424,143 @@ export class CoordinatorRepo {
         }
         catch (error) {
             this.log('coordinator-repo:commit-error', { actionId: request.actionId, error: 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.
+     */
+    async classifyCommitStaleRejection(error, request) {
+        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.
+     */
+    async confirmCommitRivalAgainstLocal(request) {
+        const blockIds = request.blockIds;
+        let results;
+        try {
+            results = await this.storageRepo.get({ blockIds });
+        }
+        catch (readError) {
+            this.log('coordinator-repo:commit-stale-classify-read-error', {
+                actionId: request.actionId,
+                error: readError.message
+            });
+            return undefined;
+        }
+        const reader = this.storageRepo;
+        // 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 = [];
+        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;
+            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.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