@optimystic/db-p2p 0.16.2 → 0.17.0

package/src/libp2p-node-base.ts

@@ -1,7 +1,7 @@
 import { createLibp2p, type Libp2p } from 'libp2p';
 import { noise } from '@chainsafe/libp2p-noise';
 import { yamux } from '@chainsafe/libp2p-yamux';
-import { identify } from '@libp2p/identify';
+import { identify, identifyPush } from '@libp2p/identify';
 import { ping } from '@libp2p/ping';
 import { dcutr } from '@libp2p/dcutr';
 import { autoNAT } from '@libp2p/autonat';
@@ -20,12 +20,12 @@ import { MemoryRawStorage } from './storage/memory-storage.js';
 import type { IRawStorage } from './storage/i-raw-storage.js';
 import { seedOwnedBlocksFromStorage } from './owned-block-seed.js';
 import { clusterMember, type ReconcileBlockCallback, type CommitCertificateSink, type DeriveExpectedClusterCallback } from './cluster/cluster-repo.js';
-import { selectQuorumRev, selectQuorumBlock, canonicalBlockHash, type RevClaim, type BlockHashCandidate } from './cluster/quorum-restore.js';
+import { createReconcileBlock } from './cluster/reconcile-block.js';
 import { createCommitCertStore, makeClusterCommitCertExtractor, type CommitCertStore } from './cluster/commit-cert.js';
 import { coordinatorRepo } from './repo/coordinator-repo.js';
 import { Libp2pKeyPeerNetwork, type NetworkMode, type NetworkStatePersistence } from './libp2p-key-network.js';
 import { ClusterClient } from './cluster/client.js';
-import type { IRepo, ICluster, ITransactionValidator, BlockId, IBlock, IBlockChangeNotifier } from '@optimystic/db-core';
+import type { IRepo, ICluster, ITransactionValidator, BlockId, IBlockChangeNotifier } from '@optimystic/db-core';
 import type { ITransactionStateStore } from './cluster/i-transaction-state-store.js';
 import { networkManagerService, type NetworkManagerService } from './network/network-manager-service.js';
 import type { SpreadOnChurnConfig, SpreadOnChurnMonitor } from './cluster/spread-on-churn.js';
@@ -85,7 +85,7 @@ import { assertSuperMajorityCoupling } from './cluster/supermajority-coupling.js
 import { createLogger } from './logger.js';
 import { PeerReputationService } from './reputation/peer-reputation.js';
 import type { IPeerReputation } from './reputation/types.js';
-import { PenaltyReason } from './reputation/types.js';
+import type { AuthorizeInboundStream, InboundStreamAuthorizationInit } from './inbound-authorization.js';
 import { DisputeService } from './dispute/dispute-service.js';
 import { DisputeClient } from './dispute/client.js';
 import { sampleArbitrators } from './dispute/arbitrator-selection.js';
