@optimystic/db-p2p 0.21.0 → 0.24.0

package/src/repo/coordinator-repo.ts

@@ -1,6 +1,6 @@
-import type { PendRequest, ActionBlocks, IRepo, MessageOptions, CommitResult, GetBlockResults, PendResult, StaleFailure, BlockGets, CommitRequest, RepoMessage, IKeyNetwork, ICluster, ClusterConsensusConfig, BlockId, ActionRev, ActionContext, ClusterRecord } from "@optimystic/db-core";
+import type { PendRequest, ActionBlocks, IRepo, MessageOptions, CommitResult, GetBlockResults, PendResult, StaleFailure, BlockGets, CommitRequest, RepoMessage, IKeyNetwork, ICluster, ClusterConsensusConfig, BlockId, ActionRev, ActionContext, ClusterRecord, BlockUnavailableReason } from "@optimystic/db-core";
 import { LruMap, blockIdsForTransforms, highestStaleAt, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
-import { ClusterCoordinator, ValidatorRejectionError } from "./cluster-coordinator.js";
+import { ClusterCoordinator, ConflictRaceLostError, ValidatorRejectionError } from "./cluster-coordinator.js";
 import type { PeerId } from "@libp2p/interface";
 import { peerIdFromString } from "@libp2p/peer-id";
 import type { FretService } from "p2p-fret";
@@ -9,12 +9,11 @@ import type { IPeerReputation } from "../reputation/types.js";
 import { PenaltyReason } from "../reputation/types.js";
 import type { ITransactionStateStore } from "../cluster/i-transaction-state-store.js";
 import { quorumSize, corroboratorCapacity, selectQuorumRev, type RevClaim, type QuorumRev } from "../cluster/quorum-restore.js";
+import { DEFAULT_CLUSTER_SIZE } from "../cluster/cluster-policy.js";
 import { RECONCILE_TIMEOUT_MS } from "../cluster/reconcile-block.js";
 import { isMissingBaseRevisionFailure, MISSING_BASE_REVISION_REASON } from "../storage/storage-repo.js";
 import type { ReconcileBlockCallback } from "../cluster/cluster-repo.js";
 
-const log = createLogger('coordinator-repo');
-
 /**
  * Acquire a block's content for a cohort-corroborated revision, from the cohort, and persist it.
  *
@@ -69,8 +68,48 @@ interface ClusterLatestQuery {
 	 * sole holder.
 	 */
 	silent: string[];
+	/**
+	 * Highest revision any cohort peer CLAIMED when no claim met the corroboration quorum
+	 * (set only alongside an absent `corroborated`). The claim failed quorum, so it must
+	 * never drive restoration — it exists so `get` can report content it serves below this
+	 * revision as possibly behind ({@link GetBlockResult.unconfirmedAheadRev}) instead of
+	 * confirmed. When a quorum DOES corroborate, higher uncorroborated claims are dropped
+	 * as before: the quorum's affirmative answer outweighs a lone voter (which may simply
+	 * be ahead on an in-flight commit), and stamping doubt there would mark every read that
+	 * races a commit broadcast.
+	 */
+	uncorroboratedRev?: number;
+	/**
+	 * How many cohort peers OTHER than this node answered the consult at all — with a claim
+	 * or with "I hold nothing". `silent` says who could not be asked; this says how many
+	 * could. Zero with a non-empty `silent` means this node reached NOBODY, which is a
+	 * different fact from partial silence: there is no better-informed answer to be had from
+	 * this node's position (see {@link AbsenceVerdict}).
+	 */
+	answered: number;
 }
 
+/**
+ * What one repair pass established about a block that is still MISSING locally after it.
+ * Ordered by how firmly the block is ruled out; `get` consults it only on the missing path.
+ */
+type AbsenceVerdict =
+	/** Nobody to ask (empty cohort, or solo-self), or every non-self cohort member answered
+	 *  "I hold nothing". As confirmed as an absence gets — stays authoritative, which is what
+	 *  keeps the routine new-collection probe at one round trip. */
+	| 'confirmed'
+	/** Some of the cohort answered and some could not be asked. (A consult that THROWS produces
+	 *  no verdict at all — `get`'s catch arm reports it directly.) */
+	| 'unconfirmed'
+	/** No cohort member outside this node could be asked at all. Mutually exclusive with
+	 *  `claimed` in practice: a claim requires a non-self peer to have answered, which is
+	 *  exactly what this verdict rules out. The precedence below still orders the pair, so
+	 *  the mapping stays total, but there is no reachable case to test. */
+	| 'isolated'
+	/** A peer claimed a revision this pass did not converge onto — quorum declined it, or a
+	 *  quorum corroborated it and acquisition failed. */
+	| 'claimed';
+
 /**
  * Extended cluster interface that includes the ability to check if a transaction was executed.
  * This is used by CoordinatorRepo to avoid duplicate execution.
@@ -156,6 +195,13 @@ export class CoordinatorRepo implements IRepo {
 	private readonly responsibilityCache = new LruMap<string, { inCluster: boolean, expires: number }>(1000);
 	private static readonly RESPONSIBILITY_TTL_MS = 60_000;
 	private readonly lastSeenCommitMs = new LruMap<string, number>(1000);
+	/** Per block, the cohort-claimed revision the last freshness consult could not settle — the
+	 *  doubt {@link flagUnconfirmedCurrency} stamps onto reads served below it. Outlives the
+	 *  consult on purpose: the read-repair window skips consults for blocks checked recently, and
+	 *  a doubt dropped there is a stale answer served as confirmed again.
+	 *  NOTE: LRU-bounded like `lastSeenCommitMs`; an eviction under >1000 doubted blocks loses the
+	 *  doubt until the next consult re-derives it (one read-repair window later, at worst). */
+	private readonly unsettledAheadClaims = new LruMap<string, number>(1000);
 	private readonly readRepairMode: 'off' | 'lazy' | 'paranoid';
 	private readonly readRepairWindowMs: number;
 	private readonly readRepairSampleRate: number;
