@optimystic/db-p2p 0.21.0 → 0.24.0

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

@@ -1,12 +1,12 @@
 import { LruMap, blockIdsForTransforms, highestStaleAt, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
-import { ClusterCoordinator, ValidatorRejectionError } from "./cluster-coordinator.js";
+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 { 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";
-const log = createLogger('coordinator-repo');
 /** How long one cohort peer gets to answer the latest-revision consult before it counts as silent. */
 const LATEST_QUERY_TIMEOUT_MS = 1000;
 /** True when a freshly-read local revision is strictly ahead of the baseline the repair started from. */
@@ -43,6 +43,13 @@ export class CoordinatorRepo {
     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.
+     *  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). */
+    unsettledAheadClaims = new LruMap(1000);
     readRepairMode;
     readRepairWindowMs;
     readRepairSampleRate;
@@ -58,6 +65,8 @@ export class CoordinatorRepo {
     /** Resolved super-majority threshold the coordinator commits on (mirrors the value handed to ClusterCoordinator). */
     superMajorityThreshold;
     reputation;
+    /** Per-instance logger, namespaced by peer id when `localPeerId` is known (degrades to the un-suffixed namespace when not — the single-node/test construction has always tolerated its absence). */
+    log;
     /** Test seam: overridable clock for window-based read-repair gating. */
     now = () => Date.now();
     /** Test seam: overridable RNG (0..1) for sample-rate gating. */
@@ -69,8 +78,12 @@ export class CoordinatorRepo {
         this.clusterLatestCallback = clusterLatestCallback;
         this.acquireBlockFromCohort = acquireBlockFromCohort;
         this.localPeerId = localPeerId;
+        this.log = createLogger('coordinator-repo', localPeerId?.toString());
         const policy = {
-            clusterSize: cfg?.clusterSize ?? 10,
+            // Same constant `resolveClusterPolicy` gives a node that declares no clusterSize, not a
+            // second literal: a direct constructor (the readme's manual-wiring path) and the node
+            // assembly must land on the same width or the two disagree about the same key's cohort.
+            clusterSize: cfg?.clusterSize ?? DEFAULT_CLUSTER_SIZE,
             assumedClusterSize: cfg?.assumedClusterSize,
             superMajorityThreshold: cfg?.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD,
             simpleMajorityThreshold: cfg?.simpleMajorityThreshold ?? 0.51,
@@ -146,12 +159,12 @@ export class CoordinatorRepo {
             inCluster = this.localPeerId.toString() in peers;
         }
         catch (err) {
-            log('proximity:check-error', { blockId, error: err.message });
+            this.log('proximity:check-error', { blockId, error: err.message });
             // On failure, assume responsible to avoid false rejections
             return true;
         }
         this.responsibilityCache.set(blockId, { inCluster, expires: Date.now() + CoordinatorRepo.RESPONSIBILITY_TTL_MS });
-        log('proximity:checked', { blockId, inCluster });
+        this.log('proximity:checked', { blockId, inCluster });
         return inCluster;
     }
     /**
@@ -165,7 +178,7 @@ export class CoordinatorRepo {
             }
         }
         if (notResponsible.length > 0) {
-            log('proximity:rejected', { blockIds: notResponsible });
+            this.log('proximity:rejected', { blockIds: notResponsible });
             throw new Error(`Not responsible for block(s): ${notResponsible.join(', ')}`);
         }
     }
@@ -180,7 +193,7 @@ export class CoordinatorRepo {
         // isResponsibleForBlock.
         for (const blockId of blockGets.blockIds) {
             if (!await this.isResponsibleForBlock(blockId)) {
-                log('proximity:get-warning', { blockId, msg: 'serving read for non-responsible block' });
+                this.log('proximity:get-warning', { blockId, msg: 'serving read for non-responsible block' });
             }
         }
         // First try local storage
@@ -197,8 +210,9 @@ export class CoordinatorRepo {
         // NOTE: NetworkTransactor.get treats an authoritative "absent" ({ state: {} })
         // as final and no longer retries it (ticket txn-perf-authoritative-notfound),
         // relying on this cluster reconciliation to have already run. When the consult
-        // FAILS outright — or runs while part of the cohort stays SILENT and the block
-        // stays missing — the entry is flagged `unavailable: 'peers-unreachable'` below,
+        // FAILS outright — or runs without ruling the block out and the block stays
+        // missing — the entry is flagged `unavailable` below with a reason naming what
+        // the consult established (see AbsenceVerdict and the mapping in the loop body),
         // which re-enables the transactor-level retry against a different peer. If a
         // coordinator is configured WITHOUT clusterLatestCallback, there is no cohort to
         // consult and the local answer IS the whole truth — it stays authoritative, with
@@ -211,10 +225,18 @@ export class CoordinatorRepo {
                 const localRev = localEntry?.state?.latest?.rev;
                 const isMissing = !localEntry?.state?.latest;
                 const isStale = !isMissing && this.shouldReadRepair(blockId);
-                if (!isMissing && !isStale)
+                if (!isMissing && !isStale) {
+                    // No consult this pass — the read-repair window says this block was checked
+                    // recently. An unsettled claim an earlier pass recorded still applies: the doubt
+                    // is a property of what this node HOLDS, not of whether a consult just ran.
+                    // Without this, every read inside the window after a failed convergence would
+                    // serve the same content as confirmed — the exact silent lie this marker exists
+                    // to end, re-opened for `readRepairWindowMs` at a time.
+                    this.flagUnconfirmedCurrency(localResult, blockId, blockGets.context);
                     continue;
+                }
                 if (isStale) {
-                    log('cluster-tx:read-repair-triggered', {
+                    this.log('cluster-tx:read-repair-triggered', {
                         blockId,
                         mode: this.readRepairMode,
                         ageMs: this.ageMs(blockId),
@@ -222,7 +244,7 @@ export class CoordinatorRepo {
                     });
                 }
                 try {
-                    const { inconclusive } = await this.fetchBlockFromCluster(blockId, blockGets.context, localRev);
+                    const { absence, claimedAheadRev } = 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]) {
@@ -230,27 +252,56 @@ export class CoordinatorRepo {
                     }
                     if (isStale) {
                         if (typeof newRev === 'number' && typeof localRev === 'number' && newRev > localRev) {
-                            log('cluster-tx:read-repair-applied', { blockId, oldRev: localRev, newRev });
+                            this.log('cluster-tx:read-repair-applied', { blockId, oldRev: localRev, newRev });
                         }
                         else {
-                            log('cluster-tx:read-repair-noop', { blockId });
+                            this.log('cluster-tx:read-repair-noop', { blockId });
                         }
                     }
-                    // The consult ran but came back INCONCLUSIVE (a silent cohort peer, or a
-                    // corroborated revision this node could not acquire — see
-                    // fetchBlockFromCluster). Either way the reader cannot rule the block out,
-                    // so a still-missing block must not pose as an authoritative absent. When
-                    // the whole cohort answers "holds nothing" the absent stays authoritative —
-                    // the new-collection probe against a healthy cohort stays one round-trip.
-                    if (isMissing && inconclusive) {
-                        this.flagUnconfirmedAbsence(localResult, blockId);
+                    // The consult ran but could not rule the block out, and the verdict names the
+                    // evidence (see AbsenceVerdict): part of the cohort was silent (`unconfirmed`
+                    // → 'peers-unreachable' — another coordinator may know better), no cohort
+                    // member outside this node could be asked at all (`isolated` →
+                    // 'cohort-unreachable' — there is no better-connected coordinator to re-ask),
+                    // or a peer positively claimed a revision this pass could neither corroborate
+                    // nor acquire (`claimed` → 'claimed-elsewhere' — the block is known to exist
+                    // somewhere). Either way a still-missing block must not pose as an
+                    // authoritative absent. When the whole cohort answers "holds nothing" the
+                    // absent stays authoritative (`confirmed`) — the new-collection probe against
+                    // a healthy cohort stays one round-trip.
+                    if (isMissing && absence !== 'confirmed') {
+                        this.flagUnconfirmedAbsence(localResult, blockId, absence === 'claimed' ? 'claimed-elsewhere'
+                            : absence === 'isolated' ? 'cohort-unreachable'
+                                : '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.
+                    if (!isMissing) {
+                        this.recordAheadClaim(blockId, claimedAheadRev);
+                        this.flagUnconfirmedCurrency(localResult, blockId, blockGets.context);
                     }
                 }
                 catch (err) {
-                    log('cluster-fetch:error', { blockId, error: err.message });
+                    this.log('cluster-fetch:error', { blockId, error: err.message });
                     // The consult that was supposed to make this answer trustworthy did not run.
+                    // NOTE: a consult that THROWS (e.g. `findCluster` itself rejected) is reported
+                    // 'peers-unreachable' even on an isolated node: a failed cohort lookup is a
+                    // routing failure and says nothing about how many cohort members were
+                    // reachable. If `findCluster` on an isolated node turns out to throw routinely
+                    // rather than return a stale cohort view, revisit — that would put the
+                    // isolated case back under this vaguer reason.
                     if (isMissing) {
-                        this.flagUnconfirmedAbsence(localResult, blockId);
+                        this.flagUnconfirmedAbsence(localResult, blockId, 'peers-unreachable');
+                    }
+                    else {
+                        // It told us nothing, so it refutes nothing: an earlier pass's unsettled
+                        // claim stands.
+                        this.flagUnconfirmedCurrency(localResult, blockId, blockGets.context);
                     }
                 }
             }
@@ -258,20 +309,91 @@ export class CoordinatorRepo {
         return localResult;
     }
     /**
-     * Downgrade an absence the coordinator could not confirm to `unavailable: 'peers-unreachable'` —
-     * the flag `NetworkTransactor.get` retries against another peer instead of taking as final.
+     * Downgrade an absence the coordinator could not confirm to the given `unavailable` reason —
+     * a flag `NetworkTransactor.get` retries against another peer instead of taking as final.
+     * The reason names the evidence (see {@link AbsenceVerdict} for the mapping in `get`); this
+     * method only decides WHETHER the entry may carry a flag at all.
      *
      * No-op once the entry carries a real answer (the consult restored the block) or a sharper flag
      * (storage's `'unmaterializable'`), so callers only need to establish that the answer is a guess.
+     *
+     * "Carries a real answer" is tested as `entry.block !== undefined`, NOT as `state.latest` being
+     * set. The two used to move together, so `state.latest` read as a serviceable proxy — but a
+     * pending-only insert (pended, not yet committed) served through the pending overlay has real
+     * CONTENT and no committed revision at all, so its `state.latest` is undefined. Flagging that
+     * entry would mark a block this node is positively holding as an unconfirmed absence, and
+     * `NetworkTransactor`'s `isAuthoritative` keys off the flag alone — the read would burn its
+     * retry budget re-asking other peers for content it already has. `state.latest` stays in the
+     * test as well so a stale-but-real committed answer is likewise never downgraded.
      */
-    flagUnconfirmedAbsence(results, blockId) {
+    flagUnconfirmedAbsence(results, blockId, reason) {
         const entry = results[blockId];
         if (!entry) {
-            results[blockId] = { state: {}, unavailable: 'peers-unreachable' };
+            results[blockId] = { state: {}, unavailable: reason };
+        }
+        else if (entry.block === undefined && !entry.state?.latest && entry.unavailable === undefined) {
+            entry.unavailable = reason;
         }
-        else if (!entry.state?.latest && entry.unavailable === undefined) {
-            entry.unavailable = 'peers-unreachable';
+    }
+    /**
+     * 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
+     * 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);
+    }
+    /**
+     * Stamp {@link GetBlockResult.unconfirmedAheadRev} on an entry sitting behind an unsettled
+     * cohort claim — served committed content the coordinator cannot confirm is current.
+     * Deliberately narrow; ALL of these must hold:
+     *  - a consult (this read's or an earlier one's, see {@link recordAheadClaim}) left a claim
+     *    unsettled for this block;
+     *  - the entry carries a committed revision (a present block, or a committed tombstone) —
+     *    never a plain absent, which is the absence path's business;
+     *  - that served revision is still strictly BELOW the claim: the repair did not converge, and
+     *    nothing committed past the claim in the meantime (if it did, the claim is settled and the
+     *    memo is dropped here);
+     *  - the caller asked for a view that should contain the claim: an unpinned "latest" read, or
+     *    a pin at/above the claimed revision. A read pinned BELOW the claim is being served
+     *    correctly and stays unstamped — this keeps a collection's context-pinned data reads
+     *    quiet while its unpinned tail read (the one seam where fresher truth could arrive —
+     *    Collection.bootstrapContext) speaks up.
+     * NOT covered, on purpose: a cohort that is merely silent and claims nothing (pinned as
+     * authoritative by the merely-STALE spec in coordinator-repo-unavailable.spec.ts) — silence
+     * carries no revision to be behind of.
+     *
+     * Pin comparability: `ActionContext.rev` and a block's `state.latest.rev` count the same
+     * per-collection revision sequence — `Collection.bootstrapContext` seeds the context straight
+     * 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
+     * node behind the claim?" asks about.
+     */
+    flagUnconfirmedCurrency(results, blockId, context) {
+        const claimedRev = this.unsettledAheadClaims.get(blockId);
+        if (claimedRev === undefined)
+            return;
+        const entry = results[blockId];
+        if (!entry || entry.unavailable !== undefined)
+            return;
+        const servedRev = entry.state?.latest?.rev;
+        if (typeof servedRev !== 'number')
+            return;
+        if (servedRev >= claimedRev) {
+            // Caught up — by this pass's repair or by a commit that landed since. Nothing to doubt.
+            this.unsettledAheadClaims.delete(blockId);
+            return;
         }
+        if (context !== undefined && context.rev < claimedRev)
+            return;
+        entry.unconfirmedAheadRev = claimedRev;
+        this.log('cluster-tx:read-unconfirmed', { blockId, servedRev, claimedAheadRev: claimedRev });
     }
     /** Decide whether the read-repair policy wants us to consult the cluster for a present-but-possibly-stale block. */
     shouldReadRepair(blockId) {
@@ -315,22 +437,28 @@ export class CoordinatorRepo {
      * ahead of `localRev` — the revision the caller's read already loaded, and the baseline every
      * decision below is measured against.
      *
-     * Returns the one thing `get` needs beyond the storage side effects: whether the pass was
-     * INCONCLUSIVE — it neither confirmed the cohort holds nothing nor left this node holding the
-     * block. Two ways that happens: a cohort peer other than this node stayed SILENT (rejected
-     * callback or per-peer deadline), or a revision WAS corroborated and the convergence onto it
-     * failed. In both, `get` has learned that its local absence may be wrong, so it must not report
-     * a still-missing block as an authoritative absent. Paths that consult nobody (no cohort,
-     * solo-self) are conclusive: there, the local answer genuinely is the whole truth.
+     * Returns the two things `get` needs beyond the storage side effects:
+     *  - `absence` — the verdict on this node's local absence of the block (see
+     *    {@link AbsenceVerdict}): whether the pass may rule the block out, and on what evidence.
+     *    Only `'confirmed'` lets a still-missing block be reported as an authoritative absent.
+     *    Paths that consult nobody (no cohort, solo-self) are `'confirmed'`: there, the local
+     *    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.
      */
     async fetchBlockFromCluster(blockId, context, localRev) {
         if (!this.clusterLatestCallback)
-            return { inconclusive: false };
+            return { absence: 'confirmed' };
         const blockIdBytes = new TextEncoder().encode(blockId);
         const peers = await this.keyNetwork.findCluster(blockIdBytes);
         const peerIds = peers ? Object.keys(peers) : [];
         if (peerIds.length === 0)
-            return { inconclusive: false };
+            return { absence: 'confirmed' };
         // 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
@@ -338,18 +466,31 @@ export class CoordinatorRepo {
         if (peerIds.length === 1
             && this.localPeerId
             && peerIds[0] === this.localPeerId.toString()) {
-            log('cluster-fetch:solo-self-skip', { blockId });
-            return { inconclusive: false };
+            this.log('cluster-fetch:solo-self-skip', { blockId });
+            return { absence: 'confirmed' };
         }
-        const { corroborated, local, silent } = await this.queryClusterForLatest(peerIds, blockId, context);
-        // Any silence flags the WHOLE consult, not a fraction of it (fail-closed): one silent
+        const { corroborated, local, silent, answered, uncorroboratedRev } = 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.
-        const cohortSilent = silent.length > 0;
+        // 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.
-        if (!corroborated)
-            return { inconclusive: cohortSilent };
+        // 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 } : {}) };
+        }
         // 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
         // block this node is no longer responsible for is absent from its own cohort view, so fall
@@ -368,9 +509,11 @@ export class CoordinatorRepo {
         // production topology rather than a dev convenience, stop re-arming the window on a
         // corroboration that came from a single voter.
         if (baselineRev !== undefined && corroborated.rev <= baselineRev) {
-            log('cluster-fetch:local-current', { blockId, localRev: baselineRev, clusterRev: corroborated.rev });
+            this.log('cluster-fetch:local-current', { blockId, localRev: baselineRev, clusterRev: corroborated.rev });
             this.markBlocksSeen([blockId]);
-            return { inconclusive: cohortSilent };
+            // 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 };
         }
         // Corroborated revision is ahead of ours — converge onto it.
         const rev = await this.restoreCorroborated(blockId, corroborated, baselineRev, peerIds);
@@ -378,18 +521,25 @@ export class CoordinatorRepo {
         // phantom convergences per run and made a real replication defect invisible for two debugging
         // sessions.
         if (rev !== undefined) {
-            log('cluster-fetch:synced', { blockId, rev });
+            this.log('cluster-fetch:synced', { blockId, rev });
         }
         else {
-            log('cluster-fetch:not-restored', { blockId, localRev: baselineRev, clusterRev: corroborated.rev });
-        }
-        // A corroborated revision this node failed to converge onto is inconclusive in its own right,
-        // even with the whole cohort answering: the reader has just been TOLD the block exists, so
-        // reporting it absent would be a lie of the same kind a silent peer causes (see `get`).
-        const inconclusive = cohortSilent || rev === undefined;
+            this.log('cluster-fetch:not-restored', { blockId, localRev: baselineRev, clusterRev: corroborated.rev });
+        }
+        // A corroborated revision this node failed to converge onto rules nothing out, even with
+        // the whole cohort answering: the reader has just been TOLD the block exists, so reporting
+        // it absent would be a lie regardless of silence — that is the `claimed` verdict, and it
+        // outranks whatever the silence-based mapping would have said.
+        const absence = rev === undefined ? 'claimed' : silenceVerdict;
+        // Converged means REACHED the corroborated revision, not merely advanced: a promotion that
+        // landed short of it (possible in principle — restoreCorroborated only requires an advance
+        // over the baseline) still leaves the served answer behind a revision the cohort attested.
+        const converged = rev !== undefined && rev >= corroborated.rev;
         // The block is marked seen either way — the cohort DID answer, so its freshness was checked,
         // which is what the read-repair window tracks. A failed convergence therefore waits out the
-        // window before retrying.
+        // window before retrying. The DOUBT it produced does not wait: `get` remembers the
+        // unsettled claim (`recordAheadClaim`) and keeps stamping reads served below it while the
+        // window suppresses the retry — the window damps repair effort, not honesty.
         // NOTE: that damping covers only a block this node holds at an OLDER revision. A block entirely
         // missing locally never consults the window (`get` triggers on `isMissing` before
         // `shouldReadRepair`), so a persistently failing acquisition — e.g. a two-node deployment that
@@ -398,7 +548,7 @@ 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 { inconclusive };
+        return { absence, ...(converged ? {} : { claimedAheadRev: corroborated.rev }) };
     }
     /**
      * Bring this node up to the cohort-corroborated `corroborated`, returning the revision it holds
@@ -445,7 +595,7 @@ export class CoordinatorRepo {
         }
         catch (err) {
             // Declines are cheap and retryable — nothing was persisted. Report and leave the block behind.
-            log('cluster-fetch:acquire-error', { blockId, rev: corroborated.rev, error: err.message });
+            this.log('cluster-fetch:acquire-error', { blockId, rev: corroborated.rev, error: err.message });
             return undefined;
         }
         const acquired = await this.readLocalRev(blockId);
@@ -456,23 +606,25 @@ 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`;
-     * `StorageRepo.get` now reports it as an entry flagged `unavailable` instead (ticket
-     * repo-reports-unavailable-vs-absent). On THIS path either shape is an absence, not a read failure —
-     * acquisition is precisely the mechanism that can supply the revision — so both are logged as
-     * `promote-unavailable` and stepped over rather than short-circuiting the caller.
+     * for a forward revision no promotion can reach used to throw out of `BlockStorage.ensureRevision`.
+     * 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`
+     * this node cannot materialize, a missing-base promotion refusal); on THIS path those are an
+     * absence too rather than a read failure, so they are logged as `promote-unavailable` and stepped
+     * over rather than short-circuiting the caller. The catch stays for any other fault, same reason.
      */
     async promoteCorroborated(blockId, corroborated) {
         try {
             const entry = await this.readLocalEntry(blockId, { committed: [corroborated], rev: corroborated.rev });
             if (entry?.unavailable !== undefined) {
-                log('cluster-fetch:promote-unavailable', { blockId, rev: corroborated.rev, error: entry.unavailable });
+                this.log('cluster-fetch:promote-unavailable', { blockId, rev: corroborated.rev, error: entry.unavailable });
                 return undefined;
             }
             return entry?.state?.latest?.rev;
         }
         catch (err) {
-            log('cluster-fetch:promote-unavailable', { blockId, rev: corroborated.rev, error: err.message });
+            this.log('cluster-fetch:promote-unavailable', { blockId, rev: corroborated.rev, error: err.message });
             return undefined;
         }
     }
@@ -525,6 +677,10 @@ export class CoordinatorRepo {
         // as a peer claim again. Harmless today — the self answer can only ever corroborate the
         // revision already held, so the pass declines as `local-current` — but if a future caller can
         // 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`.
         const selfId = this.localPeerId?.toString();
         let local;
         const claims = [];
@@ -552,23 +708,39 @@ export class CoordinatorRepo {
             claims.push({ peerId: peerIdStr, rev: value.rev, actionId: value.actionId });
         }
         if (silent.length > 0) {
-            log('cluster-fetch:peers-silent', { blockId, silent: silent.length, consulted: peerIds.length });
+            this.log('cluster-fetch:peers-silent', { blockId, silent: silent.length, consulted: peerIds.length });
         }
-        const capacity = corroboratorCapacity(peerIds.filter(id => id !== selfId).length, this.repairCorroborationClusterSize);
+        const nonSelfCount = peerIds.filter(id => id !== selfId).length;
+        const answered = nonSelfCount - silent.length;
+        const capacity = corroboratorCapacity(nonSelfCount, this.repairCorroborationClusterSize);
         const selected = selectQuorumRev(claims, this.simpleMajorityThreshold, capacity);
         if (!selected) {
-            log('cluster-fetch:no-quorum', {
+            this.log('cluster-fetch:no-quorum', {
                 blockId,
                 responders: claims.length,
-                required: quorumSize(claims.length, this.simpleMajorityThreshold, capacity)
+                required: quorumSize(claims.length, this.simpleMajorityThreshold, capacity),
+                repairCorroborationClusterSize: this.repairCorroborationClusterSize
             });
-            return { local, silent };
+            // 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.
+            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.
         this.penalizeContradictingRevClaims(claims, selected, blockId);
-        return { corroborated: { actionId: selected.actionId, rev: selected.rev }, local, silent };
+        return { corroborated: { actionId: selected.actionId, rev: selected.rev }, local, silent, answered };
     }
     /**
      * Report peers whose reported latest contradicts the quorum-corroborated pair. Best-effort.
@@ -594,7 +766,7 @@ export class CoordinatorRepo {
             }
         }
         catch (err) {
-            log('cluster-fetch:penalize-error', { blockId, error: err.message });
+            this.log('cluster-fetch:penalize-error', { blockId, error: err.message });
         }
     }
     async pend(request, options) {
@@ -612,14 +784,14 @@ export class CoordinatorRepo {
         };
         try {
             const { localExecuted } = await this.coordinator.executeClusterTransaction(coordinatingBlockIds[0], message, options);
-            log('coordinator-repo:pend-cluster-complete', {
+            this.log('coordinator-repo:pend-cluster-complete', {
                 actionId: request.actionId,
                 localExecuted
             });
             // Only call storageRepo if local cluster didn't already execute during consensus
             if (!localExecuted) {
                 const result = await this.storageRepo.pend(request, options);
-                log('coordinator-repo:pend-fallback-result', {
+                this.log('coordinator-repo:pend-fallback-result', {
                     actionId: request.actionId,
                     success: result.success,
                     hasMissing: !!result.missing?.length,
@@ -635,7 +807,20 @@ export class CoordinatorRepo {
             };
         }
         catch (error) {
-            log('coordinator-repo:pend-error', { actionId: request.actionId, error: error.message });
+            this.log('coordinator-repo:pend-error', { actionId: request.actionId, error: error.message });
+            // A lost conflict race is an optimistic-concurrency loss, not a fault: surface it as the
+            // StaleFailure shape the retry machinery already understands (`Collection.sync` and the
+            // multi-collection pendPhase retry it via `isConflictFailure`), exactly as a confirmed
+            // stale revision is. `staleAt` stays absent deliberately — it is confirmed-only, and a
+            // lost race is a rival *pend* holding the blocks, not a revision claim.
+            //
+            // NOTE: `error.conflicts` (peerId → winning messageHash) is dropped here — `StaleFailure`
+            // 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`.
+            if (error instanceof ConflictRaceLostError) {
+                return { success: false, conflict: true, reason: error.message };
+            }
             const stale = await this.classifyStaleRejection(error, request, allBlockIds);
             if (stale)
                 return stale;
@@ -670,7 +855,7 @@ export class CoordinatorRepo {
             results = await this.storageRepo.get({ blockIds });
         }
         catch (readError) {
-            log('coordinator-repo:pend-stale-classify-read-error', {
+            this.log('coordinator-repo:pend-stale-classify-read-error', {
                 actionId: request.actionId,
                 error: readError.message
             });
@@ -685,7 +870,7 @@ export class CoordinatorRepo {
             return latest && latest.rev >= requestedRev ? { blockId, rev: latest.rev } : undefined;
         }));
         if (staleAt) {
-            log('coordinator-repo:pend-stale-classified', {
+            this.log('coordinator-repo:pend-stale-classified', {
                 actionId: request.actionId,
                 blockId: staleAt.blockId,
                 latestRev: staleAt.rev,
@@ -728,7 +913,7 @@ export class CoordinatorRepo {
             }
         }
         catch (error) {
-            log('coordinator-repo:cancel-error', { actionId: actionRef.actionId, error: error.message });
+            this.log('coordinator-repo:cancel-error', { actionId: actionRef.actionId, error: error.message });
             throw error;
         }
     }
@@ -784,7 +969,7 @@ export class CoordinatorRepo {
             }
         }
         catch (error) {
-            log('coordinator-repo:commit-error', { actionId: request.actionId, error: error.message });
+            this.log('coordinator-repo:commit-error', { actionId: request.actionId, error: error.message });
             throw error;
         }
     }
@@ -794,7 +979,7 @@ export class CoordinatorRepo {
      * from replication (cohort reconcile, or read-driven acquisition), not from replay here.
      */
     tolerateLocalCommitDivergence(request, blockIds, detail) {
-        log('coordinator-repo:commit-local-failed-cluster-succeeded', { actionId: request.actionId, error: detail });
+        this.log('coordinator-repo:commit-local-failed-cluster-succeeded', { actionId: request.actionId, error: detail });
         this.markBlocksSeen(blockIds);
         return { success: true };
     }