@optimystic/db-p2p 0.22.0 → 0.24.1

package/src/cluster/cluster-repo.ts

@@ -2,7 +2,7 @@ import type { IRepo, ClusterRecord, ClusterPeers, Signature, RepoMessage, ITrans
 import type { ICluster } from "@optimystic/db-core";
 import type { IPeerNetwork } from "@optimystic/db-core";
 import { blockIdsForTransforms, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
-import { computeClusterCommitHash, computeClusterMessageHash, computeClusterPromiseHash, membershipDigest, recordMembershipDigest, clampPriority } from "@optimystic/db-core";
+import { computeClusterCommitHash, computeClusterMessageHash, computeClusterPromiseHash, membershipDigest, recordMembershipDigest, clampPriority, clusterVoteSigningPayload, clusterVoteVerificationPayload } from "@optimystic/db-core";
 import { verifyInvalidationCertificate, type ArbitratorSetRecompute } from "../dispute/invalidation.js";
 import { buildCommitCert, invalidationActionId } from "./commit-cert.js";
 import { ClusterClient } from "./client.js";
@@ -24,14 +24,27 @@ const log = createLogger('cluster-member')
 
 /** State of a transaction in the cluster */
 enum TransactionPhase {
-	Promising,       // Collecting promises from peers
+	Promising,       // We have voted; still collecting promises from other peers
 	OurPromiseNeeded, // We need to provide our promise
+	OurConflictVoteNeeded, // We hold a conflicting race winner; we must answer with a conflict vote
 	OurCommitNeeded, // We need to provide our commit
 	Consensus,       // Transaction has reached consensus
-	Rejected,        // Transaction was rejected
+	Rejected,        // Transaction was rejected (validity judgement — enough reject votes)
+	ConflictSuperseded, // Terminal but retryable: conflict votes make super-majority unreachable
 	Propagating     // Transaction is being propagated
 }
 
+/**
+ * A phase plus the data its handler needs. Only {@link TransactionPhase.OurConflictVoteNeeded}
+ * carries any — `conflictsWith`, the winning rival's messageHash — so the conflict-vote handler need
+ * not re-run conflict detection (whose race resolution has side effects) to learn what blocked it.
+ * Split by phase rather than an optional field so the handler reads it without an assertion, and so
+ * a future phase-with-data cannot silently inherit this one's payload.
+ */
+type PhaseResult =
+	| { phase: TransactionPhase.OurConflictVoteNeeded; conflictsWith: string }
+	| { phase: Exclude<TransactionPhase, TransactionPhase.OurConflictVoteNeeded> };
+
 interface TransactionState {
 	record: ClusterRecord;
 	promiseTimeout?: NodeJS.Timeout;
@@ -391,79 +404,104 @@ export class ClusterMember implements ICluster {
 			});
 		}
 
-		// Get the current transaction state
-		const phase = await this.getTransactionPhase(currentRecord);
-		log('cluster-member:phase', {
-			messageHash: record.messageHash,
-			phase,
-			promises: Object.keys(currentRecord.promises ?? {}),
-			commits: Object.keys(currentRecord.commits ?? {})
-		});
+		// Drive the phase machine to a FIXPOINT rather than handling one phase per delivery. Each
+		// vote this member adds can put the record straight into the next phase (our promise
+		// completes super-majority ⇒ our commit is due; our commit completes the majority ⇒
+		// consensus; our reject/conflict vote makes the record terminal), and any follow-on phase
+		// not re-handled here would silently wait for the coordinator's next delivery — e.g. a
+		// member whose promise the coordinator never collected receives the commit-phase record,
+		// adds its promise, and must then also commit in the SAME delivery. One loop replaces the
+		// hand-written per-branch re-checks that used to cover only the follow-ons their authors
+		// thought of. Only the three vote-adding phases continue; each strictly grows the record
+		// (adds a promise or commit key), so the loop terminates — the cap guards a
+		// phase-computation bug, not a real bound.
+		const MaxPhaseSteps = 8;
 		let shouldPersist = true;
-
-		// Handle the transaction based on its state
-		switch (phase) {
-			case TransactionPhase.OurPromiseNeeded:
-				log('cluster-member:action-promise', {
-					messageHash: record.messageHash
-				});
-				currentRecord = await this.handlePromiseNeeded(currentRecord);
-				log('cluster-member:action-promise-complete', {
-					messageHash: record.messageHash,
-					promises: Object.keys(currentRecord.promises ?? {})
-				});
-				break;
-			case TransactionPhase.OurCommitNeeded:
-				log('cluster-member:action-commit', {
-					messageHash: record.messageHash
-				});
-				currentRecord = await this.handleCommitNeeded(currentRecord);
-				log('cluster-member:action-commit-complete', {
-					messageHash: record.messageHash,
-					commits: Object.keys(currentRecord.commits ?? {})
-				});
-				// After adding our commit, check if we now have consensus and execute if so
-				{
-					const newPhase = await this.getTransactionPhase(currentRecord);
-					if (newPhase === TransactionPhase.Consensus) {
-						log('cluster-member:action-consensus-after-commit', {
-							messageHash: record.messageHash
-						});
-						await this.handleConsensus(currentRecord);
-					}
-				}
-				shouldPersist = false;
-				break;
-			case TransactionPhase.Consensus:
-				log('cluster-member:action-consensus', {
-					messageHash: record.messageHash
-				});
-				await this.handleConsensus(currentRecord);
-				// Don't call clearTransaction here - it happens in handleConsensus
-				shouldPersist = false;
-				break;
-			case TransactionPhase.Rejected:
-				log('cluster-member:action-rejected', {
-					messageHash: record.messageHash
-				});
-				// Don't call clearTransaction here - it happens in handleRejection
-				await this.handleRejection(currentRecord);
-				shouldPersist = false;
-				break;
-			case TransactionPhase.Propagating:
-				// Transaction is complete and propagating - clean it up
-				log('cluster-member:phase-propagating', {
-					messageHash: record.messageHash
-				});
-				shouldPersist = false;
-				break;
-			case TransactionPhase.Promising:
-				// Still collecting promises from peers - if we haven't added ours and there's no conflict, add it
-				// This state shouldn't normally be reached since OurPromiseNeeded is checked first
-				log('cluster-member:phase-promising-blocked', {
-					messageHash: record.messageHash
-				});
+		phaseLoop: for (let step = 0; ; step++) {
+			if (step >= MaxPhaseSteps) {
+				log('cluster-member:phase-loop-overflow', { messageHash: record.messageHash, steps: step });
 				break;
+			}
+			const phaseResult = await this.getTransactionPhase(currentRecord);
+			log('cluster-member:phase', {
+				messageHash: record.messageHash,
+				phase: phaseResult.phase,
+				step,
+				promises: Object.keys(currentRecord.promises ?? {}),
+				commits: Object.keys(currentRecord.commits ?? {})
+			});
+			switch (phaseResult.phase) {
+				case TransactionPhase.OurPromiseNeeded:
+					log('cluster-member:action-promise', {
+						messageHash: record.messageHash
+					});
+					currentRecord = await this.handlePromiseNeeded(currentRecord);
+					log('cluster-member:action-promise-complete', {
+						messageHash: record.messageHash,
+						promises: Object.keys(currentRecord.promises ?? {})
+					});
+					// Our own vote can be terminal (a reject where maxAllowedRejections is 0) or complete
+					// the super-majority — recompute rather than guess which.
+					continue;
+				case TransactionPhase.OurConflictVoteNeeded:
+					currentRecord = await this.handleConflictVoteNeeded(currentRecord, phaseResult.conflictsWith);
+					// Never persist a record we conflict-voted: this member holds the WINNER, and
+					// persisting the loser would reserve the same blocks a second time — half of what
+					// made the silent-abstention failure self-sustaining.
+					shouldPersist = false;
+					continue;
+				case TransactionPhase.OurCommitNeeded:
+					log('cluster-member:action-commit', {
+						messageHash: record.messageHash
+					});
+					currentRecord = await this.handleCommitNeeded(currentRecord);
+					log('cluster-member:action-commit-complete', {
+						messageHash: record.messageHash,
+						commits: Object.keys(currentRecord.commits ?? {})
+					});
+					shouldPersist = false;
+					// Our commit may have completed the majority — recompute; Consensus executes below.
+					continue;
+				case TransactionPhase.Consensus:
+					log('cluster-member:action-consensus', {
+						messageHash: record.messageHash
+					});
+					await this.handleConsensus(currentRecord);
+					shouldPersist = false;
+					break phaseLoop;
+				case TransactionPhase.Rejected:
+					log('cluster-member:action-rejected', {
+						messageHash: record.messageHash
+					});
+					await this.handleRejection(currentRecord);
+					shouldPersist = false;
+					break phaseLoop;
+				case TransactionPhase.ConflictSuperseded:
+					// Enough conflict votes that super-majority is unreachable. NOT a rejection — the
+					// callers retry it as a fresh transaction — so it gets its own terminal phase and the
+					// record is cleared rather than held (holding a provably-dead loser would reserve its
+					// blocks against the very retry that is supposed to win).
+					log('cluster-member:action-conflict-superseded', {
+						messageHash: record.messageHash
+					});
+					shouldPersist = false;
+					break phaseLoop;
+				case TransactionPhase.Propagating:
+					// Transaction is complete and propagating - clean it up
+					log('cluster-member:phase-propagating', {
+						messageHash: record.messageHash
+					});
+					shouldPersist = false;
+					break phaseLoop;
+				case TransactionPhase.Promising:
+					// We have already voted (approve, reject, or conflict); 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', {
+						messageHash: record.messageHash
+					});
+					break phaseLoop;
+			}
 		}
 
 		if (shouldPersist) {
@@ -701,14 +739,8 @@ export class ClusterMember implements ICluster {
 		return computeClusterCommitHash(record.messageHash, record.message, record.promises, recordMembershipDigest(record));
 	}
 
-	private computeSigningPayload(hash: string, type: string, rejectReason?: string): Uint8Array {
-		const payload = hash + ':' + type + (rejectReason ? ':' + rejectReason : '');
-		return new TextEncoder().encode(payload);
-	}
-
-	private async signVote(hash: string, type: 'approve' | 'reject', rejectReason?: string): Promise<string> {
-		const payload = this.computeSigningPayload(hash, type, rejectReason);
-		const sigBytes = await this.privateKey.sign(payload);
+	private async signVote(hash: string, type: Signature['type'], extra?: string): Promise<string> {
+		const sigBytes = await this.privateKey.sign(clusterVoteSigningPayload(hash, type, extra));
 		return uint8ArrayToString(sigBytes, 'base64url');
 	}
 
@@ -744,7 +776,7 @@ export class ClusterMember implements ICluster {
 		}
 		try {
 			const pubKey = publicKeyFromRaw(keyBytes);
-			const payload = this.computeSigningPayload(hash, signature.type, signature.rejectReason);
+			const payload = clusterVoteVerificationPayload(hash, signature);
 			const sigBytes = uint8ArrayFromString(signature.signature, 'base64url');
 			const ok = await pubKey.verify(payload, sigBytes);
 			// Key is bound to peerId: a failed verify is a genuine bad vote from a proven identity → penalize.
@@ -761,7 +793,7 @@ export class ClusterMember implements ICluster {
 		}
 	}
 
-	private async getTransactionPhase(record: ClusterRecord): Promise<TransactionPhase> {
+	private async getTransactionPhase(record: ClusterRecord): Promise<PhaseResult> {
 		const peerCount = Object.keys(record.peers).length;
 		const promiseCount = Object.keys(record.promises).length;
 		const ourId = this.peerId.toString();
@@ -769,36 +801,68 @@ export class ClusterMember implements ICluster {
 		const superMajority = Math.ceil(peerCount * this.superMajorityThreshold);
 		const maxAllowedRejections = peerCount - superMajority;
 
-		// Check for rejections — rejected if too many rejections to ever reach super-majority
+		// 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.
 		const rejectedPromises = Object.values(record.promises).filter(s => s.type === 'reject');
+		const conflictPromises = Object.values(record.promises).filter(s => s.type === 'conflict');
 		const rejectedCommits = Object.values(record.commits).filter(s => s.type === 'reject');
 		if (rejectedPromises.length > maxAllowedRejections || this.hasMajority(rejectedCommits.length, peerCount)) {
-			return TransactionPhase.Rejected;
-		}
-
-		// Check if we need to promise
-		if (!record.promises[ourId] && !this.hasConflict(record)) {
-			return TransactionPhase.OurPromiseNeeded;
-		}
-
-		// Check if we have enough approved promises to proceed to commit
+			return { phase: TransactionPhase.Rejected };
+		}
+
+		// Conflict votes 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) {
+			return { phase: TransactionPhase.ConflictSuperseded };
+		}
+
+		// Check if we need to vote. A lost race is answered with a conflict vote, not silence:
+		// absence used to mean both "unreachable" and "refusing in favour of a rival", and the
+		// coordinator could not tell the two apart. Once our conflict vote is merged into
+		// `promises`, this branch is skipped forever — a conflict vote is terminal for this record;
+		// a retry must be a fresh transaction (new messageHash), which `CoordinatorRepo.pend`
+		// already mints per call.
+		if (!record.promises[ourId]) {
+			const conflict = this.findConflict(record);
+			if (conflict) {
+				return { phase: TransactionPhase.OurConflictVoteNeeded, conflictsWith: conflict.blockedBy };
+			}
+			return { phase: TransactionPhase.OurPromiseNeeded };
+		}
+
+		// Check if we have enough approved promises to proceed to commit. Deliberately blind to what
+		// OUR own vote was: the rest of the cohort reaching super-majority is the commit rule
+		// (Theorem 1 Case 2), so a member that rejected — or conflict-voted — still signs the commit
+		// the cohort decided on rather than stalling it. Only the rejection/superseded thresholds
+		// above can stop a record here, and both are checked first.
+		//
+		// NOTE: signing the commit drops this member's reservation on the record
+		// (`shouldPersist = false` in the caller), and the phase fixpoint means that can now happen on
+		// the FIRST delivery when the record already arrives at super-majority, rather than a
+		// round-trip later. The safety argument is quorum intersection (Theorem 9: no rival can
+		// assemble its own super-majority once this one has), NOT the reservation — the reservation
+		// only orders *concurrently-pending* rivals. If a lost-update between commit-signing and
+		// consensus-apply ever shows up, hold the reservation until `handleConsensus` instead of
+		// releasing it here.
 		const approvedPromises = Object.values(record.promises).filter(s => s.type === 'approve');
 		if (approvedPromises.length >= superMajority && !record.commits[ourId]) {
-			return TransactionPhase.OurCommitNeeded;
+			return { phase: TransactionPhase.OurCommitNeeded };
 		}
 
 		// Check if still collecting promises
 		if (promiseCount < peerCount && approvedPromises.length < superMajority) {
-			return TransactionPhase.Promising;
+			return { phase: TransactionPhase.Promising };
 		}
 
 		// Check for consensus
 		const approvedCommits = Object.values(record.commits).filter(s => s.type === 'approve');
 		if (this.hasMajority(approvedCommits.length, peerCount)) {
-			return TransactionPhase.Consensus;
+			return { phase: TransactionPhase.Consensus };
 		}
 
-		return TransactionPhase.Propagating;
+		return { phase: TransactionPhase.Propagating };
 	}
 
 	private hasMajority(count: number, total: number): boolean {
@@ -837,6 +901,33 @@ export class ClusterMember implements ICluster {
 		};
 	}
 
+	/**
+	 * 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
+	 * loss is indistinguishable from an unreachable cohort at the coordinator). `conflictWith` — the
+	 * winning rival's messageHash — is folded into the signed payload, so the claim is
+	 * integrity-protected in transit and readable without parsing prose. NOT a validity judgement:
+	 * {@link getTransactionPhase} never counts conflict votes toward the permanent-rejection
+	 * threshold, and the coordinator surfaces them as a retryable loss, never a validator rejection.
+	 */
+	private async handleConflictVoteNeeded(record: ClusterRecord, conflictWith: string): Promise<ClusterRecord> {
+		log('cluster-member:action-conflict-vote', {
+			messageHash: record.messageHash,
+			conflictWith
+		});
+		const promiseHash = await this.computePromiseHash(record);
+		const sig = await this.signVote(promiseHash, 'conflict', conflictWith);
+		const signature: Signature = { type: 'conflict', signature: sig, conflictWith };
+
+		return {
+			...record,
+			promises: {
+				...record.promises,
+				[this.peerId.toString()]: signature
+			}
+		};
+	}
+
 	/**
 	 * The full promise-phase decision for a record: admit the declared membership FIRST, then (only if
 	 * admitted) validate its pend operations. Failing either yields a `{ valid:false, reason }` the caller
@@ -1268,7 +1359,7 @@ export class ClusterMember implements ICluster {
 			// Gated on the sink: with no reactivity wired the preimage has no consumer, so a sink-less
 			// node pays neither the extra `sha256` nor the extra microtask — the true zero-cost default.
 			if (this.onCommitCertificate) {
-				const commitSignedPayload = this.computeSigningPayload(await this.computeCommitHash(record), 'approve');
+				const commitSignedPayload = clusterVoteSigningPayload(await this.computeCommitHash(record), 'approve');
 				this.captureCommitCert(record, commit.actionId, commitSignedPayload);
 			}
 			let result: CommitResult;
@@ -1393,7 +1484,7 @@ export class ClusterMember implements ICluster {
 		// {@link invalidationActionId} the invalidation's change event also carries, so the bridge's
 		// cert extractor resolves it. Gated on the sink — a node with no reactivity wired pays nothing.
 		if (this.onCommitCertificate) {
-			const invSignedPayload = this.computeSigningPayload(await this.computeCommitHash(record), 'approve');
+			const invSignedPayload = clusterVoteSigningPayload(await this.computeCommitHash(record), 'approve');
 			this.captureCommitCert(record, invalidationActionId(request.invalidatedActionId, request.resolution.disputeId), invSignedPayload);
 		}
 
@@ -1520,12 +1611,20 @@ export class ClusterMember implements ICluster {
 		};
 	}
 
-	private hasConflict(record: ClusterRecord): boolean {
+	/**
+	 * Scan this member's reservation table (`activeTransactions`) for a held transaction that
+	 * conflicts with `record` AND wins the deterministic race against it. Returns the winner's
+	 * identity — `{ blockedBy: messageHash }` — rather than a bare boolean, because that identity is
+	 * exactly what the resulting conflict vote must name (`Signature.conflictWith`); the old boolean
+	 * lost it. `undefined` means no blocking conflict. Side-effectful on the way through: stale
+	 * entries are swept, and a held transaction that LOSES the race to `record` is cleared.
+	 */
+	private findConflict(record: ClusterRecord): { blockedBy: string } | undefined {
 		const now = Date.now();
 		const staleThresholdMs = 2000; // 2 seconds - allow more time for distributed consensus
 
 		const incomingBlockIds = this.getAffectedBlockIds(record.message.operations);
-		log('cluster-member:hasConflict-check', {
+		log('cluster-member:findConflict-check', {
 			messageHash: record.messageHash,
 			activeCount: this.activeTransactions.size,
 			incomingBlockIds
@@ -1537,7 +1636,7 @@ export class ClusterMember implements ICluster {
 			}
 
 			const existingBlockIds = this.getAffectedBlockIds(state.record.message.operations);
-			log('cluster-member:hasConflict-compare', {
+			log('cluster-member:findConflict-compare', {
 				existing: existingHash,
 				incoming: record.messageHash,
 				existingBlockIds,
@@ -1563,7 +1662,7 @@ export class ClusterMember implements ICluster {
 						existing: existingHash,
 						incoming: record.messageHash
 					});
-					return true; // Reject incoming
+					return { blockedBy: existingHash }; // Reject incoming, naming the winner
 				} else {
 					// Accept incoming, abort existing
 					log('cluster-member:race-accept-incoming', {
@@ -1576,38 +1675,49 @@ export class ClusterMember implements ICluster {
 			}
 		}
 
-		return false; // No blocking conflicts
+		return undefined; // No blocking conflicts
+	}
+
+	/** Number of *approve* promise votes on a record — the count the commit rule uses. */
+	private static approvalCount(record: ClusterRecord): number {
+		return Object.values(record.promises).filter(s => s.type === 'approve').length;
 	}
 
 	/**
 	 * Resolve a race between two conflicting transactions. Total and deterministic, so every honest
 	 * member computes the identical winner (the Theorem 1 Case-2 premise). Order:
-	 *   1. more promise signatures wins  (progress monotonicity — see safety note below);
-	 *   2. equal promise counts → higher aged priority wins  (fairness — see {@link recordPriority});
+	 *   1. more *approve* promise signatures wins  (progress monotonicity — see safety note below);
+	 *   2. equal approval counts → higher aged priority wins  (fairness — see {@link recordPriority});
 	 *   3. still tied → higher message hash wins.
 	 *
-	 * Promise count is FIRST so this comparison never displaces a transaction that is further along.
+	 * The count is APPROVALS, not `promises` keys. `promises` is the vote map — a reject occupies a key
+	 * there exactly as an approve does — so counting keys would treat a rejection as progress, letting a
+	 * record that can never commit outrank (and therefore block, via {@link findConflict}) a fresh rival
+	 * for the whole staleness window. Approvals is also the count the invariant below actually needs:
+	 * the commit rule is `approvedPromises >= superMajority`, which never looks at rejections.
+	 *
+	 * Approval count is FIRST so this comparison never displaces a transaction that is further along.
 	 * That restores the pre-priority safety invariant: a member commits purely on promise supermajority
 	 * (`handleCommitNeeded` signs whenever `approvedPromises >= superMajority`; the commit path has NO
 	 * conflict re-check), so `resolveRace` is the ONLY arbiter among concurrently-pending conflicts.
-	 * With promises-first, once transaction X holds a promise supermajority every conflicting rival Y has
-	 * strictly fewer promises — Y can only match X's count by getting the intersecting quorum member to
-	 * promise it, but that member already holds X at supermajority and `resolveRace(X, Y)` returns
+	 * With approvals-first, once transaction X holds a promise supermajority every conflicting rival Y has
+	 * strictly fewer approvals — Y can only match X's count by getting the intersecting quorum member to
+	 * approve it, but that member already holds X at supermajority and `resolveRace(X, Y)` returns
 	 * `keep-existing` on X's higher count, so it never does. By quorum intersection any Y-supermajority
 	 * overlaps X's in ≥1 honest member, and that member rejects Y. One winner (docs/correctness.md
 	 * Theorem 9). Priority-first would break this: it could displace an already-quorum-reached X for a
-	 * higher-priority Y with fewer promises, letting BOTH commit (split brain) — the regression fixed by
+	 * higher-priority Y with fewer approvals, letting BOTH commit (split brain) — the regression fixed by
 	 * ticket occ-priority-first-breaks-promise-monotonicity.
 	 *
-	 * Priority is now a tie-break that runs only at EQUAL promise counts, which is exactly the
+	 * Priority is now a tie-break that runs only at EQUAL approval counts, which is exactly the
 	 * concurrent-starvation case aging targets (two fresh rivals, 0 promises each, otherwise coin-flipping
 	 * on the hash). Priority still breaks those ties deterministically, so aging still solves the stated
 	 * fairness problem in its common case. It only orders two *concurrently-pending* conflicts; it does NOT
 	 * defer a fresh pend for an absent aged transaction (that residual — sequential sub-window starvation —
 	 * is the deferred feat-occ-priority-reservation).
 	 *
-	 * NOTE: residual-fairness tripwire. Under promises-first an aged transaction can still lose to a fresh
-	 * rival that has *legitimately* gathered even one more promise — that is not the pure-coin-flip
+	 * NOTE: residual-fairness tripwire. Under approvals-first an aged transaction can still lose to a fresh
+	 * rival that has *legitimately* gathered even one more approval — that is not the pure-coin-flip
 	 * starvation aging targets (equal counts, priority wins), it is the monotonicity behaviour we WANT (a
 	 * more-progressed rival is never displaced). If deeper fairness against a genuinely-more-progressed
 	 * rival is ever needed, it belongs to feat-occ-priority-reservation (reserve/defer at pend time), NOT
@@ -1616,7 +1726,7 @@ export class ClusterMember implements ICluster {
 	 * NOTE: Byzantine self-assert is a fairness DoS, not a safety hole. A coordinator can stamp
 	 * priority == MaxPriority on every transaction; recordPriority clamps to the cap so it cannot
 	 * exceed it, and priority never influences validity/operationsHash/stale-read checks — and now sits
-	 * below the promise count, so it can only break equal-count ties it might have ~50% won anyway,
+	 * below the approval count, so it can only break equal-count ties it might have ~50% won anyway,
 	 * degrading to at-worst-status-quo fairness (the same graceful-degradation class as spam under
 	 * honest-majority). Binding priority to provable age is out of scope (feat-occ-priority-reservation).
 	 *
@@ -1625,14 +1735,18 @@ export class ClusterMember implements ICluster {
 	 * (design-hot-log-tail-sharding-guidance).
 	 */
 	private resolveRace(existing: ClusterRecord, incoming: ClusterRecord): 'keep-existing' | 'accept-incoming' {
-		// 1. Transaction with more promises wins — never displace a more-progressed rival (safety, see above).
-		const existingCount = Object.keys(existing.promises).length;
-		const incomingCount = Object.keys(incoming.promises).length;
+		// 1. Transaction with more APPROVALS wins — never displace a more-progressed rival (safety, see
+		// above). Counting `promises` keys instead would count reject votes as progress: a record holding
+		// one rejection would outrank an untouched rival and reserve its blocks for the whole staleness
+		// window, and the commit rule this ordering protects (`approvedPromises >= superMajority`) never
+		// looks at rejections anyway.
+		const existingCount = ClusterMember.approvalCount(existing);
+		const incomingCount = ClusterMember.approvalCount(incoming);
 		if (existingCount !== incomingCount) {
 			return existingCount > incomingCount ? 'keep-existing' : 'accept-incoming';
 		}
 
-		// 2. Equal promise counts → higher aged priority wins (fairness tie-break).
+		// 2. Equal approval counts → higher aged priority wins (fairness tie-break).
 		const existingPriority = this.recordPriority(existing);
 		const incomingPriority = this.recordPriority(incoming);
 		if (existingPriority !== incomingPriority) {
@@ -1655,7 +1769,7 @@ export class ClusterMember implements ICluster {
 	 * NOTE: `message` is fixed for a transaction's whole lifecycle (promises/commits accrue in the
 	 * separate `promises`/`commits` maps, never in `message`), so a transaction keeps its rank through
 	 * the commit phase — there is no "priority drops to 0 at commit" asymmetry. resolveRace is only
-	 * consulted at the promise decision (hasConflict), i.e. between two still-open conflicting
+	 * consulted at the promise decision (findConflict), i.e. between two still-open conflicting
 	 * transactions, which is exactly the concurrent-contention case priority is meant to order.
 	 */
 	private recordPriority(record: ClusterRecord): number {
@@ -1813,7 +1927,13 @@ export class ClusterMember implements ICluster {
 			const state = this.activeTransactions.get(messageHash);
 			if (!state) continue;
 
-			const phase = await this.getTransactionPhase(state.record);
+			// NOTE: an expired entry already in a terminal phase is deliberately left alone here —
+			// `processUpdate` clears those on the update that made them terminal, so reaching this point
+			// in one means that update never arrived. It is not stranded: `findConflict`'s 2 s staleness
+			// sweep drops it on the next conflicting arrival. But on a member that then goes idle the
+			// entry lingers until traffic returns. If member memory ever shows entries outliving their
+			// expiration, delete unconditionally here instead of exempting the terminal phases.
+			const { phase } = await this.getTransactionPhase(state.record);
 			if (phase !== TransactionPhase.Consensus && phase !== TransactionPhase.Rejected) {
 				this.activeTransactions.delete(messageHash);
 			}

package/src/cluster/cluster-size-coupling.ts

@@ -1,45 +1,45 @@
-/** A component that exposes the cluster size it actually resolved to. */
-export interface HasEffectiveClusterSize {
-	readonly effectiveClusterSize: number;
-}
-
-/**
- * Fail-fast coupling check for a live node's cluster-size wiring, mirroring
- * `assertSuperMajorityCoupling`.
- *
- * `resolveClusterPolicy` (`cluster/cluster-policy.ts`) is the single place that settles the
- * replication factor / target cohort breadth (`clusterSize`). Every consumer that resolves its
- * own cluster size — `Libp2pKeyPeerNetwork` (peer selection) and `NetworkManagerService` (ring
- * sizing) — must be constructed from that SAME resolved value, or the membership admission
- * gate's "is this declared peer set suspiciously small?" yardstick silently diverges from the
- * cohort width peer selection actually assembles (ticket
- * `bug-cluster-size-resolution-single-source`: an unconfigured node ran peer selection at 16
- * while consensus believed full size was 10, so a cohort that had quietly lost six members still
- * measured as full).
- *
- * On a live node both are constructed from `resolveClusterPolicy(options).clusterSize`, so this
- * check normally passes. It exists to catch *future* drift — a call site reverting to its own
- * default, a new consumer added without threading the resolved value — by throwing at
- * construction with every resolved value and its source, rather than letting the node come up
- * mismatched.
- *
- * @throws Error naming the resolved size and every consumer that disagrees with it.
- */
-export function assertClusterSizeCoupling(
-	resolvedClusterSize: number,
-	consumers: Record<string, HasEffectiveClusterSize | undefined>
-): void {
-	const mismatches = Object.entries(consumers)
-		.filter((entry): entry is [string, HasEffectiveClusterSize] => entry[1] !== undefined)
-		.filter(([, consumer]) => consumer.effectiveClusterSize !== resolvedClusterSize)
-		.map(([name, consumer]) => `${name} resolved ${consumer.effectiveClusterSize}`);
-
-	if (mismatches.length > 0) {
-		throw new Error(
-			`Cluster size mismatch at node startup: resolveClusterPolicy() produced clusterSize=${resolvedClusterSize}, ` +
-			`but ${mismatches.join(', ')}. Every cluster-size consumer must be constructed from the SAME resolved ` +
-			`value (see cluster/cluster-policy.ts), or the membership admission gate's yardstick can diverge from ` +
-			`the cohort width peer selection actually assembles.`
-		);
-	}
-}
+/** A component that exposes the cluster size it actually resolved to. */
+export interface HasEffectiveClusterSize {
+	readonly effectiveClusterSize: number;
+}
+
+/**
+ * Fail-fast coupling check for a live node's cluster-size wiring, mirroring
+ * `assertSuperMajorityCoupling`.
+ *
+ * `resolveClusterPolicy` (`cluster/cluster-policy.ts`) is the single place that settles the
+ * replication factor / target cohort breadth (`clusterSize`). Every consumer that resolves its
+ * own cluster size — `Libp2pKeyPeerNetwork` (peer selection) and `NetworkManagerService` (ring
+ * sizing) — must be constructed from that SAME resolved value, or the membership admission
+ * gate's "is this declared peer set suspiciously small?" yardstick silently diverges from the
+ * cohort width peer selection actually assembles (ticket
+ * `bug-cluster-size-resolution-single-source`: an unconfigured node ran peer selection at 16
+ * while consensus believed full size was 10, so a cohort that had quietly lost six members still
+ * measured as full).
+ *
+ * On a live node both are constructed from `resolveClusterPolicy(options).clusterSize`, so this
+ * check normally passes. It exists to catch *future* drift — a call site reverting to its own
+ * default, a new consumer added without threading the resolved value — by throwing at
+ * construction with every resolved value and its source, rather than letting the node come up
+ * mismatched.
+ *
+ * @throws Error naming the resolved size and every consumer that disagrees with it.
+ */
+export function assertClusterSizeCoupling(
+	resolvedClusterSize: number,
+	consumers: Record<string, HasEffectiveClusterSize | undefined>
+): void {
+	const mismatches = Object.entries(consumers)
+		.filter((entry): entry is [string, HasEffectiveClusterSize] => entry[1] !== undefined)
+		.filter(([, consumer]) => consumer.effectiveClusterSize !== resolvedClusterSize)
+		.map(([name, consumer]) => `${name} resolved ${consumer.effectiveClusterSize}`);
+
+	if (mismatches.length > 0) {
+		throw new Error(
+			`Cluster size mismatch at node startup: resolveClusterPolicy() produced clusterSize=${resolvedClusterSize}, ` +
+			`but ${mismatches.join(', ')}. Every cluster-size consumer must be constructed from the SAME resolved ` +
+			`value (see cluster/cluster-policy.ts), or the membership admission gate's yardstick can diverge from ` +
+			`the cohort width peer selection actually assembles.`
+		);
+	}
+}