@@ -174,11 +174,25 @@ export type NodeOptions = {
 	relayServerInit?: CircuitRelayServerInit;
 	/** Storage provider - either an IRawStorage instance or a factory function. Defaults to MemoryRawStorage if not provided. */
 	storage?: RawStorageProvider;
-	clusterSize?: number; // desired cluster size per key
+	/**
+	 * Desired cluster size per key (default 10). Beyond sizing the cohort, this is the
+	 * node's declaration of how many peers *should* exist to corroborate a claim: the
+	 * read-repair corroboration floor is measured against it, so a genuine two-node
+	 * deployment must set `clusterSize: 2` for its members to be able to repair each
+	 * other (see `CoordinatorRepo.corroboratorCapacity`).
+	 */
+	clusterSize?: number;
 	clusterPolicy?: {
 		allowDownsize?: boolean;
 		sizeTolerance?: number; // acceptable relative difference (e.g. 0.5 = +/-50%)
 		superMajorityThreshold?: number; // fraction of peers needed for super-majority (default: DEFAULT_SUPER_MAJORITY_THRESHOLD = 0.75)
+		/**
+		 * Opt in to transacting below the safe cluster-size floor when FRET has no confident
+		 * network-size estimate — the membership-admission and coordinator small-cluster gates
+		 * both fail closed without it. Default false. Turn on only for single-node / local dev
+		 * meshes that knowingly run undersized.
+		 */
+		allowUnvalidatedSmallCluster?: boolean;
 	};
 
 	/** Override libp2p listen multiaddrs. */
@@ -275,6 +289,35 @@ export type NodeOptions = {
 	 */
 	privateKey?: PrivateKey;
 
+	/**
+	 * Optional predicate deciding whether a remote peer may open one of the four Optimystic
+	 * database protocols on this node (`repo`, `cluster`, `sync`, `block-transfer`). It is
+	 * consulted once per inbound stream, before any frame is decoded or any operation executed.
+	 *
+	 * This is deliberately ONE node-level option threaded to all four services rather than four
+	 * per-service options: "is this peer allowed to talk to my database?" is a property of the
+	 * node, not of the protocol, and four independently-settable options make it easy to secure
+	 * three surfaces and silently miss the fourth. (Each service still accepts the same option in
+	 * its own init, so the services stay independently testable and usable outside this factory.)
+	 *
+	 * Absent → no check at all, and today's behavior exactly. Supplied → fail-closed: `false`, a
+	 * throw, a rejection, or a timeout all deny and abort the stream. `remotePeerId` is the
+	 * dialing peer's `PeerId.toString()`. See {@link AuthorizeInboundStream} and
+	 * `docs/internals.md` § Inbound Stream Authorization.
+	 *
+	 * NOTE: this covers the four database protocols only. The reactivity, matchmaking,
+	 * cohort-topic and libp2p built-in (identify/ping/…) protocols this node also registers are
+	 * NOT gated by it.
+	 */
+	authorizeInboundStream?: AuthorizeInboundStream;
+
+	/**
+	 * Deadline for {@link NodeOptions.authorizeInboundStream}; expiry denies the stream (a hanging
+	 * predicate would otherwise pin an inbound stream slot). Defaults to
+	 * `DEFAULT_INBOUND_AUTHORIZATION_TIMEOUT_MS` (5s). Ignored when no predicate is supplied.
+	 */
+	authorizeInboundStreamTimeoutMs?: number;
+
 	/**
 	 * Optional libp2p connection gater. The libp2p browser default denies
 	 * dialing insecure WebSockets and private/loopback addresses; callers
@@ -383,6 +426,19 @@ export async function createLibp2pNodeBase(
 		}
 	};
 
+	// The ONE authorization slice, spread verbatim into all four database-protocol service inits
+	// below. Building it once (rather than repeating two option reads per service) is what makes
+	// "secured three surfaces, missed the fourth" impossible: adding a fifth protocol service is a
+	// spread of this object, and dropping it from one is visible at the call site.
+	// Absent `authorizeInboundStream` → every service constructs its gate as `undefined` and the
+	// inbound path is byte-for-byte what it was before this option existed.
+	const inboundAuthorization: InboundStreamAuthorizationInit = {
+		...(options.authorizeInboundStream ? { authorizeInboundStream: options.authorizeInboundStream } : {}),
+		...(options.authorizeInboundStreamTimeoutMs !== undefined
+			? { authorizeInboundStreamTimeoutMs: options.authorizeInboundStreamTimeoutMs }
+			: {})
+	};
+
 	const nodePrivateKey = options.privateKey ?? await generateKeyPair('Ed25519');
 
 	const listenAddrs = options.listenAddrs ?? defaults.listenAddrs;
@@ -433,8 +489,32 @@ export async function createLibp2pNodeBase(
 		// NOTE: this cast exists ONLY because of the duplicate @libp2p/interface install; if that dedups
 		// (or on a libp2p bump) drop `as unknown as NonNullable<Libp2pInit['services']>` and type the map directly.
 		services: ({
+			// `@libp2p/identify` is the ONE service here whose protocol id it builds itself:
+			// `Identify`/`IdentifyPush` both emit `/${protocolPrefix}/id[/push]/1.0.0`, always
+			// prepending the leading slash (its own default is the BARE `'ipfs'`). So this
+			// prefix must stay slash-LESS — passing `/optimystic/...` yields the malformed
+			// double-slash `//optimystic/<net>/id/1.0.0`. Every other service below
+			// (cluster/repo/sync/blockTransfer) concatenates its own template literal and so
+			// takes the slash-PREFIXED `protocolPrefix` form; do not unify the two.
+			// Locked by `identify-protocol-id.spec.ts`.
 			identify: identify({
-				protocolPrefix: `/optimystic/${options.networkName}`
+				protocolPrefix: `optimystic/${options.networkName}`
+			}),
+			// identify/push propagates *later* address/protocol changes (relay reservation,
+			// AutoNAT-learned observed addr, a service registered post-start) to already-connected
+			// peers. Without it those peers keep the stale snapshot from the initial identify.
+			// Two consequences, both now covered by tests rather than asserted here:
+			//  - Addresses: a relay-only peer's reservation completes AFTER its first connection to
+			//    the relay, so the circuit address is exactly the one identify cannot have carried.
+			//    The relay's peerStore entry stays empty and a later dial by peer id alone fails
+			//    with NoValidAddressesError against a reachable peer — `relay-address-propagation.spec.ts`
+			//    (its gated control reproduces that failure with push removed).
+			//  - Protocols: `membershipOf` in `libp2p-key-network.ts` classifies a peer serves/
+			//    foreign/unknown purely from the peerStore protocol list, so a cluster/repo handler
+			//    registered post-start never flips an already-connected peer to `serves` —
+			//    `identify-push-propagation.spec.ts`.
+			identifyPush: identifyPush({
+				protocolPrefix: `optimystic/${options.networkName}`
 			}),
 			ping: ping(),
 			// DCUtR (hole-punch) upgrades relayed node↔node connections to direct
@@ -455,7 +535,8 @@ export async function createLibp2pNodeBase(
 			cluster: (components: any) => {
 				const serviceFactory = clusterService({
 					protocolPrefix: `/optimystic/${options.networkName}`,
-					responsibilityK: options.responsibilityK ?? 1
+					responsibilityK: options.responsibilityK ?? 1,
+					...inboundAuthorization
 				});
 				return serviceFactory({
 					logger: components.logger,
@@ -481,7 +562,8 @@ export async function createLibp2pNodeBase(
 			repo: (components: any) => {
 				const serviceFactory = repoService({
 					protocolPrefix: `/optimystic/${options.networkName}`,
-					responsibilityK: options.responsibilityK ?? 1
+					responsibilityK: options.responsibilityK ?? 1,
+					...inboundAuthorization
 				});
 				// RepoService.checkRedirect needs the running node (network manager for the
 				// responsible-set computation, self id for the membership check, connection
@@ -501,7 +583,8 @@ export async function createLibp2pNodeBase(
 
 			sync: (components: any) => {
 				const serviceFactory = syncService({
-					protocolPrefix: `/optimystic/${options.networkName}`
+					protocolPrefix: `/optimystic/${options.networkName}`,
+					...inboundAuthorization
 				});
 				return serviceFactory({
 					logger: components.logger,
@@ -515,7 +598,8 @@ export async function createLibp2pNodeBase(
 			// node's own storage, not be re-routed through the cluster-coordinated repo.
 			blockTransfer: (components: any) => {
 				const serviceFactory = blockTransferService({
-					protocolPrefix: `/optimystic/${options.networkName}`
+					protocolPrefix: `/optimystic/${options.networkName}`,
+					...inboundAuthorization
 				});
 				return serviceFactory({
 					registrar: components.registrar,
@@ -618,6 +702,9 @@ export async function createLibp2pNodeBase(
 		minAbsoluteClusterSize: 2,
 		allowClusterDownsize: options.clusterPolicy?.allowDownsize ?? true,
 		clusterSizeTolerance: options.clusterPolicy?.sizeTolerance ?? 0.5,
+		// Fail closed by default (an undersized cluster with no confident network-size estimate is
+		// rejected); embedders running knowingly-small meshes opt in through clusterPolicy.
+		allowUnvalidatedSmallCluster: options.clusterPolicy?.allowUnvalidatedSmallCluster ?? false,
 		partitionDetectionWindow: 60000,
 		// Configured full cluster size — the member's own reference for "full size" in the membership
 		// admission gate (a below-full-size declared set under low FRET confidence is refused as a possible
@@ -650,69 +737,18 @@ export async function createLibp2pNodeBase(
 		}
 	};
 
-	// Active reconciliation for a block this member committed without the matching pend
-	// (cohort drift). Queries the commit cohort (self already excluded) for the block,
-	// picks the highest revision that is at least the committed rev, and persists it via
-	// the churn-replication funnel so the block is no longer under-replicated.
-	const reconcileBlock: ReconcileBlockCallback = async (blockId, committed, cohortPeerIds) => {
-		const targets = cohortPeerIds.filter(id => id !== node.peerId.toString());
-		if (targets.length === 0) return;
-
-		const fetched = await Promise.all(
-			targets.map(async peerIdStr => ({ peerIdStr, archive: await fetchArchiveFromPeer(peerIdStr, blockId) }))
-		);
-
-		// Each cohort archive contributes one (rev, actionId) claim from its max
-		// revision (>= the rev we committed). Pick the target rev by quorum
-		// corroboration rather than raw Math.max — a lone peer inflating its rev
-		// cannot steer reconciliation. Keep the serving peer + block per candidate
-		// so we can then verify content agreement.
-		// NOTE: this quorum is corroboration-of-a-claim, NOT Sybil-resistant cohort
-		// membership — deferred to backlog `debt-read-repair-commit-cert-verification`.
-		const candidates: { peerIdStr: string; rev: number; actionId: string; block?: IBlock }[] = [];
-		for (const { peerIdStr, archive } of fetched) {
-			if (!archive) continue;
-			const revs = Object.keys(archive.revisions).map(Number);
-			if (revs.length === 0) continue;
-			const maxRev = Math.max(...revs);
-			if (maxRev < committed.rev) continue;
-			const data = archive.revisions[maxRev];
-			if (!data?.action) continue;
-			candidates.push({ peerIdStr, rev: maxRev, actionId: data.action.actionId, block: data.block });
-		}
-
-		const revClaims: RevClaim[] = candidates.map(c => ({ peerId: c.peerIdStr, rev: c.rev, actionId: c.actionId }));
-		const selected = selectQuorumRev(revClaims, consensusConfig.simpleMajorityThreshold);
-		if (!selected) return; // no rev corroborated by a quorum → leave block, churn/rebalance retries later
-
-		// Content agreement: among archives corroborating the chosen (rev, actionId)
-		// and actually carrying the block, the content must be byte-identical across
-		// a quorum. A cohort member serving content that hashes differently is rejected.
-		// NOTE: selectQuorumBlock recomputes its quorum over only the block-CARRYING
-		// corroborators, not the full rev-responder set. If most peers corroborate the
-		// rev but few carry block bytes (e.g. mid-prune), the content quorum can shrink
-		// to 2. Harmless with honest peers; if a colluding pair ever becomes the only
-		// block-servers for an agreed rev, that is the Sybil regime already deferred to
-		// backlog `debt-read-repair-commit-cert-verification`.
-		const corroborating = candidates.filter(c => c.rev === selected.rev && c.actionId === selected.actionId && c.block);
-		const hashCandidates: BlockHashCandidate[] = await Promise.all(
-			corroborating.map(async c => ({ peerId: c.peerIdStr, hash: await canonicalBlockHash(c.block!), block: c.block! }))
-		);
-		const agreed = selectQuorumBlock(hashCandidates, consensusConfig.simpleMajorityThreshold);
-		if (!agreed) return; // no content quorum → skip persist
-
-		// Best-effort: penalize cohort members that served content contradicting the
-		// agreed hash for the same committed (rev, actionId). Never let this throw.
-		try {
-			for (const c of hashCandidates) {
-				if (c.hash !== agreed.hash) {
-					reputation.reportPeer(c.peerId, PenaltyReason.InvalidRestoration, `reconcile:${blockId}`);
-				}
-			}
-		} catch { /* reputation write must never block restoration */ }
-
-		await storageRepo.saveReplicatedBlock(blockId, agreed.block, { actionId: selected.actionId, rev: selected.rev });
-	};
+	// Active reconciliation for a block this member committed without a materializable base
+	// (cohort drift, or a refused `missing-base-revision` commit). See `reconcile-block.ts` for
+	// the corroboration rules — in particular why both quorums are capped by how many peers
+	// could answer at all, which is what lets a genuinely two-node cohort heal.
+	const reconcileBlock: ReconcileBlockCallback = createReconcileBlock({
+		selfPeerId: node.peerId.toString(),
+		fetchArchive: fetchArchiveFromPeer,
+		saveReplicatedBlock: (blockId, block, source) => storageRepo.saveReplicatedBlock(blockId, block, source),
+		simpleMajorityThreshold: consensusConfig.simpleMajorityThreshold,
+		clusterSize: consensusConfig.clusterSize,
+		reputation
+	});
 
 	// Member-side membership derivation for the admission gate: independently re-derive this block's
 	// responsible cluster from the SAME source the coordinator uses (IKeyNetwork.findCluster), plus FRET's
