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

package/src/storage/storage-repo.ts

@@ -1,22 +1,25 @@
 import type {
 	IRepo, MessageOptions, BlockId, CommitRequest, CommitResult, GetBlockResults, PendRequest, PendResult, ActionBlocks,
-	ActionId, BlockGets, ActionPending, PendSuccess, ActionTransform, ActionTransforms,
+	ActionId, BlockGets, ActionPending, PendSuccess, ActionTransform, ActionTransforms, Transform,
 	GetBlockResult, IBlock, ActionRev, BlockUnavailableReason,
 	PendValidationHook, UnvalidatablePendPolicy,
 	CollectionId, IBlockChangeNotifier, CollectionChangeListener, CollectionChangeEvent,
+	IBlockDurabilityNotifier, BlockDurabilityListener, BlockDurabilityReachedEvent,
 	StaleFailure
 } from "@optimystic/db-core";
 import {
 	transformForBlockId, applyTransform, groupBy, concatTransform, emptyTransforms,
-	blockIdsForTransforms, transformsFromTransform, highestStaleAt, isOwnRevision, canonicalBlockHash
+	blockIdsForTransforms, transformsFromTransform, highestStaleAt, isOwnRevision, canonicalBlockHash, localDurability
 } from "@optimystic/db-core";
 import { asyncIteratorToArray } from "../it-utility.js";
 import type { IBlockStorage } from "./i-block-storage.js";
+import { isReservationAgainst, isBaseIndependent, declaredBaseFor, type PendingClaim } from "./pending-claim.js";
 import type { IBlockReplicaStore } from "../cluster/block-transfer-service.js";
 import { proofDeclaredDigest, type BlockCommitProof } from "../cluster/commit-proof.js";
 import { RevisionNotCoveredError } from "./i-block-storage.js";
 import { acquireBlockWriteLatches, withBlockWriteLatch, type BlockWriteLatch } 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');
@@ -157,13 +160,35 @@ export interface IRevisionActionReader {
 	getRevisionAction(blockId: BlockId, rev: number): Promise<ActionId | undefined>;
 }
 
