@optimystic/db-p2p 0.14.1 → 0.16.3

package/src/cluster/cluster-repo.ts

@@ -1,15 +1,15 @@
-import type { IRepo, ClusterRecord, Signature, RepoMessage, ITransactionValidator, ClusterConsensusConfig, CommitResult, BlockId, ActionId, ActionRev, CommitRequest, CommitCert, InvalidateRequest } from "@optimystic/db-core";
+import type { IRepo, ClusterRecord, ClusterPeers, Signature, RepoMessage, ITransactionValidator, ClusterConsensusConfig, CommitResult, BlockId, ActionId, ActionRev, CommitRequest, CommitCert, InvalidateRequest } from "@optimystic/db-core";
 import type { ICluster } from "@optimystic/db-core";
 import type { IPeerNetwork } from "@optimystic/db-core";
-import { blockIdsForTransforms } 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 { verifyInvalidationCertificate, type ArbitratorSetRecompute } from "../dispute/invalidation.js";
 import { buildCommitCert, invalidationActionId } from "./commit-cert.js";
 import { ClusterClient } from "./client.js";
 import type { PeerId, PrivateKey } from "@libp2p/interface";
 import { peerIdFromString } from "@libp2p/peer-id";
 import { publicKeyFromRaw } from "@libp2p/crypto/keys";
-import { sha256 } from "multiformats/hashes/sha2";
-import { base58btc } from "multiformats/bases/base58";
+import { peerIdBindsPublicKey } from "./peer-key-binding.js";
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
 import { createLogger } from '../logger.js'
 import type { PartitionDetector } from "./partition-detector.js";
@@ -37,6 +37,18 @@ interface TransactionState {
 	lastUpdate: number;
 }
 
+/**
+ * Result of verifying one vote signature. `penalize` distinguishes "identity was never proven"
+ * (no key / not Ed25519 / key not bound to the peer id / malformed input — reject, but do NOT
+ * report the named peer, whose id may have been attacker-chosen) from "the key IS the one the
+ * peer id names, yet the signature does not verify" (reject AND report — a genuine bad vote from
+ * that proven identity). Collapsing both into a bare `false` would let a coordinator get an honest
+ * peer penalized just by attaching a key it controls under that peer's id.
+ */
+type VerifyOutcome =
+	| { valid: true }
+	| { valid: false; penalize: boolean };
+
 /**
  * Actively reconciles a block this member committed without having seen the matching
  * pend (cohort drift between the independent pend and commit cluster-transactions).
@@ -85,6 +97,33 @@ export type InvalidationApplySink = (request: InvalidateRequest) => Promise<void
  */
 export type RecomputeArbitratorSetCapability = ArbitratorSetRecompute;
 
+/**
+ * The member's own independently-derived view of a block's responsible cluster, plus FRET's confidence in
+ * the underlying network-size estimate (0..1). Returned by {@link DeriveExpectedClusterCallback} and
+ * consumed by {@link ClusterMember}'s membership admission gate: the member checks a coordinator-declared
+ * peer set against `peers` (its expected set `E`) and gates on `confidence` (low confidence ⇒ fail closed
+ * for any downsizing, the partition posture).
+ */
+export type ExpectedClusterView = {
+	/** The member's own derived responsible-peer set for the block (its view of the legitimate cluster). */
+	peers: ClusterPeers;
+	/** FRET's confidence in the current network-size estimate (0..1); ≤ threshold ⇒ treated as untrusted. */
+	confidence: number;
+};
+
+/**
+ * Independently derive this member's own view of a block's responsible cluster. Injected so
+ * {@link ClusterMember} stays transport-agnostic — the composition root supplies it from
+ * `IKeyNetwork.findCluster` + FRET (mirroring how the coordinator derives the cluster). Absent on nodes
+ * that cannot derive a view (no FRET, unit tests): with no derived view AND no configured full-size
+ * reference the gate preserves legacy approve behavior, but a configured `clusterSize` still lets the gate
+ * fail closed on an unjustified downsize. See {@link ClusterMember} admission gate.
+ */
+export type DeriveExpectedClusterCallback = (blockId: BlockId) => Promise<ExpectedClusterView>;
+
+/** Stable reject reason a member emits when a declared peer set fails the membership admission gate. */
+export const MEMBERSHIP_NOT_ADMITTED = 'membership-not-admitted';
+
 interface ClusterMemberComponents {
 	storageRepo: IRepo;
 	peerNetwork: IPeerNetwork;
@@ -106,6 +145,8 @@ interface ClusterMemberComponents {
 	onInvalidate?: InvalidationApplySink;
 	/** Layer-2 arbitrator-set recompute for invalidation verification; see {@link RecomputeArbitratorSetCapability}. */
 	recomputeArbitratorSet?: RecomputeArbitratorSetCapability;
+	/** Member-side cluster derivation for the membership admission gate; see {@link DeriveExpectedClusterCallback}. */
+	deriveExpectedCluster?: DeriveExpectedClusterCallback;
 }
 
 export function clusterMember(components: ClusterMemberComponents): ClusterMember {
@@ -124,7 +165,8 @@ export function clusterMember(components: ClusterMemberComponents): ClusterMembe
 		components.reconcileBlock,
 		components.onCommitCertificate,
 		components.onInvalidate,
-		components.recomputeArbitratorSet
+		components.recomputeArbitratorSet,
+		components.deriveExpectedCluster
 	);
 }
 
