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

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

@@ -7,7 +7,7 @@ import { quorumSize, corroboratorCapacity, selectQuorumRev, certifiedEquivocatio
 import { certifyClaim, isAttributableProofFailure, proofThresholds } from "../cluster/certified-claims.js";
 import { DEFAULT_CLUSTER_SIZE, resolveRepairCorroborationClusterSize } from "../cluster/cluster-policy.js";
 import { RECONCILE_TIMEOUT_MS } from "../cluster/reconcile-block.js";
-import { isMissingBaseRevisionFailure, MISSING_BASE_REVISION_REASON } from "../storage/storage-repo.js";
+import { isMissingBaseRevisionFailure, COMMIT_NOT_DURABLE_REASON, MISSING_BASE_REVISION_REASON } from "../storage/storage-repo.js";
 import { buildBlockCommitProof } from "../cluster/commit-proof.js";
 /** How long one cohort peer gets to answer the latest-revision consult before it counts as silent. */
 const LATEST_QUERY_TIMEOUT_MS = 1000;
@@ -166,6 +166,31 @@ export class CoordinatorRepo {
     responsibilityCache = new LruMap(1000);
     static RESPONSIBILITY_TTL_MS = 60_000;
     lastSeenCommitMs = new LruMap(1000);
+    /**
+     * Per block, when (`this.now()` at the consult's start) a consult last SETTLED that this node's
+     * absence of it is the cohort's answer too — see `absenceSettled` on {@link fetchBlockFromCluster}'s
+     * result. Only the solo-self exit settles today: when this node is the block's whole cohort, every
+     * acknowledged commit of it lands in this node's storage before the writer hears success, so the
+     * block reads present and the memo dies. Read only for a block still missing locally
+     * ({@link absenceIsSettled}); cleared by any pend or commit this node coordinates for the block, by
+     * seeing it present, and by any later consult of it that does not settle.
+     *
+     * Deliberately its OWN map rather than `lastSeenCommitMs`: that one is also stamped for missing
+     * blocks at exits whose verdict is NOT a confirmed absence (the `cohort-too-small` arm when a peer
+     * claimed a revision, the post-restore arm when acquisition failed), so reading it here would turn
+     * a `claimed-elsewhere` absence into an authoritative one for a whole window.
+     *
+     * NOTE: accepted tradeoff — a cohort-of-one view can be transient (peers still mid-identify; see
+     * the solo exit), and a block another node creates through the cohort it sees is then reported
+     * absent here for up to one `readRepairWindowMs` after this node's view grows — the same one-window
+     * cost the held-block window pays for a growing cohort. Revisit if a caller ever needs
+     * create-visibility across coordinators tighter than one window — such a caller needs a revision
+     * floor (backlog `feat-refresh-can-demand-a-revision-floor`), not a shorter window.
+     *
+     * NOTE: LRU-bounded like its siblings; an eviction under >1000 settled blocks loses a memo and
+     * costs one extra consult — the safe direction.
+     */
+    settledAbsences = new LruMap(1000);
     /** Per block, what earlier repair passes left unresolved — see {@link AheadClaimState}.
      *  Outlives the consult on purpose: the read-repair window skips consults for blocks checked
      *  recently, and a doubt dropped there is a stale answer served as confirmed again.
@@ -343,6 +368,12 @@ export class CoordinatorRepo {
         // are meant to be — a rare degradation during routing churn — since routing already placed this
         // node near the block. If they ever become routine, gate acquisition (not the serve itself) on
         // isResponsibleForBlock.
+        //
+        // NOTE: accepted tradeoff — this check and `fetchBlockFromCluster` below each run their own
+        // `findCluster` for the same block, so a cold read costs two cohort lookups where one shared
+        // lookup would do. Declined 2026-09-11: at 0.009 ms per solo lookup there is nothing to win,
+        // and this check's future is open (blocked `writer-and-servers-disagree-on-where-a-block-lives`,
+        // option D2(b)). Revisit if a device profile shows `findCluster` as material.
         for (const blockId of blockGets.blockIds) {
             if (!await this.isResponsibleForBlock(blockId)) {
                 this.log('proximity:get-warning', { blockId, msg: 'serving read for non-responsible block' });
@@ -351,7 +382,9 @@ export class CoordinatorRepo {
         // First try local storage
         const localResult = await this.storageRepo.get(blockGets, options);
         // Decide per-block whether to consult cluster peers. Two triggers:
-        //   (a) Missing — block isn't present locally at all (legacy behavior).
+        //   (a) Missing — block isn't present locally at all. Consults unless an earlier consult
+        //       SETTLED its absence within the last `readRepairWindowMs` (see `settledAbsences` and
+        //       `absenceIsSettled`) — today only when this node is the block's whole cohort.
         //   (b) Stale-by-policy — block is present but read-repair policy says verify.
         // Skip cluster fetch if this is already a sync request (to prevent recursive queries).
         // A sync read is also never marked `unavailable` here — the consult it skips is the
@@ -361,21 +394,38 @@ export class CoordinatorRepo {
         const skipClusterFetch = options?.skipClusterFetch;
         // NOTE: NetworkTransactor.get treats an authoritative "absent" ({ state: {} })
         // as final and no longer retries it (ticket txn-perf-authoritative-notfound),
-        // relying on this cluster reconciliation to have already run. When the consult
-        // FAILS outright — or runs without ruling the block out and the block stays
-        // missing — the entry is flagged `unavailable` below with a reason naming what
-        // the consult established (see AbsenceVerdict and the mapping in the loop body),
-        // which re-enables the transactor-level retry against a different peer. If a
-        // coordinator is configured WITHOUT clusterLatestCallback, there is no cohort to
-        // consult and the local answer IS the whole truth — it stays authoritative, with
-        // no flag and no transactor-level retry to compensate. That is fine (such a
-        // coordinator has no cluster to reconcile against), but keep this coupling in
-        // mind if a partial-cluster read path is added.
+        // relying on this cluster reconciliation to have already run — within the last
+        // `readRepairWindowMs`: an unflagged absent means the cohort confirmed this absence
+        // at most one window ago (a read inside the window serves the memo of that
+        // confirmation, see `settledAbsences`), the same currency guarantee a held block's
+        // content already carries. When the consult FAILS outright — or runs without ruling
+        // the block out and the block stays missing — the entry is flagged `unavailable`
+        // below with a reason naming what the consult established (see AbsenceVerdict and
+        // the mapping in the loop body), which re-enables the transactor-level retry against
+        // a different peer; none of those outcomes is ever remembered. If a coordinator is
+        // configured WITHOUT clusterLatestCallback, there is no cohort to consult and the
+        // local answer IS the whole truth — it stays authoritative, with no flag and no
+        // transactor-level retry to compensate. That is fine (such a coordinator has no
+        // cluster to reconcile against), but keep this coupling in mind if a partial-cluster
+        // read path is added.
         if (this.clusterLatestCallback && !skipClusterFetch) {
             for (const blockId of blockGets.blockIds) {
                 const localEntry = localResult[blockId];
                 const localRev = localEntry?.state?.latest?.rev;
                 const isMissing = !localEntry?.state?.latest;
+                if (!isMissing) {
+                    // Present: any remembered absence is dead. Dropped now rather than left to age out,
+                    // so a block that vanishes again inside the same window consults instead of being
+                    // served the old memo.
+                    this.settledAbsences.delete(blockId);
+                }
+                else if (this.absenceIsSettled(blockId)) {
+                    // An earlier consult settled this absence within one window: serve the local entry
+                    // as it stands — an authoritative absent, or pending-only content — with no flag and
+                    // no log line. The held-block skip below logs nothing either, and a per-read line
+                    // here would recreate the volume this skip exists to remove.
+                    continue;
+                }
                 const isStale = !isMissing && this.shouldReadRepair(blockId);
                 if (!isMissing && !isStale) {
                     // No consult this pass — the read-repair window says this block was checked
@@ -395,13 +445,33 @@ export class CoordinatorRepo {
                         localRev
                     });
                 }
+                // Evidence gathered during the consult is at least this old, so a memo stamped with it never
+                // outlives "confirmed within one window" by the consult's own duration.
+                const consultStartedAt = this.now();
                 try {
-                    const { absence, currency } = await this.fetchBlockFromCluster(blockId, blockGets.context, localRev);
+                    const { absence, currency, absenceSettled } = await this.fetchBlockFromCluster(blockId, blockGets.context, localRev);
                     const refreshed = await this.storageRepo.get({ blockIds: [blockId], context: blockGets.context }, options);
                     const newRev = refreshed[blockId]?.state?.latest?.rev;
                     if (refreshed[blockId]) {
                         localResult[blockId] = refreshed[blockId];
                     }
+                    // Remember a settled absence for one window; forget it after every other outcome. A
+                    // consult that ended `unconfirmed`, `isolated` or `claimed`, that asked a multi-peer
+                    // cohort, or that rested on no real cohort view, leaves no memo, so the next read consults (and flags) exactly as before —
+                    // including after a sampled or paranoid re-consult of a block whose memo was still fresh.
+                    // NOTE: a local pend/commit that clears the memo WHILE this consult is in flight is undone
+                    // by the stamp below — one read inside the window can then serve an absent the refused
+                    // writer knows is wrong. Bounded: that writer's next pend clears the memo again. If it ever
+                    // shows as a stuck writer, skip this stamp when a clear of this block landed after
+                    // `consultStartedAt`.
+                    if (isMissing) {
+                        if (!refreshed[blockId]?.state?.latest && absence === 'confirmed' && absenceSettled) {
+                            this.settledAbsences.set(blockId, consultStartedAt);
+                        }
+                        else {
+                            this.settledAbsences.delete(blockId);
+                        }
+                    }
                     if (isStale) {
                         if (typeof newRev === 'number' && typeof localRev === 'number' && newRev > localRev) {
                             this.log('cluster-tx:read-repair-applied', { blockId, oldRev: localRev, newRev });
@@ -453,6 +523,9 @@ export class CoordinatorRepo {
                     // rather than return a stale cohort view, revisit — that would put the
                     // isolated case back under this vaguer reason.
                     if (isMissing) {
+                        // A consult that threw settled nothing — not even a memo that was still fresh
+                        // before a sampled or paranoid re-consult.
+                        this.settledAbsences.delete(blockId);
                         this.flagUnconfirmedAbsence(localResult, blockId, 'peers-unreachable');
                     }
                     else {
@@ -662,6 +735,28 @@ export class CoordinatorRepo {
             }
         }
     }
+    /**
+     * Decide whether a block MISSING locally may skip its consult: an earlier consult settled its
+     * absence within one read-repair window (see {@link settledAbsences}). The absence counterpart of
+     * {@link shouldReadRepair}, giving absence the guarantee the window already gives content —
+     * "checked with the cohort within one window" — and nothing weaker.
+     *
+     * Modes: `paranoid` never skips ("verify every read" means every read). `lazy` uses the window and
+     * the sample rate, exactly as {@link shouldReadRepair} does. `off` uses the window but not the
+     * sample rate (a `lazy`-only knob, as it is for content): `off` disables STALE-CONTENT repair, and
+     * the absence consult is not that — it is what makes an absent answer authoritative at all — so
+     * leaving it unbounded would make the mode meant to do less network work do more.
+     */
+    absenceIsSettled(blockId) {
+        if (this.readRepairMode === 'paranoid')
+            return false;
+        const at = this.settledAbsences.get(blockId);
+        if (at == null || this.now() - at > this.readRepairWindowMs)
+            return false;
+        if (this.readRepairMode === 'lazy' && this.readRepairSampleRate > 0 && this.rand() < this.readRepairSampleRate)
+            return false;
+        return true;
+    }
     /** Milliseconds since we last marked this block fresh, or undefined if never. */
     ageMs(blockId) {
         const lastSeen = this.lastSeenCommitMs.get(blockId);
@@ -674,6 +769,16 @@ export class CoordinatorRepo {
             this.lastSeenCommitMs.set(id, now);
         }
     }
+    /**
+     * Drop any settled-absence memo for `blockIds` ({@link settledAbsences}) — called at the top of a
+     * local pend or commit, before routing and whatever the outcome. Clearing is always the safe
+     * direction: the most it can cost is one extra consult.
+     */
+    forgetSettledAbsences(blockIds) {
+        for (const id of blockIds) {
+            this.settledAbsences.delete(id);
+        }
+    }
     /**
      * True when a commit's approve votes form a strict majority of the FULL cohort — the only case
      * where "this node committed" is evidence that no rival commit moved past it. Two strict
@@ -733,10 +838,20 @@ export class CoordinatorRepo {
      *    retire it when the memo's claimants are among the peers that answered), `no-evidence`
      *    leaves it standing untouched. Required, not optional, so an exit added later has to say
      *    which it means.
+     *  - `absenceSettled` — whether this pass SETTLED the block's absence for one read-repair window:
+     *    no write of it this node has not seen can exist. Only the solo-self exit can say that today
+     *    (this node is the whole cohort, so every acknowledged commit lands here). `get` remembers a
+     *    settled absence ({@link settledAbsences}) and skips the consult while the block stays missing.
+     *    `absence === 'confirmed'` alone is not enough — the empty-cohort exit reports it without
+     *    asking anyone, and a multi-peer cohort's unanimous "nothing" can be overtaken by a commit
+     *    still on its way to this node. Required, like
+     *    `currency`, so an exit added later has to say which side it falls on rather than
+     *    remembering (or forgetting) to arm something.
      */
     async fetchBlockFromCluster(blockId, context, localRev) {
+        // Unreachable from `get` (it guards on the callback); nothing to settle against.
         if (!this.clusterLatestCallback)
-            return { absence: 'confirmed', currency: { kind: 'no-evidence' } };
+            return { absence: 'confirmed', currency: { kind: 'no-evidence' }, absenceSettled: false };
         const blockIdBytes = new TextEncoder().encode(blockId);
         const peers = await this.keyNetwork.findCluster(blockIdBytes);
         const peerIds = peers ? Object.keys(peers) : [];
@@ -747,9 +862,11 @@ export class CoordinatorRepo {
         // here would suppress a genuine repair for a whole `readRepairWindowMs` after a transient
         // blip, and re-entering costs no network work beyond the `findCluster` the read already
         // makes. Do not "fix" this by symmetry with the solo-self exit.
+        // For the same reason it returns `absenceSettled: false`: remembering the absence would serve an
+        // authoritative absent for a whole window on the strength of a lookup that returned nobody.
         // Currency: nobody was asked, so nothing was refuted — an earlier pass's unsettled claim stands.
         if (peerIds.length === 0)
-            return { absence: 'confirmed', currency: { kind: 'no-evidence' } };
+            return { absence: 'confirmed', currency: { kind: 'no-evidence' }, absenceSettled: false };
         // Solo-cluster short-circuit: the only responsible peer is us. There is no
         // remote to sync from, so skip the callback entirely. Querying ourselves
         // would dial self via SyncClient — pointless at best, and on nodes without
@@ -782,7 +899,11 @@ export class CoordinatorRepo {
             // and deliberate — the window damps repair EFFORT, not honesty — and it is the same
             // coupling the comment at the final exit below describes. Arming the window and keeping
             // the memo are answers to different questions; do not collapse them.
-            return { absence: 'confirmed', currency: { kind: 'no-evidence' } };
+            // Absence: settled. Nobody else could hold the block, and re-asking inside one window learns
+            // nothing the next `findCluster` would not — the same argument, with the same one-window
+            // self-heal when a cohort appears, as the arming above. (That arming's stamp is NOT what
+            // suppresses the next read of a missing block: `get` reads `settledAbsences` for those.)
+            return { absence: 'confirmed', currency: { kind: 'no-evidence' }, absenceSettled: true };
         }
         const { corroborated, corroboration, local, silent, answered, claims, uncorroboratedRev, deadlock } = await this.queryClusterForLatest(peerIds, blockId, context);
         // Any silence taints the WHOLE consult, not a fraction of it (fail-closed): one silent
@@ -870,7 +991,14 @@ export class CoordinatorRepo {
             if (deadlock === 'cohort-too-small') {
                 this.markBlocksSeen([blockId]);
             }
-            return { absence, currency };
+            // Absence NOT settled, even when every cohort member answered "I hold nothing". This node
+            // takes part in other coordinators' writes as a cohort member through ClusterRepo, straight
+            // into storage and never through this class's pend/commit, so nothing here would clear the
+            // memo; and a commit acknowledged at super-majority reaches the remaining members in the
+            // background. Remembering this answer served a writer's own create as absent through a
+            // lagging member (fresh-node-ddl-multi Scenario B, 5 of 20 runs). Only the solo exit
+            // settles — see backlog `feat-a-cohort-member-remembers-a-settled-absence`.
+            return { absence, currency, absenceSettled: false };
         }
         // The self answer is the sharper baseline (same storage, same context, read alongside the
         // cohort's), but it exists only when `findCluster` returned this node. A soft serve for a
@@ -921,7 +1049,8 @@ export class CoordinatorRepo {
             // ahead. Only reachable when a peer answered (a corroboration requires claims), so the
             // shared verdict resolves to `nothing-ahead` and a memo whose claimants are among those
             // answers is cleared.
-            return { absence: silenceVerdict, currency: nothingAheadVerdict };
+            // `absenceSettled`: never read for a held block; false for the same reason as the exit above.
+            return { absence: silenceVerdict, currency: nothingAheadVerdict, absenceSettled: false };
         }
         // Corroborated revision is ahead of ours — converge onto it.
         const rev = await this.restoreCorroborated(blockId, corroborated, baselineRev, peerIds);
@@ -949,12 +1078,13 @@ export class CoordinatorRepo {
         // unsettled claim (`recordAheadClaim`) and keeps stamping reads served below it while the
         // window suppresses the retry — the window damps repair effort, not honesty.
         // NOTE: that damping covers only a block this node holds at an OLDER revision. A block entirely
-        // missing locally never consults the window (`get` triggers on `isMissing` before
-        // `shouldReadRepair`), so a persistently failing acquisition — e.g. a two-node deployment that
-        // never set `assumedClusterSize`, where the content quorum can never be met — re-fetches an
-        // archive on every read of that block. Correct, and self-limiting once the cohort can agree; if
-        // it ever shows as read amplification, gate the acquisition step (not the latest-query) on the
-        // same window rather than widening `isMissing`.
+        // missing locally is suppressed only by its own absence memo (`settledAbsences`), and this exit
+        // never arms it (`absenceSettled: false` below — a failed acquisition is `claimed`). So a
+        // persistently failing acquisition — e.g. a two-node deployment that never set
+        // `assumedClusterSize`, where the content quorum can never be met — still re-fetches an archive
+        // on every read of that block. Correct, and self-limiting once the cohort can agree; if it ever
+        // shows as read amplification, gate the acquisition step (not the latest-query) on the same
+        // window rather than letting a `claimed` absence settle.
         this.markBlocksSeen([blockId]);
         // Converged: the corroboration is itself the evidence that nothing is ahead, and it came from
         // peers that answered — the shared verdict resolves to `nothing-ahead`, and the memo retires
@@ -962,7 +1092,9 @@ export class CoordinatorRepo {
         const currency = converged
             ? nothingAheadVerdict
             : { kind: 'unsettled-claim', rev: corroborated.rev, claimants: claimantsAtOrAbove(corroborated.rev), silent };
-        return { absence, currency };
+        // Never settles an absence: restored → the block is now present (nothing to remember); not
+        // restored → `claimed`.
+        return { absence, currency, absenceSettled: false };
     }
     /**
      * Bring this node up to the cohort-corroborated `corroborated`, returning the revision it holds
@@ -1500,6 +1632,12 @@ export class CoordinatorRepo {
     }
     async pend(request, options) {
         const allBlockIds = blockIdsForTransforms(request.transforms);
+        // Forget any settled absence of these blocks FIRST — before responsibility, routing, or the
+        // outcome is known. A pend refused because a block already exists somewhere is the strongest
+        // evidence there is that the memo was wrong, and the writer's retry re-reads: that read must
+        // consult (and restore) rather than serve the memo's authoritative absent for the rest of the
+        // window. After a success the block is present and the memo is dead anyway.
+        this.forgetSettledAbsences(allBlockIds);
         await this.verifyResponsibility(allBlockIds);
         const result = await this.pendThroughCluster(request, allBlockIds, options);
         // A pend the blocks ACCEPTED is the proof that no reservation is holding them any more — the
@@ -1914,11 +2052,12 @@ export class CoordinatorRepo {
             //
             // NOTE: `getClusterSize` is a second `findCluster` for the same key that
             // `executeClusterTransaction` is about to look up again, so a cancel over N blocks now
-            // costs 2N cohort lookups instead of N. Same shape `pend` and `commit` already pay, but
-            // they pay it once (they only ever consult `blockIds[0]`) where this scales with N. Fine
-            // while cancels span a handful of blocks; if wide multi-block cancels ever show up hot,
-            // have `executeClusterTransaction` return the cohort it already fetched (or own the
-            // short-circuit itself) rather than adding a cache here.
+            // costs 2N cohort lookups instead of N. `pend` and `commit` pay the same doubled lookup
+            // for a multi-peer cohort, but theirs is CONSTANT — they only ever consult `blockIds[0]`
+            // — where this scales with N. Fine while cancels span a handful of blocks; if wide
+            // multi-block cancels ever show up hot, have `executeClusterTransaction` return the
+            // cohort it already fetched (or own the short-circuit itself) rather than adding a cache
+            // here.
             const results = await Promise.all(blockIds.map(async (blockId) => {
                 const peerCount = await this.coordinator.getClusterSize(blockId);
                 if (peerCount <= 1)
@@ -1944,6 +2083,8 @@ export class CoordinatorRepo {
     }
     async commit(request, options) {
         const blockIds = request.blockIds;
+        // Same as `pend`: forget any settled absence of these blocks before routing, whatever the outcome.
+        this.forgetSettledAbsences(blockIds);
         await this.verifyResponsibility(blockIds);
         const cohortPeerIds = await this.coordinator.getClusterPeerIds(blockIds[0]);
         const peerCount = cohortPeerIds.length;
@@ -1995,7 +2136,7 @@ export class CoordinatorRepo {
             expiration: options?.expiration ?? Date.now() + this.DEFAULT_TIMEOUT
         };
         try {
-            const { record, localExecuted, localCommitResult } = await this.coordinator.executeClusterTransaction(blockIds[0], message, options);
+            const { record, localExecuted, localCommitResult, cohortCommitOutcomes } = await this.coordinator.executeClusterTransaction(blockIds[0], message, options);
             // Decided once for every success shape below (local-executed, local fallback, tolerated
             // divergence): whether this commit's quorum is freshness evidence or merely a commit.
             // NOTE: one verdict covers every block in `blockIds`, though it is measured against
@@ -2004,20 +2145,48 @@ export class CoordinatorRepo {
             // quorum that never voted. If commits ever coordinate per-block cohorts separately (see
             // `debt-sender-side-coordinating-block-binding-is-unchecked`), this must follow them.
             const armFreshness = this.commitQuorumRulesOutRivals(countApprovingCommitVotes(record), peerCount);
+            // THE DURABILITY GATE. A commit is acknowledged to the writer only when more than half of
+            // the cohort it ran on (`record.peers`) reports that its storage durably holds the
+            // committed revision under this action, each member measured after its own reconcile.
+            // Consensus votes are necessary for the commit to be authoritative; they were never
+            // evidence that it was stored — every member can sign, then refuse at apply (no base for
+            // the block, a missed pend), and the coordinator used to count the votes as success. The
+            // same strict majority `clusterReachedCommitConsensus` measures votes against; the
+            // freshness verdict above stays tied to the vote count, the two quorums are not
+            // conflated. Other members' reports arrive as `cohortCommitOutcomes`; this node's own
+            // member is added per arm below — its retained verdict when it executed, its fallback
+            // commit when it did not.
+            //
+            // NOTE: a refusal here means "not confirmed durable at a quorum", never "guaranteed
+            // absent" — the two-phase ambiguity. Members that refused with `missing-base-revision`
+            // have already dropped their pending records, so the writer must cancel and re-drive at a
+            // fresh revision, which is what the `conflict: true` shape makes `Collection.syncAttempts`
+            // and the multi-collection `pendPhase` do. But a member reached only by
+            // `scheduleCommitRetry` can still land the refused revision later, and this node's own
+            // member (or its fallback commit) may hold it already. The writer's retry with the SAME
+            // action id converges either way: `isOwnRevision` in `StorageRepo.pend` and `commit`
+            // treats an already-landed own revision as satisfied, and `inFlightActionId` in
+            // `Collection.updateInternal` keeps the retry on the same action.
+            const durability = cohortDurability(record, cohortCommitOutcomes);
             if (localExecuted) {
                 // Our own member applied this commit during consensus. Its retained storage verdict is
                 // the one honest signal we have about durability: the member-side apply tolerates an
-                // "ahead" refusal as divergence (see the NOTE in ClusterMember.applyConsensusOperation),
+                // "ahead" refusal as divergence (see the NOTE in ClusterMember.applyCommitToStorage),
                 // which is correct for a redelivered or lagging commit — but when the refusal's real
-                // cause is a RIVAL action holding the requested revision, that tolerance turns a commit
-                // no member durably stored into a fabricated success. This is the
+                // cause is a RIVAL action holding the requested revision, that tolerance would turn a
+                // commit no member durably stored into a fabricated success. This is the
                 // signed-but-not-yet-applied window: two commits for one revision can BOTH assemble
                 // consensus when every member signs the second after signing (but before applying) the
                 // first, because signing drops the member's reservation. Confirm the rival against local
                 // storage (never the verdict's prose) and answer the writer with a retryable conflict so
-                // it re-drives at a fresh revision. Own-action or unconfirmed refusals keep the
-                // prior fabricated-success shape: consensus is authoritative and this member converges
-                // via replication.
+                // it re-drives at a fresh revision. An own-action confirmation only clears the conflict
+                // answer; it does NOT make this node a holder for the gate below. The confirmation fires
+                // on the FIRST block found held under this action, and a multi-block commit torn locally
+                // (`StorageRepo.commit` lands blocks in order and stops at the first refusal) holds some
+                // blocks and not others — whereas the member's retained verdict is already a success
+                // whenever EVERY block is held (`ClusterMember.durableCommitVerdict`, measured after its
+                // reconcile). So the retained verdict is the only local contribution the gate counts;
+                // a refused one, confirmed or not, leaves it to the rest of the cohort.
                 //
                 // NOTE: a CONFIRMED rival is trusted over the consensus outcome here. That is right in
                 // the window this closes (the cohort refused the loser too), but it inverts if the two
@@ -2028,6 +2197,7 @@ export class CoordinatorRepo {
                 // after a fork; that is partition-healing scope (docs/partition-healing.md). If forks
                 // are ever observed here, weigh the retained verdict against the cohort's votes instead
                 // of trusting the local re-read alone.
+                const localDurable = localCommitResult?.success === true;
                 if (localCommitResult !== undefined && !localCommitResult.success) {
                     const rival = await this.confirmCommitRivalAgainstLocal(request);
                     if (typeof rival === 'object')
@@ -2038,23 +2208,42 @@ export class CoordinatorRepo {
                         reason: localCommitResult.reason
                     });
                 }
+                // An absent verdict (a member that predates retention, a restart, the TTL) is not
+                // evidence of holding anything: it is simply not counted.
+                const durableHolders = durability.remoteHolders + (localDurable ? 1 : 0);
+                if (!isDurableMajority(durableHolders, durability.cohortSize)) {
+                    return this.refuseCommitNotDurable(request, durableHolders, durability, 'local-executed');
+                }
                 if (armFreshness)
                     this.markBlocksSeen(blockIds);
                 return { success: true };
             }
             // Local cluster didn't execute during consensus. Attempt a local commit, but tolerate
-            // local divergence when the cluster already reached consensus — this coordinator was
-            // likely picked for commit after missing the pend phase (unreachable during pend, fresh
-            // join, etc.). The cluster's majority is authoritative; this peer catches up via sync.
+            // local divergence when the cluster already reached consensus AND a durable majority of
+            // the cohort reports holding the revision — this coordinator was likely picked for commit
+            // after missing the pend phase (unreachable during pend, fresh join, etc.), and it catches
+            // up via replication.
             //
-            // Divergence reaches us in BOTH shapes and both must be tolerated identically:
+            // Divergence reaches us in BOTH shapes and both are handled identically:
             //   - a THROW ("Pending action … not found"), when we never saw the pend;
             //   - a RETURNED `success:false` carrying `missing-base-revision`, when we saw the pend
             //     but not the revision that created the block (see StorageRepo.internalCommit).
-            // Only the throw was tolerated before the refusal existed. Reporting the refusal to the
-            // caller instead would surface a committed transaction as a stale loss: db-core's
-            // commitPhase treats any returned `success:false` as a permanent stale failure, so the
-            // client would retry an action the cluster already landed until it exhausted its budget.
+            // Reporting a tolerated divergence to the caller as the raw refusal would surface a
+            // committed transaction as a stale loss: db-core's commitPhase treats any returned
+            // `success:false` as a permanent stale failure. So a divergence on a durable majority is
+            // reported as success, and one WITHOUT a durable majority as the durability gate's
+            // retryable refusal (`tolerateLocalCommitDivergence`).
+            //
+            // The gate is evaluated BEFORE the local fallback commit, and a failing gate skips it.
+            // This node counts toward the majority only when it is in the cohort the commit ran on;
+            // an off-cohort coordinator's copy is a lone holder no cohort member will ever reconcile
+            // from (members reconcile from `record.peers`), and a refused commit must not create one —
+            // that lone off-cohort copy is exactly the seed of the "revision exists on one node that
+            // is not responsible for it" placement the durability gate exists to prevent.
+            const selfInCohort = this.localPeerId !== undefined && this.localPeerId.toString() in record.peers;
+            if (!isDurableMajority(durability.remoteHolders + (selfInCohort ? 1 : 0), durability.cohortSize)) {
+                return this.refuseCommitNotDurable(request, durability.remoteHolders, durability, 'fallback-skipped');
+            }
             //
             // Deliberately NOT self-signed here (unlike the solo short-circuit above): consensus for
             // this commit ran on the cohort, so a one-peer minted proof would be a FALSE statement
@@ -2068,18 +2257,20 @@ export class CoordinatorRepo {
             try {
                 const result = await this.storageRepo.commit(request, options, consensusProof);
                 if (result.success) {
+                    // The gate above already admitted this shape: the remote holders plus this node
+                    // (when it is in the cohort) form the majority, and this node now holds it.
                     if (armFreshness)
                         this.markBlocksSeen(blockIds);
                     return result;
                 }
                 if (isMissingBaseRevisionFailure(result) && clusterReachedCommitConsensus(record)) {
-                    return this.tolerateLocalCommitDivergence(request, blockIds, result.reason ?? MISSING_BASE_REVISION_REASON, armFreshness);
+                    return this.tolerateLocalCommitDivergence(request, blockIds, result.reason ?? MISSING_BASE_REVISION_REASON, armFreshness, durability);
                 }
                 return result;
             }
             catch (err) {
                 if (clusterReachedCommitConsensus(record)) {
-                    return this.tolerateLocalCommitDivergence(request, blockIds, err.message, armFreshness);
+                    return this.tolerateLocalCommitDivergence(request, blockIds, err.message, armFreshness, durability);
                 }
                 throw err;
             }
@@ -2224,20 +2415,64 @@ export class CoordinatorRepo {
         };
     }
     /**
-     * Report success for a commit the cluster carried but this peer could not apply locally.
-     * Convergence comes from replication (cohort reconcile, or read-driven acquisition), not from
-     * replay here. `armFreshness` says whether the commit's quorum was strong enough
-     * ({@link commitQuorumRulesOutRivals}) for the read path to treat the blocks as
-     * freshness-checked; a divergence tolerated on a downsized quorum leaves the window unarmed —
-     * this peer is known to be behind here, the last place a self-referential freshness stamp
-     * belongs.
+     * A commit the cluster carried but this peer could not apply locally. Reported as success only
+     * when a durable majority of the OTHER cohort members holds it (this node, having diverged, is
+     * not a holder) — convergence then comes from replication (cohort reconcile, or read-driven
+     * acquisition), not from replay here. Without that majority it is the durability gate's
+     * retryable refusal: nothing is known to hold the revision. `armFreshness` says whether the
+     * commit's quorum was strong enough ({@link commitQuorumRulesOutRivals}) for the read path to
+     * treat the blocks as freshness-checked; a divergence tolerated on a downsized quorum leaves the
+     * window unarmed — this peer is known to be behind here, the last place a self-referential
+     * freshness stamp belongs.
      */
-    tolerateLocalCommitDivergence(request, blockIds, detail, armFreshness) {
+    tolerateLocalCommitDivergence(request, blockIds, detail, armFreshness, durability) {
+        if (!isDurableMajority(durability.remoteHolders, durability.cohortSize)) {
+            return this.refuseCommitNotDurable(request, durability.remoteHolders, durability, `fallback-diverged: ${detail}`);
+        }
         this.log('coordinator-repo:commit-local-failed-cluster-succeeded', { actionId: request.actionId, error: detail });
         if (armFreshness)
             this.markBlocksSeen(blockIds);
         return { success: true };
     }
+    /**
+     * The durability gate's answer: a retryable refusal ({@link COMMIT_NOT_DURABLE_REASON}) naming how
+     * many of the cohort reported holding the revision. `conflict: true` because the members that
+     * refused have dropped their pending records, so the writer's only way forward is to cancel and
+     * re-drive at a fresh revision — the path a conflict-shaped answer already puts it on. The
+     * read-repair window is deliberately NOT armed: nothing about this commit is freshness evidence.
+     */
+    refuseCommitNotDurable(request, durableHolders, durability, arm) {
+        this.log('coordinator-repo:commit-not-durable', {
+            actionId: request.actionId,
+            rev: request.rev,
+            durableHolders,
+            cohortSize: durability.cohortSize,
+            remoteHolders: durability.remoteHolders,
+            remoteRefusals: durability.remoteRefusals,
+            arm
+        });
+        return {
+            success: false,
+            conflict: true,
+            reason: `${COMMIT_NOT_DURABLE_REASON}: ${durableHolders} of ${durability.cohortSize} cohort member(s) report holding rev ${request.rev} of action ${request.actionId} (${arm})`
+        };
+    }
+}
+function cohortDurability(record, outcomes) {
+    const reports = Object.values(outcomes ?? {});
+    return {
+        cohortSize: Object.keys(record.peers).length,
+        remoteHolders: reports.filter(report => report.success).length,
+        remoteRefusals: reports.filter(report => !report.success).length
+    };
+}
+/**
+ * The durability gate's rule: a STRICT majority of the cohort the commit ran on — the same majority
+ * {@link clusterReachedCommitConsensus} measures votes against, applied to durable holders instead
+ * of approving votes.
+ */
+function isDurableMajority(durableHolders, cohortSize) {
+    return cohortSize > 0 && durableHolders > cohortSize / 2;
 }
 /** True if a simple majority of cluster peers signed an approving commit. */
 function clusterReachedCommitConsensus(record) {