@optimystic/db-p2p 0.14.1 → 0.16.2

package/dist/src/cluster/cluster-repo.js

@@ -1,11 +1,11 @@
-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 } from "../dispute/invalidation.js";
 import { buildCommitCert, invalidationActionId } from "./commit-cert.js";
 import { ClusterClient } from "./client.js";
 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 { PenaltyReason } from "../reputation/types.js";
@@ -20,8 +20,10 @@ var TransactionPhase;
     TransactionPhase[TransactionPhase["Rejected"] = 4] = "Rejected";
     TransactionPhase[TransactionPhase["Propagating"] = 5] = "Propagating"; // Transaction is being propagated
 })(TransactionPhase || (TransactionPhase = {}));
+/** Stable reject reason a member emits when a declared peer set fails the membership admission gate. */
+export const MEMBERSHIP_NOT_ADMITTED = 'membership-not-admitted';
 export function clusterMember(components) {
-    return new ClusterMember(components.storageRepo, components.peerNetwork, components.peerId, components.privateKey, components.protocolPrefix, components.partitionDetector, components.fretService, components.validator, components.reputation, components.consensusConfig, components.stateStore, components.reconcileBlock, components.onCommitCertificate, components.onInvalidate, components.recomputeArbitratorSet);
+    return new ClusterMember(components.storageRepo, components.peerNetwork, components.peerId, components.privateKey, components.protocolPrefix, components.partitionDetector, components.fretService, components.validator, components.reputation, components.consensusConfig, components.stateStore, components.reconcileBlock, components.onCommitCertificate, components.onInvalidate, components.recomputeArbitratorSet, components.deriveExpectedCluster);
 }
 // How long to keep executed transaction records (10 minutes)
 const ExecutedTransactionTtlMs = 10 * 60 * 1000;
