@optimystic/db-p2p 1.0.0-beta.3 → 1.1.0

package/src/cluster/cluster-repo.ts

@@ -1,7 +1,7 @@
-import type { IRepo, ClusterRecord, ClusterPeers, Signature, RepoMessage, ITransactionValidator, ClusterConsensusConfig, UnvalidatablePendPolicy, CommitResult, PendResult, BlockId, ActionId, ActionRev, CommitRequest, CommitCert, InvalidateRequest, MemberApplyOutcome } from "@optimystic/db-core";
+import type { IRepo, ClusterRecord, ClusterPeers, Signature, RepoMessage, ITransactionValidator, ClusterConsensusConfig, UnvalidatablePendPolicy, CommitResult, PendResult, PendRequest, BlockId, ActionId, ActionRev, CommitRequest, CommitCert, InvalidateRequest, MemberApplyOutcome } from "@optimystic/db-core";
 import type { ICluster } from "@optimystic/db-core";
 import type { IPeerNetwork } from "@optimystic/db-core";
-import { blockIdsForTransforms, isOwnRevision, isConflictFailure, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
+import { blockIdsForTransforms, transformForBlockId, isOwnRevision, isConflictFailure, DEFAULT_SUPER_MAJORITY_THRESHOLD, localDurability } from "@optimystic/db-core";
 import { computeClusterCommitHash, computeClusterMessageHash, computeClusterPromiseHash, membershipDigest, recordMembershipDigest, clusterVoteSigningPayload, clusterVoteVerificationPayload } from "@optimystic/db-core";
 import { verifyInvalidationCertificate, type ArbitratorSetRecompute } from "../dispute/invalidation.js";
 import { buildCommitCert, invalidationActionId } from "./commit-cert.js";
@@ -17,12 +17,15 @@ import type { FretService } from "p2p-fret";
 import type { IPeerReputation } from "../reputation/types.js";
 import { PenaltyReason } from "../reputation/types.js";
 import type { ITransactionStateStore } from "./i-transaction-state-store.js";
-import { isMissingBaseRevisionFailure, type CommitDigestPreview, type ICommitDigestPreviewer, type ICommitProofPersister, type IRevisionActionReader } from "../storage/storage-repo.js";
+import { isMissingBaseRevisionFailure, type CommitDigestPreview, type ICommitDigestPreviewer, type ICommitProofPersister, type IRevisionActionReader, type IPendingClaimReader } from "../storage/storage-repo.js";
+import { isReservationAgainst, reservationRequestFor, cohortCanMissAPend, type PendingClaim, type ReservationRequest } from "../storage/pending-claim.js";
+import { StuckReservationTracker } from "../repo/stuck-reservation.js";
 import { checkPendValidation } from "../pend-validation.js";
 import { getAffectedBlockIds } from "./record-operations.js";
 import { operationsConflict, resolveRace } from "./race-resolution.js";
 import { buildBlockCommitProof, mintSoloCommitProof, type BlockCommitProof } from "./commit-proof.js";
 import { RECONCILE_TIMEOUT_MS } from "./reconcile-block.js";
+import type { CommittedHolders } from "./rebalance-monitor.js";
 
 const log = createLogger('cluster-member')
 
@@ -68,6 +71,45 @@ type VerifyOutcome =
 	| { valid: true }
 	| { valid: false; penalize: boolean };
 
+/**
+ * This member's promise-round decision on a record: approve, or one of two *different kinds* of no.
+ *
+ * The distinction is the whole reason the type exists. `invalid` is a validity judgement — the record
+ * is wrong and will be wrong on every retry — and becomes a `reject` vote the coordinator counts
+ * toward the permanent-rejection threshold. `held` is "not right now": the pend's blocks are reserved
+ * by a different unresolved action in this member's storage, a condition that disappears the moment
+ * that rival commits or cancels, and it becomes a `held` vote counted toward neither approvals nor
+ * rejections.
+ *
+ * A boolean plus prose cannot carry that difference, and collapsing the two was a real defect rather
+ * than a tidiness question: on a cohort of three or fewer members `maxAllowedRejections` is zero at
+ * the default threshold, so one member saying "someone else is holding this right now" became a
+ * permanent `ValidatorRejectionError` for the whole transaction.
+ *
+ * `reason` stays optional on the `invalid` arm because it is signed: it is folded into the vote
+ * payload verbatim, and an absent reason and an empty one must keep producing the bytes they do today.
+ */
+type PromiseVerdict =
+	| { valid: true }
+	| { valid: false; kind: 'invalid'; reason?: string }
+	/** `heldBy` is the rival's ACTION id (storage's pending list), never a messageHash — see {@link Signature}. */
+	| { valid: false; kind: 'held'; reason: string; heldBy: ActionId };
+
+/** A refusal that judges the record invalid — the permanent kind, and every kind but the pending-conflict one. */
+function invalidVerdict(reason?: string): PromiseVerdict {
+	return { valid: false, kind: 'invalid', reason };
+}
+
+/**
+ * Widen a boolean-plus-prose check into a {@link PromiseVerdict}. Every check written this way judges
+ * validity, so its refusal is the permanent kind; only the pending-conflict branch of
+ * {@link ClusterMember.validatePendOperations} produces the transient one, and it builds its verdict
+ * directly.
+ */
+function verdictOf(result: { valid: boolean; reason?: string }): PromiseVerdict {
+	return result.valid ? { valid: true } : invalidVerdict(result.reason);
+}
+
 /**
  * Actively reconciles a block this member committed without having seen the matching
  * pend (cohort drift between the independent pend and commit cluster-transactions).
@@ -91,6 +133,15 @@ export type ReconcileBlockCallback = (blockId: BlockId, committed: ActionRev, co
  */
 export type CommitCertificateSink = (actionId: ActionId, cert: CommitCert) => void;
 
+/**
+ * Sink for who is known to hold a commit this node's own storage durably holds — fed to the rebalance
+ * monitor so it does not push freshly committed blocks back to the members that stored them (see
+ * `RebalanceMonitor.recordCommittedHolders`). Fired by the member after applying a consensus commit,
+ * and by `CoordinatorRepo.commit` when it acknowledges one. Optional; a throwing sink is isolated +
+ * logged (it must never break consensus or the writer's answer).
+ */
+export type CommittedHoldersSink = (committed: CommittedHolders) => void;
+
 /**
  * Applies a consensus-ordered {@link InvalidateRequest} to local storage — the deterministic
  * reversal every member runs once consensus on the invalidation is reached. The implementation
@@ -179,6 +230,14 @@ export const MEMBERSHIP_NOT_ADMITTED = 'membership-not-admitted';
  */
 export const CONTENT_DIGEST_MISMATCH = 'content-digest-mismatch';
 
+/**
+ * Stable reject reason a member emits when a commit declares, for a block, a base revision
+ * (`CommitRequest.blockDigests[id].baseRev`) other than the one the same action's pend carried to
+ * this member (`PendRequest.baseRevs`, kept with the pending record) — see
+ * `ClusterMember.validateCommitBaseDeclarations`. Signed like its sibling above.
+ */
+export const BASE_DECLARATION_DISAGREES = 'base-declaration-disagrees';
+
 /**
  * The two stable reject reasons a validator-configured member emits from the shared
  * {@link checkPendValidation}: `PEND_NOT_VALIDATABLE` for a pend carrying no `validation` payload
@@ -205,6 +264,8 @@ interface ClusterMemberComponents {
 	reconcileBlock?: ReconcileBlockCallback;
 	/** Receives the consensus commit cert per committed action; see {@link CommitCertificateSink}. */
 	onCommitCertificate?: CommitCertificateSink;
+	/** Receives who holds each consensus commit this member durably applied; see {@link CommittedHoldersSink}. */
+	onCommittedHolders?: CommittedHoldersSink;
 	/** Applies a consensus-ordered invalidation to local storage; see {@link InvalidationApplySink}. */
 	onInvalidate?: InvalidationApplySink;
 	/** Layer-2 arbitrator-set recompute for invalidation verification; see {@link RecomputeArbitratorSetCapability}. */
@@ -244,7 +305,8 @@ export function clusterMember(components: ClusterMemberComponents): ClusterMembe
 		components.onInvalidate,
 		components.recomputeArbitratorSet,
 		components.deriveExpectedCluster,
-		components.now
+		components.now,
+		components.onCommittedHolders
 	);
 }
 
