@optimystic/db-p2p 0.28.0 → 0.29.0

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

@@ -5,7 +5,7 @@ import { createLogger } from '../logger.js';
 import { PenaltyReason } from "../reputation/types.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 { DEFAULT_CLUSTER_SIZE, resolveRepairCorroborationClusterSize } 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 { buildBlockCommitProof } from "../cluster/commit-proof.js";
@@ -39,8 +39,11 @@ function cohortTooSmallMessage(cohortPeers, claimants, requiredEvenIfAllAnswered
         `${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 ` +
+        `apart: (1) the deployment really does run this few machines — set ` +
+        `clusterPolicy.repairCorroborationClusterSize to the number you actually run, which moves ONLY this ` +
+        `repair yardstick, or set clusterPolicy.assumedClusterSize, which moves it AND the membership ` +
+        `admission gate's low-confidence write floor (neither lowers 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 ` +
@@ -73,6 +76,78 @@ function soleHolderMessage(cohortPeers) {
         `second voter — reaching this message means the one holder attached no such proof, or one that did not ` +
         `verify.)`;
 }
+/**
+ * How many DISTINCT later actions one unchanged holder must refuse on a block before the refusals are
+ * named as a stuck reservation rather than as an ordinary lost race.
+ *
+ * **Why a count of distinct actions and not something else.** Elapsed time answers the wrong question
+ * — a slow writer is not a stuck one, and a holder legitimately keeps its reservation for as long as
+ * its own commit takes. A raw refusal count answers the wrong question too: a single writer retrying
+ * a lost race produces a run of refusals under ONE action id (see {@link StuckReservationWatch.refused}).
+ * What no healthy holder can produce is an unbounded stream of *different* writers all losing to it,
+ * because a healthy holder's reservation lasts one pend-to-commit window.
+ *
+ * **Why 8.** The bound to clear is how many distinct actions can honestly be refused inside one such
+ * window. Measured on the in-process mesh, in the healthy-contention arm of
+ * `test/stuck-reservation-named.spec.ts`: a holder that pends, is raced by other writers, and then
+ * commits refuses **2** distinct actions per episode — the two rivals — and the count resets on every
+ * holder change. `concurrent-diary-append-acknowledgement.spec.ts` races three writers at one diary
+ * and cannot exceed that either, for the same reason: at most (writers - 1) rivals can lose to one
+ * winner. 8 is four times the measured healthy figure, and it is a floor a genuinely stuck block
+ * clears trivially (the field instance refused hundreds).
+ *
+ * **The bound stated exactly.** It is distinct SYNC CYCLES, not distinct writers: one writer that
+ * exhausts a sync's retry budget and is re-driven by its caller mints a fresh id for the next cycle,
+ * so it can contribute more than one. That does not widen the window much — a cycle only ends in
+ * exhaustion after `DefaultMaxAttempts` (10) attempts of backoff, roughly 21s (see the exhaustion
+ * NOTE in `Collection.syncAttempts`), so a lone writer needs a holder to keep the block for upwards
+ * of two and a half minutes before it reaches 8 by itself, which is not a healthy holder.
+ *
+ * **What the margin does NOT cover, stated honestly.** A block with more than 8 distinct writers
+ * racing it inside a single pend-to-commit round trip could reach 8 with a perfectly healthy holder.
+ * That is a diagnostic false positive on a log line and nothing else — this counter never refuses,
+ * expires, or deletes anything (see {@link CoordinatorRepo.noteStuckReservation}) — and the remedy if
+ * a deployment ever hits it is to raise this number, not to add a control path. Raising it costs
+ * detection latency on low-traffic blocks, which need this many distinct write ATTEMPTS before the
+ * condition can be named at all.
+ */
+const STUCK_RESERVATION_DISTINCT_ACTIONS = 8;
+/** Whether two sorted holder lists name the same reservation — i.e. whether a refusal continues an
+ *  existing episode or starts a new one. Both sides come from the same sort, so this is a plain
+ *  element-wise comparison; a block normally has exactly one holder, since a member's own pend refuses
+ *  a second one (`ClusterMember.validatePendOperations`). */
+function sameHolders(a, b) {
+    return a.length === b.length && a.every((id, i) => id === b[i]);
+}
+/**
+ * The stuck-reservation wording: written for an operator reading logs, in the same register as
+ * {@link cohortTooSmallMessage} and {@link soleHolderMessage} — what is stuck, what will and will not
+ * clear it, and what to do next.
+ *
+ * The claim is deliberately about the RESERVATION, not about the writer's intent: this node cannot
+ * see whether the holding process is alive, only that it has held the block across enough unrelated
+ * later actions that no retry is going to win. So the line says what is provable (the block accepts
+ * no writes while this record stands, and nothing on the node removes it) and points at the one check
+ * that settles the rest.
+ */
+function stuckReservationMessage(holders, refusedActions) {
+    const held = holders.join(', ');
+    return `This block is WEDGED BEHIND A PENDING WRITE THAT IS NOT COMPLETING, and retrying will never ` +
+        `clear it: action(s) ${held} reserved the block and have now refused ${refusedActions} DISTINCT, ` +
+        `unrelated later actions. Each of those refusals on its own looks exactly like an ordinary ` +
+        `optimistic-concurrency loss, which is normal and healthy — the repetition is what is not. A ` +
+        `healthy rival holds a block only for its own pend-to-commit window and then releases it by ` +
+        `committing or cancelling; a reservation that keeps refusing NEW writers is holding the block ` +
+        `against every writer on every machine, and each of them loses again identically. EXACTLY TWO ` +
+        `THINGS CLEAR IT: a cancel for action(s) ${held} on this block (route it through the cohort so ` +
+        `every member drops the record), or that same action's own commit landing. Nothing on the node ` +
+        `expires it — there is no sweep for abandoned pending records — so until one of those two happens ` +
+        `the block takes NO writes while continuing to serve reads and to look healthy in every other ` +
+        `respect. The usual cause is a writer that went away between a failed or half-applied commit and ` +
+        `the cancel it owed, so check whether whatever ran ${held} still exists before cancelling on its ` +
+        `behalf. This line is a diagnosis and nothing more: this node does not expire, refuse, or delete ` +
+        `the record on the strength of it.`;
+}
 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, components.proofAnchoring);
 }
@@ -98,6 +173,29 @@ export class CoordinatorRepo {
      *  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);
+    /**
+     * Per block, what its pending-conflict refusals have added up to — see {@link StuckReservationWatch}
+     * and {@link noteStuckReservation}. Deliberately its OWN map rather than a third fact hung off
+     * {@link unsettledAheadClaims}: that entry belongs to the read-repair path and is cleared by a block
+     * converging on a revision, whereas this one belongs to the write path and is cleared by the block
+     * accepting a write. Sharing the entry would mean teaching both of those lifetimes about a fact
+     * neither owns (backlog `debt-freshness-state-scattered-across-coordinator-repo` is the standing
+     * argument for collapsing all of this per-block state behind one collaborator; adding a fourth
+     * carve-out to the freshness entry would have made that harder, not easier).
+     *
+     * NOTE: LRU-bounded like its siblings. An eviction under >1000 conflicted blocks loses an episode's
+     * say-once flag, so the line can repeat once for that block — the same bounded duplication
+     * {@link reportRepairDeadlock} accepts, and far cheaper than the unbounded silence it replaces.
+     *
+     * NOTE: per COORDINATOR, and a block's coordinator is whichever peer the writer's key lookup
+     * resolved — normally stable, but cohort churn or a routing change moves it. When it moves, the
+     * count restarts on the new coordinator (the condition is named later) and the old one may name the
+     * same episode again (the condition is named twice). Fine while a wedged block is diagnosed by
+     * searching for its id; if a churning deployment ever makes duplicate lines the noisy failure this
+     * one exists to replace, the say-once state has to move to where the record lives (the member's own
+     * storage) rather than to where the refusal was classified.
+     */
+    stuckReservations = new LruMap(1000);
     readRepairMode;
     readRepairWindowMs;
     readRepairSampleRate;