@@ -171,6 +217,8 @@ export class CoordinatorRepo implements IRepo {
 	/** Resolved super-majority threshold the coordinator commits on (mirrors the value handed to ClusterCoordinator). */
 	private readonly superMajorityThreshold: number;
 	private readonly reputation?: IPeerReputation;
+	/** 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). */
+	private readonly log: ReturnType<typeof createLogger>;
 	/** Test seam: overridable clock for window-based read-repair gating. */
 	now: () => number = () => Date.now();
 	/** Test seam: overridable RNG (0..1) for sample-rate gating. */
@@ -190,8 +238,12 @@ export class CoordinatorRepo implements IRepo {
 		private readonly acquireBlockFromCohort?: AcquireBlockCallback
 	) {
 		this.localPeerId = localPeerId;
+		this.log = createLogger('coordinator-repo', localPeerId?.toString());
 		const policy: ClusterConsensusConfig & { clusterSize: number } = {
-			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,
@@ -270,13 +322,13 @@ export class CoordinatorRepo implements IRepo {
 			const peers = await this.keyNetwork.findCluster(blockIdBytes);
 			inCluster = this.localPeerId.toString() in peers;
 		} catch (err) {
-			log('proximity:check-error', { blockId, error: (err as Error).message });
+			this.log('proximity:check-error', { blockId, error: (err as Error).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;
 	}
 
@@ -291,7 +343,7 @@ export class CoordinatorRepo implements IRepo {
 			}
 		}
 		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(', ')}`);
 		}
 	}
@@ -307,7 +359,7 @@ export class CoordinatorRepo implements IRepo {
 		// 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' });
 			}
 		}
 
@@ -326,8 +378,9 @@ export class CoordinatorRepo implements IRepo {
 		// 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
@@ -340,10 +393,19 @@ export class CoordinatorRepo implements IRepo {
 				const localRev = localEntry?.state?.latest?.rev;
 				const isMissing = !localEntry?.state?.latest;
 				const isStale = !isMissing && this.shouldReadRepair(blockId);
-				if (!isMissing && !isStale) continue;
+				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),
@@ -352,7 +414,7 @@ export class CoordinatorRepo implements IRepo {
 				}
 
 				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]) {
@@ -360,25 +422,54 @@ export class CoordinatorRepo implements IRepo {
 					}
 					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 as Error).message });
+					this.log('cluster-fetch:error', { blockId, error: (err as Error).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);
 					}
 				}
 			}
@@ -388,21 +479,88 @@ export class CoordinatorRepo implements IRepo {
 	}
 
 	/**
-	 * 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.
 	 */
-	private flagUnconfirmedAbsence(results: GetBlockResults, blockId: BlockId): void {
+	private flagUnconfirmedAbsence(results: GetBlockResults, blockId: BlockId, reason: BlockUnavailableReason): void {
 		const entry = results[blockId];
 		if (!entry) {
-			results[blockId] = { state: {}, unavailable: 'peers-unreachable' };
-		} else if (!entry.state?.latest && entry.unavailable === undefined) {
-			entry.unavailable = 'peers-unreachable';
+			results[blockId] = { state: {}, unavailable: reason };
+		} else if (entry.block === undefined && !entry.state?.latest && entry.unavailable === undefined) {
+			entry.unavailable = reason;
 		}
 	}
 
+	/**
+	 * 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.
+	 */
+	private recordAheadClaim(blockId: BlockId, claimedRev: number | undefined): void {
+		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.
+	 */
+	private flagUnconfirmedCurrency(results: GetBlockResults, blockId: BlockId, context?: ActionContext): void {
+		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. */
 	private shouldReadRepair(blockId: BlockId): boolean {
 		switch (this.readRepairMode) {
@@ -446,21 +604,27 @@ export class CoordinatorRepo implements IRepo {
 	 * 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.
 	 */
-	private async fetchBlockFromCluster(blockId: BlockId, context?: ActionContext, localRev?: number): Promise<{ inconclusive: boolean }> {
-		if (!this.clusterLatestCallback) return { inconclusive: false };
+	private async fetchBlockFromCluster(blockId: BlockId, context?: ActionContext, localRev?: number): Promise<{ absence: AbsenceVerdict; claimedAheadRev?: number }> {
+		if (!this.clusterLatestCallback) 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 };
+		if (peerIds.length === 0) 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
@@ -471,18 +635,33 @@ export class CoordinatorRepo implements IRepo {
 			&& 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: AbsenceVerdict =
+			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: AbsenceVerdict = 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
@@ -503,9 +682,11 @@ export class CoordinatorRepo implements IRepo {
 		// 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.
@@ -515,17 +696,24 @@ export class CoordinatorRepo implements IRepo {
 		// 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 });
+			this.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;
+		// 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: AbsenceVerdict = 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
@@ -534,7 +722,7 @@ export class CoordinatorRepo implements IRepo {
 		// 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 }) };
 	}
 
 	/**
@@ -591,7 +779,7 @@ export class CoordinatorRepo implements IRepo {
 			);
 		} 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 as Error).message });
+			this.log('cluster-fetch:acquire-error', { blockId, rev: corroborated.rev, error: (err as Error).message });
 			return undefined;
 		}
 		const acquired = await this.readLocalRev(blockId);
@@ -603,22 +791,24 @@ export class CoordinatorRepo implements IRepo {
 	 * the repair. Returns the local revision afterwards.
 	 *
 	 * A pending-only block (metadata seeded by `savePendingTransaction`, no committed revision) asked
-	 * for a forward revision no promotion can reach used to throw out of `BlockStorage.ensureRevision`;
-	 * `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.
 	 */
 	private async promoteCorroborated(blockId: BlockId, corroborated: ActionRev): Promise<number | undefined> {
 		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 as Error).message });
+			this.log('cluster-fetch:promote-unavailable', { blockId, rev: corroborated.rev, error: (err as Error).message });
 			return undefined;
 		}
 	}