@@ -804,7 +840,13 @@ export async function createLibp2pNodeBase(
 		storageRepo,
 		localCluster: clusterImpl,
 		localPeerId: node.peerId,
-		clusterLatestCallback
+		clusterLatestCallback,
+		// Read-driven acquisition shares the commit path's reconcile callback verbatim: same bounded
+		// archive fetch, same (rev, actionId) and content quorums, same monotonic saveReplicatedBlock
+		// funnel. `clusterLatestCallback` alone can only tell the reader WHICH revision the cohort
+		// holds; this is what moves the bytes. Only reached once a corroborated revision exists, so a
+		// genuinely absent block still costs no archive fetch.
+		acquireBlockFromCohort: reconcileBlock
 	});
 
 	// Fail-fast coupling: the cluster member (what accepts a super-majority as sufficient) and the

package/src/repo/coordinator-repo.ts

@@ -9,10 +9,57 @@ import { createLogger } from '../logger.js';
 import type { IPeerReputation } from "../reputation/types.js";
 import { PenaltyReason } from "../reputation/types.js";
 import type { ITransactionStateStore } from "../cluster/i-transaction-state-store.js";
-import { selectQuorumRev, type RevClaim, type QuorumRev } from "../cluster/quorum-restore.js";
+import { quorumSize, selectQuorumRev, type RevClaim, type QuorumRev } from "../cluster/quorum-restore.js";
+import { RECONCILE_TIMEOUT_MS } from "../cluster/reconcile-block.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.
+ *
+ * Deliberately the SAME shape as the commit path's {@link ReconcileBlockCallback}, and in the live
+ * node the very same instance (`libp2p-node-base` passes its `reconcileBlock` to both): read-driven
+ * acquisition needs exactly what reconcile already provides — a per-peer-bounded archive fetch, a
+ * quorum vote on the target `(rev, actionId)`, a quorum vote on the *content* at that revision, and a
+ * persist through the monotonic, commit-latched `StorageRepo.saveReplicatedBlock` funnel. Reusing it
+ * is what keeps read-repair from being a weaker trust path than reconcile.
+ */
+export type AcquireBlockCallback = ReconcileBlockCallback;
+
+/** True when a freshly-read local revision is strictly ahead of the baseline the repair started from. */
+function isAdvanceOver(rev: number | undefined, baseline: ActionRev | undefined): boolean {
+	return typeof rev === 'number' && (baseline === undefined || rev > baseline.rev);
+}
+
+/**
+ * Reject if `promise` has not settled within `ms`. The timer is cleared on either outcome, so no
+ * handle outlives the race (hence no `unref`, which does not exist off Node).
+ */
+function withDeadline<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const deadline = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+	});
+	return Promise.race([promise, deadline]).finally(() => {
+		if (timer !== undefined) clearTimeout(timer);
+	});
+}
+
+/**
+ * What one round of polling the cohort learned about a block: the revision the OTHER
+ * cohort members corroborated, and what this node itself already holds. The two are kept
+ * apart on purpose — the local revision is the baseline being repaired, never evidence
+ * about the cluster (see {@link CoordinatorRepo.queryClusterForLatest}) — but the caller
+ * still needs it to tell whether the corroborated revision is actually an advance.
+ */
+interface ClusterLatestQuery {
+	/** Highest `(rev, actionId)` corroborated by peers other than this node, if any. */
+	corroborated?: ActionRev;
+	/** This node's own latest for the block, as answered by the callback's self short-circuit. */
+	local?: ActionRev;
+}
+
 /**
  * Extended cluster interface that includes the ability to check if a transaction was executed.
  * This is used by CoordinatorRepo to avoid duplicate execution.
@@ -36,6 +83,13 @@ interface CoordinatorRepoComponents {
 	 * Used for read-path cluster verification to discover unknown revisions.
 	 */
 	clusterLatestCallback?: ClusterLatestCallback;