@@ -301,6 +363,12 @@ export class ClusterMember implements ICluster {
 	// applyConsensusOperation swallowed a refusal whose real cause was a RIVAL action holding the
 	// requested revision. Pruned alongside executedTransactions (same TTL).
 	private executedCommitResults: Map<string, CommitResult> = new Map();
+	// The messageHashes whose retained commit refusal above has the BEHIND shape (missing pend or
+	// missing base — this member held no usable revision), as opposed to the ahead shape, which must
+	// never be reconciled downward. Recorded from the apply branch that produced the refusal rather
+	// than read back from its prose. Only these are eligible for reconcileRefusedCommit. Same TTL,
+	// pruning and rollback as executedCommitResults.
+	private behindCommitRefusals: Set<string> = new Set();
 	// Conflict-shaped pend refusals this member's storage produced at consensus-apply, keyed by the
 	// refused action's id rather than by messageHash. The messageHash-keyed map above cannot serve the
 	// commit-promise guard: a commit is a DIFFERENT message with a different hash, so a member holding
@@ -314,6 +382,14 @@ export class ClusterMember implements ICluster {
 	// inside the sink); this map only spares redundant work when the same invalidation reaches
 	// consensus twice (rebroadcast / sync) under different message hashes. (-> appliedAt timestamp)
 	private appliedInvalidations: Map<string, number> = new Map();
+	/**
+	 * Per block, what this member's own `held` votes have added up to — the member-side instance of
+	 * the counter `CoordinatorRepo.noteStuckReservation` keeps from the coordinator's vantage. Fed by
+	 * every `held` verdict {@link validatePendOperations} casts, so a reservation only THIS member
+	 * holds (one the coordinator's storage cannot corroborate) is still named, once, where the record
+	 * lives. Forgotten for a block the moment a vote finds it no longer reserved.
+	 */
+	private readonly stuckReservations = new StuckReservationTracker(1000);
 	// Queue of transactions to clean up
 	private cleanupQueue: string[] = [];
 	// Serialize concurrent updates for the same transaction
@@ -368,7 +444,8 @@ export class ClusterMember implements ICluster {
 		private readonly onInvalidate?: InvalidationApplySink,
 		private readonly recomputeArbitratorSet?: RecomputeArbitratorSetCapability,
 		private readonly deriveExpectedCluster?: DeriveExpectedClusterCallback,
-		now?: () => number
+		now?: () => number,
+		private readonly onCommittedHolders?: CommittedHoldersSink
 	) {
 		this.now = now ?? ((): number => Date.now());
 		this.superMajorityThreshold = consensusConfig?.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD;
@@ -420,6 +497,7 @@ export class ClusterMember implements ICluster {
 		this.cleanupQueue.length = 0;
 		this.executedPendResults.clear();
 		this.executedCommitResults.clear();
+		this.behindCommitRefusals.clear();
 		this.refusedPendActions.clear();
 	}
 
@@ -588,6 +666,15 @@ export class ClusterMember implements ICluster {
 					});
 					// Our own vote can be terminal (a reject where maxAllowedRejections is 0) or complete
 					// the super-majority — recompute rather than guess which.
+					//
+					// Deliberately NOT the conflict vote's `shouldPersist = false`, for a `held` vote or
+					// any other. A conflict vote clears the record because this member holds the WINNER
+					// in `activeTransactions` and persisting the loser would reserve the same blocks a
+					// second time. A `held` vote has no such twin: the rival lives in durable storage,
+					// not in that table, so this record's entry is the only one and dropping it would
+					// only make this member forget a transaction the rest of the cohort may still
+					// carry to super-majority. Where one `held` vote IS terminal (a small cohort), the
+					// recomputed phase is `ConflictSuperseded`, which clears the record anyway.
 					continue;
 				case TransactionPhase.OurConflictVoteNeeded:
 					currentRecord = await this.handleConflictVoteNeeded(currentRecord, phaseResult.conflictsWith);
@@ -640,7 +727,7 @@ export class ClusterMember implements ICluster {
 					shouldPersist = false;
 					break phaseLoop;
 				case TransactionPhase.Promising:
-					// We have already voted (approve, reject, or conflict); the record is still
+					// We have already voted (approve, reject, conflict, or held); the record is still
 					// collecting promises from the rest of the cohort. Nothing to add — retain the
 					// record only if our vote wasn't a conflict (`shouldPersist` already reflects that).
 					log('cluster-member:phase-promising-waiting', {
@@ -788,8 +875,9 @@ export class ClusterMember implements ICluster {
 
 	/**
 	 * Compares existing vs incoming signatures for the same peers.
-	 * If a peer's vote type changed (approve↔reject), that's equivocation:
-	 * report a penalty and keep the first-seen signature.
+	 * ANY change of vote type is equivocation — the comparison is over `Signature['type']`, so it
+	 * covers every kind without enumerating them (a new kind joins the check by existing): report a
+	 * penalty and keep the first-seen signature.
 	 * New peers are accepted normally.
 	 */
 	private detectEquivocation(
@@ -991,19 +1079,21 @@ export class ClusterMember implements ICluster {
 		const maxAllowedRejections = peerCount - superMajority;
 
 		// Check for rejections — rejected if too many rejections to ever reach super-majority.
-		// ONLY `reject` votes count here: a `conflict` vote is "not now", never a validity
-		// judgement, so it must not push a record into the permanent `Rejected` phase.
+		// ONLY `reject` votes count here: `conflict` and `held` both mean "not now", never a validity
+		// judgement, so neither may push a record into the permanent `Rejected` phase.
 		const rejectedPromises = Object.values(record.promises).filter(s => s.type === 'reject');
-		const conflictPromises = Object.values(record.promises).filter(s => s.type === 'conflict');
+		const retryableRefusals = Object.values(record.promises).filter(s => s.type === 'conflict' || s.type === 'held');
 		const rejectedCommits = Object.values(record.commits).filter(s => s.type === 'reject');
 		if (rejectedPromises.length > maxAllowedRejections || this.hasMajority(rejectedCommits.length, peerCount)) {
 			return { phase: TransactionPhase.Rejected };
 		}
 
-		// Conflict votes don't judge validity, but enough of them still make super-majority
+		// Retryable refusals don't judge validity, but enough of them still make super-majority
 		// unreachable — a distinct terminal outcome (retryable as a fresh transaction) so logs and
-		// reputation-adjacent paths keep meaning what they say.
-		if (conflictPromises.length > 0 && rejectedPromises.length + conflictPromises.length > maxAllowedRejections) {
+		// reputation-adjacent paths keep meaning what they say. `held` joins `conflict` here for the
+		// same reason `conflict` clears its record: a member that keeps reserving the blocks of a
+		// transaction that provably cannot win holds them against the very retry meant to win.
+		if (retryableRefusals.length > 0 && rejectedPromises.length + retryableRefusals.length > maxAllowedRejections) {
 			return { phase: TransactionPhase.ConflictSuperseded };
 		}
 
@@ -1073,24 +1163,20 @@ export class ClusterMember implements ICluster {
 		// peer set is a legitimate cluster it belongs to, and refuses (reject vote) rather than rubber-stamping
 		// a set the coordinator chose (e.g. a self-shrunk minority-partition set). On admission failure we skip
 		// pend validation entirely and emit the membership rejection.
-		const validationResult = await this.evaluatePromise(record);
-
-		const promiseHash = await this.computePromiseHash(record);
-		const type = validationResult.valid ? 'approve' as const : 'reject' as const;
-		const rejectReason = validationResult.valid ? undefined : validationResult.reason;
-		const sig = await this.signVote(promiseHash, type, rejectReason);
+		const verdict = await this.evaluatePromise(record);
 
-		const signature: Signature = validationResult.valid
-			? { type: 'approve', signature: sig }
-			: { type: 'reject', signature: sig, rejectReason };
-
-		if (!validationResult.valid) {
-			log('cluster-member:validation-rejected', {
+		if (!verdict.valid) {
+			// Two tags, because the two refusals are two different events for an operator: one says the
+			// cohort judged a write invalid, the other says a write queued behind a live reservation.
+			log(verdict.kind === 'held' ? 'cluster-member:validation-held' : 'cluster-member:validation-rejected', {
 				messageHash: record.messageHash,
-				reason: validationResult.reason
+				reason: verdict.reason
 			});
 		}
 
+		const promiseHash = await this.computePromiseHash(record);
+		const signature = await this.signPromiseVerdict(promiseHash, verdict);
+
 		return {
 			...record,
 			promises: {
@@ -1100,6 +1186,23 @@ export class ClusterMember implements ICluster {
 		};
 	}
 
+	/**
+	 * Turn a {@link PromiseVerdict} into this member's signed promise vote — one vote kind per refusal
+	 * kind. The single place the mapping lives, so a new refusal kind cannot reach the wire as the
+	 * wrong vote: the coordinator's thresholds read only `Signature.type`, and until `held` existed the
+	 * transient refusal had nowhere to go but `reject`.
+	 */
+	private async signPromiseVerdict(promiseHash: string, verdict: PromiseVerdict): Promise<Signature> {
+		if (verdict.valid) {
+			return { type: 'approve', signature: await this.signVote(promiseHash, 'approve') };
+		}
+		if (verdict.kind === 'held') {
+			return { type: 'held', signature: await this.signVote(promiseHash, 'held', verdict.heldBy), heldBy: verdict.heldBy };
+		}
+		const rejectReason = verdict.reason;
+		return { type: 'reject', signature: await this.signVote(promiseHash, 'reject', rejectReason), rejectReason };
+	}
+
 	/**
 	 * Answer a record that lost the deterministic race to a transaction this member already holds
 	 * (`docs/correctness.md` Theorems 1 & 9: the loser is TOLD it lost, not ignored — an unanswered
@@ -1129,17 +1232,19 @@ export class ClusterMember implements ICluster {
 
 	/**
 	 * The full promise-phase decision for a record: admit the declared membership FIRST, then (only if
-	 * admitted) validate its pend operations, then its commit operations. Failing any yields a
-	 * `{ valid:false, reason }` the caller turns into a `reject` vote. Keeping the three separate keeps
+	 * admitted) validate its pend operations, then its commit operations. Failing any yields a refusal
+	 * the caller turns into a vote — a `reject` for every validity judgement here, and a `held` for the
+	 * one transient refusal {@link validatePendOperations} can make (see {@link PromiseVerdict}).
+	 * Keeping the checks separate keeps
 	 * the reason strings distinct — a `membership-not-admitted` reject is a different signal (feeds the
 	 * dispute path) than a stale-revision / custom-validator reject, which is different again from a
 	 * `content-digest-mismatch` (see {@link validateCommitOperations}). A record carries pend OR commit
 	 * operations, so in practice exactly one of the latter two has anything to inspect.
 	 */
-	private async evaluatePromise(record: ClusterRecord): Promise<{ valid: boolean; reason?: string }> {
+	private async evaluatePromise(record: ClusterRecord): Promise<PromiseVerdict> {
 		const admission = await this.admitMembership(record);
 		if (!admission.admit) {
-			return { valid: false, reason: admission.reason ?? MEMBERSHIP_NOT_ADMITTED };
+			return invalidVerdict(admission.reason ?? MEMBERSHIP_NOT_ADMITTED);
 		}
 		const pendValidation = await this.validatePendOperations(record);
 		if (!pendValidation.valid) {
@@ -1151,7 +1256,7 @@ export class ClusterMember implements ICluster {
 		// declared one).
 		const commitRevValidation = await this.validateCommitRevisions(record);
 		if (!commitRevValidation.valid) {
-			return commitRevValidation;
+			return verdictOf(commitRevValidation);
 		}
 		// Then our own refusal history: a commit whose pend THIS member refused, where local state
 		// still corroborates the refusal. Runs after the revision check because that one is sharper
@@ -1159,9 +1264,16 @@ export class ClusterMember implements ICluster {
 		// applied here; this arm covers the window where it has not.
 		const refusedPendValidation = await this.validateCommitAgainstRefusedPend(record);
 		if (!refusedPendValidation.valid) {
-			return refusedPendValidation;
+			return verdictOf(refusedPendValidation);
 		}
-		return await this.validateCommitOperations(record);
+		// The declared base before the declared content: it needs no materialization, and when the two
+		// disagree the digest check would be previewing operations computed against a different base
+		// than the one declared — its verdict names the symptom, this one names the cause.
+		const baseDeclarationValidation = await this.validateCommitBaseDeclarations(record);
+		if (!baseDeclarationValidation.valid) {
+			return verdictOf(baseDeclarationValidation);
+		}
+		return verdictOf(await this.validateCommitOperations(record));
 	}
 
 	/**
@@ -1459,11 +1571,21 @@ export class ClusterMember implements ICluster {
 
 	/**
 	 * Validates pend operations in a cluster record using the transaction validator.
-	 * Also checks for stale revisions, and for blocks held by a different unresolved pending
+	 * Also checks for stale revisions, and for blocks RESERVED by a different unresolved pending
 	 * action, to prevent consensus on operations that storage would refuse at apply.
 	 * Returns success if no validator is configured (backwards compatibility).
+	 *
+	 * Every refusal here is a validity judgement EXCEPT the pending-conflict one, which is transient by
+	 * construction and returns the `held` kind — see {@link PromiseVerdict}. Transient means the
+	 * reservation it answers is one its holder is still going to commit or cancel: a record claiming
+	 * the slot this pend wants, or a later one. A record claiming a slot the collection has already
+	 * moved past is NOT a reservation against this pend and is not refused on — see
+	 * {@link reservingRivals} — because its holder is never going to remove it: the holder either
+	 * committed at that slot on the rest of the cohort (this member missed the commit) or lost the
+	 * slot, and in both cases the record would otherwise refuse every later write to the block, from
+	 * every writer, for as long as this member lives.
 	 */
-	private async validatePendOperations(record: ClusterRecord): Promise<{ valid: boolean; reason?: string }> {
+	private async validatePendOperations(record: ClusterRecord): Promise<PromiseVerdict> {
 		// Find pend operations in the message
 		for (const operation of record.message.operations) {
 			if ('pend' in operation) {
@@ -1489,7 +1611,7 @@ export class ClusterMember implements ICluster {
 								blockId,
 								reason: blockResult.unavailable
 							});
-							return { valid: false, reason: `block ${blockId} unavailable (${blockResult.unavailable}): cannot verify revision` };
+							return invalidVerdict(`block ${blockId} unavailable (${blockResult.unavailable}): cannot verify revision`);
 						}
 						const latest = blockResult?.state?.latest;
 						if (latest !== undefined && latest.rev >= pendRequest.rev) {
@@ -1512,19 +1634,19 @@ export class ClusterMember implements ICluster {
 							// is NOT a StaleFailure producer, so StaleFailure.staleAt does not apply; the
 							// coordinator's own local re-read (CoordinatorRepo.classifyStaleRejection)
 							// supplies that number when it can confirm the revision itself.
-							return { valid: false, reason: `stale revision: block ${blockId} at rev ${latest.rev}, requested rev ${pendRequest.rev}` };
+							return invalidVerdict(`stale revision: block ${blockId} at rev ${latest.rev}, requested rev ${pendRequest.rev}`);
 						}
 					}
 				}
 
-				// Reject a pend whose blocks are held by a DIFFERENT unresolved pending action. This is
-				// the durable reservation the in-memory table (`findConflict` / `activeTransactions`)
+				// Refuse a pend whose blocks are RESERVED by a DIFFERENT unresolved pending action. This
+				// is the durable reservation the in-memory table (`findConflict` / `activeTransactions`)
 				// cannot provide: that table clears the moment the rival's PEND record reaches
 				// consensus, but the rival's storage pending record — written at pend-apply, removed at
 				// commit or cancel — spans exactly the pend→commit window in which `latest.rev` has not
 				// yet advanced. Storage's own pend would refuse this request at consensus-apply for the
-				// same reason (`StorageRepo.pend`'s listPendingTransactions scan); voting reject here
-				// moves that verdict into the phase where the cohort aggregates it, so the loser is
+				// same reason (`StorageRepo.pend`'s pending-claim scan, under the same rule); voting
+				// here moves that verdict into the phase where the cohort aggregates it, so the loser is
 				// refused with a real answer instead of burning a consensus round it cannot win. A
 				// member that has not yet applied the rival's pend has no record and simply abstains
 				// from this reason; the apply-time verdict catches that residual — retained locally
@@ -1533,19 +1655,53 @@ export class ClusterMember implements ICluster {
 				// member. Self is excluded so a redelivered pend
 				// for this same action stays approvable. An unavailable block carries no `pendings` and
 				// abstains (the rev branch above already fail-closes when a revision claim is at stake).
-				// Reason stays plain prose: it is fed to computeSigningPayload and carried as
-				// Signature.rejectReason, exactly like the stale-revision reason above.
+				//
+				// This is the ONE refusal in this method that is not a validity judgement: a RESERVING
+				// rival's record is removed the moment it commits or cancels, so the very same pend
+				// succeeds on retry. It therefore returns the `held` kind, which becomes a `held` vote
+				// the coordinator counts toward neither approvals nor rejections. `heldBy` carries the
+				// first rival as signed structured data; the prose reason names the same one, and stays
+				// prose because it is fed to computeSigningPayload exactly like the reasons above.
+				//
+				// Which rivals reserve is decided by the slot each record claims against what the
+				// incoming writer built on, not by the record's presence (`reservingRivals`): a record
+				// whose slot is at or below the base this pend declares for the block — or, for a pend
+				// naming no base, below the revision it requests — belongs to a commit this member missed
+				// or a race its holder lost, and would never clear on its own; refusing on it wedged the
+				// block for every writer (ticket `a-member-that-missed-a-commit-refuses-every-later-write`).
+				// Approving over it is safe because the incoming writer's operations were computed
+				// against a version of the block that already holds that record's change. This member
+				// comes current when the approved pend's own commit applies here — through
+				// `internalCommit`, or through the behind-reconcile its fork guard triggers. In a cohort
+				// that can reach its promise bar without one member (`cohortCanMissAPend`: four members up
+				// at the default threshold), a record claiming a slot PAST the declared base still
+				// reserves even when the requested revision has moved beyond it: that is a writer that
+				// read the block without the record's change — served by a member that never held the
+				// rival's pend — and admitting it would lose the change. See `isReservationAgainst`.
 				for (const blockId of blockIds) {
-					const rivals = (blockResults[blockId]?.state?.pendings ?? []).filter(actionId => actionId !== pendRequest.actionId);
-					if (rivals.length > 0) {
-						log('cluster-member:validation-pending-conflict', {
-							messageHash: record.messageHash,
-							blockId,
-							actionId: pendRequest.actionId,
-							rivals
-						});
-						return { valid: false, reason: `pending conflict: block ${blockId} held by unresolved action(s) ${rivals.join(', ')}` };
+					const rivalIds = (blockResults[blockId]?.state?.pendings ?? []).filter(actionId => actionId !== pendRequest.actionId);
+					const rivals = rivalIds.length === 0 ? [] : await this.reservingRivals(record, blockId, rivalIds, pendRequest);
+					if (rivals.length === 0) {
+						// Not reserved (any more): whatever episode this member was counting on the block
+						// has ended, so a later wedge gets its own count.
+						this.stuckReservations.forget([blockId]);
+						continue;
 					}
+					const heldBy = rivals[0]!;
+					log('cluster-member:validation-pending-conflict', {
+						messageHash: record.messageHash,
+						blockId,
+						actionId: pendRequest.actionId,
+						requestedRev: pendRequest.rev,
+						rivals
+					});
+					this.nameStuckReservation(blockId, rivals, pendRequest.actionId);
+					return {
+						valid: false,
+						kind: 'held',
+						heldBy,
+						reason: `pending conflict: block ${blockId} held by unresolved action(s) ${rivals.join(', ')}`
+					};
 				}
 
 				// Re-check the transaction when a validator is configured. The unvalidatable-pend
@@ -1572,7 +1728,7 @@ export class ClusterMember implements ICluster {
 						})
 				);
 				if (!validation.valid) {
-					return { valid: false, reason: validation.reason };
+					return invalidVerdict(validation.reason);
 				}
 			}
 		}
@@ -1580,6 +1736,88 @@ export class ClusterMember implements ICluster {
 		return { valid: true };
 	}
 
+	/**
+	 * Of the rival pending records `get` listed on `blockId`, the ones that RESERVE the block against
+	 * `pendRequest` — see `isReservationAgainst` for the rule, fed the pend's revision and the base it
+	 * declares for this block (`reservationRequestFor`, the same reading storage applies at apply).
+	 * Asks storage's {@link IPendingClaimReader} for the slot each record claims; a repo without that
+	 * capability (a plain `IRepo` mock) or a read that fails degrades to "every rival reserves", which
+	 * is the refusal this member cast before claims were recorded — never to silently admitting one. A
+	 * rival that `get` listed but that is gone by the time the claims are read has resolved in
+	 * between, and is not a rival any more.
+	 */
+	private async reservingRivals(record: ClusterRecord, blockId: BlockId, rivalIds: ActionId[], pendRequest: PendRequest): Promise<ActionId[]> {
+		const reader = this.storageRepo as IRepo & Partial<IPendingClaimReader>;
+		if (typeof reader.listPendingClaims !== 'function') {
+			return rivalIds;
+		}
+		let claims: PendingClaim[];
+		try {
+			claims = await reader.listPendingClaims(blockId);
+		} catch (err) {
+			log('cluster-member:pending-claims-read-error', { messageHash: record.messageHash, blockId, error: (err as Error).message });
+			return rivalIds;
+		}
+		const reservation = this.reservationRequestOf(record, pendRequest, blockId);
+		const claimOf = new Map(claims.map(claim => [claim.actionId, claim]));
+		const reserving: ActionId[] = [];
+		for (const actionId of rivalIds) {
+			const claim = claimOf.get(actionId);
+			if (claim === undefined) continue;
+			if (isReservationAgainst(claim, reservation)) {
+				reserving.push(actionId);
+			} else {
+				log('cluster-member:validation-pending-superseded', {
+					messageHash: record.messageHash,
+					blockId,
+					actionId: pendRequest.actionId,
+					requestedRev: pendRequest.rev,
+					baseRev: reservation.baseRev,
+					rival: actionId,
+					claimedRev: claim.rev
+				});
+			}
+		}
+		return reserving;
+	}
+
+	/** `pendRequest`'s {@link ReservationRequest} for `blockId`, logging a base the rule cannot read —
+	 *  never a refusal: `baseRevs` is untrusted wire data, and a malformed entry only drops that block
+	 *  back to the revision rule. The base is read only when `record`'s cohort can reach its promise
+	 *  super-majority without one of its members (`cohortCanMissAPend`); in a cohort that needs every
+	 *  member, a stray record on one member (a cancel that never reached it) would otherwise refuse
+	 *  every later writer for good, and no member can have missed the pend the base arm guards against. */
+	private reservationRequestOf(record: ClusterRecord, pendRequest: PendRequest, blockId: BlockId): ReservationRequest {
+		if (!cohortCanMissAPend(Object.keys(record.peers).length, this.superMajorityThreshold)) {
+			return { rev: pendRequest.rev };
+		}
+		const { request, ignoredBase } = reservationRequestFor(pendRequest, blockId, transformForBlockId(pendRequest.transforms, blockId));
+		if (ignoredBase !== undefined) {
+			log('cluster-member:pend-base-ignored', {
+				messageHash: record.messageHash,
+				blockId,
+				actionId: pendRequest.actionId,
+				requestedRev: pendRequest.rev,
+				base: ignoredBase
+			});
+		}
+		return request;
+	}
+
+	/**
+	 * Feed this member's own `held` vote to its {@link stuckReservations} counter and say, once per
+	 * episode and in words, when a block is wedged behind a reservation that is not going to clear —
+	 * the member-side twin of `CoordinatorRepo.noteStuckReservation`, for the reservations that
+	 * node cannot corroborate from its own storage. `peerId` is carried because this logger is not
+	 * suffixed with one and several members can share a process.
+	 */
+	private nameStuckReservation(blockId: BlockId, holders: readonly ActionId[], refusedActionId: ActionId): void {
+		const { named } = this.stuckReservations.note(new Map([[blockId, holders]]), refusedActionId);
+		for (const episode of named) {
+			log('cluster-member:stuck-reservation', { peerId: this.peerId.toString(), ...episode });
+		}
+	}
+
 	/**
 	 * Promise-round check that a commit record's requested revision is not already committed HERE
 	 * under a different action. This is the member-side arm that keeps a DEAD rival's re-broadcast
@@ -1793,6 +2031,113 @@ export class ClusterMember implements ICluster {
 		return undefined;
 	}
 
+	/**
+	 * Promise-round check that a commit declares, for each block, the base revision the same action's
+	 * PEND carried to this member. The author says the base twice — `PendRequest.baseRevs[id]`, kept
+	 * with this member's pending record as `PendingClaim.baseRev`, and
+	 * `CommitRequest.blockDigests[id].baseRev` — and an honest author says the same thing both times
+	 * (`Tracker` pins the base at staging; the pend and the digest both read that pin). When they
+	 * differ, this member's record holds operations computed against a base other than the one the
+	 * commit is about to be applied as, so vote reject with {@link BASE_DECLARATION_DISAGREES}.
+	 * `StorageRepo.internalCommit` refuses the same shape at apply (`guardCommitBase`); refusing here
+	 * too puts a signed verdict on the record one round earlier, and when the cohort's records agree
+	 * with each other but not with the commit (a writer whose commit contradicts its own pend) the
+	 * whole cohort refuses at the vote, where the apply-time refusal alone would have every member
+	 * refuse after consensus and reconcile against a revision nobody holds.
+	 *
+	 * Needs no preview, so it runs on a repo that can read one record's claim
+	 * ({@link IPendingClaimReader}`.pendingClaimOf`) whether or not it can materialize. Abstains — votes
+	 * as it would without the check — whenever it cannot compare: the commit declares nothing, an entry
+	 * is surplus to `blockIds` or carries no numeric `baseRev` (untrusted wire data, same posture as the
+	 * digest check), this member holds no record for the action on the block, the record carries no
+	 * base (an inserted or deleted block, a base-less sender, or a record written before bases were
+	 * kept), the read fails — or this member does not hold the declared base as its latest.
+	 *
+	 * That last abstain is what keeps an HONEST retry off this reject. The one disagreement an honest
+	 * writer can meet here is a stale record from an earlier attempt of a retried action (same action
+	 * id) meeting the retry's commit, when the retry's pend — which would have overwritten the record
+	 * — never reached this member. Such a member is typically behind: it missed a pend, and the retry
+	 * declares a base the rest of the cohort moved to. At three members one reject sinks the commit
+	 * record (the default super-majority allows none), where abstaining lets the others commit and
+	 * leaves this member to `guardCommitBase`, which refuses to apply the stale record and reconciles.
+	 * When this member's latest IS the declared base, the stale operations are exactly what it would
+	 * apply over it, and the digest check below rejects the same shape whenever they materialize
+	 * differently; rejecting here names the cause instead.
+	 */
+	private async validateCommitBaseDeclarations(record: ClusterRecord): Promise<{ valid: boolean; reason?: string }> {
+		const reader = this.storageRepo as IRepo & Partial<IPendingClaimReader>;
+		if (typeof reader.pendingClaimOf !== 'function') {
+			return { valid: true };
+		}
+		for (const operation of record.message.operations) {
+			if (!('commit' in operation)) {
+				continue;
+			}
+			const commit = operation.commit;
+			if (!commit.blockDigests) {
+				continue;
+			}
+			const committedIds = new Set<string>(commit.blockIds);
+			for (const [blockId, declared] of Object.entries(commit.blockDigests)) {
+				const declaredBaseRev: unknown = declared?.baseRev;
+				if (!committedIds.has(blockId) || typeof declaredBaseRev !== 'number') {
+					continue;
+				}
+				let storedBaseRev: number | undefined;
+				try {
+					storedBaseRev = (await reader.pendingClaimOf(blockId as BlockId, commit.actionId))?.baseRev;
+				} catch (err) {
+					log('cluster-member:base-declaration-read-error', {
+						messageHash: record.messageHash,
+						blockId,
+						error: err instanceof Error ? err.message : String(err)
+					});
+					continue; // a local read fault is an abstain, never a verdict
+				}
+				if (storedBaseRev === undefined || storedBaseRev === declaredBaseRev) {
+					continue;
+				}
+				const latestRev = await this.latestRevOf(record, blockId as BlockId);
+				if (latestRev !== declaredBaseRev) {
+					log('cluster-member:base-declaration-disagrees-abstained', {
+						messageHash: record.messageHash,
+						blockId,
+						actionId: commit.actionId,
+						storedBaseRev,
+						declaredBaseRev,
+						latestRev
+					});
+					continue;
+				}
+				log('cluster-member:base-declaration-disagrees', {
+					messageHash: record.messageHash,
+					blockId,
+					actionId: commit.actionId,
+					rev: commit.rev,
+					storedBaseRev,
+					declaredBaseRev
+				});
+				return { valid: false, reason: BASE_DECLARATION_DISAGREES };
+			}
+		}
+		return { valid: true };
+	}
+
+	/** This member's own committed revision of `blockId` (raw storage, no cluster recursion), or
+	 *  `undefined` when it holds none or the read fails — a fault reads as "cannot judge". */
+	private async latestRevOf(record: ClusterRecord, blockId: BlockId): Promise<number | undefined> {
+		try {
+			return (await this.storageRepo.get({ blockIds: [blockId] }))[blockId]?.state?.latest?.rev;
+		} catch (err) {
+			log('cluster-member:base-declaration-read-error', {
+				messageHash: record.messageHash,
+				blockId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+			return undefined;
+		}
+	}
+
 	/**
 	 * Promise-round check of a commit record's declared content digests
 	 * (`CommitRequest.blockDigests`) against what this member's OWN pended copy of each transform
@@ -1991,6 +2336,7 @@ export class ClusterMember implements ICluster {
 			this.executedTransactions.delete(record.messageHash);
 			this.executedPendResults.delete(record.messageHash);
 			this.executedCommitResults.delete(record.messageHash);
+			this.behindCommitRefusals.delete(record.messageHash);
 			for (const operation of record.message.operations) {
 				if ('pend' in operation) this.refusedPendActions.delete(operation.pend.actionId);
 			}
@@ -2138,7 +2484,7 @@ export class ClusterMember implements ICluster {
 					membershipVersion: record.membershipVersion
 				});
 			}
-			const applied = await this.applyCommitToStorage(record, commit, proof);
+			const { applied, behind } = await this.applyCommitToStorage(record, commit, proof);
 			// Retain the POST-RECONCILE durable verdict (see getExecutedCommitResult and
 			// withOwnApplyOutcome): what this member's storage holds NOW, after any behind-reconcile the
 			// apply triggered — not what the first apply attempt said. A member that pulled the
@@ -2147,7 +2493,7 @@ export class ClusterMember implements ICluster {
 			// verdicts — its own member's through getExecutedCommitResult, every other member's off the
 			// response record — and the two readers must see the same answer, hence one verdict,
 			// computed once, retained here for both.
-			this.executedCommitResults.set(messageHash, await this.durableCommitVerdict(commit, applied));
+			this.retainCommitVerdict(record, commit, await this.durableCommitVerdict(commit, applied), behind);
 			return;
 		}
 		if ('invalidate' in operation) {
@@ -2159,12 +2505,14 @@ export class ClusterMember implements ICluster {
 	/**
 	 * Apply one consensus commit to local storage, tolerating every divergence shape the way the
 	 * doc comment on {@link applyConsensusOperation} describes and reconciling the behind ones.
-	 * Returns storage's own result — or, for the thrown missing-pend shape, which produces no
+	 * `applied` is storage's own result — or, for the thrown missing-pend shape, which produces no
 	 * `CommitResult` at all, a refusal built from the throw — so {@link durableCommitVerdict} works
-	 * from one uniform shape. Genuine faults (a bare-reason returned failure, an unrecognized throw)
-	 * propagate so {@link handleConsensus} rolls back the executed marker and rethrows.
+	 * from one uniform shape. `behind` is true exactly when one of the two behind branches ran, which
+	 * is what makes a refusal eligible for {@link reconcileRefusedCommit}. Genuine faults (a
+	 * bare-reason returned failure, an unrecognized throw) propagate so {@link handleConsensus} rolls
+	 * back the executed marker and rethrows.
 	 */
-	private async applyCommitToStorage(record: ClusterRecord, commit: CommitRequest, proof: BlockCommitProof | undefined): Promise<CommitResult> {
+	private async applyCommitToStorage(record: ClusterRecord, commit: CommitRequest, proof: BlockCommitProof | undefined): Promise<{ applied: CommitResult; behind: boolean }> {
 		const messageHash = record.messageHash;
 		let result: CommitResult;
 		try {
@@ -2184,12 +2532,12 @@ export class ClusterMember implements ICluster {
 				// cohort peer so the block is no longer under-replicated. Best-effort:
 				// failures are logged inside, never thrown (a throw would reset the stream).
 				await this.reconcileDivergentCommit(record, commit);
-				return { success: false, reason: (err as Error).message };
+				return { applied: { success: false, reason: (err as Error).message }, behind: true };
 			}
 			throw err;
 		}
 		if (result.success) {
-			return result;
+			return { applied: result, behind: false };
 		}
 		// success:false is a StaleFailure. `missing` ⇒ ahead/stale divergence
 		// (we already hold ≥ this rev): tolerate, do NOT reconcile downward. A
@@ -2219,7 +2567,7 @@ export class ClusterMember implements ICluster {
 				reason: result.reason,
 				hasMissing: true
 			});
-			return result;
+			return { applied: result, behind: false };
 		}
 		// This member holds no materializable base for one of the blocks, so
 		// `StorageRepo.commit` REFUSED rather than record a revision it could never serve.
@@ -2235,11 +2583,64 @@ export class ClusterMember implements ICluster {
 				reason: result.reason
 			});
 			await this.reconcileDivergentCommit(record, commit);
-			return result;
+			return { applied: result, behind: true };
 		}
 		throw new Error(`Consensus commit for action ${commit.actionId} failed: ${result.reason ?? 'unknown reason'}`);
 	}
 
+	/**
+	 * Retain `verdict` as this member's durable verdict for `record`'s commit (see
+	 * {@link executedCommitResults}), remember whether a refusal was the behind shape, and — once the
+	 * verdict is a success — report the committed holders. Shared by the consensus apply and
+	 * {@link reconcileRefusedCommit} so both leave the same state behind.
+	 */
+	private retainCommitVerdict(record: ClusterRecord, commit: CommitRequest, verdict: CommitResult, behind: boolean): void {
+		this.executedCommitResults.set(record.messageHash, verdict);
+		if (verdict.success) {
+			this.behindCommitRefusals.delete(record.messageHash);
+			this.reportCommittedHolders(record, commit);
+		} else if (behind) {
+			this.behindCommitRefusals.add(record.messageHash);
+		}
+	}
+
+	/**
+	 * One more reconcile for a commit this member already applied at consensus but could not hold:
+	 * its retained verdict is a BEHIND-shaped refusal (missing pend or missing base), and the
+	 * reconcile that ran during the apply found no cohort peer holding the revision yet. The
+	 * coordinating node calls this for its own member once the remote members have applied and at
+	 * least one reported holding the revision. Its own delivery goes first (see
+	 * `ClusterCoordinator.broadcastMergedRecord`), so that first reconcile ran before anyone else
+	 * held anything. The remote holder's copy carries the cohort's commit proof, so the existing
+	 * certified single-holder path adopts it; no new trust is involved.
+	 *
+	 * Does nothing unless the retained verdict for `record.messageHash` is a behind refusal; in
+	 * particular an ahead-shaped refusal (`missing`) is never reconciled downward. Recomputes and
+	 * re-retains the durable verdict afterwards, so `getExecutedCommitResult` then answers a success
+	 * when the revision landed. Bounded by the same per-block reconcile timeout and never throws.
+	 */
+	async reconcileRefusedCommit(record: ClusterRecord): Promise<void> {
+		const messageHash = record.messageHash;
+		const refused = this.executedCommitResults.get(messageHash);
+		if (refused === undefined || refused.success || !this.behindCommitRefusals.has(messageHash)) {
+			return;
+		}
+		const operation = record.message.operations.find((op): op is { commit: CommitRequest } => 'commit' in op);
+		if (operation === undefined) {
+			return;
+		}
+		const commit = operation.commit;
+		log('cluster-member:consensus-commit-reconcile-again', { messageHash, actionId: commit.actionId, rev: commit.rev });
+		await this.reconcileDivergentCommit(record, commit);
+		const verdict = await this.durableCommitVerdict(commit, refused);
+		// The apply's retention may have been pruned or rolled back while the reconcile ran; never
+		// resurrect it.
+		if (this.executedCommitResults.get(messageHash) !== refused) {
+			return;
+		}
+		this.retainCommitVerdict(record, commit, verdict, true);
+	}
+
 	/**
 	 * The durable verdict for a consensus commit: `applied` itself when storage landed it (a
 	 * success from `StorageRepo.commit` means every block is committed, or already was, under this
@@ -2268,7 +2669,10 @@ export class ClusterMember implements ICluster {
 			return applied;
 		}
 		log('cluster-member:consensus-commit-durable-after-reconcile', { actionId: commit.actionId, rev: commit.rev });
-		return { success: true };
+		// A member's own verdict about its own storage: `local`. Read by the coordinator for its
+		// `success` flag only (`cohortCommitOutcomes`, `localCommitResult`) — it never becomes the
+		// answer handed to the writer; `CoordinatorRepo.commit` computes the cohort's own on every exit.
+		return { success: true, durability: localDurability() };
 	}
 
 	/**
@@ -2392,6 +2796,29 @@ export class ClusterMember implements ICluster {
 		}
 	}
 
+	/**
+	 * Tell the {@link CommittedHoldersSink} which cohort members hold a commit this member just
+	 * durably applied. A member learns nothing about the others' storage at apply time, so the
+	 * evidence is the record's approving commit signers: each is a cohort member that signed to apply
+	 * this commit. A signer that then failed to apply is wrongly recorded, which only spares it a
+	 * rebalance push; its own reconcile, read-repair, and — on the coordinating node — the
+	 * coordinator's durability-checked report (which lands after this one and overrides it) still
+	 * reach it.
+	 */
+	private reportCommittedHolders(record: ClusterRecord, commit: CommitRequest): void {
+		if (!this.onCommittedHolders) {
+			return;
+		}
+		const holders = Object.entries(record.commits)
+			.filter(([peerId, vote]) => vote.type === 'approve' && peerId in record.peers)
+			.map(([peerId]) => peerId);
+		try {
+			this.onCommittedHolders({ blockIds: commit.blockIds, holders });
+		} catch (err) {
+			log('cluster-member:committed-holders-sink-error', { actionId: commit.actionId, error: (err as Error).message });
+		}
+	}
+
 	/**
 	 * After tolerating a "behind" commit divergence, pull the committed revision of
 	 * each block from a cohort peer that holds it and restore it locally. Best-effort:
@@ -2616,6 +3043,7 @@ export class ClusterMember implements ICluster {
 				this.executedTransactions.delete(messageHash);
 				this.executedPendResults.delete(messageHash);
 				this.executedCommitResults.delete(messageHash);
+				this.behindCommitRefusals.delete(messageHash);
 			}
 		}
 		// Prune actionId-keyed pend refusals on the same TTL as the verdicts they were derived from.