@@ -165,9 +263,11 @@ export class CoordinatorRepo {
         // unrepaired, degraded rather than dead, so there is no reason to relax it for a caller that
         // has not adopted the new field. A real node is handed an explicit
         // `repairCorroborationClusterSize` by `resolveClusterPolicy`; the `assumedClusterSize` middle
-        // term keeps direct constructors (embedders, existing tests) behaving as before.
-        this.repairCorroborationClusterSize =
-            cfg?.repairCorroborationClusterSize ?? policy.assumedClusterSize ?? policy.clusterSize;
+        // term keeps direct constructors (embedders, existing tests) behaving as before. The chain
+        // itself is `resolveClusterPolicy`'s own, called rather than restated so this manual-wiring
+        // path and the node assembly cannot drift on how much trust a lone peer gets — including on
+        // degenerate declarations, which fall through here exactly as they do there.
+        this.repairCorroborationClusterSize = resolveRepairCorroborationClusterSize(cfg?.repairCorroborationClusterSize, policy.assumedClusterSize, policy.clusterSize);
         this.reputation = reputation;
         const localClusterRef = localCluster && localPeerId ? {
             update: localCluster.update.bind(localCluster),
@@ -296,7 +396,7 @@ export class CoordinatorRepo {
                     });
                 }
                 try {
-                    const { absence, claimedAheadRev } = await this.fetchBlockFromCluster(blockId, blockGets.context, localRev);
+                    const { absence, currency } = await this.fetchBlockFromCluster(blockId, blockGets.context, localRev);
                     const refreshed = await this.storageRepo.get({ blockIds: [blockId], context: blockGets.context }, options);
                     const newRev = refreshed[blockId]?.state?.latest?.rev;
                     if (refreshed[blockId]) {
@@ -327,14 +427,19 @@ export class CoordinatorRepo {
                                 : 'peers-unreachable');
                     }
                     // A PRESENT block served below a cohort claim the repair could not settle is
-                    // the mirror lie: real content posing as confirmed-current. This consult is the
-                    // authority on that claim, so it replaces whatever an earlier one recorded —
-                    // including clearing it when nobody claims anything any more. The missing case
-                    // is excluded — it is the absence path above, and a bare absent below a claim
-                    // already reads as either authoritative (cohort answered, nothing corroborated)
-                    // or flagged.
+                    // the mirror lie: real content posing as confirmed-current. A consult that
+                    // REACHED THE CLAIMANTS is the authority on that claim, so it replaces whatever
+                    // an earlier one recorded — including clearing it when those peers claim nothing
+                    // any more. One that reached nobody (`currency.kind === 'no-evidence'` — no
+                    // cohort, solo-self, or total silence) refutes nothing, and neither does one
+                    // whose answers came from peers that never made the claim; `recordAheadClaim`
+                    // weighs the verdict's evidence against the recorded claimants, and only in the
+                    // direction that could hide a stale serve (a higher claim always lands). The missing
+                    // case is excluded — it is the absence path above, and a bare absent below a
+                    // claim already reads as either authoritative (cohort answered, nothing
+                    // corroborated) or flagged.
                     if (!isMissing) {
-                        this.recordAheadClaim(blockId, claimedAheadRev);
+                        this.recordAheadClaim(blockId, currency);
                         this.flagUnconfirmedCurrency(localResult, blockId, blockGets.context);
                     }
                 }
@@ -388,14 +493,78 @@ export class CoordinatorRepo {
         }
     }
     /**
-     * Remember (or forget) the cohort claim a freshness consult could not settle for a block.
-     * Only a consult that actually RAN may call this: it is the authority, so `undefined` clears
-     * a claim an earlier pass recorded. Entries are also dropped once this node reaches the
+     * Remember (or forget) the cohort claim a freshness consult could not settle for a block, per
+     * that consult's {@link CurrencyVerdict}. Entries are also dropped once this node reaches the
      * claimed revision (see {@link flagUnconfirmedCurrency}), which is what bounds the map.
+     *
+     * **The weakening rule, in one sentence.** A recorded claim may be WEAKENED — retired, or
+     * revised down to a lower revision — when at least one non-self cohort member answered this
+     * consult AND no peer that MADE the claim was silent in it. Everything else about the rule
+     * follows from that, and each of the three cases a claimant can be in has its own reason:
+     *
+     *  - A claimant that ANSWERED, on a consult that found nothing ahead of it, has retired its
+     *    own word. Its answer is evidence about its own claim — the only kind that counts.
+     *  - A claimant that was SILENT blocks weakening. Nobody else can speak for it; a peer that
+     *    never knew the claimed revision answering "I hold nothing" is not a refutation.
+     *  - A claimant that is NEITHER answered nor silent has left this node's cohort view:
+     *    `findCluster` no longer holds it responsible for the block, so its old word no longer
+     *    binds the current cohort. This is what BOUNDS the doubt — see the membership discussion
+     *    at `nothingAheadVerdict` in {@link fetchBlockFromCluster}.
+     *
+     * Note the arithmetic that makes it a one-liner: the non-self cohort IS `answered` ∪ `silent`,
+     * so "answered, or gone from the cohort" is exactly "not silent". No membership set has to be
+     * carried or diffed.
+     *
+     * RAISING a claim needs no licence — a higher claimed revision subsumes the one it replaces,
+     * so `flagUnconfirmedCurrency` stamps everything it used to and more. Only the weakening
+     * direction can hide a stale serve, which is why the gate below is one test applied to both
+     * shapes rather than a rule attached to retirement alone.
+     *
+     * Forgetting requires EVIDENCE. A consult that reached nobody (`no-evidence`) refutes nothing
+     * and leaves the memo exactly as it was. That used to be a rule the caller had to obey and
+     * could not: the old `claimedAheadRev: number | undefined` said the same thing for "peers
+     * refuted the claim" and for "nobody was asked", so every non-consulting exit silently erased
+     * the doubt and served stale content as confirmed-current. The verdict type states the
+     * difference instead, so a new exit cannot mean the wrong one by omission — and `nothing-ahead`
+     * now carries the evidence rather than a pre-baked refutation for the same reason, so a caller
+     * cannot assert a refutation it did not observe.
      */