-export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaStore, ICommitDigestPreviewer, ICommitProofPersister, IRevisionActionReader {
+/**
+ * The capability that answers "which pending records hold this block, and for which slot and
+ * base?" — the questions the promise-round votes need. The rival check
+ * (`ClusterMember.validatePendOperations`) lists every record's claim, because a record the incoming
+ * writer has built on is not a reservation against it (`isReservationAgainst`), and
+ * `GetBlockResult.state.pendings` carries only action ids; the commit vote
+ * (`ClusterMember.validateCommitBaseDeclarations`) reads one record's claim, to compare the base its
+ * pend carried with the one the commit declares. Named for the same reason as
+ * {@link IRevisionActionReader}: a repo that lacks `listPendingClaims` degrades the pend vote to
+ * "every rival reserves" rather than to silently admitting one, and one that lacks `pendingClaimOf`
+ * makes the commit vote abstain — each method is probed on its own.
+ */
+export interface IPendingClaimReader {
+	/** See `IBlockStorage.listPendingClaims`. Read-only; never takes the block write latch. */
+	listPendingClaims(blockId: BlockId): Promise<PendingClaim[]>;
+	/** See `IBlockStorage.pendingClaimOf`. Read-only; never takes the block write latch. */
+	pendingClaimOf(blockId: BlockId, actionId: ActionId): Promise<PendingClaim | undefined>;
+}
+
+export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockDurabilityNotifier, IBlockReplicaStore, ICommitDigestPreviewer, ICommitProofPersister, IRevisionActionReader, IPendingClaimReader {
 	private readonly validatePend?: PendValidationHook;
 	private readonly unvalidatablePendPolicy: UnvalidatablePendPolicy;
 	/** Per-collection change listeners; empty sets are pruned on unsubscribe. */
 	private readonly changeListeners = new Map<CollectionId, Set<CollectionChangeListener>>();
 	/** Catch-all change listeners — fire for EVERY collection's commit on this node. */
 	private readonly anyChangeListeners = new Set<CollectionChangeListener>();
+	/** Full-replication listeners — fire when a block this node acknowledged below `full` has
+	 *  reached every cohort member. See {@link IBlockDurabilityNotifier}. */
+	private readonly durabilityListeners = new Set<BlockDurabilityListener>();
 
 	constructor(
 		private readonly createBlockStorage: (blockId: BlockId) => IBlockStorage,
@@ -254,7 +279,34 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		}
 	}
 
-	async get({ blockIds, context }: BlockGets, _options?: MessageOptions): Promise<GetBlockResults> {
+	/** Subscribe to full-replication events. See {@link IBlockDurabilityNotifier}. */
+	onBlockDurabilityReached(listener: BlockDurabilityListener): () => void {
+		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: BlockDurabilityReachedEvent): void {
+		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 }: BlockGets, _options?: MessageOptions): Promise<GetBlockResults> {
 		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
@@ -263,7 +315,7 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		// parallel map closures below — safe because each push happens synchronously
 		// between awaits (single-threaded), never concurrently.
 		const promotions: { collectionId: CollectionId, blockId: BlockId, actionId: ActionId, rev: number }[] = [];
-		const results = await Promise.all(distinctBlockIds.map(async (blockId) => {
+		const results = await Promise.all(distinctBlockIds.map(async (blockId): Promise<[BlockId, GetBlockResult]> => {
 			const blockStorage = this.createBlockStorage(blockId);
 			// Set when this node KNOWS its answer for the block is a guess: the promotion
 			// below refused for a missing base, or getBlock() threw (truncated history /
@@ -301,22 +353,38 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 						// `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 });
 								}
 							}
 						} catch (err) {
@@ -324,7 +392,9 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 							// 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;
 							}
@@ -393,6 +463,11 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 					// 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,
@@ -450,9 +525,34 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		// 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.
+	 */
+	private async answerLineage(results: [BlockId, GetBlockResult][], target: ActionRev): Promise<void> {
+		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
@@ -661,9 +761,22 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 				// consensus round per such write), refuse at `ClusterMember.validatePendOperations`
 				// instead of here.
 
-				// Then handle any pending actions
-				const pending = await asyncIteratorToArray(blockStorage.listPendingTransactions());
-				pendings.push(...pending.map(actionId => ({ blockId, actionId })));
+				// 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
@@ -715,13 +828,17 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 				}
 				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()
 			} as PendSuccess;
 		} finally {
 			// Releases on every path, including the early returns above and the
@@ -985,7 +1102,8 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		// 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() };
 	}
 
 	/**
@@ -1180,8 +1298,13 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 
 		// 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;
@@ -1201,6 +1324,16 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		return undefined;
 	}
 
+	/** See {@link IPendingClaimReader}. */
+	async listPendingClaims(blockId: BlockId): Promise<PendingClaim[]> {
+		return await this.createBlockStorage(blockId).listPendingClaims();
+	}
+
+	/** See {@link IPendingClaimReader}. */
+	async pendingClaimOf(blockId: BlockId, actionId: ActionId): Promise<PendingClaim | undefined> {
+		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
@@ -1220,8 +1353,10 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 	/**
 	 * @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`).
 	 */
 	private async internalCommit(blockId: BlockId, actionId: ActionId, rev: number, storage: IBlockStorage, latch: BlockWriteLatch, proof?: BlockCommitProof, declaredBaseRev?: unknown): Promise<CollectionId | undefined> {
 		// Note: This method is called under the block write latch — by commit() (within its locked
@@ -1244,48 +1379,8 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		// 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);
 
@@ -1315,8 +1410,9 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		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
@@ -1350,6 +1446,118 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		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.
+	 */
+	private async guardCommitBase(
+		blockId: BlockId, actionId: ActionId, rev: number, storage: IBlockStorage, latch: BlockWriteLatch,
+		transform: Transform, latest: ActionRev | undefined, declaredBaseRev: unknown
+	): Promise<void> {
+		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.
+	 */
+	private async mayPromoteOnRead(blockId: BlockId, storage: IBlockStorage, actionId: ActionId, pending: Transform, latest: ActionRev | undefined): Promise<boolean> {
+		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

package/src/storage/struct.ts

@@ -13,6 +13,64 @@ export type BlockMetadata = {
 	ranges: RevisionRange[];
 	/** Latest revision - present if the repo is not empty */
 	latest?: ActionRev;
+	/**
+	 * The lowest revision this node's content at `latest` is KNOWN to derive from: every revision
+	 * record above it was produced HERE, by applying an update-only transform to the content of the
+	 * revision before it. So a revision at or above the floor that the revision index names is part
+	 * of what `latest` was built from, and one the index does not name is provably not.
+	 *
+	 * Anything that installs content this node did not derive moves the floor up to that revision,
+	 * because it says nothing about what the content was built from: a replica or forward tombstone
+	 * (`saveReplica`/`saveDeletion` — cohort reconcile, churn replication, invalidation), and a
+	 * commit whose transform carries an `insert`, which replaces the block wholesale. The block's
+	 * first commit starts the floor at its own revision.
+	 *
+	 * Absent on metadata written before the field existed; the next commit then starts it at the
+	 * revision it built on, which claims nothing about the history below. Read through
+	 * `IBlockStorage.lineageOf`, never compared by hand.
+	 */
+	lineageFloor?: number;
+	/**
+	 * The revision each pending record on this block was pended AT, keyed by the record's action id —
+	 * the `rev` of the `PendRequest` it belongs to. This is what turns a pending record into a
+	 * *reservation for a slot* rather than a bare "someone is writing": a record the incoming writer
+	 * has built on — its requested revision is past the slot, or, where the promise vote reads it, its
+	 * declared base for the block is at or past the slot — is no rival (see `isReservationAgainst` in
+	 * `pending-claim.ts`),
+	 * and one claiming a revision this block has already committed can never be promoted here at all.
+	 *
+	 * Kept here, beside `latest`, rather than inside the pending record itself, because the raw
+	 * drivers move a pending record into the committed store byte-for-byte on promotion (a rename on
+	 * the filesystem backend), so the record's value has to stay a plain transform. The pending
+	 * NAMESPACE remains the record; this map only says what slot each record claims. An entry whose
+	 * record is gone is inert — every reader joins it against the namespace
+	 * (`IBlockStorage.listPendingClaims`) — and is dropped when the record is deleted or when
+	 * `latest` advances to or past it. A record with no entry (written before the field existed, or
+	 * pended without a revision) reads as an unknown claim, which is treated as the strongest kind.
+	 */
+	pendingRevs?: Record<ActionId, number>;
+	/**
+	 * The committed revision each pending record's update operations were computed against, keyed
+	 * by the record's action id — the pend's `baseRevs[blockId]` (`PendRequest.baseRevs`). Absent for
+	 * a record whose pend carried no base for this block (inserted, deleted, or unknown to the
+	 * author) and for records written before the field existed; both read as base-unknown. Kept
+	 * beside `pendingRevs`, and for the same reason: the raw drivers move a pending record into the
+	 * committed store byte-for-byte on promotion, so the record's value has to stay a plain
+	 * transform. Written, dropped and swept in the same metadata writes as `pendingRevs`
+	 * (`BlockStorage.recordClaim`), so the two can never describe different records.
+	 *
+	 * A SIBLING map rather than a change to `pendingRevs`' shape, deliberately: metadata written by
+	 * the release before this field must stay readable without a migration, and a record with no
+	 * entry here simply reads as base-unknown. What each apply site does with an unknown base is
+	 * its own rule — `StorageRepo.internalCommit` falls back to the commit's declaration and then
+	 * abstains; the read-driven promotion in `StorageRepo.get` declines.
+	 *
+	 * NOTE: the two maps are not always co-keyed. A rev-less pend that names a base would leave an
+	 * entry here and none in `pendingRevs`, which the slot-driven dead-claim sweep cannot see, so it
+	 * would live until the record is deleted or promoted. Harmless, and no production caller sends a
+	 * rev-less pend (see the NOTE in `StorageRepo.pend`); if one ever appears, sweep this map too.
+	 */
+	pendingBases?: Record<ActionId, number>;
 };
 
 export type ArchiveRevisions = Record<number, {