@@ -681,6 +871,10 @@ export class CoordinatorRepo implements IRepo {
 		// 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: ActionRev | undefined;
 		const claims: RevClaim[] = [];
@@ -706,18 +900,34 @@ export class CoordinatorRepo implements IRepo {
 			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
@@ -725,7 +935,7 @@ export class CoordinatorRepo implements IRepo {
 		// 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 };
 	}
 
 	/**
@@ -750,7 +960,7 @@ export class CoordinatorRepo implements IRepo {
 				}
 			}
 		} catch (err) {
-			log('cluster-fetch:penalize-error', { blockId, error: (err as Error).message });
+			this.log('cluster-fetch:penalize-error', { blockId, error: (err as Error).message });
 		}
 	}
 
@@ -772,14 +982,14 @@ export class CoordinatorRepo implements IRepo {
 
 		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 as any).missing?.length,
@@ -794,7 +1004,20 @@ export class CoordinatorRepo implements IRepo {
 				blockIds: allBlockIds
 			};
 		} catch (error) {
-			log('coordinator-repo:pend-error', { actionId: request.actionId, error: (error as Error).message });
+			this.log('coordinator-repo:pend-error', { actionId: request.actionId, error: (error as 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;
 			throw error;
@@ -827,7 +1050,7 @@ export class CoordinatorRepo implements IRepo {
 		try {
 			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 as Error).message
 			});
@@ -842,7 +1065,7 @@ export class CoordinatorRepo implements IRepo {
 			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,
@@ -891,7 +1114,7 @@ export class CoordinatorRepo implements IRepo {
 				await this.storageRepo.cancel(actionRef, options);
 			}
 		} catch (error) {
-			log('coordinator-repo:cancel-error', { actionId: actionRef.actionId, error: (error as Error).message });
+			this.log('coordinator-repo:cancel-error', { actionId: actionRef.actionId, error: (error as Error).message });
 			throw error;
 		}
 	}
@@ -948,7 +1171,7 @@ export class CoordinatorRepo implements IRepo {
 				throw err;
 			}
 		} catch (error) {
-			log('coordinator-repo:commit-error', { actionId: request.actionId, error: (error as Error).message });
+			this.log('coordinator-repo:commit-error', { actionId: request.actionId, error: (error as Error).message });
 			throw error;
 		}
 	}
@@ -959,7 +1182,7 @@ export class CoordinatorRepo implements IRepo {
 	 * from replication (cohort reconcile, or read-driven acquisition), not from replay here.
 	 */
 	private tolerateLocalCommitDivergence(request: CommitRequest, blockIds: BlockId[], detail: string): CommitResult {
-		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 };
 	}