-    recordAheadClaim(blockId, claimedRev) {
+    recordAheadClaim(blockId, currency) {
+        if (currency.kind === 'no-evidence')
+            return;
         const prior = this.unsettledAheadClaims.get(blockId);
-        if (claimedRev === undefined) {
+        const priorRev = prior?.rev;
+        // The one gate, applied to both shapes that can weaken a recorded claim: retiring it
+        // (`nothing-ahead`) and revising it down to a lower revision (`unsettled-claim` below
+        // `priorRev`) are the same act, and a lower claim replacing a higher one used to slip past
+        // the retirement rule and erase the higher claimant's word exactly as an unrelated peer's
+        // "I hold nothing" once did. Only the claimants' own silence protects their claim, though:
+        // everyone else's silence is irrelevant to it, and degrading this into "any silence blocks
+        // weakening" would flag a block forever behind one permanently unreachable cohort peer.
+        const weakensPrior = priorRev !== undefined
+            && (currency.kind === 'nothing-ahead' || currency.rev < priorRev);
+        if (weakensPrior) {
+            const silentClaimants = (prior?.claimants ?? []).filter(id => currency.silent.includes(id));
+            if (silentClaimants.length > 0) {
+                // The operator's only signal that a block's doubt CANNOT settle from this node's
+                // position: the peer that claimed the revision is unreachable, so every read of the
+                // block stays marked possibly-stale until it answers or leaves the cohort view.
+                // NOTE: emitted per pass, not say-once. In `lazy` mode `readRepairWindowMs` (10s
+                // default) rate-limits consults, so this is at most one line per window; in
+                // `paranoid` mode a consult runs on EVERY read and so this logs on every read. If
+                // that ever shows as noise, move it behind a say-once flag on the entry (beside
+                // `deadlocksReported`) rather than dropping the line — it is the only place the
+                // condition is named.
+                this.log('cluster-fetch:claim-unrefutable', { blockId, rev: priorRev, silentClaimants });
+                return; // the memo stands exactly as recorded
+            }
+        }
+        if (currency.kind === 'nothing-ahead') {
+            // Nothing recorded to retire, or a consult nobody outside this node answered — which
+            // `fetchBlockFromCluster` reports as `no-evidence` rather than this verdict, so the
+            // second test is the type's guarantee restated, not a reachable path.
+            if (priorRev === undefined || currency.answered.length === 0)
+                return;
             // 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
@@ -406,8 +575,23 @@ export class CoordinatorRepo {
                 this.unsettledAheadClaims.delete(blockId);
             return;
         }
+        // Repeated claims at the SAME revision accumulate claimants: pass 1 hears it from A, pass 2
+        // hears it from B while A is silent, and retiring later on B's answer alone would ignore A's
+        // still-unanswered word. A claim at a DIFFERENT revision replaces outright — a higher one
+        // subsumes the old, and a lower one has just passed the weakening gate above, so every peer
+        // that made the older claim has either answered this pass or left the cohort view.
+        // NOTE: the same-revision union never prunes, so a claimant that departed the cohort while
+        // the revision stayed stuck lingers in the list. Inert (a departed peer is never `silent`,
+        // so it never blocks weakening) and bounded per pass by cohort width, but across many passes
+        // with churn the list is bounded only by how many distinct peers ever claimed that exact
+        // revision. Prune against the pass's `answered` ∪ `silent` if a long-lived stuck block ever
+        // shows this entry growing.
+        const claimants = priorRev === currency.rev
+            ? [...new Set([...(prior?.claimants ?? []), ...currency.claimants])]
+            : [...currency.claimants];
         this.unsettledAheadClaims.set(blockId, {
-            rev: claimedRev,
+            rev: currency.rev,
+            claimants,
             ...(prior?.deadlocksReported ? { deadlocksReported: prior.deadlocksReported } : {})
         });
     }
@@ -490,6 +674,33 @@ export class CoordinatorRepo {
             this.lastSeenCommitMs.set(id, now);
         }
     }
+    /**
+     * True when a commit's approve votes form a strict majority of the FULL cohort — the only case
+     * where "this node committed" is evidence that no rival commit moved past it. Two strict
+     * majorities of one cohort must share a voter, so a rival that also reached a full-cohort
+     * majority would have surfaced here as a conflict vote instead of approving both. A commit below
+     * that bar — the solo short-circuit under a larger declared cohort, or a record that enrolled
+     * fewer than a full-cohort majority — rules nothing out; it still succeeds, it just must not arm
+     * the lazy read-repair window ({@link markBlocksSeen}), so the next read consults the cohort as
+     * if the commit had not happened.
+     *
+     * What it does NOT rule out, at any vote count: a rival that assembled its own quorum on a
+     * SHRUNKEN cohort view, which needs no full-cohort majority to complete
+     * ({@link clusterReachedCommitConsensus} accepts an enrolled-subset majority). Two commits that
+     * land at one revision on disjoint quorums are a fork, and healing one is
+     * `docs/partition-healing.md`'s business, not a freshness window's.
+     *
+     * Denominator: the full cohort, never the enrolled/reachable subset — `record.peers` is exactly
+     * the thing a downsize shrinks (contrast `clusterReachedCommitConsensus`, whose enrolled-subset
+     * majority answers "did consensus complete", a different question — leave it be).
+     * {@link repairCorroborationClusterSize} is the declared yardstick resolved for this same
+     * shrunken-view trap on the repair side, maxed with the observed cohort for the case where
+     * routing sees more peers than were declared.
+     */
+    commitQuorumRulesOutRivals(approvals, observedCohortSize) {
+        const fullCohortSize = Math.max(observedCohortSize, this.repairCorroborationClusterSize);
+        return approvals > fullCohortSize / 2;
+    }
     /**
      * Test seam: directly set the last-seen timestamp for a block. Used by read-repair
      * specs to simulate "the local commit happened at time T" without needing to drive
@@ -511,20 +722,34 @@ export class CoordinatorRepo {
      *    answer genuinely is the whole truth. When several verdicts apply at once the sharpest
      *    evidence wins: `claimed` > `isolated` > `unconfirmed` > `confirmed` — a peer positively
      *    saying "it exists" outranks any amount of silence.
-     *  - `claimedAheadRev` — a cohort peer claimed a revision strictly ahead of what this node
-     *    holds and the pass did NOT converge onto it: the claim failed the corroboration quorum,
-     *    or was corroborated but could not be acquired. Content `get` serves below this revision
-     *    cannot be confirmed current (see {@link GetBlockResult.unconfirmedAheadRev}); the claim
-     *    itself must never drive restoration.
+     *  - `currency` — the verdict on whether what this node holds is CURRENT (see
+     *    {@link CurrencyVerdict}). `unsettled-claim` means a cohort peer claimed a revision
+     *    strictly ahead of what this node holds and the pass did NOT converge onto it: the claim
+     *    failed the corroboration quorum, or was corroborated but could not be acquired. Content
+     *    `get` serves below that revision cannot be confirmed current (see
+     *    {@link GetBlockResult.unconfirmedAheadRev}); the claim itself must never drive
+     *    restoration. `nothing-ahead` and `no-evidence` differ in exactly one way that matters:
+     *    `nothing-ahead` carries the evidence that can retire an earlier pass's memo (and does
+     *    retire it when the memo's claimants are among the peers that answered), `no-evidence`
+     *    leaves it standing untouched. Required, not optional, so an exit added later has to say
+     *    which it means.
      */
     async fetchBlockFromCluster(blockId, context, localRev) {
         if (!this.clusterLatestCallback)
-            return { absence: 'confirmed' };
+            return { absence: 'confirmed', currency: { kind: 'no-evidence' } };
         const blockIdBytes = new TextEncoder().encode(blockId);
         const peers = await this.keyNetwork.findCluster(blockIdBytes);
         const peerIds = peers ? Object.keys(peers) : [];
+        // NOTE: deliberately does NOT call `markBlocksSeen` — unlike the solo-self exit below.
+        // An empty cohort is a ROUTING FAILURE, not a settled answer, and `Libp2pKeyPeerNetwork`
+        // cannot even produce one (its `findCluster` always includes self); the only producer
+        // today is the mesh harness's injected `findClusterFails`. Arming the read-repair window
+        // here would suppress a genuine repair for a whole `readRepairWindowMs` after a transient
+        // blip, and re-entering costs no network work beyond the `findCluster` the read already
+        // makes. Do not "fix" this by symmetry with the solo-self exit.
+        // Currency: nobody was asked, so nothing was refuted — an earlier pass's unsettled claim stands.
         if (peerIds.length === 0)
-            return { absence: 'confirmed' };
+            return { absence: 'confirmed', currency: { kind: 'no-evidence' } };
         // Solo-cluster short-circuit: the only responsible peer is us. There is no
         // remote to sync from, so skip the callback entirely. Querying ourselves
         // would dial self via SyncClient — pointless at best, and on nodes without
@@ -533,29 +758,119 @@ export class CoordinatorRepo {
             && this.localPeerId
             && peerIds[0] === this.localPeerId.toString()) {
             this.log('cluster-fetch:solo-self-skip', { blockId });
-            return { absence: 'confirmed' };
+            // Arm the lazy read-repair window. Without this the window is never stamped,
+            // `shouldReadRepair` reads `lastSeen == null` forever, and every read re-enters this
+            // exit — read -> stale -> consult -> solo skip -> no-op -> still stale, unbounded
+            // (GitHub issue #8: a solo node spent 47 minutes on a cold schema apply, logging 3,880
+            // triggers against 3,879 no-ops).
+            // What arming claims, precisely: NOT that this node has no rivals. A self-only cohort
+            // is also what `Libp2pKeyPeerNetwork.findCluster` returns while genuine same-network
+            // peers are still 'unknown' mid-identify (see its membership-scoping comment). It
+            // claims only that re-asking sooner than one window cannot learn anything the next
+            // `findCluster` would not, since this exit runs no other query — so a cohort that
+            // appears, grows, or finishes identifying is consulted within one `readRepairWindowMs`.
+            // NOTE: that self-heal delay IS `readRepairWindowMs` — 10s by default, well under
+            // bootstrap. If it is ever configured into the minutes, a cold node would serve
+            // unverified reads for that whole period; gate arming on cohort provenance if so.
+            // Deliberately opposite to the commit-side rule that withholds arming from a commit
+            // whose quorum proves nothing about rivals: that damps nothing, this bounds an
+            // otherwise unbounded loop. Landing both, keep both — see the specs for each.
+            this.markBlocksSeen([blockId]);
+            // Currency: this exit queried NOBODY, so it refutes nothing — an earlier pass's unsettled
+            // claim survives it. Note the coupling with the arming just above: retained doubt now
+            // persists for up to `readRepairWindowMs` before a consult can refute it. That is correct
+            // and deliberate — the window damps repair EFFORT, not honesty — and it is the same
+            // coupling the comment at the final exit below describes. Arming the window and keeping
+            // the memo are answers to different questions; do not collapse them.
+            return { absence: 'confirmed', currency: { kind: 'no-evidence' } };
         }
-        const { corroborated, local, silent, answered, uncorroboratedRev } = await this.queryClusterForLatest(peerIds, blockId, context);
+        const { corroborated, corroboration, local, silent, answered, claims, uncorroboratedRev, deadlock } = await this.queryClusterForLatest(peerIds, blockId, context);
         // Any silence taints the WHOLE consult, not a fraction of it (fail-closed): one silent
         // peer could be the sole holder, and the cost — an extra transactor-level retry against
         // another coordinator — is paid only while a peer is actually unreachable. Silence with
         // NOBODY else reached at all is its own verdict: partial silence says "ask a better-
         // connected coordinator", total silence says there is no better-informed answer to be
         // had from this node.
-        const silenceVerdict = silent.length > 0 ? (answered === 0 ? 'isolated' : 'unconfirmed') : 'confirmed';
-        // Nothing corroborated: keep local data AND stay eligible for repair — marking the
-        // block seen here would suppress the next attempt for the whole read-repair window.
+        const silenceVerdict = silent.length > 0 ? (answered.length === 0 ? 'isolated' : 'unconfirmed') : 'confirmed';
+        // The CURRENCY half's counterpart: the verdict to use at every exit that found nothing ahead.
+        // A consult that reached NOBODY outside this node refutes nothing, so a memo an earlier pass
+        // recorded must survive it. Keyed on `answered` (cohort members other than this node that
+        // answered at all) rather than on `silenceVerdict === 'isolated'`: the two agree in every
+        // reachable state — an empty `answered` with an EMPTY silent set would need a cohort of
+        // nothing but self, which the solo short-circuit above already took — but stating the rule
+        // in terms of "did anyone answer" says what it means without depending on that argument.
+        // Computed once here, like `silenceVerdict`, so it is stated in one place instead of
+        // re-derived at four `return`s.
+        //
+        // Deliberately NOT the same shape as `silenceVerdict` above, and no longer a defect that it
+        // is not: the two answer DIFFERENT QUESTIONS. `silenceVerdict` asks whether this pass saw
+        // the whole cohort, which partial silence answers "no" (fail-closed: one silent peer could
+        // be the sole holder of a block this node lacks entirely). This one carries EVIDENCE rather
+        // than a verdict, because whether an answer refutes anything depends on the claim being
+        // weighed: `recordAheadClaim` retires a memo only when a claimant answered and no claimant
+        // was silent. Do not "harmonize" them into one three-level verdict; and do not collapse this
+        // back to a bare `refuted`, which is what let a peer that never knew the claim retire it.
+        //
+        // **How doubt settles when a claimant never comes back — not a timer.** A permanently silent
+        // claimant would keep a block marked forever, so what bounds the doubt is COHORT MEMBERSHIP:
+        // `Libp2pKeyPeerNetwork.findCluster` builds `peerIds` from the live routing table, so a peer
+        // that is genuinely gone leaves the cohort view, stops appearing in `silent`, and stops
+        // blocking retirement. Two consequences, both accepted:
+        //  - If a dead peer never leaves the cohort view, the memo stands forever. That is a
+        //    membership defect to fix in the membership layer, not a licence to lie here — the block
+        //    genuinely IS possibly stale while a responsible cohort member holds a revision nobody
+        //    can obtain. `cluster-fetch:claim-unrefutable` (see `recordAheadClaim`) gives the
+        //    operator a name for it rather than erasing the doubt silently.
+        //  - A transiently-shrunken cohort view can retire a live claim early: `findCluster` never
+        //    admits a not-yet-identified peer, so one mid-identify is briefly absent and briefly
+        //    looks departed. Self-correcting — when it rejoins still holding the higher revision, the
+        //    next consult re-records the claim from its answer. One window of clean reads, versus the
+        //    permanent denial the alternative rule ("only a fully-answered cohort refutes") produces
+        //    from a single unreachable peer.
+        const nothingAheadVerdict = answered.length === 0 ? { kind: 'no-evidence' } : { kind: 'nothing-ahead', answered, silent };
+        /** The peers whose word this pass would be recording: those claiming at or above `rev`. A
+         *  claimant is who must later answer for the claim, so a peer claiming something LOWER is
+         *  not one — its answer says nothing about the revision in doubt. */
+        const claimantsAtOrAbove = (rev) => claims.filter(c => c.rev >= rev).map(c => c.peerId);
+        // Nothing corroborated: keep local data AND (usually) stay eligible for repair — marking the
+        // block seen suppresses the next attempt for the whole read-repair window, which is only
+        // right when re-asking sooner could not teach this node anything (see the `deadlock` arming
+        // below for the one decline where that is provable).
         // An uncorroborated claim strictly ahead of what this node holds still travels up as
         // doubt: the answer about to be served may be behind it, and only the caller knows
         // whether that matters for the view it was asked for.
         if (!corroborated) {
             const uncorroboratedBaseline = local?.rev ?? localRev;
-            const claimIsAhead = uncorroboratedRev !== undefined
-                && (uncorroboratedBaseline === undefined || uncorroboratedRev > uncorroboratedBaseline);
             // A claim — even one the quorum declined — is a peer positively attesting the block
             // exists, the sharpest fact this pass can surface. It outranks silence.
             const absence = uncorroboratedRev !== undefined ? 'claimed' : silenceVerdict;
-            return { absence, ...(claimIsAhead ? { claimedAheadRev: uncorroboratedRev } : {}) };
+            // A claim present but NOT ahead of the baseline falls to the shared verdict — which
+            // resolves to `nothing-ahead` in practice here, since `uncorroboratedRev` can only exist
+            // when a peer answered. Using the shared value anyway keeps the rule stated once.
+            const currency = uncorroboratedRev !== undefined
+                && (uncorroboratedBaseline === undefined || uncorroboratedRev > uncorroboratedBaseline)
+                ? { kind: 'unsettled-claim', rev: uncorroboratedRev, claimants: claimantsAtOrAbove(uncorroboratedRev), silent }
+                : nothingAheadVerdict;
+            // Arm the lazy read-repair window when — and only when — the decline is provably
+            // PERMANENT for the cohort-size reason: `cohort-too-small` means the cohort cannot field
+            // the quorum even if every member answered and agreed (an undeclared two-machine cohort
+            // against the default floor is the ordinary producer), so repeating the identical
+            // hopeless consult sooner than one window teaches nothing — the same justification the
+            // solo-self exit arms under. Every other decline stays unarmed, because there re-asking
+            // CAN genuinely learn: a silent peer can recover (and the verdict is never computed off a
+            // pass with silence — the guard in classifyRepairDeadlock is load-bearing here, not just
+            // for the log), a `sole-holder`'s missing copy can arrive (the cohort-growth push, or a
+            // commit), and a plain shortfall can fill. The doubt memo above is untouched either way:
+            // the window damps repair EFFORT, never honesty — reads inside it still carry
+            // `unconfirmedAheadRev` via flagUnconfirmedCurrency (pinned in
+            // coordinator-repo-small-cohort-arming.spec.ts). Note the verdict arrives on EVERY
+            // qualifying pass while the deadlock LOG stays once-per-episode — the split in
+            // reportRepairDeadlock is what lets the window re-arm after it expires without the log
+            // repeating.
+            if (deadlock === 'cohort-too-small') {
+                this.markBlocksSeen([blockId]);
+            }
+            return { absence, currency };
         }
         // The self answer is the sharper baseline (same storage, same context, read alongside the
         // cohort's), but it exists only when `findCluster` returned this node. A soft serve for a
@@ -568,18 +883,45 @@ export class CoordinatorRepo {
         // cohort that lags behind the reader corroborates an OLDER revision; adopting it
         // would be a regression, and logging it as a sync would be a lie. The cohort did
         // answer, so the block is verified fresh — mark it seen.
-        // NOTE: in a cohort of two, that sole peer is the only corroborator, so a lying one can park
-        // the reader here — corroborating the revision it already holds — and re-arm the lazy window
-        // on every pass, hiding a real divergence. Bounded by `readRepairWindowMs` (10s default) and
-        // no worse than the peer simply staying silent. If two-member cohorts become a supported
-        // production topology rather than a dev convenience, stop re-arming the window on a
-        // corroboration that came from a single voter.
+        // NOTE: accepted tradeoff — this arm arms the lazy window even when the corroboration came
+        // from a SINGLE voter (a two-member cohort's sole partner, or a single-signer certified
+        // claim). The once-proposed remedy — stop re-arming on a single-voter corroboration — was
+        // weighed and REJECTED when cohorts of one and two became supported production topology
+        // (ticket `small-cohort-arming-rule`), for three reasons:
+        //  1. Re-asking the sole partner sooner learns nothing: the repeat consult reaches the same
+        //     one peer, and a lying peer repeats the lie. Same justification as the solo-self exit —
+        //     not "the partner is trusted", but "a faster cadence cannot produce new evidence".
+        //  2. Not arming punishes only the honest: an honest partner corroborating "you are current"
+        //     is also a single voter, so refusing to arm makes every healthy two-machine cohort pay
+        //     one network round trip per read, forever, while buying zero protection against a
+        //     dishonest partner.
+        //  3. The residual threat is a WITHHOLDING attack, and no consult cadence or proof rule
+        //     touches it: a commit proof certifies "revision R was committed", nothing can certify
+        //     "no revision after R exists", so a sole partner withholding a newer revision is
+        //     indistinguishable from that revision never existing. Kept narrow by the commit rule —
+        //     a two-member commit needs BOTH members' signatures (super-majority and majority both
+        //     resolve to 2 of 2; ClusterMember.hasMajority) — so a revision the reader never
+        //     co-signed can exist only across the reader's own storage loss, or from a commit under
+        //     a different cohort shape (a partition-era solo commit, whose single-signer proof the
+        //     partner can present or withhold).
+        // What was bought instead is observability: `voters` (and `certified`) on the line below say
+        // when this node's currency rests on one peer's word, without re-deriving it from logs.
+        // Revisit only if a cadence-independent freshness signal (e.g. cross-cohort anchoring) ever
+        // exists to arm against — a shorter cadence alone can never be the fix, per reason 1.
         if (baselineRev !== undefined && corroborated.rev <= baselineRev) {
-            this.log('cluster-fetch:local-current', { blockId, localRev: baselineRev, clusterRev: corroborated.rev });
+            this.log('cluster-fetch:local-current', {
+                blockId, localRev: baselineRev, clusterRev: corroborated.rev,
+                voters: corroboration?.voters,
+                ...(corroboration?.certified ? { certified: true } : {})
+            });
             this.markBlocksSeen([blockId]);
             // Only reachable when this node HOLDS a revision (the baseline), so `get` never
             // consults this verdict — computed consistently rather than hard-coded.
-            return { absence: silenceVerdict };
+            // Currency: the cohort corroborated at or below what this node holds, so nothing is
+            // ahead. Only reachable when a peer answered (a corroboration requires claims), so the
+            // shared verdict resolves to `nothing-ahead` and a memo whose claimants are among those
+            // answers is cleared.
+            return { absence: silenceVerdict, currency: nothingAheadVerdict };
         }
         // Corroborated revision is ahead of ours — converge onto it.
         const rev = await this.restoreCorroborated(blockId, corroborated, baselineRev, peerIds);
@@ -614,7 +956,13 @@ export class CoordinatorRepo {
         // it ever shows as read amplification, gate the acquisition step (not the latest-query) on the
         // same window rather than widening `isMissing`.
         this.markBlocksSeen([blockId]);
-        return { absence, ...(converged ? {} : { claimedAheadRev: corroborated.rev }) };
+        // Converged: the corroboration is itself the evidence that nothing is ahead, and it came from
+        // peers that answered — the shared verdict resolves to `nothing-ahead`, and the memo retires
+        // if its claimants are among those peers.
+        const currency = converged
+            ? nothingAheadVerdict
+            : { kind: 'unsettled-claim', rev: corroborated.rev, claimants: claimantsAtOrAbove(corroborated.rev), silent };
+        return { absence, currency };
     }
     /**
      * Bring this node up to the cohort-corroborated `corroborated`, returning the revision it holds
@@ -749,8 +1097,16 @@ export class CoordinatorRepo {
         // make self report something the reader does not hold, make `localPeerId` required instead.
         // The same unset-`localPeerId` tolerance also lets self count toward `answered` below, and
         // lets a self read that REJECTS land in `silent`: a solo repo whose own storage throws then
-        // reads as `answered === 0` and reports isolation ('cohort-unreachable') rather than a local
-        // fault. Same fix if it ever matters — require `localPeerId`.
+        // reads as an EMPTY `answered` and reports isolation ('cohort-unreachable') rather than a
+        // local fault. Same fix if it ever matters — require `localPeerId`.
+        // What this tolerance no longer does is let this node erase its own doubt. `answered` used
+        // to be a bare count, so an unset `localPeerId` on a self-only-answering pass reached
+        // "somebody answered, nothing is ahead" off this node's own answer and dropped the memo —
+        // the exact erasure the marker exists to prevent. Claim PROVENANCE closes it without
+        // touching the constructor: the claimant recorded is the remote peer that reported the
+        // revision (never self, whose answer reads the storage being repaired, per the argument
+        // above), so when that peer goes silent it is a silent claimant and the memo stands. This
+        // node agreeing with itself retires nothing.
         const selfId = this.localPeerId?.toString();
         let local;
         const claims = [];
@@ -825,7 +1181,10 @@ export class CoordinatorRepo {
             }
         }));
         const nonSelfCount = peerIds.filter(id => id !== selfId).length;
-        const answered = nonSelfCount - silent.length;
+        // Identities, not a count: the caller matches a memo's recorded claimants against who spoke
+        // this pass. `answered` and `silent` partition the non-self cohort view, so the old
+        // `nonSelfCount - silent.length` is exactly `answered.length`.
+        const answered = peerIds.filter(id => id !== selfId && !silent.includes(id));
         const capacity = corroboratorCapacity(nonSelfCount, this.repairCorroborationClusterSize);
         const required = quorumSize(claims.length, this.simpleMajorityThreshold, capacity);
         const selected = selectQuorumRev(claims, this.simpleMajorityThreshold, capacity);
@@ -849,15 +1208,17 @@ export class CoordinatorRepo {
                 blockId,
                 cohortPeers: nonSelfCount,
                 holders: claims.length,
-                absent: answered - claims.length,
+                absent: answered.length - 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
+            // in words — and return the verdict, which the caller acts on EVERY pass (arming the
+            // read-repair window on `cohort-too-small`; see fetchBlockFromCluster). The `no-quorum`
+            // line above fires on every pass and cannot tell the two apart.
+            const deadlock = this.reportRepairDeadlock({
+                blockId, claims, silentCount: silent.length, cohortPeers: nonSelfCount, answered: answered.length, 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
@@ -873,7 +1234,11 @@ export class CoordinatorRepo {
             // (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 } : {}) };
+            return {
+                local, silent, answered, claims,
+                ...(uncorroboratedRev !== undefined ? { uncorroboratedRev } : {}),
+                ...(deadlock !== undefined ? { deadlock } : {})
+            };
         }
         if (selected.certified) {
             // Which rule won matters when reading a repair log: a certified selection may rest on a
@@ -887,12 +1252,26 @@ export class CoordinatorRepo {
         // 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 };
+        return {
+            corroborated: { actionId: selected.actionId, rev: selected.rev },
+            // The supporters used to be dropped on the floor here, leaving "how many peers this
+            // currency judgment rests on" underivable downstream — see ClusterLatestQuery.corroboration.
+            corroboration: {
+                voters: selected.supporters.length,
+                ...(selected.certified ? { certified: true } : {})
+            },
+            local, silent, answered, claims
+        };
     }
     /**
      * 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:
+     * transient shortage of answers — and RETURN the verdict, computed fresh on every pass by
+     * {@link classifyRepairDeadlock} (the pure half; the say-once suppression below applies only to
+     * the log line). The caller acts on the returned reason every pass: `fetchBlockFromCluster` arms
+     * the lazy read-repair window on `cohort-too-small`, because a decline the cohort provably cannot
+     * escape teaches nothing when repeated sooner than one window. 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.
@@ -946,44 +1325,15 @@ export class CoordinatorRepo {
      * `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 { blockId, claims, cohortPeers, answered, required, capacity } = pass;
+        const reason = this.classifyRepairDeadlock(pass);
+        if (reason === undefined)
+            return undefined;
+        // From here down is LOGGING only, under the once-per-episode suppression. The verdict above
+        // is returned regardless: the caller arms the read-repair window off it on every qualifying
+        // pass (a window that expired must re-arm), and letting the say-once flag swallow the verdict
+        // would arm exactly once per episode — one quiet window, then the re-ask-forever loop back.
         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
@@ -991,7 +1341,7 @@ export class CoordinatorRepo {
         // 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;
+            return reason;
         this.log('cluster-fetch:repair-deadlock', {
             blockId,
             reason,
@@ -1001,7 +1351,7 @@ export class CoordinatorRepo {
             required,
             requiredEvenIfAllAnswered,
             repairCorroborationClusterSize: this.repairCorroborationClusterSize,
-            message: cohortTooSmall
+            message: reason === 'cohort-too-small'
                 ? cohortTooSmallMessage(cohortPeers, claims.length, requiredEvenIfAllAnswered, this.repairCorroborationClusterSize)
                 : soleHolderMessage(cohortPeers)
         });
@@ -1015,6 +1365,73 @@ export class CoordinatorRepo {
         // 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] });
+        return reason;
+    }
+    /**
+     * The PURE half of {@link reportRepairDeadlock}: classify one declining pass as provably
+     * permanent (`cohort-too-small` / `sole-holder`) or not (`undefined`), with no logging and no
+     * state. Split out so the verdict can run on EVERY pass — the caller in
+     * `fetchBlockFromCluster` arms the lazy read-repair window off `cohort-too-small` each time,
+     * and the window has to re-arm after it expires — while the log line keeps its once-per-episode
+     * suppression. Before the split the verdict was computed for the log line and thrown away,
+     * which is what left an undeclared two-machine cohort re-running the provably hopeless consult
+     * on every read (measured: 6 peer queries across three reads inside one 10 s window, versus 0
+     * with the size declared).
+     *
+     * The guards are part of the VERDICT, not merely of the logging — the arming consumer depends
+     * on both:
+     *  - a pass with ANY silent peer proves nothing (an incomplete picture — the silent peer could
+     *    recover, so re-asking can learn; and permanent claims are not made off partial views);
+     *  - a pass with ZERO claims is an agreed absence — an answer, not a deadlock.
+     */
+    classifyRepairDeadlock(pass) {
+        const { claims, silentCount, cohortPeers, answered, capacity } = pass;
+        // An incomplete picture proves nothing about the deployment; the next clean pass says it.
+        if (silentCount > 0)
+            return undefined;
+        // Nobody claimed anything: the cohort agrees the block is absent, which is an answer, not a
+        // deadlock.
+        if (claims.length === 0)
+            return undefined;
+        // 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. (`sole-holder` never arms the read-repair window — the missing thing
+        // is a COPY, which the cohort-growth push or the next commit can deliver at any moment, so
+        // re-asking can genuinely learn.)
+        const soleHolder = claims.length === 1 && answered === cohortPeers;
+        if (!cohortTooSmall && !soleHolder)
+            return undefined;
+        // Both shapes hold at once whenever `cohortTooSmall` does — not merely "can". At the fixed
+        // simple-majority term (0.51) the proportional quorum never exceeds the peer count, so
+        // `cohortTooSmall` reduces to exactly ONE non-self cohort peer with the resolved size at three
+        // or more; combined with the guards above (nobody silent, somebody claimed) that peer is also
+        // the only claimant and everybody answered, which is `soleHolder`. So this precedence is
+        // load-bearing on every cohort-too-small pass, not a rare tie-break — and it is what keeps the
+        // ARMING consumer keyed on the reason that means "no cadence can help" rather than on the one
+        // that means "a copy has not arrived yet".
+        // `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.
+        return cohortTooSmall ? 'cohort-too-small' : 'sole-holder';
     }
     /**
      * Report peers whose reported latest PROVABLY contradicts a CORROBORATED selection: the same
@@ -1084,6 +1501,21 @@ export class CoordinatorRepo {
     async pend(request, options) {
         const allBlockIds = blockIdsForTransforms(request.transforms);
         await this.verifyResponsibility(allBlockIds);
+        const result = await this.pendThroughCluster(request, allBlockIds, options);
+        // A pend the blocks ACCEPTED is the proof that no reservation is holding them any more — the
+        // only such proof this node gets without asking a question it has no reason to ask.
+        // Scope, honestly: this is NOT what re-arms the line for a later wedge. The holder comparison
+        // in `noteStuckReservation` already does that on its own, and every real holder set is new,
+        // since an action id is 16 random bytes minted per sync cycle (`Collection.syncInternal`). What
+        // forgetting buys is that a settled episode stops occupying an LRU slot it can only use to
+        // evict a live one — plus defence in depth if an action id ever does repeat.
+        if (result.success)
+            this.clearStuckReservations(allBlockIds);
+        return result;
+    }
+    /** The cluster half of {@link pend}, after responsibility is verified: consensus, the local-verdict
+     *  arms, and the two optimistic-concurrency classifiers a rejection is run through. */
+    async pendThroughCluster(request, allBlockIds, options) {
         const coordinatingBlockIds = options?.coordinatingBlockIds ?? allBlockIds;
         const peerCount = await this.coordinator.getClusterSize(coordinatingBlockIds[0]);
         if (peerCount <= 1) {
@@ -1298,9 +1730,21 @@ export class CoordinatorRepo {
         }
         if (pending.length === 0)
             return undefined;
+        // Counted as its own statement, never inside the log payload below: this call is the detection
+        // mechanism, not a formatting step, and payload expressions in this repo are fair game to wrap
+        // in an `enabled` gate (`Collection.advanceContext` does exactly that). A gate added there
+        // later would silently stop the counter and with it `coordinator-repo:stuck-reservation`.
+        // {@link reportRepairDeadlock} keeps its say-once bookkeeping outside its own log call for the
+        // same reason.
+        const distinctRefusedActions = this.noteStuckReservation(pending, request.actionId);
         this.log('coordinator-repo:pend-conflict-classified', {
             actionId: request.actionId,
-            rivals: pending.map(p => `${p.blockId}:${p.actionId}`)
+            rivals: pending.map(p => `${p.blockId}:${p.actionId}`),
+            // How many distinct actions the most-refusing of this request's holders has now turned away
+            // (see {@link noteStuckReservation}). Carried on every classification, not just the stuck
+            // ones, so a healthy contended deployment's real figure is readable from its own logs rather
+            // than assumed — which is what calibrates STUCK_RESERVATION_DISTINCT_ACTIONS.
+            distinctRefusedActions
         });
         return {
             success: false,
@@ -1309,6 +1753,111 @@ export class CoordinatorRepo {
             reason: `pending conflict: block(s) held by unresolved rival action(s) ${[...new Set(pending.map(p => p.actionId))].join(', ')}`
         };
     }
+    /**
+     * Count one confirmed pending-conflict refusal against the holder(s) of each block it names, and say
+     * ONCE — in words, at the moment it becomes provable — when a block is wedged behind a reservation
+     * that is not going to clear.
+     *
+     * **Why this needs saying at all.** Every individual refusal here is indistinguishable from an
+     * ordinary lost race, which is a normal and healthy event, so the logs of a permanently wedged block
+     * read exactly like the logs of a busy one. Finding the difference today means noticing that the
+     * SAME rival action id keeps appearing across unrelated writers for as long as the process lives —
+     * a pattern nothing points at, and one that cost a downstream project several tickets and weeks to
+     * re-derive from raw traces. The node has the fact in hand at every refusal; this makes it sayable.
+     *
+     * **The signal, and the two things that are NOT the signal.** The discriminator is repetition
+     * against an unchanged holder — see {@link STUCK_RESERVATION_DISTINCT_ACTIONS} for why distinct
+     * refused actions is the right counter and for the measured threshold. Two cheaper-looking tests
+     * were tried and do not work: the members' in-memory reservation table
+     * (`ClusterMember.activeTransactions`) clears the moment a rival's pend reaches consensus, so a
+     * perfectly healthy rival inside its pend-to-commit window is absent from it too and absence there
+     * says nothing; and "the block already passed this pending record's revision" catches a different
+     * orphan class entirely — in the verified instance the wedged block sat at revision 1 while the
+     * orphaned record was for revision 2, still nominally promotable.
+     *
+     * **Never a control path.** This classifies and logs; it never refuses, expires, or deletes
+     * anything. Deciding when a durable pending record may be removed is precisely the hard problem
+     * backlog `debt-unpromotable-pending-records-need-a-sweep` exists for — deleting a live reservation
+     * is worse than the leak — and a counter accurate enough for a log line is not evidence enough to
+     * destroy state.
+     *
+     * Returns the highest distinct-refusal count any of this refusal's blocks has now reached, for the
+     * classification line to carry; it saturates at the threshold once an episode has been reported,
+     * since the ids are dropped at that point.
+     *
+     * NOTE: fed only by {@link classifyPendingConflictRejection}, i.e. by refusals that arrive as a
+     * cohort-wide validator rejection. A block only PART of whose cohort holds the stranded record can
+     * still reach approval super-majority, and its refusal then comes back through the retained local
+     * apply verdict (`getExecutedPendResult`) instead, which this never sees — so a partially wedged
+     * block goes unnamed. That is the weaker condition (the write does land on the healthy members),
+     * and instrumenting the second path would count a refusal that the cohort as a whole did not make.
+     * If partial strands ever turn out to be the common shape in the field, the counter belongs on the
+     * member side (`ClusterMember.validatePendOperations`), where each member sees its own votes.
+     */
+    noteStuckReservation(pending, refusedActionId) {
+        const rivalsByBlock = new Map();
+        for (const { blockId, actionId } of pending) {
+            const rivals = rivalsByBlock.get(blockId);
+            if (rivals)
+                rivals.push(actionId);
+            else
+                rivalsByBlock.set(blockId, [actionId]);
+        }
+        let highest = 0;
+        for (const [blockId, rivals] of rivalsByBlock) {
+            const holders = [...new Set(rivals)].sort();
+            const prior = this.stuckReservations.get(blockId);
+            // A different holder set is a DIFFERENT episode — the block changed hands, which is the
+            // healthy cycle — so the count starts over and the new holder gets its own chance to speak.
+            const watch = prior !== undefined && sameHolders(prior.holders, holders)
+                ? prior
+                : { holders, refused: new Set(), reported: false };
+            if (watch !== prior)
+                this.stuckReservations.set(blockId, watch);
+            if (watch.reported) {
+                highest = Math.max(highest, STUCK_RESERVATION_DISTINCT_ACTIONS);
+                continue;
+            }
+            watch.refused.add(refusedActionId);
+            highest = Math.max(highest, watch.refused.size);
+            if (watch.refused.size < STUCK_RESERVATION_DISTINCT_ACTIONS)
+                continue;
+            this.log('coordinator-repo:stuck-reservation', {
+                blockId,
+                // The ids an operator needs to grep for and to cancel, kept as data beside the prose so a
+                // log search finds the block and the action without parsing English.
+                holdingActionIds: holders,
+                distinctRefusedActions: watch.refused.size,
+                message: stuckReservationMessage(holders, watch.refused.size)
+            });
+            watch.reported = true;
+            // Said once per episode: from here the flag alone suppresses, and the ids have done their
+            // work (their count is in the line above), so drop them rather than growing a set for the
+            // unbounded remainder of a permanent condition.
+            watch.refused.clear();
+        }
+        return highest;
+    }
+    /**
+     * Forget any stuck-reservation episode recorded for these blocks, optionally only when
+     * `holderActionId` is one of the actions that episode named.
+     *
+     * Called from the two events the message itself names as the only cures: a write the block accepted
+     * ({@link pend}), and a cancel for the holding action ({@link cancel}). Forgetting is the whole
+     * effect, and it is LRU hygiene rather than behaviour: a later wedge is named by a DIFFERENT holder,
+     * which `noteStuckReservation`'s holder comparison already treats as a new episode whether the old
+     * entry is still there or not. Both call sites therefore have no observable effect through the
+     * public surface (no spec can distinguish them — reproducing a repeated holder set would mean
+     * reusing an action id, which nothing that mints them does), and both are kept because a settled
+     * episode holding an LRU slot can only evict a live one.
+     */
+    clearStuckReservations(blockIds, holderActionId) {
+        for (const blockId of blockIds) {
+            if (holderActionId !== undefined && !this.stuckReservations.peek(blockId)?.holders.includes(holderActionId))
+                continue;
+            this.stuckReservations.delete(blockId);
+        }
+    }
     async cancel(actionRef, options) {
         const blockIds = actionRef.blockIds;
         await this.verifyResponsibility(blockIds);
@@ -1345,6 +1894,11 @@ export class CoordinatorRepo {
             if (!anyLocalExecuted) {
                 await this.storageRepo.cancel(actionRef, options);
             }
+            // The remedy a stuck-reservation line names, actually taken: the record this node was
+            // complaining about is gone, so forget the episode and let a LATER wedge on the same block
+            // speak. Scoped to the cancelled action — a cancel for some OTHER action says nothing about
+            // the reservation that is holding these blocks.
+            this.clearStuckReservations(blockIds, actionRef.actionId);
         }
         catch (error) {
             this.log('coordinator-repo:cancel-error', { actionId: actionRef.actionId, error: error.message });
@@ -1388,7 +1942,14 @@ export class CoordinatorRepo {
             // ICommitProofPersister contract; a plain IRepo double ignores the extra argument.
             const proof = await this.localCluster?.mintSoloCommitProof?.(message);
             const result = await this.storageRepo.commit(request, options, proof);
-            if (result.success)
+            // One self-approval arms the read-repair window only where the DECLARED cohort is also one
+            // — then no rival quorum can exist to be missed. At any larger declared size (including
+            // an undeclared one, which resolves to the replication factor, and including degraded
+            // routing where peerCount is 0) this commit proves nothing about rival quorums — see
+            // commitQuorumRulesOutRivals — so the window stays unarmed and the read path's
+            // solo-self-skip exit re-arms it once per consult instead (which keeps GitHub issue #8's
+            // consult storm bounded at one per window).
+            if (result.success && this.commitQuorumRulesOutRivals(1, peerCount))
                 this.markBlocksSeen(blockIds);
             return result;
         }
@@ -1398,6 +1959,14 @@ export class CoordinatorRepo {
         };
         try {
             const { record, localExecuted, localCommitResult } = await this.coordinator.executeClusterTransaction(blockIds[0], message, options);
+            // Decided once for every success shape below (local-executed, local fallback, tolerated
+            // divergence): whether this commit's quorum is freshness evidence or merely a commit.
+            // NOTE: one verdict covers every block in `blockIds`, though it is measured against
+            // `blockIds[0]`'s cohort alone. Consistent with the rest of this path — consensus for the
+            // whole commit runs on that one cohort — so a per-block verdict would be measuring a
+            // quorum that never voted. If commits ever coordinate per-block cohorts separately (see
+            // `debt-sender-side-coordinating-block-binding-is-unchecked`), this must follow them.
+            const armFreshness = this.commitQuorumRulesOutRivals(countApprovingCommitVotes(record), peerCount);
             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
@@ -1432,7 +2001,8 @@ export class CoordinatorRepo {
                         reason: localCommitResult.reason
                     });
                 }
-                this.markBlocksSeen(blockIds);
+                if (armFreshness)
+                    this.markBlocksSeen(blockIds);
                 return { success: true };
             }
             // Local cluster didn't execute during consensus. Attempt a local commit, but tolerate
@@ -1461,17 +2031,18 @@ export class CoordinatorRepo {
             try {
                 const result = await this.storageRepo.commit(request, options, consensusProof);
                 if (result.success) {
-                    this.markBlocksSeen(blockIds);
+                    if (armFreshness)
+                        this.markBlocksSeen(blockIds);
                     return result;
                 }
                 if (isMissingBaseRevisionFailure(result) && clusterReachedCommitConsensus(record)) {
-                    return this.tolerateLocalCommitDivergence(request, blockIds, result.reason ?? MISSING_BASE_REVISION_REASON);
+                    return this.tolerateLocalCommitDivergence(request, blockIds, result.reason ?? MISSING_BASE_REVISION_REASON, armFreshness);
                 }
                 return result;
             }
             catch (err) {
                 if (clusterReachedCommitConsensus(record)) {
-                    return this.tolerateLocalCommitDivergence(request, blockIds, err.message);
+                    return this.tolerateLocalCommitDivergence(request, blockIds, err.message, armFreshness);
                 }
                 throw err;
             }
@@ -1616,13 +2187,18 @@ export class CoordinatorRepo {
         };
     }
     /**
-     * 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
-     * from replication (cohort reconcile, or read-driven acquisition), not from replay here.
+     * Report success for a commit the cluster carried but this peer could not apply locally.
+     * Convergence comes from replication (cohort reconcile, or read-driven acquisition), not from
+     * replay here. `armFreshness` says whether the commit's quorum was strong enough
+     * ({@link commitQuorumRulesOutRivals}) for the read path to treat the blocks as
+     * freshness-checked; a divergence tolerated on a downsized quorum leaves the window unarmed —
+     * this peer is known to be behind here, the last place a self-referential freshness stamp
+     * belongs.
      */
-    tolerateLocalCommitDivergence(request, blockIds, detail) {
+    tolerateLocalCommitDivergence(request, blockIds, detail, armFreshness) {
         this.log('coordinator-repo:commit-local-failed-cluster-succeeded', { actionId: request.actionId, error: detail });
-        this.markBlocksSeen(blockIds);
+        if (armFreshness)
+            this.markBlocksSeen(blockIds);
         return { success: true };
     }
 }
@@ -1631,7 +2207,10 @@ function clusterReachedCommitConsensus(record) {
     const peerCount = Object.keys(record.peers).length;
     if (peerCount === 0)
         return false;
-    const approvedCommits = Object.values(record.commits).filter(s => s.type === 'approve').length;
-    return approvedCommits > peerCount / 2;
+    return countApprovingCommitVotes(record) > peerCount / 2;
+}
+/** Approve-typed commit votes on a consensus record — the numerator `commitQuorumRulesOutRivals` measures against the full cohort. */
+function countApprovingCommitVotes(record) {
+    return Object.values(record.commits).filter(s => s.type === 'approve').length;
 }
 //# sourceMappingURL=coordinator-repo.js.map