@optimystic/db-p2p 0.21.0 → 0.22.0

package/src/libp2p-node-rn.ts

@@ -1,10 +1,10 @@
-import type { Libp2p } from 'libp2p';
 import {
 	createLibp2pNodeBase,
 	type Libp2pTransports,
 	type NodeOptions,
 	type RawStorageProvider,
 } from './libp2p-node-base.js';
+import type { OptimysticNode } from './optimystic-node.js';
 
 export type { Libp2pTransports, NodeOptions, RawStorageProvider };
 
@@ -14,7 +14,7 @@ export type { Libp2pTransports, NodeOptions, RawStorageProvider };
  * This entrypoint intentionally does not import Node-only transports (like `@libp2p/tcp`).
  * Callers must provide `options.transports` (and typically `options.listenAddrs`).
  */
-export async function createLibp2pNode(options: NodeOptions): Promise<Libp2p> {
+export async function createLibp2pNode(options: NodeOptions): Promise<OptimysticNode> {
 	const transports = options.transports;
 	if (!transports || transports.length === 0) {
 		throw new Error(

package/src/libp2p-node.ts

@@ -1,4 +1,3 @@
-import type { Libp2p } from 'libp2p';
 import { tcp } from '@libp2p/tcp';
 import { webSockets } from '@libp2p/websockets';
 import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
@@ -8,10 +7,11 @@ import {
 	type NodeOptions,
 	type RawStorageProvider,
 } from './libp2p-node-base.js';
+import type { OptimysticNode } from './optimystic-node.js';
 
 export type { Libp2pTransports, NodeOptions, RawStorageProvider };
 
-export async function createLibp2pNode(options: NodeOptions): Promise<Libp2p> {
+export async function createLibp2pNode(options: NodeOptions): Promise<OptimysticNode> {
 	const port = options.port ?? 0;
 	const wsHost = options.wsHost ?? '0.0.0.0';
 

package/src/network/network-manager-service.ts

@@ -58,6 +58,11 @@ export class NetworkManagerService implements Startable {
 		}
 	}
 
+	/** The cluster size this instance actually resolved to, for `assertClusterSizeCoupling`. */
+	get effectiveClusterSize(): number {
+		return this.cfg.clusterSize;
+	}
+
 	setLibp2p(libp2p: Libp2p): void {
 		this.libp2pRef = libp2p;
 	}

package/src/optimystic-node.ts

@@ -0,0 +1,36 @@
+import type { Libp2p, PrivateKey } from '@libp2p/interface';
+import type { IBlockChangeNotifier, IRepo } from '@optimystic/db-core';
+import type { DisputeService } from './dispute/dispute-service.js';
+import type { Libp2pKeyPeerNetwork } from './libp2p-key-network.js';
+import type { PeerReputationService } from './reputation/peer-reputation.js';
+import type { StorageRepo } from './storage/storage-repo.js';
+
+/**
+ * The handles `createLibp2pNodeBase` attaches to the libp2p node it returns. This is the
+ * sanctioned in-process surface a host reads — declared once here so reaching it does not
+ * require a cast, and so a host cannot silently rebuild a component the node already owns.
+ *
+ * Deliberately NOT the full set of `(node as any).*` attachments made in `libp2p-node-base.ts`:
+ * the churn/rebalance/ring-shift monitors, the cohort-topic host and the reactivity registries
+ * are node-internal wiring, not a host-facing surface, and typing them is a separate job.
+ */
+export interface OptimysticNodeAttachments {
+	/**
+	 * The node's ONE key network — built from its resolved cluster policy, network-namespaced
+	 * protocol prefix, reputation tracker and persistence. A host that needs key/coordinator
+	 * lookup uses THIS; constructing a second one gives peer selection a different cohort
+	 * width and coordinator than the node's own consensus path uses for the same key.
+	 */
+	keyNetwork: Libp2pKeyPeerNetwork;
+	coordinatedRepo: IRepo;
+	storageRepo: StorageRepo;
+	/** Per-collection change origin. Replaced by the cohort-topic bridge notifier when enabled. */
+	blockChangeNotifier: IBlockChangeNotifier;
+	reputation: PeerReputationService;
+	/** Present only when the dispute subsystem is configured. */
+	disputeService?: DisputeService;
+	/** The node's libp2p Ed25519 identity key, for hosts binding a client-transaction signer. */
+	peerPrivateKey: PrivateKey;
+}
+
+export type OptimysticNode = Libp2p & OptimysticNodeAttachments;

package/src/repo/coordinator-repo.ts

@@ -9,6 +9,7 @@ import type { IPeerReputation } from "../reputation/types.js";
 import { PenaltyReason } from "../reputation/types.js";
 import type { ITransactionStateStore } from "../cluster/i-transaction-state-store.js";
 import { quorumSize, corroboratorCapacity, selectQuorumRev, type RevClaim, type QuorumRev } from "../cluster/quorum-restore.js";
+import { DEFAULT_CLUSTER_SIZE } 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 type { ReconcileBlockCallback } from "../cluster/cluster-repo.js";
@@ -191,7 +192,10 @@ export class CoordinatorRepo implements IRepo {
 	) {
 		this.localPeerId = localPeerId;
 		const policy: ClusterConsensusConfig & { clusterSize: number } = {
-			clusterSize: cfg?.clusterSize ?? 10,
+			// Same constant `resolveClusterPolicy` gives a node that declares no clusterSize, not a
+			// second literal: a direct constructor (the readme's manual-wiring path) and the node
+			// assembly must land on the same width or the two disagree about the same key's cohort.
+			clusterSize: cfg?.clusterSize ?? DEFAULT_CLUSTER_SIZE,
 			assumedClusterSize: cfg?.assumedClusterSize,
 			superMajorityThreshold: cfg?.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD,
 			simpleMajorityThreshold: cfg?.simpleMajorityThreshold ?? 0.51,
@@ -393,12 +397,21 @@ export class CoordinatorRepo implements IRepo {
 	 *
 	 * No-op once the entry carries a real answer (the consult restored the block) or a sharper flag
 	 * (storage's `'unmaterializable'`), so callers only need to establish that the answer is a guess.
+	 *
+	 * "Carries a real answer" is tested as `entry.block !== undefined`, NOT as `state.latest` being
+	 * set. The two used to move together, so `state.latest` read as a serviceable proxy — but a
+	 * pending-only insert (pended, not yet committed) served through the pending overlay has real
+	 * CONTENT and no committed revision at all, so its `state.latest` is undefined. Flagging that
+	 * entry would mark a block this node is positively holding as an unconfirmed absence, and
+	 * `NetworkTransactor`'s `isAuthoritative` keys off the flag alone — the read would burn its
+	 * retry budget re-asking other peers for content it already has. `state.latest` stays in the
+	 * test as well so a stale-but-real committed answer is likewise never downgraded.
 	 */
 	private flagUnconfirmedAbsence(results: GetBlockResults, blockId: BlockId): void {
 		const entry = results[blockId];
 		if (!entry) {
 			results[blockId] = { state: {}, unavailable: 'peers-unreachable' };
-		} else if (!entry.state?.latest && entry.unavailable === undefined) {
+		} else if (entry.block === undefined && !entry.state?.latest && entry.unavailable === undefined) {
 			entry.unavailable = 'peers-unreachable';
 		}
 	}
@@ -603,11 +616,13 @@ export class CoordinatorRepo implements IRepo {
 	 * the repair. Returns the local revision afterwards.
 	 *
 	 * A pending-only block (metadata seeded by `savePendingTransaction`, no committed revision) asked
-	 * for a forward revision no promotion can reach used to throw out of `BlockStorage.ensureRevision`;
-	 * `StorageRepo.get` now reports it as an entry flagged `unavailable` instead (ticket
-	 * repo-reports-unavailable-vs-absent). On THIS path either shape is an absence, not a read failure —
-	 * acquisition is precisely the mechanism that can supply the revision — so both are logged as
-	 * `promote-unavailable` and stepped over rather than short-circuiting the caller.
+	 * for a forward revision no promotion can reach used to throw out of `BlockStorage.ensureRevision`.
+	 * It no longer does: "no committed base here" is an absence, so that read comes back as a plain
+	 * unflagged `{ state: {} }` and this method simply returns `undefined` — acquisition then supplies
+	 * the revision. The `unavailable` arm below still fires for the shapes that ARE a guess (a `latest`
+	 * this node cannot materialize, a missing-base promotion refusal); on THIS path those are an
+	 * absence too rather than a read failure, so they are logged as `promote-unavailable` and stepped
+	 * over rather than short-circuiting the caller. The catch stays for any other fault, same reason.
 	 */
 	private async promoteCorroborated(blockId: BlockId, corroborated: ActionRev): Promise<number | undefined> {
 		try {
@@ -715,7 +730,8 @@ export class CoordinatorRepo implements IRepo {
 			log('cluster-fetch:no-quorum', {
 				blockId,
 				responders: claims.length,
-				required: quorumSize(claims.length, this.simpleMajorityThreshold, capacity)
+				required: quorumSize(claims.length, this.simpleMajorityThreshold, capacity),
+				repairCorroborationClusterSize: this.repairCorroborationClusterSize
 			});
 			return { local, silent };
 		}

package/src/rn.ts

@@ -1,4 +1,5 @@
 export * from './cluster/client.js';
+export * from './cluster/cluster-policy.js';
 export * from './cluster/cluster-repo.js';
 export * from './cluster/service.js';
 export * from './protocol-client.js';
@@ -25,6 +26,7 @@ export * from './sync/service.js';
 export * from './it-utility.js';
 export * from './libp2p-key-network.js';
 export * from './libp2p-node-rn.js';
+export * from './optimystic-node.js';
 export * from './routing/responsibility.js';
 export * from './routing/libp2p-known-peers.js';
 export * from './network/network-manager-service.js';

package/src/storage/block-storage.ts

@@ -50,14 +50,44 @@ export class BlockStorage implements IBlockStorage {
 			return undefined;
 		}
 
-		// Pending-only state: metadata was seeded by savePendingTransaction but no
-		// revision has been committed yet. Treat as "doesn't exist" for the default
-		// request path — matches StorageRepo.get()'s contract that undefined => empty.
-		if (rev === undefined && meta.latest === undefined) {
-			return undefined;
+		// Pending-only state: metadata was seeded by savePendingTransaction but no revision has been
+		// committed yet. "No committed base here" is an ABSENCE, not a fault — nothing is being
+		// FAILED to reconstruct — so both arms below answer `undefined` rather than throwing, whether
+		// or not the caller named a revision. StorageRepo.get then applies any pending overlay over
+		// that absent base; a throw here would instead be caught into `unavailable: 'unmaterializable'`
+		// and a writer reading back its own not-yet-committed insert would be told it is unreadable.
+		// `unmaterializable` must keep its one meaning: records prove the block exists and this node
+		// cannot reconstruct it.
+		if (meta.latest === undefined) {
+			if (rev === undefined) {
+				return undefined;
+			}
+			// A named rev still ATTEMPTS the restore: `restoreCallback` may be able to supply that
+			// revision even though nothing is committed locally, and a successful restore serves real
+			// content with `latest` still undefined. That capability is pinned by the 'getBlock for an
+			// absent revision fires restoreCallback (restore not short-circuited)' test in
+			// test/block-storage.spec.ts — do not short-circuit it away.
+			//
+			// Only ensureRevision's FAILURE is swallowed (no callback wired, or restore could not
+			// supply the rev): that is precisely the "no committed base here" absence. materializeBlock
+			// below is deliberately OUTSIDE the try — a throw from there means revision records exist
+			// with no materialization anywhere under them, which is genuine corruption and must keep
+			// reading as `unmaterializable`.
+			//
+			// NOTE: a contextful read of a pending-only block still attempts a network restore before
+			// falling back to absent (same cost as the pre-fix throw path); if pending-only read-backs
+			// ever show as hot, short-circuit when ranges are empty.
+			try {
+				await this.ensureRevision(meta, rev);
+			} catch (err) {
+				log('getBlock:no-committed-base blockId=%s rev=%d error=%s', this.blockId, rev,
+					err instanceof Error ? err.message : String(err));
+				return undefined;
+			}
+			return await this.materializeBlock(meta, rev);
 		}
 
-		const targetRev = rev ?? meta.latest!.rev;
+		const targetRev = rev ?? meta.latest.rev;
 		await this.ensureRevision(meta, targetRev);
 		return await this.materializeBlock(meta, targetRev);
 	}
@@ -271,6 +301,29 @@ export class BlockStorage implements IBlockStorage {
 			};
 			await this.saveRestored(archive);
 
+			// INVARIANT P: a block never holds a pending record AND a committed record for the same
+			// action id. On the commit path `promotePendingTransaction` maintains it by MOVING the
+			// record atomically; this forward path writes the committed transform directly (via
+			// saveRestored above), so it owes the deletion itself. Without it, a node that pended the
+			// action but diverged before committing keeps a record nothing can ever promote — reported
+			// as a phantom conflicting action by every later `pend` on the block, which under
+			// `policy: 'f'` refuses that node's participation in the block's writes permanently.
+			//
+			// Deliberately on the WRITE path only: the monotonic guard above returns before here, and
+			// that early return must stay a true no-op (the earlier call that wrote the revision is the
+			// one that owed the deletion). Deliberately here rather than in `saveRestored`, which is
+			// also reached from ensureRevision's historical restore under a different latch, where a
+			// deletion could race a concurrent promotePendingTransaction; this path holds
+			// `BlockStorage.saveReplica:<id>` and (via StorageRepo.saveReplicatedBlock) the per-block
+			// commit latch, so it is already mutually exclusive with a live commit.
+			//
+			// NOTE: deletes only this revision's actionId, not every pending whose action is already
+			// committed. A broader sweep would repair records orphaned by routes that do not carry the
+			// committing actionId; if orphaned pendings ever show up in the field on blocks whose
+			// committing action id differs, widen to a sweep over listPendingTransactions filtered by
+			// getTransaction.
+			await this.storage.deletePendingTransaction(this.blockId, actionId);
+
 			// Seed metadata when absent, advance latest, and merge the covered range.
 			const prevRev = meta?.latest?.rev;
 			if (!meta) {

package/src/storage/i-block-storage.ts

@@ -47,7 +47,18 @@ export interface IBlockStorage {
     /** Saves a revision */
     saveRevision(rev: number, actionId: ActionId): Promise<void>;
 
-    /** Promotes a pending action to committed */
+    /**
+     * Promotes a pending action to committed, MOVING the record from the pending namespace to the
+     * committed one in a single atomic step.
+     *
+     * **Invariant P** — a block never holds a pending record and a committed record for the same
+     * action id at the same time. This method maintains it on the commit path; every OTHER writer of
+     * a committed transform for a block ({@link saveReplica}, {@link saveDeletion}, and any forward
+     * path added later) must maintain it too, by deleting that action's pending record when it
+     * writes the committed one. A pending record left beside a committed one can never be promoted,
+     * and is reported as a phantom conflicting action by `StorageRepo.pend` on every later write to
+     * the block.
+     */
     promotePendingTransaction(actionId: ActionId): Promise<void>;
 
     /** Sets the latest revision information */
@@ -62,6 +73,11 @@ export interface IBlockStorage {
      * it falls back to `rev = 1` and a deterministic `actionId` derived from the block
      * (so retries stay idempotent — never random).
      *
+     * Maintains **Invariant P** (see {@link promotePendingTransaction}): writing the committed
+     * transform for `actionId` also deletes that action's pending record on this block, so a node
+     * that pended the action but diverged before committing it does not keep an unpromotable record.
+     * Only on the write path — the monotonic no-op below deletes nothing.
+     *
      * No-op (still durable) when an equal-or-newer revision is already present: `latest`
      * is never downgraded. Idempotent for a fixed `(rev, actionId)`. Returns the
      * effective latest `ActionRev`.
@@ -75,6 +91,9 @@ export interface IBlockStorage {
      * materialization as a deletion, so a `getBlock()` after a tombstone reads back as *absent*
      * (`undefined`) while a historical `getBlock(creationRev)` still materializes the created content.
      *
+     * Maintains **Invariant P** (see {@link promotePendingTransaction}) on the write path, exactly as
+     * {@link saveReplica} does: the tombstone's `actionId` loses its pending record on this block.
+     *
      * Idempotent for a fixed `(rev, actionId)`; never downgrades `latest` (a no-op — still durable —
      * when an equal-or-newer revision is already present). Returns the effective latest `ActionRev`.
      */

package/src/storage/storage-repo.ts

@@ -280,19 +280,30 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 			}
 
 			// Include pending action if requested, applying the pending transform over whatever
-			// committed base getBlock() resolved (possibly none).
-			// NOTE: the `blockRev == null` arm is currently DEAD, so a pending-only insert is NOT
-			// served here despite what this branch is shaped to do: `ActionContext.rev` is required,
-			// and BlockStorage.getBlock only tolerates a missing committed base when `rev` is
-			// undefined — so a contextful read of a block with no committed revision throws above and
-			// is caught into `unavailable: 'unmaterializable'` before reaching here. Asserted in
-			// storage-repo.spec.ts ('KNOWN GAP: a pending-only insert read WITH a context ...'); see
-			// tickets/backlog/debt-pending-only-insert-unreadable-with-context.
+			// committed base getBlock() resolved (possibly none — a pending-only insert has no
+			// committed revision under it and getBlock reports that as an absent base, not a fault).
 			if (context?.actionId !== undefined) {
 				const pendingTransform = await blockStorage.getPendingTransaction(context.actionId);
 				if (!pendingTransform) {
+					if (unavailable !== undefined) {
+						// The promotion refusal above deleted this very pending record
+						// (`refuseMissingBase` drops the pending it cannot promote). This node DID hold
+						// the record and dropped it, so the honest answer is an availability one — not
+						// a caller-contract violation, and never a throw that would fail the whole batch.
+						return [blockId, { state: {}, unavailable } as GetBlockResult];
+					}
 					// Caller-contract violation (the caller asserted a pending this repo never had, or
 					// cancelled) — an error, not an availability question. Deliberately NOT `unavailable`.
+					//
+					// It is NOT the only way to reach here. A context that both PROVES its own action
+					// (`committed` names it) and names it as the pending overlay (`actionId`) is
+					// self-contradictory, and the two halves of that contradiction land differently: if
+					// the read-driven promotion above REFUSED, the arm above answers gracefully; if it
+					// SUCCEEDED, `promotePendingTransaction` moved the record and we throw here — failing
+					// the whole batch for a request the refusal path tolerates. No production code sets
+					// `ActionContext.actionId` at all today, so neither is reachable except from tests or
+					// a peer that crafts the field on the wire. See
+					// tickets/blocked/repo-pending-overlay-has-no-producer.
 					throw new Error(`Pending action ${context.actionId} not found`);
 				}
 				const block = applyTransform(blockRev?.block, pendingTransform);
@@ -304,13 +315,21 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 					},
 					// The COMMITTED revision underneath the pending overlay. A pending has no revision
 					// of its own, so the honest answer is the base it was applied to. Absent when there
-					// was no base — unreachable today (see the NOTE above), kept so the field stays
-					// correct rather than fabricating a revision if that arm is ever reopened.
+					// was no base at all — a pending-only insert served over an absent committed base,
+					// where fabricating a revision would claim content this node never committed.
 					...(blockRev ? { materializedRev: blockRev.actionRev.rev } : {}),
 					// A pending applied to a missing base can materialize nothing (applyTransform drops
 					// updates with no block to apply them to) — that absence is a guess, and is flagged.
-					// A materialized block is a real answer regardless of the earlier refusal.
-					...(unavailable !== undefined && block === undefined ? { unavailable } : {})
+					// A materialized block is a real answer regardless of the earlier refusal. TWO ways
+					// an empty result is a guess: the promotion refusal fired (`unavailable` set), or
+					// there was no committed base under the overlay at all (`blockRev === undefined`) —
+					// this node holds a pending record PROVING the block exists and produced nothing.
+					// The second clause's ABSENCE in the other direction is equally load-bearing: a
+					// pending DELETE over a real committed base also lands here with no block, and that
+					// is an authoritative tombstone which must stay unflagged.
+					...(block === undefined && (unavailable !== undefined || blockRev === undefined)
+						? { unavailable: unavailable ?? 'unmaterializable' }
+						: {})
 				} as GetBlockResult];
 			}
 
@@ -495,6 +514,34 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		}));
 	}
 
+	/**
+	 * Commit a previously-pended action across its blocks, under the per-block commit latches.
+	 *
+	 * **Divergence vs genuine fault.** When the batch cannot be completed, the reason decides what
+	 * happens to the pending records the pend left behind. `ClusterMember.applyConsensusOperation`
+	 * makes the same split one layer up — it *tolerates* a divergence (and reconciles every
+	 * `commit.blockIds` entry from a cohort peer) but *propagates* a genuine fault for retry — so this
+	 * method must agree with it:
+	 *
+	 * - **Divergence** — this node is behind the agreed history, either because it holds no
+	 *   materializable base ({@link MissingBaseRevisionError}) or because it never received the pend
+	 *   (the `Pending action … not found` throw). Reconcile is guaranteed to follow and will advance
+	 *   every block in the batch past `request.rev`, so no pending record here can ever be promoted:
+	 *   {@link dropUnpromotablePendings} deletes them (see {@link refuseMissingBase}, which already
+	 *   accepts this tradeoff for the single refusing block).
+	 * - **Genuine fault** — any other throw out of {@link internalCommit} (a raw-storage error, …).
+	 *   `ClusterMember` propagates it and the commit is retried, and a retry can still replay the
+	 *   pendings, so they are KEPT.
+	 *
+	 * The stale/`missedCommits` early return (this node is AHEAD — it already holds a revision at or
+	 * past `request.rev`, committed under a different action) deliberately keeps pendings too, and its
+	 * cure is the losing client's `cancel`: `CoordinatorRepo.cancel` runs through consensus, so every
+	 * member drops the record, not just the coordinator. Replication cannot be the cure here — this
+	 * node is already ahead, and a later forward write carries a DIFFERENT action id, which is not
+	 * what `BlockStorage.saveForwardRevision` deletes. A client that dies between the stale result and
+	 * its `cancel` therefore still strands the record; that is pre-existing and orthogonal to the
+	 * divergence split above.
+	 */
 	async commit(request: CommitRequest, _options?: MessageOptions): Promise<CommitResult> {
 		log('commit actionId=%s rev=%d blockIds=%d', request.actionId, request.rev, request.blockIds.length);
 		const uniqueBlockIds = Array.from(new Set(request.blockIds)).sort();
@@ -620,6 +667,12 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 			// pending-present — a never-pended block cannot coexist with it in one retry. If a path
 			// ever produces that mix, emit recovered blocks' events before throwing here.
 			if (missingPends.length) {
+				// Divergence (this node is behind): `ClusterMember` treats this throw as the canonical
+				// "behind" signal and reconciles EVERY block in the batch, advancing each past
+				// `request.rev`. Nothing can promote the pendings the other blocks still hold, so drop
+				// them here — while the latches are still held — before reporting. The thrown message
+				// must stay byte-identical: `ClusterMember.isMissingPendingActionError` matches on it.
+				await this.dropUnpromotablePendings(toCommit, request.actionId);
 				throw new Error(`Pending action ${request.actionId} not found for block(s): ${missingPends.map(p => p.blockId).join(', ')}`);
 			}
 
@@ -648,6 +701,10 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 			// This loop will execute atomically for all blocks due to the acquired locks.
 			// Recovered (Crash-D3) blocks are already committed at request.rev and their pending is
 			// gone, so skip them — internalCommit would throw on the missing pending record.
+			//
+			// Set when the mid-loop failure was a divergence rather than a genuine fault — the split
+			// documented on commit() above, which decides the fate of the batch's pending records.
+			let divergentFailure = false;
 			for (const { blockId, storage } of toCommit) {
 				if (recovered.has(blockId)) {
 					continue;
@@ -666,9 +723,20 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 					// treats them as idempotent no-ops and advances the remainder. Break
 					// instead of returning so locks release and those landings emit below.
 					failure = { reason: err instanceof Error ? err.message : 'Unknown error during commit' };
+					divergentFailure = err instanceof MissingBaseRevisionError;
 					break;
 				}
 			}
+
+			// The break left every not-yet-reached block still holding its pending record. Whether
+			// that record is still usable depends ENTIRELY on why we stopped — see the table on
+			// commit() above. Runs inside the try, so the per-block latches are still held.
+			// NOTE: a non-divergence fault deliberately KEEPS the batch's pendings so a retry can
+			// replay them. If ClusterMember ever stops retrying propagated commit faults, this arm
+			// becomes dead weight and the discriminator can collapse to "always drop".
+			if (divergentFailure) {
+				await this.dropUnpromotablePendings(toCommit, request.actionId);
+			}
 		}
 		finally {
 			// Release locks in reverse order of acquisition
@@ -683,6 +751,44 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 		return failure ? { success: false, reason: failure.reason } : { success: true };
 	}
 
+	/**
+	 * Delete `actionId`'s pending record from every given block, tolerating absence.
+	 *
+	 * Called by {@link commit} when it abandons a batch **because this node has diverged from the
+	 * agreed history** — the caller has already made that determination; this helper does not
+	 * re-derive it. Once `ClusterMember` reconciles the batch, every one of these blocks sits at or
+	 * past `request.rev`, so a commit retry partitions them as already-done/stale and never revisits
+	 * their pendings; left in place they are reported as phantom conflicting actions by {@link pend}
+	 * for every later write to the block (under `policy: 'f'`, forever).
+	 *
+	 * No special-casing is needed for blocks that already landed (record promoted), that were
+	 * `recovered` (record already gone), or for the refusing block itself
+	 * ({@link refuseMissingBase} deleted its record): deleting an absent pending record is a no-op on
+	 * every backend.
+	 *
+	 * Per-block failures are logged and swallowed rather than propagated: this cleanup must never
+	 * replace the failure the caller is about to report — the pre-loop throw's message is pattern-
+	 * matched by `ClusterMember.isMissingPendingActionError`, and a swapped error would misroute
+	 * consensus. A leftover record only degrades this node's participation in that one block.
+	 */
+	private async dropUnpromotablePendings(
+		blocks: { blockId: BlockId, storage: IBlockStorage }[],
+		actionId: ActionId
+	): Promise<void> {
+		if (blocks.length === 0) {
+			return;
+		}
+		log('commit:drop-unpromotable-pendings actionId=%s blockIds=%d', actionId, blocks.length);
+		await Promise.all(blocks.map(async ({ blockId, storage }) => {
+			try {
+				await storage.deletePendingTransaction(actionId);
+			} catch (err) {
+				log('commit:drop-unpromotable-pending-failed blockId=%s actionId=%s error=%s', blockId, actionId,
+					err instanceof Error ? err.message : String(err));
+			}
+		}));
+	}
+
 	/**
 	 * Reconciles `metadata.latest` for a single block with the highest contiguous
 	 * fully-promoted revision in durable storage. Use after a crash between
@@ -830,9 +936,13 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 	 * BlockStorage reports every one of these as a bare `Error`, so they cannot be told apart here,
 	 * and treating them as divergence is the safe default: this node genuinely cannot materialize the
 	 * base right now, and the cluster's policy is to heal rather than throw out of consensus. The
-	 * price is that a transient fault ALSO drops the pending (see {@link refuseMissingBase}), so the
-	 * block converges by replication instead of by a replay the retry could have done. Narrowing this
-	 * would require typed faults out of BlockStorage; until then, prefer the tolerant reading.
+	 * price is that a transient fault ALSO drops pending records — this block's (see
+	 * {@link refuseMissingBase}) AND, because {@link commit} keys its cleanup off the same error type,
+	 * every not-yet-reached block in the same batch — so those blocks converge by replication instead
+	 * of by a replay the retry could have done. That is a wider blast radius than the per-block
+	 * refusal alone, and it is why the discriminator must NOT be loosened beyond this error type.
+	 * Narrowing this would require typed faults out of BlockStorage; until then, prefer the tolerant
+	 * reading.
 	 */
 	private async readCommitBase(
 		blockId: BlockId,
@@ -881,9 +991,10 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
  * Converts list of missing actions per block into a list of missing actions across blocks.
  *
  * NOTE: relies on each (actionId, blockId) pair appearing at most once — one revision per action
- * per block. If a block ever records two revisions under the same actionId, concatTransform's
- * last-wins merge would silently drop the earlier revision's ops for that block; group by
- * (actionId, rev) instead. See debt-concat-transform-overlapping-updates.
+ * per block. If a block ever records two revisions under the same actionId, concatTransform now
+ * concatenates both revisions' ops into one array rather than dropping the earlier one — still
+ * wrong, since ops from distinct revisions are not composable against a single base, but loud
+ * rather than silent. Group by (actionId, rev) instead if that case becomes reachable.
  */
 function perBlockActionTransformsToPerAction(missing: { blockId: BlockId; transforms: ActionTransform[]; }[]) {
 	const missingFlat = missing.flatMap(({ blockId, transforms }) =>

package/src/testing/raw-storage-conformance.ts

@@ -194,6 +194,26 @@ export function runRawStorageConformance(
 			expect(await collect(storage.listPendingTransactions(blockId))).to.deep.equal([]);
 		});
 
+		it('deletePendingTransaction on an absent entry is a tolerated no-op', async () => {
+			// Load-bearing across backends: the commit path deletes a pending record it has NOT
+			// checked for presence — `StorageRepo.dropUnpromotablePendings` over a whole batch, and
+			// `BlockStorage.saveForwardRevision` maintaining Invariant P — so a backend that threw
+			// (or rejected) on a miss would turn every ordinary commit into a logged failure.
+			const blockId = 'pend-del-absent' as BlockId;
+			await storage.deletePendingTransaction(blockId, 'never-pended' as ActionId);
+
+			// Also a no-op beside a LIVE pending for a different action: the delete must be scoped
+			// to its action id, never a per-block clear.
+			await storage.savePendingTransaction(blockId, 'a1' as ActionId, { delete: true });
+			await storage.deletePendingTransaction(blockId, 'other' as ActionId);
+			expect(await storage.getPendingTransaction(blockId, 'a1' as ActionId)).to.deep.equal({ delete: true });
+
+			// Idempotent: deleting the same entry twice is fine.
+			await storage.deletePendingTransaction(blockId, 'a1' as ActionId);
+			await storage.deletePendingTransaction(blockId, 'a1' as ActionId);
+			expect(await collect(storage.listPendingTransactions(blockId))).to.deep.equal([]);
+		});
+
 		it('listPendingTransactions tolerates awaits interleaved between yields (drain-before-yield)', async () => {
 			const blockId = 'drain-pend' as BlockId;
 			await storage.savePendingTransaction(blockId, 'a1' as ActionId, { delete: true });