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

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

@@ -1,9 +1,11 @@
-import { transformForBlockId, applyTransform, groupBy, concatTransform, emptyTransforms, blockIdsForTransforms, transformsFromTransform, highestStaleAt, isOwnRevision, canonicalBlockHash } from "@optimystic/db-core";
+import { transformForBlockId, applyTransform, groupBy, concatTransform, emptyTransforms, blockIdsForTransforms, transformsFromTransform, highestStaleAt, isOwnRevision, canonicalBlockHash, localDurability } from "@optimystic/db-core";
 import { asyncIteratorToArray } from "../it-utility.js";
+import { isReservationAgainst, isBaseIndependent, declaredBaseFor } from "./pending-claim.js";
 import { proofDeclaredDigest } from "../cluster/commit-proof.js";
 import { RevisionNotCoveredError } from "./i-block-storage.js";
 import { acquireBlockWriteLatches, withBlockWriteLatch } from "./block-latch.js";
 import { createLogger } from "../logger.js";
+import { cloneDecoded } from "./raw-store-codec.js";
 import { checkPendValidation } from "../pend-validation.js";
 const log = createLogger('storage-repo');
 /**
@@ -45,6 +47,23 @@ export class MissingBaseRevisionError extends Error {
 export function isMissingBaseRevisionFailure(result) {
     return !result.success && (result.reason?.startsWith(MISSING_BASE_REVISION_REASON) ?? false);
 }
+/**
+ * Stable, greppable prefix on the failure reason `CoordinatorRepo.commit` answers with when a commit
+ * assembled consensus but FEWER than a majority of the cohort reported durably holding the committed
+ * revision afterwards. Same convention as {@link MISSING_BASE_REVISION_REASON}: a string marker,
+ * because the reason crosses the wire as `StaleFailure.reason` prose. The refusal is retryable
+ * (`conflict: true`) and means "not confirmed durable at a quorum" — never "guaranteed absent"; see
+ * the durability gate in `CoordinatorRepo.commit` for the two-phase ambiguity that wording covers.
+ */
+export const COMMIT_NOT_DURABLE_REASON = 'commit-not-durable';
+/**
+ * True when a {@link CommitResult} was refused by the coordinator's durability gate — consensus was
+ * reached but no durable majority reported holding the revision. Sibling of
+ * {@link isMissingBaseRevisionFailure}, for callers that need to tell this refusal from a stale loss.
+ */
+export function isCommitNotDurableFailure(result) {
+    return !result.success && (result.reason?.startsWith(COMMIT_NOT_DURABLE_REASON) ?? false);
+}
 export class StorageRepo {
     createBlockStorage;
     validatePend;
@@ -53,6 +72,9 @@ export class StorageRepo {
     changeListeners = new Map();
     /** Catch-all change listeners — fire for EVERY collection's commit on this node. */
     anyChangeListeners = new Set();
+    /** Full-replication listeners — fire when a block this node acknowledged below `full` has
+     *  reached every cohort member. See {@link IBlockDurabilityNotifier}. */
+    durabilityListeners = new Set();
     constructor(createBlockStorage, options) {
         this.createBlockStorage = createBlockStorage;
         this.validatePend = options?.validatePend;
@@ -138,7 +160,34 @@ export class StorageRepo {
             }
         }
     }
-    async get({ blockIds, context }, _options) {
+    /** Subscribe to full-replication events. See {@link IBlockDurabilityNotifier}. */
+    onBlockDurabilityReached(listener) {
+        this.durabilityListeners.add(listener);
+        let unsubscribed = false;
+        return () => {
+            if (unsubscribed)
+                return;
+            unsubscribed = true;
+            this.durabilityListeners.delete(listener);
+        };
+    }
+    /**
+     * Fire one {@link BlockDurabilityReachedEvent} to every subscriber. The producer is the
+     * under-replication drain, which reaches this through a one-method sink the node hands it and
+     * calls it only AFTER the block's ledger entry is gone. Same listener isolation as
+     * {@link fireChangeListeners}: a throwing listener is logged and the rest still run.
+     */
+    emitBlockDurabilityReached(event) {
+        for (const listener of Array.from(this.durabilityListeners)) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                log('onBlockDurabilityReached listener threw for blocks=%o: %o', event.blockIds, err);
+            }
+        }
+    }
+    async get({ blockIds, context, lineageOf }, _options) {
         const distinctBlockIds = Array.from(new Set(blockIds));
         log('get blockIds=%d', distinctBlockIds.length);
         // Read-driven promotions that land durably here, captured so we can emit a
@@ -184,22 +233,38 @@ export class StorageRepo {
                         // `context.committed` array, and an in-place `.sort()` would reorder the shared
                         // request context under the caller's feet.
                         //
-                        // NOTE: this loop SKIPS an entry whose pending it does not hold and promotes the
-                        // next one anyway — so a member missing an intermediate revision that touched THIS
-                        // block forks it exactly as an un-guarded commit would. `internalCommit`'s declared-
-                        // base guard cannot help here: `context.committed` is a collection-level list of
-                        // (actionId, rev) with no per-block base, and "no pending for that action" is the
-                        // normal case for the many actions that never touched this block. Closing it needs
-                        // the authored base stored WITH the pended transform — tracked by
-                        // `backlog/bug-a-pended-transform-does-not-carry-its-base`.
+                        // The loop skips an entry whose pending record it does not hold — the normal case
+                        // for the many actions that never touched this block — so on its own it would
+                        // promote the record after a missed change straight over the stale copy. What
+                        // stops that is the base each record's pend carried (`PendingClaim.baseRev`):
+                        // `mayPromoteOnRead` applies a record only to the exact revision its operations
+                        // were computed against and DECLINES otherwise, leaving the record and `latest`
+                        // untouched and ending the walk for this block (each later entry builds on this
+                        // one). No commit declaration is needed, which is the point: there is no commit
+                        // request on this path.
                         try {
                             for (const { actionId, rev } of [...missing].sort((a, b) => a.rev - b.rev)) {
                                 const pending = await blockStorage.getPendingTransaction(actionId);
-                                if (pending) {
-                                    const collectionId = await this.internalCommit(blockId, actionId, rev, blockStorage, latch);
-                                    if (collectionId !== undefined) {
-                                        promotions.push({ collectionId, blockId, actionId, rev });
+                                if (!pending) {
+                                    continue;
+                                }
+                                // Re-read per entry: the previous iteration may have just promoted the base this one needs.
+                                const held = await blockStorage.getLatest();
+                                if (!(await this.mayPromoteOnRead(blockId, blockStorage, actionId, pending, held))) {
+                                    // A decline is not a refusal: the record stays, and the committed content
+                                    // served below is real, merely behind — the reader's floors and the
+                                    // coordinator's read-repair own "behind", so no flag. The one exception is
+                                    // a block this node holds NO committed revision of: the answer below would
+                                    // be an absent that this node's own record contradicts, so it is flagged as
+                                    // a guess rather than posing as "never existed".
+                                    if (held === undefined) {
+                                        unavailable = 'unmaterializable';
                                     }
+                                    break;
+                                }
+                                const collectionId = await this.internalCommit(blockId, actionId, rev, blockStorage, latch);
+                                if (collectionId !== undefined) {
+                                    promotions.push({ collectionId, blockId, actionId, rev });
                                 }
                             }
                         }
@@ -208,7 +273,9 @@ export class StorageRepo {
                             // can be promoted here (each builds on the one before). Leave `latest` where it
                             // is — the invariant internalCommit just enforced — and let the commit-path
                             // healing supply the content; a read must not fail for it. Every other fault
-                            // still propagates.
+                            // still propagates. Reached only by a base-independent record now (an update-only
+                            // one is declined above, never refused here): a delete over no committed
+                            // revision, or an insert whose held `latest` is unmaterializable.
                             if (!(err instanceof MissingBaseRevisionError)) {
                                 throw err;
                             }
@@ -275,6 +342,11 @@ export class StorageRepo {
                     // tickets/blocked/repo-pending-overlay-has-no-producer.
                     throw new Error(`Pending action ${context.actionId} not found`);
                 }
+                // A record the promotion above DECLINED (its base not reached here) is still present, so
+                // it is overlaid on whatever committed content this node holds — content older than the
+                // base its operations were computed against. Tolerated on this branch alone: the caller
+                // asserted its own pending, no production code sets `actionId` (the blocked ticket
+                // above), and the no-base case is still flagged by the clauses below.
                 const block = applyTransform(blockRev?.block, pendingTransform);
                 return [blockId, {
                         block,
@@ -328,8 +400,31 @@ export class StorageRepo {
         // parallel reads complete so emission stays outside the per-block work, matching
         // commit's ordering. No-op when nothing was promoted.
         this.emitPromotions(promotions);
+        if (lineageOf !== undefined) {
+            await this.answerLineage(results, lineageOf);
+        }
         return Object.fromEntries(results);
     }
+    /**
+     * Answers {@link BlockGets.lineageOf} on every entry, from this node's own records (see
+     * {@link IBlockStorage.lineageOf}). Runs after the block reads, so it describes storage at least
+     * as new as the content served beside it; every fact it reads only ever moves forward, so a
+     * commit landing in between cannot make the answer wrong, only early.
+     *
+     * A read fault answers `unknown` rather than failing the batch: the asker reads that as "this
+     * node could not say", which is exactly what happened.
+     */
+    async answerLineage(results, target) {
+        await Promise.all(results.map(async ([blockId, entry]) => {
+            try {
+                entry.lineage = await this.createBlockStorage(blockId).lineageOf(target);
+            }
+            catch (err) {
+                log('get:lineage-unreadable blockId=%s rev=%d error=%s', blockId, target.rev, err instanceof Error ? err.message : String(err));
+                entry.lineage = 'unknown';
+            }
+        }));
+    }
     /**
      * The one place a local coverage gap is healed from a peer. `getBlock` is local-only; when it
      * reports the target revision as not covered ({@link RevisionNotCoveredError}) this fetches it
@@ -513,9 +608,33 @@ export class StorageRepo {
                         }
                     }
                 }
-                // Then handle any pending actions
-                const pending = await asyncIteratorToArray(blockStorage.listPendingTransactions());
-                pendings.push(...pending.map(actionId => ({ blockId, actionId })));
+                // NOTE: a pend of an update-only transform for a block this node holds NO revision of
+                // falls through here and is recorded (`latest` is undefined, so there is nothing to be
+                // stale against). It can never be promoted on this node without a reconcile —
+                // `internalCommit`'s fork guard refuses it (`missing-base-revision`) and drops the
+                // record — so the pend round it wins is one this member could not honour on its own.
+                // Harmless today: the commit-tier durability gate (`CoordinatorRepo.commit`) refuses
+                // the acknowledgement unless a majority of the cohort holds the revision after
+                // reconcile, and the coordinating member's proof-carrying copy is what a behind member
+                // reconciles from. If pend-time refusals ever become worth their cost (one wasted
+                // consensus round per such write), refuse at `ClusterMember.validatePendOperations`
+                // instead of here.
+                // Then the pending records that RESERVE the block against this request. A record claiming a
+                // slot the collection has already moved past is not one of them (the revision rule of
+                // `isReservationAgainst`): counting it refused every later writer on the strength of a
+                // commit this node merely missed. Deliberately NOT fed the pend's declared base: the base
+                // arm is the promise vote's alone, and only in a cohort that can leave a member out
+                // (`ClusterMember.reservingRivals`), so this scan is never stricter than the vote — a pend
+                // the cohort approved is not then refused here at apply, and a member that voted `held` on
+                // a stray record but was outvoted still stores the pend, whose commit then sweeps the record.
+                for (const claim of await blockStorage.listPendingClaims()) {
+                    if (isReservationAgainst(claim, { rev: request.rev })) {
+                        pendings.push({ blockId, actionId: claim.actionId });
+                    }
+                    else {
+                        log('pend:superseded-claim actionId=%s blockId=%s rival=%s claimedRev=%d requestedRev=%d', request.actionId, blockId, claim.actionId, claim.rev, request.rev);
+                    }
+                }
             }
             // Every refusal below returns having written ZERO pending records — that is what pass 1
             // finishing before pass 2 begins buys.
@@ -565,12 +684,15 @@ export class StorageRepo {
                 }
                 const blockStorage = this.createBlockStorage(blockId);
                 const blockTransform = transformForBlockId(request.transforms, blockId);
-                await blockStorage.savePendingTransaction(request.actionId, blockTransform, request.rev, latches.get(blockId));
+                await blockStorage.savePendingTransaction(request.actionId, blockTransform, request.rev, declaredBaseFor(request.baseRevs, blockId, blockTransform), latches.get(blockId));
             }
+            // This layer answers for one machine's storage and nothing else: `local`, with no cohort
+            // view. The coordinator above it replaces this with the cohort's answer on every cluster path.
             return {
                 success: true,
                 pending: pendings,
-                blockIds
+                blockIds,
+                durability: localDurability()
             };
         }
         finally {
@@ -823,7 +945,8 @@ export class StorageRepo {
         // including those that landed before a mid-loop failure (alreadyDone / stale
         // partitions never reach `collectionBlocks`).
         this.emitCollectionChanges(collectionBlocks, request.actionId, request.rev, request.tailId);
-        return failure ? { success: false, reason: failure.reason } : { success: true };
+        // `local`, as in `pend`: a single machine's verdict about its own storage.
+        return failure ? { success: false, reason: failure.reason } : { success: true, durability: localDurability() };
     }
     /**
      * Delete `actionId`'s pending record from every given block, tolerating absence.
@@ -1005,8 +1128,13 @@ export class StorageRepo {
         }
         // Clone both: applyTransform assigns `transform.insert` into the result by reference and
         // applyOperations mutates the block in place, so materializing on live storage/pending objects
-        // would corrupt them for the real commit that follows.
-        const newBlock = applyTransform(structuredClone(base), structuredClone(transform));
+        // would corrupt them for the real commit that follows. `cloneDecoded` (a JSON round-trip) rather
+        // than `structuredClone`, which Hermes lacks; lossless here because both values were just decoded
+        // from JSON by the store (every `IRawStorage` in this repo is the JSON-coded `KvRawStorage`).
+        // NOTE: if an `IRawStorage` that hands out live, never-serialized objects is ever wired in, this
+        // preview can drift from internalCommit (which applies to the uncloned values): an update op
+        // setting a field to `undefined` clones to `null`, which canonical JSON hashes differently.
+        const newBlock = applyTransform(cloneDecoded(base), cloneDecoded(transform));
         // `undefined` covers the tombstone (delete transform) and updates-with-no-base (applyTransform
         // drops updates when there is no block to apply them to) — both materialize nothing.
         const digest = newBlock ? await canonicalBlockHash(newBlock) : undefined;
@@ -1024,6 +1152,14 @@ export class StorageRepo {
         }
         return undefined;
     }
+    /** See {@link IPendingClaimReader}. */
+    async listPendingClaims(blockId) {
+        return await this.createBlockStorage(blockId).listPendingClaims();
+    }
+    /** See {@link IPendingClaimReader}. */
+    async pendingClaimOf(blockId, actionId) {
+        return await this.createBlockStorage(blockId).pendingClaimOf(actionId);
+    }
     /**
      * The {@link BlockCommitProof} this node retained for `blockId` at `rev`, or `undefined` when it
      * kept none — a revision committed before proofs were persisted, a member whose materialization
@@ -1042,8 +1178,10 @@ export class StorageRepo {
     /**
      * @param declaredBaseRev The committed revision of the base the WRITER applied this block's
      * transform to, as declared in the commit op's `blockDigests[blockId].baseRev`. Untrusted wire
-     * data, so it is typed `unknown` and validated below. Absent from the read-driven promotion in
-     * {@link get}, which has no commit request and therefore nothing to compare against.
+     * data, so it is typed `unknown` and validated in {@link guardCommitBase} — where it is the
+     * FALLBACK, not the primary check: the base the record's own pend carried (`PendingClaim.baseRev`)
+     * is read first. Absent from the read-driven promotion in {@link get}, which has no commit request
+     * and has already judged the stored base (`mayPromoteOnRead`).
      */
     async internalCommit(blockId, actionId, rev, storage, latch, proof, declaredBaseRev) {
         // Note: This method is called under the block write latch — by commit() (within its locked
@@ -1063,47 +1201,8 @@ export class StorageRepo {
         }
         // Get prior materialized block if it exists
         const latest = await storage.getLatest();
-        // FORK GUARD: apply an update-only transform ONLY to the base the writer actually read.
-        // Revisions are allocated per COLLECTION, not per block, so `rev - 1` is meaningless here — a
-        // member legitimately holds block X at rev 1 and receives a commit of X at rev 7 when revs 2-6
-        // touched other blocks. The only sound discriminator is the writer's own per-block declaration:
-        // it read the block at `declaredBaseRev`, so a member holding anything else would be applying
-        // the transform to different bytes and silently forking the block's content at this revision.
-        //
-        // Each clause is deliberate:
-        // - `typeof declaredBaseRev === 'number'` — `blockDigests` is untrusted wire data with no
-        //   ingress schema (same rule as ClusterMember.validateCommitOperations). Missing, malformed,
-        //   or absent-by-design declarations ABSTAIN, preserving today's behavior for pre-upgrade
-        //   writers, undeclarable blocks, and the read-driven promotion in get().
-        // - `!transform.insert` — an insert-carrying transform is base-independent, so there is nothing
-        //   to fork. Keyed on the member's OWN pended transform (as previewCommitDigest does), never on
-        //   the declaration, so a hostile writer cannot flip the arm by attaching a bogus baseRev.
-        // - `latest?.rev !== declaredBaseRev` covers all three unsafe states: BEHIND the declared base
-        //   (missed updates — the fork case), AHEAD of it (this member holds a revision the writer
-        //   never saw — divergent history), and no local revision at all against a numeric declaration.
-        //
-        // Refusing is cheap and self-healing: refuseMissingBase throws MissingBaseRevisionError, which
-        // commit() classifies as divergence and ClusterMember.applyConsensusOperation maps to "behind",
-        // running reconcileDivergentCommit to pull the committed revision from a cohort peer. The
-        // writer's retry then lands on a healed base. A hostile writer declaring a junk numeric baseRev
-        // can force refusals and reconcile churn, but never a fork.
-        //
-        // NOTE: the AHEAD case is reported as "behind" divergence like every other missing-base
-        // refusal, so a cohort where nobody holds `rev` reconciles, fails `no-rev-quorum`, and logs
-        // that rather than a clean stale failure. Correct outcome — the writer read a base the cohort
-        // has moved past, and its retry re-reads — but the log reads as lag when it is the opposite.
-        // If those lines ever have to be triaged in volume, give the ahead arm its own reason string.
-        //
-        // NOTE: this guard only reaches what the writer declared, so two arms of the same fork still
-        // stand — both tracked by `backlog/bug-a-pended-transform-does-not-carry-its-base`:
-        // (1) a commit whose block declares NO digest — pre-upgrade writer, undeclarable block
-        // (read-far-then-update eviction, see db-core transform/digest.ts), or a delete-only transform —
-        // gap-applies exactly as before; (2) the read-driven promotion in `get`, which reaches this
-        // method with no commit request at all (`declaredBaseRev` undefined) and so cannot check. If
-        // forked-content reports persist, those are the residuals to look at.
-        if (typeof declaredBaseRev === 'number' && !transform.insert && latest?.rev !== declaredBaseRev) {
-            return await this.refuseMissingBase(blockId, actionId, rev, storage, latch, `local latest ${latest?.rev ?? 'none'} is not the declared base ${declaredBaseRev} of rev ${rev}`);
-        }
+        // FORK GUARD: apply an update-only transform ONLY to the base its author computed it against.
+        await this.guardCommitBase(blockId, actionId, rev, storage, latch, transform, latest, declaredBaseRev);
         const priorBlock = await this.readCommitBase(blockId, actionId, rev, storage, latest, latch);
         // Apply transform and save materialized block
         // applyTransform handles undefined priorBlock correctly for inserts
@@ -1126,8 +1225,9 @@ export class StorageRepo {
         // the 'latest' pointer doesn't point to a revision that hasn't been fully recorded.
         await storage.saveRevision(rev, actionId, latch);
         await storage.promotePendingTransaction(actionId, latch);
-        // Update latest revision *last*
-        await storage.setLatest({ actionId, rev }, latch);
+        // Update latest revision *last*. An insert replaced the block wholesale, so its content was
+        // not built on what this node held before (see BlockMetadata.lineageFloor).
+        await storage.setLatest({ actionId, rev }, transform.insert === undefined, latch);
         // Persist the cohort's commit proof AFTER the commit is durably latest — the proof is
         // evidence about a landed revision, never a precondition of landing it. The retention rule
         // (persist only when the LOCAL materialization matches the digest the commit op declared)
@@ -1157,6 +1257,111 @@ export class StorageRepo {
         // undefined so the caller skips it rather than emitting a bogus event.
         return newBlock?.header.collectionId ?? priorBlock?.header.collectionId;
     }
+    /**
+     * The fork guard: an update-only transform is applied ONLY to the base its author computed it
+     * against. Revisions are allocated per COLLECTION, not per block, so `rev - 1` is meaningless here —
+     * a member legitimately holds block X at rev 1 and receives a commit of X at rev 7 when revs 2-6
+     * touched other blocks (the retired decision `st-commit-contiguity-guard-premise`). The only sound
+     * discriminator is what the author said the base was, and the author says it twice:
+     *
+     * - `stored` — the base the record's own PEND carried for this block (`PendRequest.baseRevs`, kept
+     *   as `PendingClaim.baseRev`). PRIMARY, because it was recorded with the very operations it
+     *   describes and is present on every path that applies the record, commit message or not.
+     * - `declared` — `blockDigests[blockId].baseRev` on the commit. The FALLBACK, for a record whose
+     *   pend named no base: a sender running older code, or a drift-blind source (test doubles).
+     *   Untrusted wire data with no ingress schema (same rule as ClusterMember.validateCommitOperations):
+     *   anything but a number abstains rather than being coerced into a comparison.
+     *
+     * Three steps, in order:
+     *
+     * 1. Both present and unequal → refuse, with its own detail and log line. An honest writer never
+     *    does this (the base pinned at staging is the one pended and the one declared — `Tracker`), so
+     *    the shape it closes is a member holding a STALE pending record from an earlier attempt of a
+     *    retried action — the retry's pend never reached this member — that receives the retry's
+     *    commit: the old record's operations were computed against a different base, and a guard that
+     *    read only the declaration would apply them wherever this member's latest happened to equal
+     *    the new declaration.
+     * 2. `effective = stored ?? declared`; a number, and `latest?.rev !== effective` → refuse. Covers
+     *    all three unsafe states: BEHIND the base (missed updates — the fork case), AHEAD of it (this
+     *    member holds a revision the writer never saw — divergent history), and no local revision at
+     *    all against a numeric base.
+     * 3. Neither present → apply as before the guard existed, logged as `commit:base-undeclared` so the
+     *    residual is countable. This is the one arm left open, BY CHOICE, for senders that name no
+     *    base anywhere: refusing a base-less pend outright would turn every such writer's write into a
+     *    hard failure on a release that may run mixed versions for a while.
+     *
+     * Base-independent transforms — an insert (replaces the block wholesale) or a delete (materializes
+     * to nothing) — are never guarded, keyed on the member's OWN pended transform and never on a
+     * declaration, so a hostile writer cannot flip the arm by attaching a bogus base.
+     *
+     * Refusing is cheap and self-healing: refuseMissingBase throws MissingBaseRevisionError, which
+     * commit() classifies as divergence and ClusterMember.applyConsensusOperation maps to "behind",
+     * running reconcileDivergentCommit to pull the committed revision from a cohort peer. The writer's
+     * retry then lands on a healed base. A hostile writer naming a junk numeric base — on the pend or
+     * on the commit — can force refusals and reconcile churn, but never a fork.
+     *
+     * NOTE: the AHEAD case is reported as "behind" divergence like every other missing-base refusal, so
+     * a cohort where nobody holds `rev` reconciles, fails `no-rev-quorum`, and logs that rather than a
+     * clean stale failure. Correct outcome — the writer read a base the cohort has moved past, and its
+     * retry re-reads — but the log reads as lag when it is the opposite. If those lines ever have to be
+     * triaged in volume, give the ahead arm its own reason string.
+     */
+    async guardCommitBase(blockId, actionId, rev, storage, latch, transform, latest, declaredBaseRev) {
+        if (isBaseIndependent(transform)) {
+            return;
+        }
+        // NOTE: `pendingClaimOf` re-reads the record `internalCommit` already holds (to prove the claim
+        // is live) plus the metadata — two local KV gets per update-only commit, unmeasured. If the
+        // commit path ever shows them in a profile, read the metadata alone here: the caller's record
+        // read is the liveness proof.
+        const stored = (await storage.pendingClaimOf(actionId))?.baseRev;
+        const declared = typeof declaredBaseRev === 'number' ? declaredBaseRev : undefined;
+        if (stored !== undefined && declared !== undefined && stored !== declared) {
+            log('commit:base-disagreement blockId=%s rev=%d actionId=%s stored=%d declared=%d', blockId, rev, actionId, stored, declared);
+            return await this.refuseMissingBase(blockId, actionId, rev, storage, latch, `stored base ${stored} disagrees with declared base ${declared} of rev ${rev}`);
+        }
+        const effective = stored ?? declared;
+        if (effective === undefined) {
+            // NOTE: debug level only, so the base-less residual is countable but not visible in production
+            // logs; every bare test-double pend lands here, so a visible level would drown the suites. If
+            // a mixed-version fleet ever needs the count, give this one line its own logger.
+            log('commit:base-undeclared blockId=%s rev=%d actionId=%s latest=%s', blockId, rev, actionId, latest?.rev ?? 'none');
+            return;
+        }
+        if (latest?.rev !== effective) {
+            return await this.refuseMissingBase(blockId, actionId, rev, storage, latch, `local latest ${latest?.rev ?? 'none'} is not the ${stored !== undefined ? 'stored' : 'declared'} base ${effective} of rev ${rev}`);
+        }
+    }
+    /**
+     * Whether the read-driven promotion in {@link get} may apply `actionId`'s pending record here: a
+     * base-independent record (an insert or a delete) always; an update-only one only when the base
+     * its pend carried (`PendingClaim.baseRev`) is a number equal to this node's `latest`. Anything
+     * else — a base this node has not reached, one it is past, or none stored at all — DECLINES, and
+     * the caller leaves the record and `latest` untouched.
+     *
+     * Declining is deliberately distinct from {@link refuseMissingBase}, which deletes the record
+     * because it can never be promoted here. A declined record is not dead: this node's latest reaches
+     * the stored base only through a replica or reconcile, and when that lands `sweepDeadClaims`
+     * removes the record if its slot is passed, or a later context read promotes it if not. A record
+     * whose pend named no base is declined too — the promotion must not apply a change whose base it
+     * cannot establish, and block repair supplies the version instead. The cost falls on base-less
+     * senders alone: their held-but-missed records no longer come current on a read, only through the
+     * next commit's reconcile or the coordinator's read-repair.
+     *
+     * {@link guardCommitBase} still runs inside `internalCommit` afterwards; under the latch the
+     * caller holds, this check is exactly what makes it pass.
+     */
+    async mayPromoteOnRead(blockId, storage, actionId, pending, latest) {
+        if (isBaseIndependent(pending)) {
+            return true;
+        }
+        const stored = (await storage.pendingClaimOf(actionId))?.baseRev;
+        if (stored !== undefined && latest?.rev === stored) {
+            return true;
+        }
+        log('get:promote-declined blockId=%s actionId=%s storedBase=%s latest=%s', blockId, actionId, stored ?? 'none', latest?.rev ?? 'none');
+        return false;
+    }
     /**
      * Retain `proof` for a block this call found ALREADY committed at `(rev, actionId)` — the paths
      * that land (or find already landed) a revision without running {@link internalCommit}, and would