@optimystic/db-p2p 0.24.2 → 0.25.0

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

@@ -1,4 +1,4 @@
-import { blockIdsForTransforms, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
+import { blockIdsForTransforms, isOwnRevision, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
 import { computeClusterCommitHash, computeClusterMessageHash, computeClusterPromiseHash, membershipDigest, recordMembershipDigest, clampPriority, clusterVoteSigningPayload, clusterVoteVerificationPayload } from "@optimystic/db-core";
 import { verifyInvalidationCertificate } from "../dispute/invalidation.js";
 import { buildCommitCert, invalidationActionId } from "./commit-cert.js";
@@ -10,6 +10,8 @@ import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } fr
 import { createLogger } from '../logger.js';
 import { PenaltyReason } from "../reputation/types.js";
 import { isMissingBaseRevisionFailure } from "../storage/storage-repo.js";
+import { checkPendValidation } from "../pend-validation.js";
+import { buildBlockCommitProof } from "./commit-proof.js";
 import { RECONCILE_TIMEOUT_MS } from "./reconcile-block.js";
 const log = createLogger('cluster-member');
 /** State of a transaction in the cluster */
@@ -26,6 +28,21 @@ var TransactionPhase;
 })(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';
+/**
+ * Stable reject reason a member emits when its own materialization of a commit's block disagrees
+ * with the content digest the transaction author declared (`CommitRequest.blockDigests`). Rides in
+ * the reject vote's `rejectReason`, which `clusterVoteSigningPayload` folds into the signed bytes —
+ * so the rejection itself is integrity-protected.
+ */
+export const CONTENT_DIGEST_MISMATCH = 'content-digest-mismatch';
+/**
+ * The two stable reject reasons a validator-configured member emits from the shared
+ * {@link checkPendValidation}: `PEND_NOT_VALIDATABLE` for a pend carrying no `validation` payload
+ * under `ClusterConsensusConfig.unvalidatablePendPolicy: 'reject'`, and `VALIDATOR_FAULT` for a
+ * checker that threw. Defined in `pend-validation.ts` (which the storage tier runs too, so both
+ * tiers refuse with the same prefixes) and re-exported here next to its siblings above.
+ */
+export { PEND_NOT_VALIDATABLE, VALIDATOR_FAULT } from "../pend-validation.js";
 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, components.deriveExpectedCluster);
 }