+	/**
+	 * Optional callback that actually moves a block's bytes from the cohort into local storage once
+	 * {@link clusterLatestCallback} has established a corroborated revision this node lacks. Absent →
+	 * the read path can still *select* the right revision but converges only when the node already
+	 * holds the corroborated action as a promotable pending. See {@link AcquireBlockCallback}.
+	 */
+	acquireBlockFromCohort?: AcquireBlockCallback;
 }
 
 export function coordinatorRepo(
@@ -56,7 +110,8 @@ export function coordinatorRepo(
 		fretService,
 		components.clusterLatestCallback,
 		reputation,
-		stateStore
+		stateStore,
+		components.acquireBlockFromCohort
 	);
 }
 
@@ -73,6 +128,8 @@ export class CoordinatorRepo implements IRepo {
 	private readonly readRepairSampleRate: number;
 	/** Simple-majority threshold from the consensus policy; drives the read-repair corroboration quorum. */
 	private readonly simpleMajorityThreshold: number;
+	/** Configured full cluster size; the operator's declaration of how many corroborators should exist. */
+	private readonly clusterSize: number;
 	/** Resolved super-majority threshold the coordinator commits on (mirrors the value handed to ClusterCoordinator). */
 	private readonly superMajorityThreshold: number;
 	private readonly reputation?: IPeerReputation;
@@ -91,7 +148,8 @@ export class CoordinatorRepo implements IRepo {
 		fretService?: FretService,
 		private readonly clusterLatestCallback?: ClusterLatestCallback,
 		reputation?: IPeerReputation,
-		stateStore?: ITransactionStateStore
+		stateStore?: ITransactionStateStore,
+		private readonly acquireBlockFromCohort?: AcquireBlockCallback
 	) {
 		this.localPeerId = localPeerId;
 		const policy: ClusterConsensusConfig & { clusterSize: number } = {
@@ -120,6 +178,7 @@ export class CoordinatorRepo implements IRepo {
 		this.readRepairSampleRate = policy.readRepairSampleRate!;
 		this.simpleMajorityThreshold = policy.simpleMajorityThreshold;
 		this.superMajorityThreshold = policy.superMajorityThreshold;
+		this.clusterSize = policy.clusterSize;
 		this.reputation = reputation;
 		const localClusterRef = localCluster && localPeerId ? {
 			update: localCluster.update.bind(localCluster),
@@ -312,33 +371,163 @@ export class CoordinatorRepo implements IRepo {
 			return;
 		}
 
-		const clusterLatest = await this.queryClusterForLatest(peerIds, blockId, context);
-		if (clusterLatest) {
-			// Found on cluster - trigger restoration to sync the block
-			await this.storageRepo.get({ blockIds: [blockId], context: { committed: [clusterLatest], rev: clusterLatest.rev } });
-			log('cluster-fetch:synced', { blockId, rev: clusterLatest.rev });
+		const { corroborated, local } = await this.queryClusterForLatest(peerIds, blockId, context);
+		// 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;
+
+		// Never restore backwards. With this node's own claim excluded from the quorum, a
+		// 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.
+		if (local && corroborated.rev <= local.rev) {
+			log('cluster-fetch:local-current', { blockId, localRev: local.rev, clusterRev: corroborated.rev });
 			this.markBlocksSeen([blockId]);
+			return;
 		}
+
+		// Corroborated revision is ahead of ours — converge onto it.
+		const rev = await this.restoreCorroborated(blockId, corroborated, local, peerIds);
+
+		// Log the OUTCOME, not the attempt. Logging `synced` unconditionally reported hundreds of
+		// phantom convergences per run and made a real replication defect invisible for two debugging
+		// sessions.
+		if (rev !== undefined) {
+			log('cluster-fetch:synced', { blockId, rev });
+		} else {
+			log('cluster-fetch:not-restored', { blockId, localRev: local?.rev, clusterRev: 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.
+		// 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 left
+		// at the default `clusterSize: 10`, where the content quorum can never be met — re-fetches an
+		// archive on every read of that block. Correct, and self-limiting once the cohort can agree; if
+		// 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]);
 	}
 
 	/**
-	 * Query cluster peers for their latest revision and return the highest
-	 * revision corroborated by a quorum of distinct peers.
+	 * Bring this node up to the cohort-corroborated `corroborated`, returning the revision it holds
+	 * afterwards when that is an advance over `local`, else `undefined`.
+	 *
+	 * Two mechanisms, cheapest first:
+	 *  1. **Promote a local pending** — free, no network, and the only mechanism that existed before
+	 *     block acquisition. Covers the node that saw the pend and missed the commit broadcast.
+	 *  2. **Acquire the bytes from the cohort** ({@link AcquireBlockCallback}) — covers everything else,
+	 *     including a block this node has never seen at all.
+	 *
+	 * **Why acquisition is gated here and not on a plain local miss.** `BlockStorage.getBlock` returns
+	 * `undefined` for a block with no local metadata *without* consulting its restore callback, so that
+	 * an insert probing a fresh random block id for a collision does not cost a network fetch. That
+	 * remains true: this method runs only after {@link queryClusterForLatest} produced a quorum-
+	 * corroborated `(rev, actionId)`, which a genuinely non-existent block can never produce (no peer
+	 * claims it, so `selectQuorumRev` declines and `fetchBlockFromCluster` returns before reaching
+	 * here). The cost of a genuine absence is unchanged — the latest-query round trip that already
+	 * happened — while a block the cohort demonstrably holds is no longer thrown away.
+	 *
+	 * Cohort peer ids are passed straight through: the callback filters self out and caps its own
+	 * corroboration quorum by how many peers could answer at all.
+	 */
+	private async restoreCorroborated(
+		blockId: BlockId,
+		corroborated: ActionRev,
+		local: ActionRev | undefined,
+		cohortPeerIds: string[]
+	): Promise<number | undefined> {
+		const promoted = await this.promoteCorroborated(blockId, corroborated);
+		if (isAdvanceOver(promoted, local)) {
+			return promoted;
+		}
+
+		if (!this.acquireBlockFromCohort) {
+			return undefined;
+		}
+		try {
+			// Bounded: a stalled cohort peer must not hold up the caller's read. Persisting happens
+			// inside the callback via `saveReplicatedBlock`, which takes the per-block commit latch —
+			// safe to call from here because the read path holds no latch of its own (`StorageRepo.get`
+			// acquires and releases it around the promotion above, and nothing wraps this method).
+			await withDeadline(
+				this.acquireBlockFromCohort(blockId, corroborated, cohortPeerIds),
+				RECONCILE_TIMEOUT_MS,
+				`block acquisition for ${blockId}`
+			);
+		} 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 });
+			return undefined;
+		}
+		const acquired = await this.readLocalRev(blockId);
+		return isAdvanceOver(acquired, local) ? acquired : undefined;
+	}
+
+	/**
+	 * Promote a corroborated action this node already holds as a local pending — the no-network half of
+	 * the repair. Returns the local revision afterwards.
+	 *
+	 * A pending-only block (metadata seeded by `savePendingTransaction`, no committed revision) asked
+	 * for a forward revision throws out of `BlockStorage.ensureRevision` when no restore can supply it.
+	 * On THIS path that is an absence, not a read failure — acquisition is precisely the mechanism that
+	 * can supply it — so the throw is logged and swallowed rather than short-circuiting the caller.
+	 */
+	private async promoteCorroborated(blockId: BlockId, corroborated: ActionRev): Promise<number | undefined> {
+		try {
+			return await this.readLocalRev(blockId, { committed: [corroborated], rev: corroborated.rev });
+		} catch (err) {
+			log('cluster-fetch:promote-unavailable', { blockId, rev: corroborated.rev, error: (err as Error).message });
+			return undefined;
+		}
+	}
+
+	/** This node's own `latest.rev` for a block, optionally driving a promotion context through the read. */
+	private async readLocalRev(blockId: BlockId, context?: ActionContext): Promise<number | undefined> {
+		const result = await this.storageRepo.get({ blockIds: [blockId], context });
+		return result[blockId]?.state?.latest?.rev;
+	}
+
+	/**
+	 * How many peers other than this node could corroborate a claim about a block, given a
+	 * cohort view of `peerIds`. Deliberately the MAX of what we observe and what the
+	 * configured cluster size implies: the corroboration floor may only be relaxed for a
+	 * cohort that is genuinely small, never for one that merely *looks* small. `findCluster`
+	 * results are unauthenticated, so a partition — or an attacker with routing influence —
+	 * can shrink this node's view to itself plus one peer; measuring against the configured
+	 * size keeps that shrunken view from talking the requirement down to a single voter.
+	 * The escape hatch for a real two-node deployment is therefore to configure
+	 * `clusterSize: 2`, an explicit operator declaration, mirroring how
+	 * `allowUnvalidatedSmallCluster` gates the membership admission floor.
+	 */
+	private corroboratorCapacity(peerIds: string[]): number {
+		const selfId = this.localPeerId?.toString();
+		const observed = peerIds.filter(id => id !== selfId).length;
+		return Math.max(observed, this.clusterSize - 1);
+	}
+
+	/**
+	 * Query cluster peers for their latest revision and return the highest revision
+	 * corroborated by a quorum of distinct peers, alongside this node's own latest.
 	 *
 	 * Replaces the old "max rev any single peer reports" — which let one lying
 	 * peer over-reporting its revision steer restoration — with quorum
-	 * corroboration on the exact `(rev, actionId)` pair (see
-	 * {@link selectQuorumRev}). The local node's own latest is included as a
-	 * corroborating vote because `clusterLatestCallback` self-short-circuits to
-	 * local storage. Returns `undefined` (keep local, do not restore) when no
-	 * revision is corroborated.
+	 * corroboration on the exact `(rev, actionId)` pair (see {@link selectQuorumRev}).
+	 *
+	 * This node's own answer is split out of the claim set rather than counted in it:
+	 * `clusterLatestCallback` short-circuits self to local storage, so including it let a
+	 * reader whose only peer timed out "corroborate" the very revision it was trying to
+	 * repair. It is returned separately so the caller can compare, not vote.
 	 *
 	 * NOTE: the quorum is corroboration-of-a-claim, NOT Sybil-resistant cohort
-	 * membership — a peer minting fresh keypairs still casts a vote. Commit-cert
-	 * + membership anchoring is deferred to backlog
+	 * membership — a peer minting fresh keypairs still casts a vote, and the claims
+	 * themselves are bare assertions (a `BlockArchive` carries no commit certificate, so
+	 * there is nothing here to verify a `(rev, actionId)` against). Commit-cert +
+	 * membership anchoring is deferred to backlog
 	 * `debt-read-repair-commit-cert-verification`.
 	 */
-	private async queryClusterForLatest(peerIds: string[], blockId: BlockId, context?: ActionContext): Promise<ActionRev | undefined> {
+	private async queryClusterForLatest(peerIds: string[], blockId: BlockId, context?: ActionContext): Promise<ClusterLatestQuery> {
 		// Add timeout wrapper to prevent hanging on unresponsive peers
 		const withTimeout = <T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> =>
 			Promise.race([
@@ -356,18 +545,28 @@ export class CoordinatorRepo implements IRepo {
 			})
 		);
 
+		const selfId = this.localPeerId?.toString();
+		let local: ActionRev | undefined;
 		const claims: RevClaim[] = [];
 		for (const result of latestResults) {
-			if (result.status === 'fulfilled' && result.value.value) {
-				const { peerIdStr, value } = result.value;
-				claims.push({ peerId: peerIdStr, rev: value.rev, actionId: value.actionId });
+			if (result.status !== 'fulfilled' || !result.value.value) continue;
+			const { peerIdStr, value } = result.value;
+			if (peerIdStr === selfId) {
+				local = value;
+				continue;
 			}
+			claims.push({ peerId: peerIdStr, rev: value.rev, actionId: value.actionId });
 		}
 
-		const selected = selectQuorumRev(claims, this.simpleMajorityThreshold);
+		const capacity = this.corroboratorCapacity(peerIds);
+		const selected = selectQuorumRev(claims, this.simpleMajorityThreshold, capacity);
 		if (!selected) {
-			log('cluster-fetch:no-quorum', { blockId, responders: claims.length });
-			return undefined;
+			log('cluster-fetch:no-quorum', {
+				blockId,
+				responders: claims.length,
+				required: quorumSize(claims.length, this.simpleMajorityThreshold, capacity)
+			});
+			return { local };
 		}
 
 		// Best-effort: penalize peers whose claim contradicts the corroborated pair
@@ -375,7 +574,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 { actionId: selected.actionId, rev: selected.rev };
+		return { corroborated: { actionId: selected.actionId, rev: selected.rev }, local };
 	}
 
 	/**