@@ -168,8 +210,28 @@ export class ClusterMember implements ICluster {
 	private readonly expirationInterval: NodeJS.Timeout;
 	private readonly cleanupInterval: NodeJS.Timeout;
 
-	/** Effective super-majority threshold. Defaults to 1.0 (unanimity) for backward compatibility. */
+	/**
+	 * Confidence floor at/below which FRET's network-size view is treated as untrustworthy for the
+	 * membership gate. Above it the member trusts its derived view (confident path); at/below it the gate
+	 * fails closed for downsizing. Matches the coordinator's `validateSmallCluster` confidence gate (> 0.5).
+	 */
+	private static readonly MembershipConfidenceThreshold = 0.5;
+
+	/**
+	 * Effective super-majority threshold this member accepts as sufficient for a commit. Defaults to
+	 * {@link DEFAULT_SUPER_MAJORITY_THRESHOLD} (0.75) when no config is supplied — the SAME default the
+	 * coordinator uses, so the two can never silently disagree about whether a transaction is final.
+	 * (Previously defaulted to 1.0/unanimity, which split the member from a coordinator committing at 0.75.)
+	 */
 	private readonly superMajorityThreshold: number;
+	// Membership admission gate parameters (see {@link admitMembership}). Read once from consensusConfig
+	// so the gate has stable thresholds independent of the (untrusted) values a record declares.
+	private readonly minAbsoluteClusterSize: number;
+	private readonly clusterSizeTolerance: number;
+	private readonly membershipAdmissionFraction: number;
+	/** Configured full cluster size, or undefined when unknown (then the gate cannot judge a downsize). */
+	private readonly configuredClusterSize: number | undefined;
+	private readonly allowUnvalidatedSmallCluster: boolean;
 
 	constructor(
 		private readonly storageRepo: IRepo,
@@ -187,9 +249,15 @@ export class ClusterMember implements ICluster {
 		private readonly reconcileBlock?: ReconcileBlockCallback,
 		private readonly onCommitCertificate?: CommitCertificateSink,
 		private readonly onInvalidate?: InvalidationApplySink,
-		private readonly recomputeArbitratorSet?: RecomputeArbitratorSetCapability
+		private readonly recomputeArbitratorSet?: RecomputeArbitratorSetCapability,
+		private readonly deriveExpectedCluster?: DeriveExpectedClusterCallback
 	) {
-		this.superMajorityThreshold = consensusConfig?.superMajorityThreshold ?? 1.0;
+		this.superMajorityThreshold = consensusConfig?.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD;
+		this.minAbsoluteClusterSize = consensusConfig?.minAbsoluteClusterSize ?? 3;
+		this.clusterSizeTolerance = consensusConfig?.clusterSizeTolerance ?? 0.5;
+		this.membershipAdmissionFraction = consensusConfig?.membershipAdmissionFraction ?? 0.75;
+		this.configuredClusterSize = consensusConfig?.clusterSize;
+		this.allowUnvalidatedSmallCluster = consensusConfig?.allowUnvalidatedSmallCluster ?? false;
 		// Periodically clean up expired transactions (.unref() so tests/short-lived processes can exit)
 		this.expirationInterval = setInterval(() => this.queueExpiredTransactions(), 60000);
 		this.expirationInterval.unref();
@@ -198,6 +266,16 @@ export class ClusterMember implements ICluster {
 		this.cleanupInterval.unref();
 	}
 
+	/**
+	 * The resolved super-majority threshold this member runs on. Exposed so the composition root can
+	 * fail-fast if the member and the coordinator would run different thresholds (see the coupling
+	 * assertion in `libp2p-node-base.ts`) — a mismatch is a latent phase-disagreement, caught at startup
+	 * rather than mid-consensus.
+	 */
+	get effectiveSuperMajorityThreshold(): number {
+		return this.superMajorityThreshold;
+	}
+
 	/**
 	 * Clears all interval and timeout handles and empties active state.
 	 * Called during node shutdown to prevent leaked timers.
@@ -338,10 +416,7 @@ export class ClusterMember implements ICluster {
 						log('cluster-member:action-consensus-after-commit', {
 							messageHash: record.messageHash
 						});
-						// Check persistent store for post-recovery dedup before synchronous guard
-						if (!await this.wasTransactionExecutedAsync(currentRecord.messageHash)) {
-							await this.handleConsensus(currentRecord);
-						}
+						await this.handleConsensus(currentRecord);
 					}
 				}
 				shouldPersist = false;
@@ -350,12 +425,7 @@ export class ClusterMember implements ICluster {
 				log('cluster-member:action-consensus', {
 					messageHash: record.messageHash
 				});
-				// Check persistent store for post-recovery dedup before synchronous guard
-				if (await this.wasTransactionExecutedAsync(currentRecord.messageHash)) {
-					log('cluster-member:consensus-already-executed', { messageHash: record.messageHash });
-				} else {
-					await this.handleConsensus(currentRecord);
-				}
+				await this.handleConsensus(currentRecord);
 				// Don't call clearTransaction here - it happens in handleConsensus
 				shouldPersist = false;
 				break;
@@ -432,10 +502,32 @@ export class ClusterMember implements ICluster {
 		if (existing.messageHash !== incoming.messageHash) {
 			throw new Error('Message hash mismatch');
 		}
-		if (JSON.stringify(existing.message) !== JSON.stringify(incoming.message)) {
+		if (ClusterMember.canonicalJson(existing.message) !== ClusterMember.canonicalJson(incoming.message)) {
 			throw new Error('Message content mismatch');
 		}
-		if (JSON.stringify(existing.peers) !== JSON.stringify(incoming.peers)) {
+		if (existing.membershipVersion === 2 || incoming.membershipVersion === 2) {
+			// v2: the sorted peer-id set (captured by membershipDigest) is bound into messageHash, so equal
+			// messageHash MUST imply equal membership on any honest path. A mismatch here — different digest
+			// or version at equal hash — is a protocol violation (a bug or a hash-collision attack), NOT an
+			// honest divergence: two honest members with different views now hold two DIFFERENT hashes, i.e.
+			// two competing transactions the race machinery resolves, not one contested record. Log loudly
+			// and reject; never silently adopt the incoming set. (validateRecord already proved each record's
+			// own digest matches its own peers, so multiaddr / pubkey churn within the SAME id set — which
+			// keeps the same digest and hash — does NOT trip this.)
+			if (existing.membershipVersion !== incoming.membershipVersion || existing.membershipDigest !== incoming.membershipDigest) {
+				log('cluster-member:peers-mismatch-invariant-violation', {
+					messageHash: existing.messageHash,
+					existingVersion: existing.membershipVersion,
+					incomingVersion: incoming.membershipVersion,
+					existingDigest: existing.membershipDigest,
+					incomingDigest: incoming.membershipDigest,
+					existingPeers: Object.keys(existing.peers ?? {}).sort(),
+					incomingPeers: Object.keys(incoming.peers ?? {}).sort()
+				});
+				throw new Error('Peers mismatch');
+			}
+		} else if (ClusterMember.canonicalJson(existing.peers) !== ClusterMember.canonicalJson(incoming.peers)) {
+			// v1 (legacy, membership unbound): full peer-object equality is the only available guard.
 			throw new Error('Peers mismatch');
 		}
 
@@ -466,6 +558,10 @@ export class ClusterMember implements ICluster {
 		phase: 'promise' | 'commit',
 		messageHash: string
 	): Record<string, Signature> {
+		// NOTE: relies on validateSignatures() (via validateRecord in processUpdate) having already run on
+		// every record reaching here, so each peerId's signature is key-bound. Without that guarantee the
+		// Equivocation penalty below would act on self-asserted, unverified peer ids and could frame an
+		// honest peer. Do not call this on unvalidated signatures.
 		const merged = { ...existing };
 
 		for (const [peerId, incomingSig] of Object.entries(incoming)) {
@@ -498,8 +594,27 @@ export class ClusterMember implements ICluster {
 	}
 
 	private async validateRecord(record: ClusterRecord): Promise<void> {
-		// Validate message hash matches the message content
-		const expectedHash = await this.computeMessageHash(record.message);
+		// Reject a record whose membership-binding version this code does not implement. The cluster
+		// consensus code is a single deployable unit (all cluster members upgrade together), so a version
+		// we don't understand is rejected rather than cross-version-consensus'd.
+		if (record.membershipVersion !== undefined && record.membershipVersion !== 1 && record.membershipVersion !== 2) {
+			throw new Error(`Unsupported membershipVersion: ${record.membershipVersion}`);
+		}
+
+		// v2: the declared membership digest must match the record's own peer set. A record whose declared
+		// digest doesn't match its peers is malformed (and its messageHash — computed over that digest —
+		// would not bind the real membership).
+		// NOTE: recomputes membershipDigest (one SHA256 over the sorted peer-id list) on every incoming v2
+		// record; if a hot cluster ever shows this as a cost, memoize per (messageHash → digest).
+		if (record.membershipVersion === 2) {
+			const expectedDigest = await membershipDigest(record.peers);
+			if (expectedDigest !== record.membershipDigest) {
+				throw new Error(`Membership digest mismatch: expected=${expectedDigest}, received=${record.membershipDigest ?? 'undefined'}`);
+			}
+		}
+
+		// Validate message hash matches the message content (v2 folds in the membership digest)
+		const expectedHash = await this.computeMessageHash(record);
 		if (expectedHash !== record.messageHash) {
 			throw new Error(`Message hash mismatch: expected=${expectedHash}, received=${record.messageHash}`);
 		}
@@ -514,21 +629,25 @@ export class ClusterMember implements ICluster {
 	}
 
 	/**
-	 * Compute message hash using the same algorithm as the coordinator.
-	 * Must match cluster-coordinator.ts createMessageHash().
+	 * Compute message hash using the same algorithm as the coordinator. Version-dispatched: a v2 record
+	 * folds its membership digest into the preimage, a v1 / unversioned record hashes byte-identically to
+	 * before this change. Must match cluster-coordinator.ts createMessageHash().
 	 */
-	private async computeMessageHash(message: RepoMessage): Promise<string> {
-		const msgBytes = new TextEncoder().encode(ClusterMember.canonicalJson(message));
-		const hashBytes = await sha256.digest(msgBytes);
-		return base58btc.encode(hashBytes.digest);
+	private async computeMessageHash(record: Pick<ClusterRecord, 'message' | 'membershipVersion' | 'membershipDigest'>): Promise<string> {
+		return computeClusterMessageHash(record.message, recordMembershipDigest(record));
 	}
 
 	private async validateSignatures(record: ClusterRecord): Promise<void> {
-		// Validate promise signatures
+		// Validate promise signatures. Reject on any failure, but only report an InvalidSignature
+		// penalty when the key was proven to belong to `peerId` (outcome.penalize) — otherwise the id
+		// is attacker-chosen and reporting it would let a coordinator frame an honest peer.
 		const promiseHash = await this.computePromiseHash(record);
 		for (const [peerId, signature] of Object.entries(record.promises)) {
-			if (!await this.verifySignature(record, peerId, promiseHash, signature)) {
-				this.reputation?.reportPeer(peerId, PenaltyReason.InvalidSignature, `promise:${record.messageHash}`);
+			const outcome = await this.verifySignature(record, peerId, promiseHash, signature);
+			if (!outcome.valid) {
+				if (outcome.penalize) {
+					this.reputation?.reportPeer(peerId, PenaltyReason.InvalidSignature, `promise:${record.messageHash}`);
+				}
 				throw new Error(`Invalid promise signature from ${peerId}`);
 			}
 		}
@@ -536,14 +655,23 @@ export class ClusterMember implements ICluster {
 		// Validate commit signatures
 		const commitHash = await this.computeCommitHash(record);
 		for (const [peerId, signature] of Object.entries(record.commits)) {
-			if (!await this.verifySignature(record, peerId, commitHash, signature)) {
-				this.reputation?.reportPeer(peerId, PenaltyReason.InvalidSignature, `commit:${record.messageHash}`);
+			const outcome = await this.verifySignature(record, peerId, commitHash, signature);
+			if (!outcome.valid) {
+				if (outcome.penalize) {
+					this.reputation?.reportPeer(peerId, PenaltyReason.InvalidSignature, `commit:${record.messageHash}`);
+				}
 				throw new Error(`Invalid commit signature from ${peerId}`);
 			}
 		}
 	}
 
-	/** Deterministic JSON: sorts object keys so hash is order-independent */
+	/**
+	 * Deterministic JSON: sorts object keys so comparisons are order-independent.
+	 * NOTE: this is a second copy of the canonicalization in db-core `membership.ts` (which feeds the hash
+	 * preimages). It is used here only for equality checks (message-content / v1-peers compare), and those
+	 * run *after* a messageHash-equality gate, so a drift between the two can't silently forge agreement —
+	 * but keep them byte-identical. If a third caller appears, promote to a single exported helper.
+	 */
 	private static canonicalJson(value: unknown): string {
 		return JSON.stringify(value, (_, v) =>
 			v && typeof v === 'object' && !Array.isArray(v)
@@ -553,15 +681,11 @@ export class ClusterMember implements ICluster {
 	}
 
 	private async computePromiseHash(record: ClusterRecord): Promise<string> {
-		const msgBytes = new TextEncoder().encode(record.messageHash + ClusterMember.canonicalJson(record.message));
-		const hashBytes = await sha256.digest(msgBytes);
-		return uint8ArrayToString(hashBytes.digest, 'base64url');
+		return computeClusterPromiseHash(record.messageHash, record.message, recordMembershipDigest(record));
 	}
 
 	private async computeCommitHash(record: ClusterRecord): Promise<string> {
-		const msgBytes = new TextEncoder().encode(record.messageHash + ClusterMember.canonicalJson(record.message) + ClusterMember.canonicalJson(record.promises));
-		const hashBytes = await sha256.digest(msgBytes);
-		return uint8ArrayToString(hashBytes.digest, 'base64url');
+		return computeClusterCommitHash(record.messageHash, record.message, record.promises, recordMembershipDigest(record));
 	}
 
 	private computeSigningPayload(hash: string, type: string, rejectReason?: string): Uint8Array {
@@ -575,17 +699,53 @@ export class ClusterMember implements ICluster {
 		return uint8ArrayToString(sigBytes, 'base64url');
 	}
 
-	private async verifySignature(record: ClusterRecord, peerId: string, hash: string, signature: Signature): Promise<boolean> {
+	/**
+	 * Verify one vote signature and classify the outcome (see {@link VerifyOutcome}). Total on hostile
+	 * input: a missing/empty key, a non-Ed25519 id, a key not bound to `peerId`, or malformed bytes all
+	 * yield `{ valid:false, penalize:false }` (reject without penalizing an unproven identity) rather
+	 * than throwing. Only after the key is proven to be the one `peerId` names does a failed
+	 * cryptographic verify yield `{ valid:false, penalize:true }`.
+	 *
+	 * NOTE: the binding check (`peerIdBindsPublicKey`) proves the vote was signed by the key `peerId`
+	 * names — it does NOT establish that `peerId` is legitimately in the cohort. A coordinator minting
+	 * fresh keypairs and using each key's own derived id passes this for every one. Sybil/cohort
+	 * membership is a separate layer (cohort-topic membership certificates), not solved here.
+	 */
+	private async verifySignature(record: ClusterRecord, peerId: string, hash: string, signature: Signature): Promise<VerifyOutcome> {
 		const peerInfo = record.peers[peerId];
 		if (!peerInfo?.publicKey?.length) {
-			throw new Error(`No public key for peer ${peerId}`);
-		}
-		// publicKey is base64url-encoded string (JSON-serialization safe)
-		const keyBytes = uint8ArrayFromString(peerInfo.publicKey, 'base64url');
-		const pubKey = publicKeyFromRaw(keyBytes);
-		const payload = this.computeSigningPayload(hash, signature.type, signature.rejectReason);
-		const sigBytes = uint8ArrayFromString(signature.signature, 'base64url');
-		return pubKey.verify(payload, sigBytes);
+			// No key to check against — identity not proven. Reject without penalty.
+			return { valid: false, penalize: false };
+		}
+		let keyBytes: Uint8Array;
+		try {
+			// publicKey is base64url-encoded string (JSON-serialization safe)
+			keyBytes = uint8ArrayFromString(peerInfo.publicKey, 'base64url');
+		} catch {
+			return { valid: false, penalize: false };
+		}
+		// The key must be the one `peerId` provably names, else the vote could be attributed to any peer
+		// id while signed by a key the coordinator controls. Binding failure ⇒ identity unproven ⇒ no penalty.
+		if (!peerIdBindsPublicKey(peerId, keyBytes)) {
+			return { valid: false, penalize: false };
+		}
+		try {
+			const pubKey = publicKeyFromRaw(keyBytes);
+			const payload = this.computeSigningPayload(hash, signature.type, signature.rejectReason);
+			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.
+			// NOTE: residual — an Ed25519 peer's public key is derivable from its (public) id, so an attacker
+			// can attach a victim's REAL key with a garbage signature and still trip this InvalidSignature
+			// penalty on the victim. Binding narrows framing (the attacker must use the victim's own key, not
+			// an arbitrary one) but cannot eliminate it here: a single signature can't distinguish "victim
+			// signed badly" from "someone pasted the victim's public key + junk". Fully closing it needs an
+			// authenticated membership/channel layer (cohort-topic membership certs), out of scope for this fix.
+			return ok ? { valid: true } : { valid: false, penalize: true };
+		} catch {
+			// Malformed signature bytes / key decode failure: reject, but do not penalize on unparseable input.
+			return { valid: false, penalize: false };
+		}
 	}
 
 	private async getTransactionPhase(record: ClusterRecord): Promise<TransactionPhase> {
@@ -633,8 +793,11 @@ export class ClusterMember implements ICluster {
 	}
 
 	private async handlePromiseNeeded(record: ClusterRecord): Promise<ClusterRecord> {
-		// Validate pend operations if we have a validator
-		const validationResult = await this.validatePendOperations(record);
+		// Membership admission gate runs BEFORE pend validation: a member independently checks the declared
+		// 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;
@@ -661,6 +824,161 @@ 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. Failing either yields a `{ valid:false, reason }` the caller
+	 * turns into a `reject` vote. Splitting membership from pend validation 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.
+	 */
+	private async evaluatePromise(record: ClusterRecord): Promise<{ valid: boolean; reason?: string }> {
+		const admission = await this.admitMembership(record);
+		if (!admission.admit) {
+			return { valid: false, reason: admission.reason ?? MEMBERSHIP_NOT_ADMITTED };
+		}
+		return await this.validatePendOperations(record);
+	}
+
+	/**
+	 * Membership admission gate. Decides whether the coordinator-declared peer set (`record.peers`, call it
+	 * `D`) is a *legitimate* cluster this member may vote inside, judged against the member's OWN
+	 * independently-derived view — not against anything the (untrusted) record declares about its size.
+	 * Evaluated on the promise path before the member signs an approve.
+	 *
+	 * The predicate admits `D` iff ALL hold:
+	 *  1. **Self-membership** — this member's id ∈ `D`; else this block is not its responsibility (and a
+	 *     coordinator must not route a record to a non-member to pad approval counts).
+	 *  2. **Not a self-shrink below the floor** — with a confident derived view `E`, `|D| ≥ ⌈fraction·|E|⌉`
+	 *     (and ≥ minAbsoluteClusterSize). `|E|` is the member's own confident cluster-size estimate `K_est`,
+	 *     so a minority-partition set (small `D`) is rejected against the member's larger view.
+	 *  3. **Consistency with the derived view** — `|D △ E|` within `clusterSizeTolerance·|E|`; honest churn
+	 *     of a peer or two is absorbed, a wholesale-disjoint or half-size set is not.
+	 *
+	 * **Fail-closed posture.** When the member cannot confidently derive `E` (no capability, low FRET
+	 * confidence — exactly what a partition induces), it must refuse any *downsizing* decision: a
+	 * below-full-size `D` is rejected against the configured full `clusterSize`. With NEITHER a confident
+	 * view NOR a configured full size the gate cannot judge a downsize at all, so it preserves the legacy
+	 * approve behavior (backward-compatible for nodes/tests with no derivation wired). `allowUnvalidatedSmallCluster`
+	 * is the explicit opt-in (single-node / local dev knowingly below the safe floor), matching the
+	 * coordinator's `validateSmallCluster` semantics.
+	 */
+	private async admitMembership(record: ClusterRecord): Promise<{ admit: boolean; reason?: string }> {
+		const ourId = this.peerId.toString();
+		const declared = Object.keys(record.peers ?? {});
+
+		// Predicate 1: self-membership. Always enforced (independent of any opt-in): a member does not vote
+		// in a cluster it is not part of.
+		if (!declared.includes(ourId)) {
+			log('cluster-member:admission-reject', { messageHash: record.messageHash, reason: 'self-not-member', declaredSize: declared.length });
+			return { admit: false, reason: `${MEMBERSHIP_NOT_ADMITTED}:self-not-member` };
+		}
+
+		// Explicit opt-in: knowingly transact below the safe floor (single-node / local dev). Skips the
+		// size/consistency gates but not self-membership above.
+		if (this.allowUnvalidatedSmallCluster) {
+			return { admit: true };
+		}
+
+		const derived = await this.deriveExpectedClusterView(record);
+		// An empty derived view (kEst === 0) carries no usable reference set: measured against it every
+		// non-empty declared set is wholly "inconsistent" (maxDiff = ceil(tol·0) = 0), which would spuriously
+		// reject a legitimate full cluster — a stricter, worse outcome than an absent view. Treat empty as
+		// not-confident so it takes the fail-closed-or-legacy branch below instead. (Not normally reachable:
+		// a responsible member's findCluster includes at least itself; this guards a transient empty read.)
+		const derivedSize = derived !== undefined ? Object.keys(derived.peers ?? {}).length : 0;
+		const confident = derived !== undefined
+			&& derived.confidence > ClusterMember.MembershipConfidenceThreshold
+			&& derivedSize > 0;
+
+		if (!confident) {
+			// Fail closed for downsizing under low/absent confidence. A full-size (or larger) declared set is
+			// still admitted — there is nothing to shrink. Without a configured full-size reference we cannot
+			// tell a downsize from a legitimate small cluster, so we preserve legacy approve behavior.
+			if (this.configuredClusterSize === undefined) {
+				return { admit: true };
+			}
+			if (declared.length >= this.configuredClusterSize) {
+				return { admit: true };
+			}
+			log('cluster-member:admission-reject', {
+				messageHash: record.messageHash,
+				reason: 'low-confidence-downsize',
+				declaredSize: declared.length,
+				configuredClusterSize: this.configuredClusterSize,
+				confidence: derived?.confidence
+			});
+			return { admit: false, reason: `${MEMBERSHIP_NOT_ADMITTED}:low-confidence-downsize` };
+		}
+
+		const expected = Object.keys(derived!.peers ?? {});
+		const kEst = expected.length;
+
+		// Predicate 2: floor derived from the member's OWN confident estimate.
+		const floor = Math.max(this.minAbsoluteClusterSize, Math.ceil(this.membershipAdmissionFraction * kEst));
+		if (declared.length < floor) {
+			log('cluster-member:admission-reject', {
+				messageHash: record.messageHash,
+				reason: 'below-floor',
+				declaredSize: declared.length,
+				floor,
+				kEst
+			});
+			return { admit: false, reason: `${MEMBERSHIP_NOT_ADMITTED}:below-floor` };
+		}
+
+		// Predicate 3: consistency with the derived view within tolerance.
+		const symmetricDiff = ClusterMember.symmetricDifferenceSize(declared, expected);
+		const maxDiff = Math.ceil(this.clusterSizeTolerance * kEst);
+		if (symmetricDiff > maxDiff) {
+			log('cluster-member:admission-reject', {
+				messageHash: record.messageHash,
+				reason: 'inconsistent-with-derived-view',
+				declaredSize: declared.length,
+				kEst,
+				symmetricDiff,
+				maxDiff
+			});
+			return { admit: false, reason: `${MEMBERSHIP_NOT_ADMITTED}:inconsistent-with-derived-view` };
+		}
+
+		return { admit: true };
+	}
+
+	/**
+	 * Derive this member's own view of the record's block cluster via the injected capability, or
+	 * `undefined` when it cannot (no capability, no coordinating block id, or a derivation error — all of
+	 * which the gate treats as "not confident"). Derived from the record's coordinating block, the same key
+	 * the coordinator used to select the cluster.
+	 */
+	private async deriveExpectedClusterView(record: ClusterRecord): Promise<ExpectedClusterView | undefined> {
+		if (!this.deriveExpectedCluster) {
+			return undefined;
+		}
+		const blockId = record.coordinatingBlockIds?.[0];
+		if (blockId === undefined) {
+			return undefined;
+		}
+		try {
+			// NOTE: derives (findCluster) once per inbound record on the promise path — one routing lookup
+			// per vote. If this shows up as hot, cache the derived view per (blockId, short TTL): it is a
+			// pure read of current topology, so a few-seconds-stale view is safe for admission.
+			return await this.deriveExpectedCluster(blockId as BlockId);
+		} catch (err) {
+			log('cluster-member:derive-expected-cluster-error', { messageHash: record.messageHash, error: (err as Error).message });
+			return undefined;
+		}
+	}
+
+	/** |A △ B| over two id lists (order-independent set symmetric difference). */
+	private static symmetricDifferenceSize(a: string[], b: string[]): number {
+		const setA = new Set(a);
+		const setB = new Set(b);
+		let count = 0;
+		for (const x of setA) if (!setB.has(x)) count++;
+		for (const x of setB) if (!setA.has(x)) count++;
+		return count;
+	}
+
 	/**
 	 * Validates pend operations in a cluster record using the transaction validator.
 	 * Also checks for stale revisions to prevent consensus on operations that would fail.
@@ -731,9 +1049,12 @@ export class ClusterMember implements ICluster {
 	 * @warning This method executes on ALL cluster peers, not just the coordinator.
 	 * Each peer independently applies the operations to its local storage.
 	 *
-	 * @pitfall **Check-then-act race** - Must check AND mark as executed atomically
-	 * (before any `await`) to prevent duplicate execution. JavaScript's single-threaded
-	 * nature makes synchronous check-and-set atomic.
+	 * @pitfall **Check-then-act race** - The in-memory guard must be checked AND set
+	 * atomically (before any `await`) to prevent duplicate execution; JavaScript's
+	 * single-threaded nature makes that synchronous check-and-set atomic. The durable
+	 * marker, by contrast, is persisted only *after* apply succeeds — writing it eagerly
+	 * would leave a stuck marker on a caught fault or a crash mid-apply, silently dropping
+	 * the transaction on this member on redelivery.
 	 *
 	 * @pitfall **Independent node storage** - Each node has its own storage. After consensus,
 	 * each node applies operations locally. Nodes must fetch missing blocks from cluster
@@ -742,31 +1063,52 @@ export class ClusterMember implements ICluster {
 	 * @see docs/internals.md "Check-Then-Act Race in Consensus" and "Independent Node Storage" pitfalls
 	 */
 	private async handleConsensus(record: ClusterRecord): Promise<void> {
+		// Check persistent store first for post-recovery dedup (in-memory map is cleared on restart).
+		// wasTransactionExecutedAsync also checks the in-memory map as a fast path.
+		if (await this.wasTransactionExecutedAsync(record.messageHash)) {
+			log('cluster-member:consensus-already-executed', { messageHash: record.messageHash });
+			return;
+		}
 		// Check-and-set ATOMICALLY to prevent race condition where multiple calls
-		// pass the check before any completes. Since JavaScript is single-threaded,
+		// pass the async check before any completes. Since JavaScript is single-threaded,
 		// this synchronous check-and-set is atomic before any await.
 		if (this.executedTransactions.has(record.messageHash)) {
 			log('cluster-member:consensus-already-executed', { messageHash: record.messageHash });
 			return;
 		}
-		// Mark as executing IMMEDIATELY before any async operations
+		// Set the in-memory guard IMMEDIATELY, before any async operations: its synchronous
+		// check-and-set (line above's `has` + this `set`) is what prevents the concurrent
+		// apply-window race where two handleConsensus calls for the same hash both pass the
+		// async check. The durable marker is deliberately NOT written here — see below.
 		const executedAt = Date.now();
 		this.executedTransactions.set(record.messageHash, executedAt);
-		this.stateStore?.markExecuted(record.messageHash, executedAt)
-			.catch(err => log('cluster-member:persist-executed-error', { messageHash: record.messageHash, error: (err as Error).message }));
 
 		try {
 			for (const operation of record.message.operations) {
 				await this.applyConsensusOperation(record, operation);
 			}
 		} catch (err) {
-			// A genuinely unexpected fault (e.g. storage I/O) — roll back the executed
+			// A genuinely unexpected fault (e.g. storage I/O) — roll back the in-memory
 			// marker so a corrected retry can re-run, and propagate so the caller learns
-			// the real cause. Recoverable local divergence is absorbed inside
-			// applyConsensusOperation and never reaches here.
+			// the real cause. The durable marker was never written (it lands only after
+			// apply succeeds, below), so there is nothing to roll back. Recoverable local
+			// divergence is absorbed inside applyConsensusOperation and never reaches here.
 			this.executedTransactions.delete(record.messageHash);
 			throw err;
 		}
+
+		// Persist the durable marker only now that apply has actually succeeded. Writing it
+		// eagerly (before the loop) would leave a stuck marker on a caught fault OR a crash
+		// mid-apply, and on redelivery handleConsensus short-circuits at the async
+		// wasTransactionExecuted check — silently dropping the transaction on this member
+		// forever. The durable marker exists only for post-restart dedup (the in-memory map
+		// is empty after restart), and the narrow window between "apply succeeded" and
+		// "durable write landed" is safe to re-run on restart: re-applying an
+		// already-applied consensus transaction is idempotent (the "ahead" divergence path
+		// in applyConsensusOperation tolerates it as a no-op), so it converges rather than
+		// dropping. Fire-and-forget: a persist failure must not fail the apply that succeeded.
+		this.stateStore?.markExecuted(record.messageHash, executedAt)
+			.catch(err => log('cluster-member:persist-executed-error', { messageHash: record.messageHash, error: (err as Error).message }));
 	}
 
 	/**
@@ -1136,25 +1478,93 @@ export class ClusterMember implements ICluster {
 	}
 
 	/**
-	 * Resolve race between two conflicting transactions.
-	 * Transaction with more promises wins. If tied, higher hash wins.
+	 * 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});
+	 *   3. still tied → higher message hash wins.
+	 *
+	 * Promise 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
+	 * `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
+	 * ticket occ-priority-first-breaks-promise-monotonicity.
+	 *
+	 * Priority is now a tie-break that runs only at EQUAL promise 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
+	 * 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
+	 * to this race tie-break.
+	 *
+	 * 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,
+	 * 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).
+	 *
+	 * NOTE: keep priority a self-contained additive message field + this one comparison key so it
+	 * composes with — does not block — a future HLC/crdt-sync redesign of this same path
+	 * (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;
-
-		// Transaction with more promises wins
-		if (existingCount > incomingCount) {
-			return 'keep-existing';
+		if (existingCount !== incomingCount) {
+			return existingCount > incomingCount ? 'keep-existing' : 'accept-incoming';
 		}
-		if (incomingCount > existingCount) {
-			return 'accept-incoming';
+
+		// 2. Equal promise counts → higher aged priority wins (fairness tie-break).
+		const existingPriority = this.recordPriority(existing);
+		const incomingPriority = this.recordPriority(incoming);
+		if (existingPriority !== incomingPriority) {
+			return existingPriority > incomingPriority ? 'keep-existing' : 'accept-incoming';
 		}
 
-		// Tie-breaker: higher message hash wins (deterministic)
+		// 3. Tie-breaker: higher message hash wins (deterministic).
 		return existing.messageHash > incoming.messageHash ? 'keep-existing' : 'accept-incoming';
 	}
 
+	/**
+	 * Aged advisory priority carried by a record's pend operation, clamped to [0, MaxPriority].
+	 * The multi-collection path carries it on `pend.transaction.priority`; the single-collection
+	 * (`Collection.sync`) path carries it as top-level `pend.priority`; a record with neither — a
+	 * legacy/unversioned coordinator's transaction, or a non-pend operation — is priority 0
+	 * (backward compatible: such transactions simply never age). Both carriers live inside the signed
+	 * `message`, so priority is integrity-protected in transit; clamping here bounds a self-asserted
+	 * out-of-range value to the cap.
+	 *
+	 * 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
+	 * transactions, which is exactly the concurrent-contention case priority is meant to order.
+	 */
+	private recordPriority(record: ClusterRecord): number {
+		for (const op of record.message.operations) {
+			if ('pend' in op) {
+				return clampPriority(op.pend.transaction?.priority ?? op.pend.priority);
+			}
+		}
+		return 0;
+	}
+
 	private operationsConflict(ops1: RepoMessage['operations'], ops2: RepoMessage['operations']): boolean {
 		// Check if one is a commit for the same action as a pend - these don't conflict
 		const actionId1 = this.getActionId(ops1);
@@ -1226,7 +1636,7 @@ export class ClusterMember implements ICluster {
 				const client = ClusterClient.create(peerIdFromString(peerId), this.peerNetwork, this.protocolPrefix);
 				promises.push(client.update(record));
 			} catch (error) {
-				console.error(`Failed to propagate to peer ${peerId}:`, error);
+				log('ERROR: Failed to propagate to peer %s: %o', peerId, error);
 			}
 		}
 		await Promise.allSettled(promises);