@@ -68,6 +85,19 @@ export class ClusterMember {
     activeTransactions = new Map();
     // Track executed consensus transactions to prevent duplicate execution (messageHash -> executedAt timestamp)
     executedTransactions = new Map();
+    // Local storage's verdict for a pend operation applied during consensus (messageHash -> PendResult).
+    // Retained so the coordinator can return storage's real answer instead of fabricating success —
+    // a pend that every member refused (rival pending action, or the revision already taken) must
+    // reach the writer as a conflict, not a win. Pruned alongside executedTransactions (same TTL).
+    executedPendResults = new Map();
+    // Local storage's verdict for a COMMIT operation applied during consensus (messageHash ->
+    // CommitResult). Retained so the coordinator can detect when the ahead-divergence tolerance in
+    // applyConsensusOperation swallowed a refusal whose real cause was a RIVAL action holding the
+    // requested revision — the commit-tier acknowledgement hole: a commit that assembled consensus
+    // inside every member's signed-but-not-yet-applied window is refused by every member's storage
+    // at apply, and without this verdict the coordinator fabricates a success no member durably
+    // stored. Pruned alongside executedTransactions (same TTL).
+    executedCommitResults = new Map();
     // Fast in-memory dedup for applied invalidations, keyed `${invalidatedActionId}:${disputeId}`.
     // The durable source of truth is the invalidation log entry (Log.findInvalidation, re-checked
     // inside the sink); this map only spares redundant work when the same invalidation reaches
@@ -101,6 +131,9 @@ export class ClusterMember {
     /** Operator-asserted smallest genuine cohort size, or undefined when unknown. */
     assumedClusterSize;
     allowUnvalidatedSmallCluster;
+    /** What a validator-configured member does with a pend carrying no `validation` payload — see
+     * {@link ClusterConsensusConfig.unvalidatablePendPolicy}. Read once, like the gate parameters. */
+    unvalidatablePendPolicy;
     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, deriveExpectedCluster) {
@@ -124,6 +157,7 @@ export class ClusterMember {
         this.membershipAdmissionFraction = consensusConfig?.membershipAdmissionFraction ?? 0.75;
         this.assumedClusterSize = consensusConfig?.assumedClusterSize;
         this.allowUnvalidatedSmallCluster = consensusConfig?.allowUnvalidatedSmallCluster ?? false;
+        this.unvalidatablePendPolicy = consensusConfig?.unvalidatablePendPolicy ?? 'accept';
         // State the resolved gate parameters once, so an operator diagnosing a membership rejection can see
         // what this node actually resolved. A fact, not a warning: `assumedClusterSize < clusterSize` is the
         // normal default state, so warning on it would fire for every node and be ignored.
@@ -164,6 +198,8 @@ export class ClusterMember {
         }
         this.activeTransactions.clear();
         this.cleanupQueue.length = 0;
+        this.executedPendResults.clear();
+        this.executedCommitResults.clear();
     }
     /**
      * Checks if a transaction's operations were already executed during consensus.
@@ -172,6 +208,31 @@ export class ClusterMember {
     wasTransactionExecuted(messageHash) {
         return this.executedTransactions.has(messageHash);
     }
+    /**
+     * Local storage's verdict for the pend operation this member applied at consensus for
+     * `messageHash`, when one was retained. The coordinator reads this so the answer a writer gets
+     * is the answer storage gave — the cluster path must not fabricate a success the single-node
+     * path (`CoordinatorRepo.pend`'s `peerCount <= 1` short-circuit) would never produce. Absent for
+     * transactions carrying no pend operation, for transactions applied before this member restarted
+     * (the map is in-memory only; the coordinator then falls back to its fabricated-success shape,
+     * with the promise-phase pending check in {@link validatePendOperations} narrowing that window),
+     * and after the executed-transaction TTL prunes it.
+     */
+    getExecutedPendResult(messageHash) {
+        return this.executedPendResults.get(messageHash);
+    }
+    /**
+     * Commit-shaped sibling of {@link getExecutedPendResult}: local storage's verdict for a commit
+     * operation applied during consensus, when this member retained one. `CoordinatorRepo.commit`
+     * consults it after a locally-executed commit-consensus — a retained refusal whose cause a local
+     * re-read confirms as a rival holding the requested revision is returned to the writer as a
+     * retryable conflict instead of the fabricated success the ahead-divergence tolerance would
+     * otherwise imply. Same availability caveats as the pend accessor: in-memory only, absent for
+     * pre-restart applies, pruned on the executed-transaction TTL.
+     */
+    getExecutedCommitResult(messageHash) {
+        return this.executedCommitResults.get(messageHash);
+    }
     /**
      * Handles an incoming cluster update, managing the two-phase commit process
      * and coordinating with the local storage repo
@@ -642,9 +703,19 @@ export class ClusterMember {
         // 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.
+        // only orders *concurrently-pending* rivals.
+        //
+        // The lost update this predicted WAS observed (a pend admitted between a rival's
+        // pend-consensus and commit-consensus, then refused by every member's storage at apply and
+        // still reported to the writer as a success). Holding the reservation until `handleConsensus`
+        // would not have closed it — the loser was approved before the winner's apply had even
+        // reached most members — so the cure went elsewhere: `validatePendOperations` now rejects a
+        // pend whose blocks are held by a different unresolved STORAGE pending record (the durable
+        // reservation that spans pend-apply → commit/cancel), and the coordinator returns storage's
+        // retained apply verdict instead of fabricating success (`getExecutedPendResult`). Residual:
+        // a member that has not yet applied the rival's pend abstains from that vote, and only the
+        // coordinating node's own verdict is threaded back — see the handoff notes on
+        // `CoordinatorRepo.pend`.
         const approvedPromises = Object.values(record.promises).filter(s => s.type === 'approve');
         if (approvedPromises.length >= superMajority && !record.commits[ourId]) {
             return { phase: TransactionPhase.OurCommitNeeded };
@@ -717,17 +788,31 @@ 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.
+     * admitted) validate its pend operations, then its commit operations. Failing any yields a
+     * `{ valid:false, reason }` the caller turns into a `reject` vote. Keeping the three separate keeps
+     * the reason strings distinct — a `membership-not-admitted` reject is a different signal (feeds the
+     * dispute path) than a stale-revision / custom-validator reject, which is different again from a
+     * `content-digest-mismatch` (see {@link validateCommitOperations}). A record carries pend OR commit
+     * operations, so in practice exactly one of the latter two has anything to inspect.
      */
     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);
+        const pendValidation = await this.validatePendOperations(record);
+        if (!pendValidation.valid) {
+            return pendValidation;
+        }
+        // Revision staleness before content digests: a commit whose revision a rival already took can
+        // never win, and the sharper stale reject also skips the per-block digest previews (the digest
+        // check would abstain on such a block anyway — its local base rev no longer matches the
+        // declared one).
+        const commitRevValidation = await this.validateCommitRevisions(record);
+        if (!commitRevValidation.valid) {
+            return commitRevValidation;
+        }
+        return await this.validateCommitOperations(record);
     }
     /**
      * Membership admission gate. Decides whether the coordinator-declared peer set (`record.peers`, call it
@@ -868,18 +953,44 @@ export class ClusterMember {
     }
     /**
      * 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.
+     * `undefined` when it cannot (no capability, no coordinating block id, a coordinating block not bound
+     * to the record's own operations, 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.
+     *
+     * Read off `record.message`, NOT a top-level record field: `messageHash` covers the message only, so
+     * only the in-message copy is tamper-evident to a relaying peer. (There is no top-level copy any more —
+     * see {@link ClusterRecord.message}.)
      */
     async deriveExpectedClusterView(record) {
         if (!this.deriveExpectedCluster) {
             return undefined;
         }
-        const blockId = record.coordinatingBlockIds?.[0];
+        const blockId = record.message.coordinatingBlockIds?.[0];
         if (blockId === undefined) {
             return undefined;
         }
+        // Hashing the field makes it tamper-evident to RELAYS, but the coordinator is the party this gate
+        // exists to check and it picks the field before it computes the hash. Unbound, a Byzantine
+        // coordinator declares a shrunken cohort `D` and names a coordinating block whose real cohort
+        // resembles `D`: every member then derives that block's cohort, finds kEst = |D|, symmetric
+        // difference 0, and admits — the gate fully defeated. Binding the coordinating block to a block the
+        // record's OWN operations touch removes that free choice. `getAffectedBlockIds` is the same block
+        // extraction conflict detection already runs on this message — one definition, so the set a
+        // coordinating id must come from cannot drift from the set the record is judged to touch.
+        if (!this.getAffectedBlockIds(record.message.operations).includes(blockId)) {
+            log('cluster-member:coordinating-block-unbound', {
+                messageHash: record.messageHash,
+                coordinatingBlockId: blockId
+            });
+            // Fail closed into the branch that already exists rather than throwing: a hard reject would
+            // change `validateRecord`'s failure surface, and "not confident" already refuses any downsize.
+            return undefined;
+        }
+        // Which block a member derived its cohort view from is the single most useful fact when an
+        // admission decision has to be explained after the fact — and the only externally visible sign
+        // that the confident predicates ran at all rather than the fallback floor.
+        log('cluster-member:derive-expected-cluster', { messageHash: record.messageHash, blockId });
         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
@@ -906,7 +1017,8 @@ export class ClusterMember {
     }
     /**
      * Validates pend operations in a cluster record using the transaction validator.
-     * Also checks for stale revisions to prevent consensus on operations that would fail.
+     * Also checks for stale revisions, and for blocks held by a different unresolved pending
+     * action, to prevent consensus on operations that storage would refuse at apply.
      * Returns success if no validator is configured (backwards compatibility).
      */
     async validatePendOperations(record) {
@@ -914,11 +1026,12 @@ export class ClusterMember {
         for (const operation of record.message.operations) {
             if ('pend' in operation) {
                 const pendRequest = operation.pend;
+                const blockIds = blockIdsForTransforms(pendRequest.transforms);
+                // One state read serves both checks below: `latest` for staleness, `pendings` for the
+                // unresolved-rival check.
+                const blockResults = await this.storageRepo.get({ blockIds });
                 // Check for stale revisions before allowing consensus
                 if (pendRequest.rev !== undefined) {
-                    const blockIds = blockIdsForTransforms(pendRequest.transforms);
-                    // Get block states to check latest revisions
-                    const blockResults = await this.storageRepo.get({ blockIds });
                     for (const blockId of blockIds) {
                         const blockResult = blockResults[blockId];
                         if (blockResult?.unavailable !== undefined) {
@@ -935,13 +1048,19 @@ export class ClusterMember {
                             });
                             return { valid: false, reason: `block ${blockId} unavailable (${blockResult.unavailable}): cannot verify revision` };
                         }
-                        const latestRev = blockResult?.state?.latest?.rev;
-                        if (latestRev !== undefined && latestRev >= pendRequest.rev) {
+                        const latest = blockResult?.state?.latest;
+                        if (latest !== undefined && latest.rev >= pendRequest.rev) {
+                            // Self is excluded so a redelivered pend for this same action stays
+                            // approvable — the same exclusion the pending-rival check below documents,
+                            // and the same rule storage applies (see {@link isOwnRevision}).
+                            if (isOwnRevision(latest, pendRequest.rev, pendRequest.actionId)) {
+                                continue;
+                            }
                             log('cluster-member:validation-stale-revision', {
                                 messageHash: record.messageHash,
                                 blockId,
                                 requestedRev: pendRequest.rev,
-                                latestRev
+                                latestRev: latest.rev
                             });
                             // Deliberately prose-only: this reason is fed to computeSigningPayload, signed,
                             // and carried as Signature.rejectReason, so adding a structured revision here
@@ -950,17 +1069,294 @@ export class ClusterMember {
                             // is NOT a StaleFailure producer, so StaleFailure.staleAt does not apply; the
                             // coordinator's own local re-read (CoordinatorRepo.classifyStaleRejection)
                             // supplies that number when it can confirm the revision itself.
-                            return { valid: false, reason: `stale revision: block ${blockId} at rev ${latestRev}, requested rev ${pendRequest.rev}` };
+                            return { valid: false, reason: `stale revision: block ${blockId} at rev ${latest.rev}, requested rev ${pendRequest.rev}` };
                         }
                     }
                 }
-                // Run custom validator if configured
-                if (this.validator && pendRequest.transaction && pendRequest.operationsHash) {
-                    const result = await this.validator.validate(pendRequest.transaction, pendRequest.operationsHash);
-                    if (!result.valid) {
-                        return { valid: false, reason: result.reason };
+                // Reject a pend whose blocks are held by a DIFFERENT unresolved pending action. This is
+                // the durable reservation the in-memory table (`findConflict` / `activeTransactions`)
+                // cannot provide: that table clears the moment the rival's PEND record reaches
+                // consensus, but the rival's storage pending record — written at pend-apply, removed at
+                // commit or cancel — spans exactly the pend→commit window in which `latest.rev` has not
+                // yet advanced. Storage's own pend would refuse this request at consensus-apply for the
+                // same reason (`StorageRepo.pend`'s listPendingTransactions scan); voting reject here
+                // moves that verdict into the phase where the cohort aggregates it, so the loser is
+                // refused with a real answer instead of burning a consensus round it cannot win. A
+                // member that has not yet applied the rival's pend has no record and simply abstains
+                // from this reason; the coordinator returning the retained apply verdict
+                // (getExecutedPendResult) catches that residual. Self is excluded so a redelivered pend
+                // for this same action stays approvable. An unavailable block carries no `pendings` and
+                // abstains (the rev branch above already fail-closes when a revision claim is at stake).
+                // Reason stays plain prose: it is fed to computeSigningPayload and carried as
+                // Signature.rejectReason, exactly like the stale-revision reason above.
+                for (const blockId of blockIds) {
+                    const rivals = (blockResults[blockId]?.state?.pendings ?? []).filter(actionId => actionId !== pendRequest.actionId);
+                    if (rivals.length > 0) {
+                        log('cluster-member:validation-pending-conflict', {
+                            messageHash: record.messageHash,
+                            blockId,
+                            actionId: pendRequest.actionId,
+                            rivals
+                        });
+                        return { valid: false, reason: `pending conflict: block ${blockId} held by unresolved action(s) ${rivals.join(', ')}` };
                     }
                 }
+                // Re-check the transaction when a validator is configured. The unvalidatable-pend
+                // policy and the throwing-validator catch live in the shared `checkPendValidation`,
+                // which the storage tier runs too, so a member cannot vote approve on a shape its own
+                // storage would refuse at apply. Its reasons are fed to computeSigningPayload and
+                // carried as Signature.rejectReason, exactly like the stale-revision reason above, so
+                // a fail-closed refusal here is signed evidence rather than a lost vote.
+                const validator = this.validator;
+                const validation = await checkPendValidation(pendRequest, validator && (({ transaction, operationsHash }) => validator.validate(transaction, operationsHash)), this.unvalidatablePendPolicy, event => event.kind === 'unvalidatable'
+                    // An operator can grep this line to see how much traffic goes unchecked.
+                    ? log('cluster-member:pend-unvalidatable', {
+                        messageHash: record.messageHash,
+                        actionId: pendRequest.actionId,
+                        policy: event.policy
+                    })
+                    : log('cluster-member:validator-fault', {
+                        messageHash: record.messageHash,
+                        error: event.error
+                    }));
+                if (!validation.valid) {
+                    return { valid: false, reason: validation.reason };
+                }
+            }
+        }
+        return { valid: true };
+    }
+    /**
+     * Promise-round check that a commit record's requested revision is not already committed HERE
+     * under a different action. This is the member-side arm that keeps a DEAD rival's re-broadcast
+     * commit from assembling consensus: after a race winner commits and members clear its record
+     * from the reservation table, a loser's re-driven commit meets no conflict votes — without this
+     * check every caught-up member would abstain (the content-digest check below abstains for
+     * update-only transforms whose base moved) and the loser could reach commit-consensus for a
+     * write no member will ever durably store (its apply is refused stale and tolerated as 'ahead'
+     * divergence — see `applyConsensusOperation`).
+     *
+     * Same "must run on the promise round" rule as {@link validateCommitOperations}: the
+     * commit-round vote is deliberately blind, so promise votes are the only ones that carry
+     * "I checked this". The four-way rule, per committed block:
+     *  - no local `latest`, or `latest.rev < commit.rev` → abstain (approve). Preserves the
+     *    lagging-member tolerance (`coordinator-repo-commit-divergence.spec.ts`): a member behind
+     *    the commit cannot judge it.
+     *  - `latest.rev === commit.rev` with the SAME action → abstain (approve). Idempotent
+     *    redelivery of an already-durable commit; rejecting would make the writer rebase and
+     *    re-append an action that already landed — a duplicate entry. (Storage's `alreadyDone`
+     *    partition returns success for this shape at apply.)
+     *  - `latest.rev === commit.rev` with a DIFFERENT action → reject: a rival took the revision.
+     *  - `latest.rev > commit.rev` → consult the {@link IRevisionActionReader} capability for who
+     *    holds `commit.rev`: a different action → reject; the same action → abstain (already
+     *    durable, history simply moved on); no record / capability absent / read fault → abstain.
+     *
+     * Never throws out of the vote path: any read fault is an abstain (mirroring the digest check's
+     * preview-error arm), because a member that fails to vote at all is worse than one that
+     * abstains. Reason stays plain prose — it is fed to computeSigningPayload and carried as
+     * Signature.rejectReason, exactly like the stale-revision pend reject.
+     *
+     * Residual (see the commit-tier handoff): a member that signed the winner's commit but has not
+     * yet APPLIED it sits in a window where it holds neither the winner's record (reservation
+     * dropped at commit-sign, `shouldPersist = false`) nor the winner's revision (storage still
+     * behind) — it abstains here. A capability-less member, or one with history truncated below
+     * `latest`, abstains at `latest.rev > commit.rev` too. A rival's commit can therefore still
+     * pass the promise round if EVERY member is simultaneously in one of those states — on a fast
+     * cohort that window is the COMMON case, not the corner. The backstop is downstream of
+     * consensus: every member's apply then refuses the rival as stale, the coordinating node's own
+     * member retains that refusal (`getExecutedCommitResult`), and `CoordinatorRepo.commit`
+     * confirms the rival against local storage and answers the writer with a retryable conflict
+     * instead of a fabricated success. `ConflictRaceLostError` conversion and classified
+     * rejections close the re-drive route the same way.
+     */
+    async validateCommitRevisions(record) {
+        for (const operation of record.message.operations) {
+            if (!('commit' in operation)) {
+                continue;
+            }
+            const commit = operation.commit;
+            let blockResults;
+            try {
+                // The member's raw storage repo (no cluster recursion) — the same seam
+                // validatePendOperations reads on every pend vote.
+                blockResults = await this.storageRepo.get({ blockIds: commit.blockIds });
+            }
+            catch (err) {
+                log('cluster-member:commit-staleness-read-error', {
+                    messageHash: record.messageHash,
+                    actionId: commit.actionId,
+                    error: err instanceof Error ? err.message : String(err)
+                });
+                continue; // a local read fault is an abstain, never an escape out of the vote path
+            }
+            for (const blockId of commit.blockIds) {
+                const latest = blockResults[blockId]?.state?.latest;
+                if (!latest || latest.rev < commit.rev) {
+                    continue; // behind (or block never seen): cannot judge — abstain
+                }
+                if (isOwnRevision(latest, commit.rev, commit.actionId)) {
+                    continue; // idempotent redelivery of an already-durable commit — MUST NOT reject
+                }
+                if (latest.rev === commit.rev) {
+                    log('cluster-member:validation-stale-commit', {
+                        messageHash: record.messageHash,
+                        blockId,
+                        actionId: commit.actionId,
+                        rev: commit.rev,
+                        committedBy: latest.actionId
+                    });
+                    return { valid: false, reason: `stale commit: block ${blockId} rev ${commit.rev} committed by a different action` };
+                }
+                // latest.rev > commit.rev: latest can no longer name who took commit.rev — ask the
+                // revision index. Structural probe, same pattern as previewCommitDigest below: a repo
+                // without the capability abstains.
+                const reader = this.storageRepo;
+                if (typeof reader.getRevisionAction !== 'function') {
+                    continue;
+                }
+                let takenBy;
+                try {
+                    takenBy = await reader.getRevisionAction(blockId, commit.rev);
+                }
+                catch (err) {
+                    log('cluster-member:commit-staleness-revision-read-error', {
+                        messageHash: record.messageHash,
+                        blockId,
+                        rev: commit.rev,
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                    continue; // read fault → abstain
+                }
+                if (takenBy !== undefined && takenBy !== commit.actionId) {
+                    log('cluster-member:validation-stale-commit', {
+                        messageHash: record.messageHash,
+                        blockId,
+                        actionId: commit.actionId,
+                        rev: commit.rev,
+                        committedBy: takenBy,
+                        latestRev: latest.rev
+                    });
+                    return { valid: false, reason: `stale commit: block ${blockId} rev ${commit.rev} committed by a different action` };
+                }
+                // takenBy === commit.actionId (already durable, history moved on) or undefined
+                // (truncated history — unknown): abstain either way.
+            }
+        }
+        return { valid: true };
+    }
+    /**
+     * Promise-round check of a commit record's declared content digests
+     * (`CommitRequest.blockDigests`) against what this member's OWN pended copy of each transform
+     * would materialize (`StorageRepo.previewCommitDigest`). This is what makes a promise approval on
+     * a commit record MEAN something about content: before this hook, the promise round validated
+     * nothing for commits (`validatePendOperations` only inspects pend operations).
+     *
+     * MUST run on the promise round, not the commit round: the commit-round vote is cast deliberately
+     * blind — `getTransactionPhase` signs the commit whenever promise approvals reach super-majority,
+     * regardless of this member's own promise vote — so promise approvals are the only votes that
+     * carry "I checked this". Do not move it.
+     *
+     * Checkable/abstain rule, keyed on the member's OWN pended transform (the payload the client
+     * authored, delivered at pend — a hostile declarer cannot force or dodge a check by mis-declaring
+     * `baseRev`):
+     *  - transform carries an `insert` → base-independent, ALWAYS check (declared `baseRev` ignored);
+     *  - `updates` only → check iff this member's local base rev equals the declared `baseRev`
+     *    (StorageRepo.commit accepts any `latest.rev < request.rev`, so a lagging member applying an
+     *    update-only transform to an older base legitimately materializes different bytes);
+     *  - `delete` only / no base / unmaterializable base → materializes nothing to compare, abstain;
+     *  - no pending transform for the action (this member never saw the pend) → abstain.
+     * "Abstain" = contribute no content attestation: approve exactly as before this check existed.
+     *
+     * Residual: a false digest survives only when the declarer lies AND enough of the cohort is
+     * simultaneously unable to check (lagging on update-only blocks, missed pends) that no honest
+     * checker is left — any single caught-up honest member rejects. Strictly stronger than before,
+     * when commit signatures bound no content at all. Verifying/persisting a durable content proof is
+     * later work (persist-block-commit-proof).
+     */
+    async validateCommitOperations(record) {
+        // Capability probe: `storageRepo` is typed IRepo, and only a repo that owns the local
+        // materialization can preview one. A repo without the capability abstains everywhere (also
+        // keeps mock-repo harnesses and non-storage compositions on the legacy approve path).
+        // NOTE: probing structurally means a decorating/caching repo later inserted at this seam
+        // silently disables the whole check with no signal. `ICommitDigestPreviewer` exists so such a
+        // decorator has a named contract to forward; if a non-forwarding wrapper is ever wired here,
+        // promote this to a typed component field rather than widening the probe.
+        const repo = this.storageRepo;
+        if (typeof repo.previewCommitDigest !== 'function') {
+            return { valid: true };
+        }
+        for (const operation of record.message.operations) {
+            if (!('commit' in operation)) {
+                continue;
+            }
+            const commit = operation.commit;
+            // An upgraded member receiving a commit with no declarations abstains everywhere.
+            if (!commit.blockDigests) {
+                continue;
+            }
+            // One Set per commit operation: the surplus-entry filter below is a membership test per
+            // declared id, and `blockIds` is a per-coordinator batch that can be wide.
+            const committedIds = new Set(commit.blockIds);
+            // NOTE: previews run one block at a time, so a commit declaring N blocks adds N sequential
+            // preview round-trips (each 1-3 block-storage reads plus a structuredClone of the base and
+            // the transform) to this member's promise-round latency. Unmeasured, and sequencing buys the
+            // short-circuit on the first mismatch. If wide commits ever show up as promise latency,
+            // fan the previews out with Promise.all and reduce the results, rather than sampling a
+            // subset of the declared ids — a skipped id is an unchecked id.
+            for (const [blockId, declared] of Object.entries(commit.blockDigests)) {
+                // Surplus (or hostile) entry for a block this commit does not even cover: ignore it —
+                // never throw out of the vote path, and never reject on content nobody is committing.
+                if (!committedIds.has(blockId)) {
+                    continue;
+                }
+                // `blockDigests` is untrusted wire data with no ingress schema behind it, so the entry
+                // need not be the shape the type promises. A malformed entry is treated as an omitted
+                // one (abstain) rather than a mismatch: rejecting on it would let a garbled request
+                // look like forged content, and reading through it would throw a TypeError out of the
+                // vote path — this member would then fail to vote at all instead of voting reject.
+                if (typeof declared?.digest !== 'string') {
+                    continue;
+                }
+                let preview;
+                try {
+                    preview = await repo.previewCommitDigest(blockId, commit.actionId, commit.rev);
+                }
+                catch (err) {
+                    log('cluster-member:content-digest-preview-error', {
+                        messageHash: record.messageHash,
+                        blockId,
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                    continue; // a local preview fault is an abstain, never a content judgement
+                }
+                // No pend seen here, or the transform materializes nothing to compare (tombstone,
+                // updates with no base, unmaterializable base) → abstain.
+                if (preview === undefined || preview.digest === undefined) {
+                    continue;
+                }
+                // `typeof === 'number'` rather than `!== undefined` for the same untrusted-shape reason
+                // as the digest guard above: a non-numeric declared baseRev can never equal a local
+                // one, so it degrades to an abstain instead of comparing junk.
+                const checkable = preview.baseIndependent
+                    || (typeof declared.baseRev === 'number' && preview.baseRev === declared.baseRev);
+                if (!checkable) {
+                    continue;
+                }
+                if (preview.digest !== declared.digest) {
+                    log('cluster-member:content-digest-mismatch', {
+                        messageHash: record.messageHash,
+                        blockId,
+                        actionId: commit.actionId,
+                        rev: commit.rev,
+                        declaredDigest: declared.digest,
+                        declaredBaseRev: declared.baseRev,
+                        previewDigest: preview.digest,
+                        previewBaseRev: preview.baseRev,
+                        baseIndependent: preview.baseIndependent
+                    });
+                    // One vote per record: a single mismatching block rejects the whole record.
+                    return { valid: false, reason: CONTENT_DIGEST_MISMATCH };
+                }
             }
         }
         return { valid: true };
@@ -1033,7 +1429,11 @@ export class ClusterMember {
             // 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.
+            // A retained pend verdict rolls back with the marker: it belongs to an apply
+            // that is now considered not-executed, and a re-run will retain a fresh one.
             this.executedTransactions.delete(record.messageHash);
+            this.executedPendResults.delete(record.messageHash);
+            this.executedCommitResults.delete(record.messageHash);
             throw err;
         }
         // Persist the durable marker only now that apply has actually succeeded. Writing it
@@ -1103,6 +1503,13 @@ export class ClusterMember {
         }
         if ('pend' in operation) {
             const result = await this.storageRepo.pend(operation.pend);
+            // Retain the verdict either way so the coordinator can hand the writer storage's real
+            // answer (see getExecutedPendResult). A refusal here is NOT local divergence the way a
+            // commit refusal is: pend-consensus confers no durability — a refusal carrying `pending`
+            // (a rival's unresolved action holds the blocks) or `missing` (the requested revision is
+            // already committed) is the optimistic-concurrency verdict, and swallowing it acknowledged
+            // writes that no member stored.
+            this.executedPendResults.set(messageHash, result);
             if (!result.success) {
                 log('cluster-member:consensus-pend-diverged', {
                     messageHash,
@@ -1133,9 +1540,23 @@ export class ClusterMember {
                 const commitSignedPayload = clusterVoteSigningPayload(await this.computeCommitHash(record), 'approve');
                 this.captureCommitCert(record, commit.actionId, commitSignedPayload);
             }
+            // Project the consensus record into a durable BlockCommitProof and hand it down the commit
+            // path — StorageRepo persists it only where the local materialization matches the declared
+            // digest (see persistProofIfContentMatches). A cheap projection (no hashing/signing).
+            // `undefined` for a v1 / unversioned record: its hashes bind no peer set, so it is never
+            // certifiable — logged so an operator can see why a cohort retains no proofs. The cast is the
+            // named ICommitProofPersister contract; a plain IRepo mock ignores the extra argument.
+            const proof = buildBlockCommitProof(record);
+            if (proof === undefined) {
+                log('cluster-member:commit-proof-skipped', {
+                    messageHash,
+                    actionId: commit.actionId,
+                    membershipVersion: record.membershipVersion
+                });
+            }
             let result;
             try {
-                result = await this.storageRepo.commit(commit);
+                result = await this.storageRepo.commit(commit, undefined, proof);
             }
             catch (err) {
                 // `StorageRepo.commit` throws (rather than returning success:false) when
@@ -1156,12 +1577,34 @@ export class ClusterMember {
                 }
                 throw err;
             }
+            // Retain the verdict either way (see getExecutedCommitResult): a success confirms local
+            // durability, and an ahead-shaped refusal is the only evidence the coordinator has that
+            // the tolerance below swallowed a rival's win at the requested revision. The
+            // missing-pending throw path above retains nothing — no CommitResult exists there, and
+            // the coordinator's fabricated-success fallback plus cohort reconcile is the right shape
+            // for a member that is genuinely behind.
+            this.executedCommitResults.set(messageHash, result);
             if (!result.success) {
                 // success:false is a StaleFailure. `missing` ⇒ ahead/stale divergence
                 // (we already hold ≥ this rev): tolerate, do NOT reconcile downward. A
                 // missing-base reason ⇒ behind divergence, reconcile (below). Any other bare
                 // `reason` with no `missing` ⇒ a genuine internalCommit fault: propagate so
                 // handleConsensus rolls back the executed marker and rethrows.
+                //
+                // NOTE: this 'ahead' tolerance is what turns a rival's commit that somehow reaches
+                // consensus into a reported success no member durably stored (consensus without
+                // durability — the commit-tier acknowledgement hole). It must stay: a member
+                // genuinely ahead of a redelivered/lagging commit is the common, correct case. The
+                // guards live UPSTREAM: `validateCommitRevisions` rejects the rival at the promise
+                // round, `CoordinatorRepo.commit` returns lost races as retryable conflicts instead
+                // of re-driving them, and the verdict retained just above (getExecutedCommitResult)
+                // lets the coordinating node convert its OWN member's rival-confirmed refusal into a
+                // conflict answer — that last guard is what closes the signed-but-not-yet-applied
+                // window, where two commits for one revision both assemble consensus because signing
+                // drops each member's reservation before applying advances its storage. If
+                // consensus-without-durability is ever observed again, look at those guards' abstain
+                // residuals (non-coordinating members' verdicts are not threaded back; capability-less
+                // or history-truncated storage abstains), not at this branch.
                 if (result.missing?.length) {
                     log('cluster-member:consensus-commit-diverged', {
                         messageHash,
@@ -1496,7 +1939,7 @@ export class ClusterMember {
     }
     /**
      * 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
+     * The multi-collection path carries it on `pend.validation.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
@@ -1512,7 +1955,11 @@ export class ClusterMember {
     recordPriority(record) {
         for (const op of record.message.operations) {
             if ('pend' in op) {
-                return clampPriority(op.pend.transaction?.priority ?? op.pend.priority);
+                // Every hop optional: `validation` arrives off the wire inside a signed message whose
+                // hash binds its bytes, not its shape, so a malformed pair must yield priority 0 (what
+                // clampPriority already does for a missing or Byzantine number) rather than throw out
+                // of the vote path — the lost vote this fail-closed pass exists to prevent.
+                return clampPriority(op.pend.validation?.transaction?.priority ?? op.pend.priority);
             }
         }
         return 0;
@@ -1553,6 +2000,13 @@ export class ClusterMember {
         }
         return undefined;
     }
+    /**
+     * Every block id the message's own operations name. Two consumers, deliberately sharing one
+     * definition: conflict detection (which writes must serialize against each other) and the membership
+     * admission gate's binding check (the set a legitimate `coordinatingBlockIds[0]` must come from —
+     * {@link ClusterMember.deriveExpectedClusterView}). If the two ever disagreed, a coordinator could
+     * name a block the record is not judged to touch.
+     */
     getAffectedBlockIds(operations) {
         const blockIds = new Set();
         for (const operation of operations) {
@@ -1636,6 +2090,8 @@ export class ClusterMember {
         for (const [messageHash, executedAt] of Array.from(this.executedTransactions.entries())) {
             if (executedAt < expirationThreshold) {
                 this.executedTransactions.delete(messageHash);
+                this.executedPendResults.delete(messageHash);
+                this.executedCommitResults.delete(messageHash);
             }
         }
         // Prune old applied-invalidation dedup markers on the same TTL.