@@ -56,6 +58,7 @@ export class ClusterMember {
     onCommitCertificate;
     onInvalidate;
     recomputeArbitratorSet;
+    deriveExpectedCluster;
     // Track active transactions by their message hash
     activeTransactions = new Map();
     // Track executed consensus transactions to prevent duplicate execution (messageHash -> executedAt timestamp)
@@ -72,11 +75,30 @@ export class ClusterMember {
     // Interval handles for periodic cleanup (stored so dispose() can clear them)
     expirationInterval;
     cleanupInterval;
-    /** 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).
+     */
+    static 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.)
+     */
     superMajorityThreshold;
+    // 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.
+    minAbsoluteClusterSize;
+    clusterSizeTolerance;
+    membershipAdmissionFraction;
+    /** Configured full cluster size, or undefined when unknown (then the gate cannot judge a downsize). */
+    configuredClusterSize;
+    allowUnvalidatedSmallCluster;
     constructor(storageRepo, peerNetwork, peerId, privateKey, protocolPrefix, 
     // Reserved for partition-healing (backlog ticket 6.5-partition-healing); held but not yet consumed.
-    _partitionDetector, fretService, validator, reputation, consensusConfig, stateStore, reconcileBlock, onCommitCertificate, onInvalidate, recomputeArbitratorSet) {
+    _partitionDetector, fretService, validator, reputation, consensusConfig, stateStore, reconcileBlock, onCommitCertificate, onInvalidate, recomputeArbitratorSet, deriveExpectedCluster) {
         this.storageRepo = storageRepo;
         this.peerNetwork = peerNetwork;
         this.peerId = peerId;
@@ -90,7 +112,13 @@ export class ClusterMember {
         this.onCommitCertificate = onCommitCertificate;
         this.onInvalidate = onInvalidate;
         this.recomputeArbitratorSet = recomputeArbitratorSet;
-        this.superMajorityThreshold = consensusConfig?.superMajorityThreshold ?? 1.0;
+        this.deriveExpectedCluster = deriveExpectedCluster;
+        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();
@@ -98,6 +126,15 @@ export class ClusterMember {
         this.cleanupInterval = setInterval(() => this.processCleanupQueue(), 1000);
         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() {
+        return this.superMajorityThreshold;
+    }
     /**
      * Clears all interval and timeout handles and empties active state.
      * Called during node shutdown to prevent leaked timers.
@@ -227,10 +264,7 @@ export class ClusterMember {
                         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;
@@ -239,13 +273,7 @@ export class ClusterMember {
                 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;
@@ -319,10 +347,33 @@ export class ClusterMember {
         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');
         }
         // Merge signatures with equivocation detection
@@ -341,6 +392,10 @@ export class ClusterMember {
      * New peers are accepted normally.
      */
     detectEquivocation(existing, incoming, phase, messageHash) {
+        // 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)) {
             const existingSig = existing[peerId];
@@ -367,8 +422,25 @@ export class ClusterMember {
         return merged;
     }
     async validateRecord(record) {
-        // 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}`);
         }
@@ -380,47 +452,56 @@ export class ClusterMember {
         }
     }
     /**
-     * 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().
      */
-    async computeMessageHash(message) {
-        const msgBytes = new TextEncoder().encode(ClusterMember.canonicalJson(message));
-        const hashBytes = await sha256.digest(msgBytes);
-        return base58btc.encode(hashBytes.digest);
+    async computeMessageHash(record) {
+        return computeClusterMessageHash(record.message, recordMembershipDigest(record));
     }
     async validateSignatures(record) {
-        // 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}`);
             }
         }
         // 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.
+     */
     static canonicalJson(value) {
         return JSON.stringify(value, (_, v) => v && typeof v === 'object' && !Array.isArray(v)
             ? Object.keys(v).sort().reduce((o, k) => { o[k] = v[k]; return o; }, {})
             : v);
     }
     async computePromiseHash(record) {
-        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));
     }
     async computeCommitHash(record) {
-        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));
     }
     computeSigningPayload(hash, type, rejectReason) {
         const payload = hash + ':' + type + (rejectReason ? ':' + rejectReason : '');
@@ -431,17 +512,55 @@ export class ClusterMember {
         const sigBytes = await this.privateKey.sign(payload);
         return uint8ArrayToString(sigBytes, 'base64url');
     }
+    /**
+     * 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.
+     */
     async verifySignature(record, peerId, hash, signature) {
         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;
+        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 };
+        }
     }
     async getTransactionPhase(record) {
         const peerCount = Object.keys(record.peers).length;
@@ -479,8 +598,11 @@ export class ClusterMember {
         return count > total / 2;
     }
     async handlePromiseNeeded(record) {
-        // 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' : 'reject';
         const rejectReason = validationResult.valid ? undefined : validationResult.reason;
@@ -502,6 +624,154 @@ export class ClusterMember {
             }
         };
     }
+    /**
+     * 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.
+     */
+    async evaluatePromise(record) {
+        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.
+     */
+    async admitMembership(record) {
+        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.
+     */
+    async deriveExpectedClusterView(record) {
+        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);
+        }
+        catch (err) {
+            log('cluster-member:derive-expected-cluster-error', { messageHash: record.messageHash, error: err.message });
+            return undefined;
+        }
+    }
+    /** |A △ B| over two id lists (order-independent set symmetric difference). */
+    static symmetricDifferenceSize(a, b) {
+        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.
@@ -566,9 +836,12 @@ export class ClusterMember {
      * @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
@@ -577,31 +850,51 @@ export class ClusterMember {
      * @see docs/internals.md "Check-Then-Act Race in Consensus" and "Independent Node Storage" pitfalls
      */
     async handleConsensus(record) {
+        // 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.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.message }));
     }
     /**
      * Applies one consensus-approved operation to local storage.
@@ -940,22 +1233,89 @@ export class ClusterMember {
         return false; // No blocking conflicts
     }
     /**
-     * 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).
      */
     resolveRace(existing, 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.
+     */
+    recordPriority(record) {
+        for (const op of record.message.operations) {
+            if ('pend' in op) {
+                return clampPriority(op.pend.transaction?.priority ?? op.pend.priority);
+            }
+        }
+        return 0;
+    }
     operationsConflict(ops1, ops2) {
         // Check if one is a commit for the same action as a pend - these don't conflict
         const actionId1 = this.getActionId(ops1);
@@ -1026,7 +1386,7 @@ export class ClusterMember {
                 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);