@peerbit/shared-log 16.0.21 → 16.0.23

package/src/index.ts

@@ -719,6 +719,14 @@ type PersistedDeliveryPlanningRecord<T, R extends "u32" | "u64"> = Readonly<{
 	createFullPlanningSource?: () => Entry<T>;
 }>;
 
+type PersistedAppendBackfillSource<T, R extends "u32" | "u64"> = {
+	entry: Entry<T>;
+	coordinates: NumberFromType<R>[];
+	assignmentExtraLeaders: LeaderMap;
+	deliveryExtraTargets: Set<string>;
+	extrasOwnershipRevision?: number;
+};
+
 type NativeBackboneSimpleDocumentProjectionPlan = {
 	documentVariantType?: "u8" | "string";
 	documentVariantValue?: string;
@@ -1744,6 +1752,71 @@ export type DeliveryOptions = {
 	signal?: AbortSignal;
 };
 
+export type PersistedReceiptPeerReadinessPendingReason =
+	| "closed"
+	| "no-current-session"
+	| "session-opening"
+	| "capability-pending"
+	| "replication-state-pending"
+	| "replication-confirmation-pending"
+	| "not-replicating"
+	| "not-entry-leader"
+	| "ownership-changing";
+
+export type PersistedReceiptPeerReadinessUnsupportedReason =
+	| "persisted-receipts-unsupported"
+	| "replication-confirmation-unsupported";
+
+/**
+ * Detached view of one public key's current persisted-receipt generation.
+ * `generation` is opaque: callers may compare it for equality, but must not
+ * interpret its contents or use it as a future-session capability. Equal
+ * generations mean the connection/receive/capability binding is unchanged;
+ * leadership and outbound confirmation can still change within a generation.
+ */
+export type PersistedReceiptPeerReadiness =
+	| Readonly<{
+			status: "ready";
+			generation: string;
+	  }>
+	| Readonly<{
+			status: "pending";
+			reason: PersistedReceiptPeerReadinessPendingReason;
+			generation?: string;
+	  }>
+	| Readonly<{
+			status: "unsupported";
+			reason: PersistedReceiptPeerReadinessUnsupportedReason;
+			generation: string;
+	  }>;
+
+export type PersistedReceiptPeerReady = Extract<
+	PersistedReceiptPeerReadiness,
+	{ status: "ready" }
+>;
+
+export type PersistedReceiptPeerReadinessOptions<
+	T,
+	R extends "u32" | "u64",
+> = Readonly<{
+	/** Require this peer to be a freshly planned leader for every entry. */
+	entries?: readonly (ShallowOrFullEntry<T> | EntryReplicated<R>)[];
+	/**
+	 * Total leader-plan replica degree used for `entries`; defaults to this log's
+	 * configured minimum. This is not the persisted delivery `minAcks` count.
+	 */
+	replicas?: number;
+}>;
+
+export type WaitForPersistedReceiptPeerReadinessOptions<
+	T,
+	R extends "u32" | "u64",
+> = PersistedReceiptPeerReadinessOptions<T, R> &
+	Readonly<{
+		timeout?: number;
+		signal?: AbortSignal;
+	}>;
+
 type PersistedDeliveryOptions = Readonly<{
 	reliability: "persisted";
 	minAcks: number;
@@ -1785,6 +1858,7 @@ const PERSISTED_RECEIPT_RETRY_MS = 50;
 const MAX_PERSISTED_RECEIPT_ATTEMPT_MS = 2_000;
 const MAX_PERSISTED_RECEIPT_REQUESTS_GLOBAL = 8;
 const MAX_PERSISTED_RECEIPT_REQUESTS_PER_PEER = 2;
+const MAX_PERSISTED_RECEIPT_READINESS_WAITERS = 1_024;
 const PERSISTED_RECEIPT_INGRESS_PEER_REQUEST_CAPACITY = 16;
 const PERSISTED_RECEIPT_INGRESS_PEER_HASH_CAPACITY = 8_192;
 const PERSISTED_RECEIPT_INGRESS_PEER_REQUESTS_PER_SECOND = 8;
@@ -2159,6 +2233,10 @@ export type ReplicatorLeaveEvent = { publicKey: PublicSignKey };
 export type ReplicationChangeEvent = { publicKey: PublicSignKey };
 export type ReplicatorMatureEvent = { publicKey: PublicSignKey };
 export type ReplicationStatusEvent = ReplicationStatus;
+/** `peerHash` is the result of `PublicSignKey.hashcode()`. */
+export type PersistedReceiptPeerReadinessEvent = Readonly<{
+	peerHash: string;
+}>;
 
 class ReplicationStatusSnapshotChangedError extends Error {
 	constructor() {
@@ -2181,6 +2259,12 @@ export interface SharedLogEvents extends ProgramEvents {
 	"replication:change": CustomEvent<ReplicationChangeEvent>;
 	"replicator:mature": CustomEvent<ReplicatorMatureEvent>;
 	"replication:status": CustomEvent<ReplicationStatusEvent>;
+	/**
+	 * Non-exhaustive wake hint that a peer may now produce a new readiness
+	 * snapshot. Consumers must re-read the snapshot; this event is deliberately
+	 * not a durable transition log and a `ready` result remains advisory.
+	 */
+	"persisted-receipt:readiness": CustomEvent<PersistedReceiptPeerReadinessEvent>;
 }
 
 export type SharedLogRuntimeSnapshot = Readonly<{
@@ -3734,6 +3818,23 @@ export class SharedLog<
 	// parallel map so existing capability-number consumers remain unchanged.
 	private _peerSyncCapabilitySessions!: Map<string, bigint>;
 	private _peerSyncCapabilityTimestamps!: Map<string, bigint>;
+	// design-note: these fields cache a stable, public diagnostics token for the
+	// composite of PeerSession identity, receive epoch, and signed capability
+	// session. They are not consulted to admit or fence asynchronous work. A
+	// separate opaque token is necessary because exposing any of those internal
+	// identities would leak protocol/session values, while PeerSession alone does
+	// not change when receive or capability state is replaced.
+	private _persistedReceiptReadinessGenerations!: WeakMap<
+		PeerSession,
+		{
+			receiveEpoch: object | null;
+			capabilitySession?: bigint;
+			generation: string;
+		}
+	>;
+	private _persistedReceiptReadinessGenerationPrefix!: string;
+	private _persistedReceiptReadinessGenerationCounter!: number;
+	private _persistedReceiptReadinessWaiters!: Set<object>;
 	private _persistedReceiptStorage?: PersistedReceiptStorage;
 	private _persistedReceiptRequestsInFlight!: Map<string, number>;
 	private _persistedReceiptRequestsInFlightTotal!: number;
@@ -4091,6 +4192,12 @@ export class SharedLog<
 		this._peerSyncCapabilities = new Map();
 		this._peerSyncCapabilitySessions = new Map();
 		this._peerSyncCapabilityTimestamps = new Map();
+		this._persistedReceiptReadinessGenerations = new WeakMap();
+		this._persistedReceiptReadinessGenerationPrefix = toHexString(
+			randomBytes(8),
+		);
+		this._persistedReceiptReadinessGenerationCounter = 0;
+		this._persistedReceiptReadinessWaiters = new Set();
 		this._persistedReceiptStorage = undefined;
 		this._persistedReceiptRequestsInFlight = new Map();
 		this._persistedReceiptRequestsInFlightTotal = 0;
@@ -5053,15 +5160,23 @@ export class SharedLog<
 				) {
 					return false;
 				}
+				const nextCapabilities = previous.capabilities | capabilities;
+				const nextTimestamp =
+					previous.timestamp === undefined || timestamp > previous.timestamp
+						? timestamp
+						: previous.timestamp;
 				this._openingSyncCapabilitiesByPeer.set(peerHash, {
 					epoch: openingSession,
-					capabilities: previous.capabilities | capabilities,
+					capabilities: nextCapabilities,
 					transportSession,
-					timestamp:
-						previous.timestamp === undefined || timestamp > previous.timestamp
-							? timestamp
-							: previous.timestamp,
+					timestamp: nextTimestamp,
 				});
+				if (
+					previous.capabilities !== nextCapabilities ||
+					previous.timestamp === undefined
+				) {
+					this.dispatchPersistedReceiptReadinessChange(peerHash);
+				}
 				return true;
 			}
 			this._openingSyncCapabilitiesByPeer.set(peerHash, {
@@ -5070,17 +5185,25 @@ export class SharedLog<
 				transportSession,
 				timestamp,
 			});
+			this.dispatchPersistedReceiptReadinessChange(peerHash);
 			return true;
 		}
 
 		if (transportSession === undefined || timestamp === undefined) {
 			// Test/in-process synthetic contexts predate signed envelope captures.
 			// They may exercise capability-number behavior, but can never authorize V2.
+			const readinessChanged =
+				this._peerSyncCapabilities.get(peerHash) !== capabilities ||
+				this._peerSyncCapabilitySessions.has(peerHash) ||
+				this._peerSyncCapabilityTimestamps.has(peerHash);
 			this._peerSyncCapabilities.set(peerHash, capabilities);
 			this._peerSyncCapabilitySessions.delete(peerHash);
 			this._peerSyncCapabilityTimestamps.delete(peerHash);
 			this._v2Send.advancePeerCapability(peerHash);
 			this._v2Receive.revokePeerCapability(peerHash);
+			if (readinessChanged) {
+				this.dispatchPersistedReceiptReadinessChange(peerHash);
+			}
 			return true;
 		}
 
@@ -5105,6 +5228,10 @@ export class SharedLog<
 			!sameTransportSession ||
 			(previousCapabilities & senderGrantCapabilityMask) !==
 				(nextCapabilities & senderGrantCapabilityMask);
+		const readinessChanged =
+			!sameTransportSession ||
+			previousTimestamp === undefined ||
+			previousCapabilities !== nextCapabilities;
 		this._peerSyncCapabilities.set(peerHash, nextCapabilities);
 		this._peerSyncCapabilitySessions.set(peerHash, transportSession);
 		this._peerSyncCapabilityTimestamps.set(
@@ -5121,6 +5248,9 @@ export class SharedLog<
 			// recovery re-solicitation may restart from the base interval.
 			this.resetReplicationInfoV2RecoveryEscalation(peerHash);
 		}
+		if (readinessChanged) {
+			this.dispatchPersistedReceiptReadinessChange(peerHash);
+		}
 		return true;
 	}
 
@@ -5470,20 +5600,173 @@ export class SharedLog<
 		return this.sendFusedRawExchangeHeadsPlan(plan, to, options);
 	}
 
+	private persistedReceiptReadinessGeneration(
+		peerSession: PeerSession,
+		receiveEpoch: object | null,
+		capabilitySession: bigint | undefined,
+	): string {
+		const current = this._persistedReceiptReadinessGenerations.get(peerSession);
+		if (
+			current?.receiveEpoch === receiveEpoch &&
+			current.capabilitySession === capabilitySession
+		) {
+			return current.generation;
+		}
+		const generation = `${this._persistedReceiptReadinessGenerationPrefix}:${(++this
+			._persistedReceiptReadinessGenerationCounter).toString(36)}`;
+		this._persistedReceiptReadinessGenerations.set(peerSession, {
+			receiveEpoch,
+			capabilitySession,
+			generation,
+		});
+		return generation;
+	}
+
+	private pendingPersistedReceiptReadiness(
+		reason: PersistedReceiptPeerReadinessPendingReason,
+		generation?: string,
+	): PersistedReceiptPeerReadiness {
+		return Object.freeze({
+			status: "pending" as const,
+			reason,
+			...(generation === undefined ? {} : { generation }),
+		});
+	}
+
+	private unsupportedPersistedReceiptReadiness(
+		reason: PersistedReceiptPeerReadinessUnsupportedReason,
+		generation: string,
+	): PersistedReceiptPeerReadiness {
+		return Object.freeze({
+			status: "unsupported" as const,
+			reason,
+			generation,
+		});
+	}
+
+	private dispatchPersistedReceiptReadinessChange(peerHash: string): void {
+		this.events.dispatchEvent(
+			new CustomEvent<PersistedReceiptPeerReadinessEvent>(
+				"persisted-receipt:readiness",
+				{ detail: Object.freeze({ peerHash }) },
+			),
+		);
+	}
+
+	private persistedReceiptReadinessCandidate(peerHash: string):
+		| {
+				capabilitySession: bigint;
+				peerSession: PeerSession;
+				receiveEpoch: object | null;
+				generation: string;
+		  }
+		| PersistedReceiptPeerReadiness {
+		if (this.closed) {
+			return this.pendingPersistedReceiptReadiness("closed");
+		}
+		const peerSession = this._peerSessions.current(peerHash);
+		if (!peerSession) {
+			return this.pendingPersistedReceiptReadiness("no-current-session");
+		}
+		const receiveEpoch = this._peerSessions.receiveEpoch(peerHash);
+		const capabilitySession = this._peerSyncCapabilitySessions.get(peerHash);
+		const generation = this.persistedReceiptReadinessGeneration(
+			peerSession,
+			receiveEpoch,
+			capabilitySession,
+		);
+		if (
+			peerSession.phase !== "open" ||
+			!peerSession.isActive() ||
+			this._peerSessions.isReplicationInfoBlocked(peerHash) ||
+			!this._peerSessions.isReceiveCleanupGateOpen(peerHash)
+		) {
+			return this.pendingPersistedReceiptReadiness(
+				"session-opening",
+				generation,
+			);
+		}
+		if (
+			capabilitySession === undefined ||
+			!this._peerSyncCapabilityTimestamps.has(peerHash)
+		) {
+			return this.pendingPersistedReceiptReadiness(
+				"capability-pending",
+				generation,
+			);
+		}
+		const capabilities = this._peerSyncCapabilities.get(peerHash) ?? 0;
+		if ((capabilities & SYNC_CAPABILITY_PERSISTED_ENTRY_RECEIPTS) === 0) {
+			return this.unsupportedPersistedReceiptReadiness(
+				"persisted-receipts-unsupported",
+				generation,
+			);
+		}
+		if ((capabilities & SYNC_CAPABILITY_REPLICATION_INFO_V2_CONFIRM) === 0) {
+			return this.unsupportedPersistedReceiptReadiness(
+				"replication-confirmation-unsupported",
+				generation,
+			);
+		}
+		if (
+			!this._v2Receive.isCurrentActive({
+				peerHash,
+				peerSession,
+				receiveEpoch,
+				senderTransportSession: capabilitySession,
+			})
+		) {
+			return this.pendingPersistedReceiptReadiness(
+				"replication-state-pending",
+				generation,
+			);
+		}
+		if (!this.uniqueReplicators.has(peerHash)) {
+			return this.pendingPersistedReceiptReadiness(
+				"not-replicating",
+				generation,
+			);
+		}
+		return {
+			capabilitySession,
+			peerSession,
+			receiveEpoch,
+			generation,
+		};
+	}
+
 	private persistedReceiptPeerSession(
 		peerHash: string,
 	): { capabilitySession: bigint; peerSession: PeerSession } | undefined {
+		// This is a hot receipt/transfer-loop predicate. Keep it allocation-light,
+		// while mirroring every exact-session gate in
+		// persistedReceiptReadinessCandidate (which additionally creates public
+		// reason/generation snapshots).
 		const capabilitySession = this._peerSyncCapabilitySessions.get(peerHash);
 		const peerSession = this._peerSessions.current(peerHash);
+		const receiveEpoch = this._peerSessions.receiveEpoch(peerHash);
+		const requiredCapabilities =
+			SYNC_CAPABILITY_PERSISTED_ENTRY_RECEIPTS |
+			SYNC_CAPABILITY_REPLICATION_INFO_V2_CONFIRM;
 		if (
+			this.closed ||
 			capabilitySession == null ||
 			!peerSession ||
 			peerSession.phase !== "open" ||
-			!this._peerSessions.isCurrent(peerHash, peerSession) ||
+			!peerSession.isActive() ||
+			this._peerSessions.isReplicationInfoBlocked(peerHash) ||
+			!this._peerSessions.isReceiveCleanupGateOpen(peerHash) ||
+			!this.uniqueReplicators.has(peerHash) ||
 			!this._peerSyncCapabilityTimestamps.has(peerHash) ||
 			((this._peerSyncCapabilities.get(peerHash) ?? 0) &
-				SYNC_CAPABILITY_PERSISTED_ENTRY_RECEIPTS) ===
-				0
+				requiredCapabilities) !==
+				requiredCapabilities ||
+			!this._v2Receive.isCurrentActive({
+				peerHash,
+				peerSession,
+				receiveEpoch,
+				senderTransportSession: capabilitySession,
+			})
 		) {
 			return undefined;
 		}
@@ -5754,6 +6037,10 @@ export class SharedLog<
 		ownershipLifecycleController = this.captureReplicationOwnershipLifecycle(),
 		persistedDeadline?: PersistedDeliveryDeadline,
 		transferOnFirstRound = false,
+		onFreshLeaderPlan?: (
+			leadersByEntry: readonly LeaderMap[],
+			ownershipRevision: number,
+		) => void,
 	): Promise<void> {
 		const minAcks = Math.floor(delivery.minAcks!);
 		const records = new Map(
@@ -5844,6 +6131,8 @@ export class SharedLog<
 					ownershipLifecycleController,
 				);
 				if (!isRoundOwnershipCurrent()) continue;
+				onFreshLeaderPlan?.(leadersByEntry, ownershipRevision);
+				if (!isRoundOwnershipCurrent()) continue;
 				const selfHash = this.node.identity.publicKey.hashcode();
 				if (needsInitialLeaderCheck) {
 					needsInitialLeaderCheck = false;
@@ -5946,6 +6235,32 @@ export class SharedLog<
 									current.peerSession === captured.peerSession
 								);
 							};
+							try {
+								await this._v2Send.confirmLatestForPeer(
+									{
+										peerHash: peer,
+										peerSession: captured.peerSession,
+										receiverTransportSession: captured.capabilitySession,
+									},
+									{
+										timeout: getAttemptTimeout(),
+										signal: roundSignal,
+									},
+								);
+							} catch {
+								// The exact receiver generation did not prove that it applied
+								// our latest role state. Replan instead of transferring to a
+								// peer that can still make a stale admission decision.
+								if (transferAllOnRound && isPeerRoundCurrent()) {
+									const state = ensureRepairState();
+									for (const hash of hashes) state.hashes.add(hash);
+								}
+								return;
+							}
+							if (!isPeerRoundCurrent()) {
+								purgePeerDeliveryState(peer);
+								return;
+							}
 							const repairs = repairsByPeer.get(peer)?.hashes;
 							const transferHashes = transferAllOnRound
 								? hashes
@@ -6122,6 +6437,9 @@ export class SharedLog<
 							replicas,
 							ownershipLifecycleController,
 						);
+						if (!isRoundOwnershipCurrent()) return false;
+						onFreshLeaderPlan?.(validatedLeaders, ownershipRevision);
+						if (!isRoundOwnershipCurrent()) return false;
 						for (let index = 0; index < entryArray.length; index++) {
 							if (signal.aborted || !isRoundOwnershipCurrent()) {
 								if (signal.aborted) {
@@ -6205,6 +6523,75 @@ export class SharedLog<
 		}
 	}
 
+	private async collectDeferredAppendBackfillExtras(
+		entry: Entry<T>,
+		replicas: number,
+		baseLeaders: LeaderMap,
+		nativeDeliveryPlan: AppendDeliveryPlan | undefined,
+		ownershipLifecycleController: AbortController,
+	): Promise<
+		Omit<PersistedAppendBackfillSource<T, R>, "entry" | "coordinates">
+	> {
+		const ownershipRevision =
+			this._instanceLifecycle?._receiveOwnershipRevision ?? 0;
+		const ownershipWasStable =
+			this.isReceiveOwnershipSnapshotStable(ownershipRevision);
+		const assignmentExtraLeaders: LeaderMap = new Map();
+		const deliveryExtraTargets = new Set<string>();
+		if (nativeDeliveryPlan) {
+			for (const peer of nativeDeliveryPlan.repairTargets) {
+				// The sampled entry leaders are replaced by settlement's fresh plan.
+				// Retain only native repair additions that were outside that base map.
+				if (!baseLeaders.has(peer)) deliveryExtraTargets.add(peer);
+			}
+		} else {
+			const selfHash = this.node.identity.publicKey.hashcode();
+			const fullReplicaDeliveryCandidates =
+				await this.getNativeFullReplicaDeliveryCandidates(replicas, selfHash);
+			this.throwIfReplicationOwnershipLifecycleInactive(
+				ownershipLifecycleController,
+			);
+			if (replicas >= Math.max(1, fullReplicaDeliveryCandidates.size)) {
+				for (const peer of fullReplicaDeliveryCandidates) {
+					if (!baseLeaders.has(peer)) {
+						assignmentExtraLeaders.set(peer, { intersecting: true });
+					}
+				}
+			}
+		}
+
+		const referenceLeaders: LeaderMap = new Map();
+		for await (const message of createExchangeHeadsMessages(this.log, [
+			entry,
+		])) {
+			this.throwIfReplicationOwnershipLifecycleInactive(
+				ownershipLifecycleController,
+			);
+			await this._mergeLeadersFromGidReferences(
+				message,
+				replicas,
+				referenceLeaders,
+				ownershipLifecycleController,
+				{ freshLeaderPlan: true },
+			);
+		}
+		this.throwIfReplicationOwnershipLifecycleInactive(
+			ownershipLifecycleController,
+		);
+		for (const peer of referenceLeaders.keys()) {
+			deliveryExtraTargets.add(peer);
+		}
+		return {
+			assignmentExtraLeaders,
+			deliveryExtraTargets,
+			extrasOwnershipRevision:
+				ownershipWasStable &&
+				this.isReceiveOwnershipSnapshotStable(ownershipRevision)
+					? ownershipRevision
+					: undefined,
+		};
+	}
+
 	private async _appendDeliverToReplicators(
 		entry: Entry<T>,
 		coordinates: NumberFromType<R>[],
@@ -6299,7 +6686,11 @@ export class SharedLog<
 				if (!delivery) {
 					for (const peer of nativeDeliveryPlan.repairTargets) {
 						throwIfInactive();
-						this.queueAppendBackfill(peer, entryReplicatedForRepair);
+						this.queueAppendBackfill(
+							peer,
+							entryReplicatedForRepair,
+							ownershipLifecycleController,
+						);
 					}
 					if (nativeDeliveryPlan.defaultSendSilent) {
 						const rawTargets = this.canUseLiveRawGossip(
@@ -6372,7 +6763,11 @@ export class SharedLog<
 				}
 				for (const peer of nativeDeliveryPlan.repairTargets) {
 					throwIfInactive();
-					this.queueAppendBackfill(peer, entryReplicatedForRepair);
+					this.queueAppendBackfill(
+						peer,
+						entryReplicatedForRepair,
+						ownershipLifecycleController,
+					);
 				}
 				continue;
 			}
@@ -6427,7 +6822,11 @@ export class SharedLog<
 					// delivery acks, we still need a targeted backfill source of truth for the
 					// authoritative recipients or one entry can get stuck at 2/3 replicas
 					// forever. Best-effort fallback subscribers are not repair-worthy.
-					this.queueAppendBackfill(peer, entryReplicatedForRepair);
+					this.queueAppendBackfill(
+						peer,
+						entryReplicatedForRepair,
+						ownershipLifecycleController,
+					);
 				}
 				if (isLeader) {
 					const rawTargets = this.canUseLiveRawGossip(set, selfHash);
@@ -6536,7 +6935,11 @@ export class SharedLog<
 				// Direct append delivery is intentionally optimistic. Queue one delayed,
 				// batched maybe-sync pass for the intended recipients so stable 3-peer
 				// append workloads do not depend on perfect first-try delivery ordering.
-				this.queueAppendBackfill(peer, entryReplicatedForRepair);
+				this.queueAppendBackfill(
+					peer,
+					entryReplicatedForRepair,
+					ownershipLifecycleController,
+				);
 			}
 		}
 
@@ -6551,6 +6954,7 @@ export class SharedLog<
 		minReplicasValue: number,
 		leaders: LeaderMap,
 		ownershipLifecycleController = this.captureReplicationOwnershipLifecycle(),
+		options?: { freshLeaderPlan?: boolean },
 	) {
 		const throwIfInactive = () =>
 			this.throwIfReplicationOwnershipLifecycleInactive(
@@ -6576,13 +6980,13 @@ export class SharedLog<
 					found = await this.findLeadersFromEntry(
 						gidEntry,
 						minReplicasValue,
-						undefined,
+						options?.freshLeaderPlan ? { freshLeaderPlan: true } : undefined,
 						ownershipLifecycleController,
 					);
 				} else {
 					found = await this._findLeaders(
 						coordinates,
-						undefined,
+						options?.freshLeaderPlan ? { freshLeaderPlan: true } : undefined,
 						ownershipLifecycleController,
 					);
 				}
@@ -6891,8 +7295,13 @@ export class SharedLog<
 	private canCacheLeaderSelectionContext(options?: {
 		roleAge?: number;
 		candidates?: Iterable<string>;
+		freshLeaderPlan?: boolean;
 	}) {
-		return options?.roleAge == null && options?.candidates == null;
+		return (
+			options?.roleAge == null &&
+			options?.candidates == null &&
+			options?.freshLeaderPlan !== true
+		);
 	}
 
 	private cloneLeaderSelectionContext(
@@ -6910,6 +7319,7 @@ export class SharedLog<
 	private getCachedLeaderSelectionContext(options?: {
 		roleAge?: number;
 		candidates?: Iterable<string>;
+		freshLeaderPlan?: boolean;
 	}): LeaderSelectionContext | undefined {
 		if (!this.canCacheLeaderSelectionContext(options)) {
 			return;
@@ -6926,6 +7336,7 @@ export class SharedLog<
 			| {
 					roleAge?: number;
 					candidates?: Iterable<string>;
+					freshLeaderPlan?: boolean;
 			  }
 			| undefined,
 		context: LeaderSelectionContext,
@@ -8035,8 +8446,11 @@ export class SharedLog<
 			? checkedPruneCoordinator.fencePeerRemoval(keyHash)
 			: undefined;
 		const blockPeerReceiveAdmission = () => {
-			releaseReceiveCleanupGate ??=
-				this._peerSessions.acquireReceiveCleanupGate(keyHash);
+			if (!releaseReceiveCleanupGate) {
+				releaseReceiveCleanupGate =
+					this._peerSessions.acquireReceiveCleanupGate(keyHash);
+				this.dispatchPersistedReceiptReadinessChange(keyHash);
+			}
 		};
 		if (!isMe && !isSpeculativePeerRemoval) {
 			// Revoke this peer's receipts synchronously, before this removal can
@@ -8277,7 +8691,10 @@ export class SharedLog<
 			});
 			removalCallCompleted = true;
 		} finally {
-			releaseReceiveCleanupGate?.();
+			if (releaseReceiveCleanupGate) {
+				releaseReceiveCleanupGate();
+				this.dispatchPersistedReceiptReadinessChange(keyHash);
+			}
 			if (
 				replicationInfoRecoveryEpochAdvanced &&
 				ownsReplicationOwnershipLifecycle() &&
@@ -10191,10 +10608,7 @@ export class SharedLog<
 		});
 	}
 
-	private flushAppendBackfill(
-		repairLifecycleController: AbortController = this._instanceLifecycle
-			?.ownershipLifecycleController as AbortController,
-	) {
+	private flushAppendBackfill(repairLifecycleController: AbortController) {
 		if (
 			!this.isRepairLifecycleActive(repairLifecycleController) ||
 			this._appendBackfillPendingByTarget.size === 0
@@ -10215,9 +10629,11 @@ export class SharedLog<
 		}
 	}
 
-	private queueAppendBackfill(target: string, entry: EntryReplicated<R>) {
-		const repairLifecycleController = this._instanceLifecycle
-			?.ownershipLifecycleController as AbortController;
+	private queueAppendBackfill(
+		target: string,
+		entry: EntryReplicated<R>,
+		repairLifecycleController: AbortController,
+	) {
 		if (!this.isRepairLifecycleActive(repairLifecycleController)) {
 			return;
 		}
@@ -10249,6 +10665,62 @@ export class SharedLog<
 		this._appendBackfillTimer = timer;
 	}
 
+	private queuePersistedAppendBackfill(
+		source: PersistedAppendBackfillSource<T, R>,
+		leaders: LeaderMap,
+		replicas: number,
+		repairLifecycleController: AbortController,
+		ownershipRevision: number,
+	): void {
+		try {
+			if (
+				!this.isRepairLifecycleActive(repairLifecycleController) ||
+				!this.isReceiveOwnershipSnapshotStable(ownershipRevision)
+			) {
+				return;
+			}
+			const assignmentLeaders = new Map(leaders);
+			const deliveryTargets = new Set(leaders.keys());
+			if (source.extrasOwnershipRevision === ownershipRevision) {
+				for (const [peer, sample] of source.assignmentExtraLeaders) {
+					assignmentLeaders.set(peer, sample);
+				}
+				for (const peer of source.deliveryExtraTargets) {
+					deliveryTargets.add(peer);
+				}
+			}
+			const repairEntry = this.createEntryReplicatedForRepair({
+				entry: source.entry,
+				coordinates: source.coordinates,
+				leaders: assignmentLeaders,
+				replicas,
+			});
+			const selfHash = this.node.identity.publicKey.hashcode();
+			for (const peer of assignmentLeaders.keys()) {
+				deliveryTargets.add(peer);
+			}
+			for (const peer of deliveryTargets) {
+				if (peer === selfHash) continue;
+				if (!this.isReceiveOwnershipSnapshotStable(ownershipRevision)) return;
+				try {
+					this.queueAppendBackfill(
+						peer,
+						repairEntry,
+						repairLifecycleController,
+					);
+				} catch (error) {
+					if (this.isRepairLifecycleActive(repairLifecycleController)) {
+						logger.error(error);
+					}
+				}
+			}
+		} catch (error) {
+			if (this.isRepairLifecycleActive(repairLifecycleController)) {
+				logger.error(error);
+			}
+		}
+	}
+
 	private dispatchMaybeMissingEntries(
 		target: string,
 		entries: ReadonlyMap<string, RepairDispatchEntry<R>>,
@@ -11894,6 +12366,12 @@ export class SharedLog<
 		let persistedPlanningRecord:
 			| PersistedDeliveryPlanningRecord<T, R>
 			| undefined;
+		let persistedBackfillSource:
+			| PersistedAppendBackfillSource<T, R>
+			| undefined;
+		let persistedBackfillLeaders: LeaderMap | undefined;
+		let persistedBackfillOwnershipRevision: number | undefined;
+		let localAppendProcessed = false;
 		if (persistedDelivery) {
 			(appendOptions as TrustedLogAppendOptions<T>).__peerbitOnLocalCommit = (
 				hashes,
@@ -11947,8 +12425,17 @@ export class SharedLog<
 			await this.processLocalAppend(processingEntry, result.removed, options, {
 				minReplicasValue,
 				appendFacts: persistedAppendCommit,
+				// Persisted settlement must confirm each exact receiver generation before
+				// using its transfer as receipt evidence. Keep the optimistic append path
+				// out of that ordering decision.
+				captureDeferredBackfillSource: persistedDelivery
+					? (source) => {
+							persistedBackfillSource = source;
+						}
+					: undefined,
 				ownershipLifecycleController,
 			});
+			localAppendProcessed = true;
 			throwIfDeliveryAborted();
 			if (persistedDelivery && persistedDeadline) {
 				await this.settlePersistedDelivery(
@@ -11957,6 +12444,12 @@ export class SharedLog<
 					persistedDelivery,
 					ownershipLifecycleController,
 					persistedDeadline,
+					true,
+					(leadersByEntry, ownershipRevision) => {
+						const leaders = leadersByEntry[0];
+						persistedBackfillLeaders = leaders ? new Map(leaders) : undefined;
+						persistedBackfillOwnershipRevision = ownershipRevision;
+					},
 				);
 			}
 			this.throwIfReplicationOwnershipLifecycleInactive(
@@ -11969,6 +12462,27 @@ export class SharedLog<
 			}
 			throw error;
 		} finally {
+			if (
+				persistedBackfillSource &&
+				persistedBackfillLeaders &&
+				persistedBackfillOwnershipRevision !== undefined &&
+				localAppendProcessed
+			) {
+				// A persisted quorum changes the return condition, not the configured
+				// replication degree. Reuse settlement's latest fresh leader plan rather
+				// than carrying an optimistic target or extending the receipt deadline
+				// with another plan. Fence best-effort repair to this append's ownership
+				// generation, and never let it mask the primary result.
+				try {
+					this.queuePersistedAppendBackfill(
+						persistedBackfillSource,
+						persistedBackfillLeaders,
+						minReplicasValue,
+						ownershipLifecycleController,
+						persistedBackfillOwnershipRevision,
+					);
+				} catch {}
+			}
 			persistedDeadline?.dispose();
 		}
 	}
@@ -16080,6 +16594,9 @@ export class SharedLog<
 			minReplicasValue: number;
 			appendFacts?: PreparedAppendFacts;
 			deferHeadCoordinatePersistence?: boolean;
+			captureDeferredBackfillSource?: (
+				source: PersistedAppendBackfillSource<T, R>,
+			) => void;
 			nativeAppendPlan?: NativeAppendEntryPlan<R>;
 			extraCoordinateDeleteHashes?: string[];
 			ownershipLifecycleController?: AbortController;
@@ -16223,7 +16740,41 @@ export class SharedLog<
 			ownershipLifecycleController,
 		);
 
-		if (options?.target !== "none") {
+		if (properties.captureDeferredBackfillSource) {
+			let extras: Omit<
+				PersistedAppendBackfillSource<T, R>,
+				"entry" | "coordinates"
+			> = {
+				assignmentExtraLeaders: new Map(),
+				deliveryExtraTargets: new Set(),
+			};
+			try {
+				extras = await this.collectDeferredAppendBackfillExtras(
+					entry,
+					properties.minReplicasValue,
+					leaders!,
+					nativeDeliveryPlan,
+					ownershipLifecycleController,
+				);
+			} catch (error) {
+				if (this.isRepairLifecycleActive(ownershipLifecycleController)) {
+					logger.error(error);
+				}
+			}
+			this.throwIfReplicationOwnershipLifecycleInactive(
+				ownershipLifecycleController,
+			);
+			properties.captureDeferredBackfillSource({
+				entry,
+				coordinates: [...coordinates],
+				...extras,
+			});
+		}
+
+		if (
+			options?.target !== "none" &&
+			!properties.captureDeferredBackfillSource
+		) {
 			const hasDelivery = !(deliveryArg === undefined || deliveryArg === false);
 
 			if (target === "all" && hasDelivery) {
@@ -16624,6 +17175,12 @@ export class SharedLog<
 		this._peerSyncCapabilities = new Map();
 		this._peerSyncCapabilitySessions = new Map();
 		this._peerSyncCapabilityTimestamps = new Map();
+		this._persistedReceiptReadinessGenerations = new WeakMap();
+		this._persistedReceiptReadinessGenerationPrefix = toHexString(
+			randomBytes(8),
+		);
+		this._persistedReceiptReadinessGenerationCounter = 0;
+		this._persistedReceiptReadinessWaiters = new Set();
 		this._persistedReceiptStorage = undefined;
 		this._persistedReceiptRequestsInFlight = new Map();
 		this._persistedReceiptRequestsInFlightTotal = 0;
@@ -18300,6 +18857,7 @@ export class SharedLog<
 			ownershipLifecycleController,
 			this._checkedPrune,
 		);
+		this.dispatchPersistedReceiptReadinessChange(peerHash);
 	}
 
 	private cleanupPendingIHavePeer(peerHash: string) {
@@ -18324,6 +18882,7 @@ export class SharedLog<
 				receiveEpoch,
 			});
 		}
+		this.dispatchPersistedReceiptReadinessChange(peerHash);
 	}
 
 	private async resolveCandidatePeersForHash(
@@ -19765,6 +20324,7 @@ export class SharedLog<
 			this._peerSyncCapabilities?.clear();
 			this._peerSyncCapabilitySessions?.clear();
 			this._peerSyncCapabilityTimestamps?.clear();
+			this._persistedReceiptReadinessGenerations = new WeakMap();
 			this._persistedReceiptStorage = undefined;
 			this._persistedReceiptRequestsInFlight?.clear();
 			this._persistedReceiptRequestsInFlightTotal = 0;
@@ -22321,10 +22881,14 @@ export class SharedLog<
 					}
 					return;
 				} else if (msg instanceof ReplicationInfoV2AppliedMessage) {
-					this._v2Send.acceptApplied(msg, {
-						from: context.from,
-						receiverTransportSession: context.message.header.session,
-					});
+					if (
+						this._v2Send.acceptApplied(msg, {
+							from: context.from,
+							receiverTransportSession: context.message.header.session,
+						})
+					) {
+						this.dispatchPersistedReceiptReadinessChange(receiveFromHash);
+					}
 					return;
 				} else if (isReplicationInfoV2Message(msg)) {
 					await this.handleReplicationInfoV2Announcement(
@@ -22498,6 +23062,12 @@ export class SharedLog<
 			this._peerSyncCapabilitySessions.get(lane.fromHash) ===
 				context.message.header.session &&
 			this._peerSyncCapabilityTimestamps.has(lane.fromHash) &&
+			this._v2Receive.isCurrentActive({
+				peerHash: lane.fromHash,
+				peerSession: session,
+				receiveEpoch: lane.receiveEpoch,
+				senderTransportSession: context.message.header.session,
+			}) &&
 			this.isRepairLifecycleActive(lane.ownershipLifecycleController)
 		);
 	}
@@ -23134,6 +23704,7 @@ export class SharedLog<
 				// A committed V2 announcement is applied progress: the peer answers,
 				// so recovery re-solicitation may restart from the base interval.
 				this.resetReplicationInfoV2RecoveryEscalation(fromHash);
+				this.dispatchPersistedReceiptReadinessChange(fromHash);
 			});
 		} finally {
 			this._v2Receive.release(admission);
@@ -23488,6 +24059,465 @@ export class SharedLog<
 		throwIfInactive();
 	}
 
+	private nudgePersistedReceiptPeerReadiness(publicKey: PublicSignKey): void {
+		if (this.closed) return;
+		const peerHash = publicKey.hashcode();
+		const peerSession = this._peerSessions.current(peerHash);
+		if (
+			!peerSession ||
+			peerSession.phase === "departing" ||
+			(peerSession.phase === "opening" &&
+				!peerSession.openingBarrierActive)
+		) {
+			// A barrier rejection deliberately leaves the current session in its
+			// fail-closed opening phase after the barrier window has settled. Ask the
+			// authenticated peer for a fresh subscriber snapshot so the replacement
+			// session can recover; never rotate a barrier that is still in flight.
+			this.requestSubscriberSnapshotForCapability(publicKey);
+			return;
+		}
+		if (peerSession.phase !== "open" || !peerSession.isActive()) {
+			return;
+		}
+		const receiveEpoch = this._peerSessions.receiveEpoch(peerHash);
+		this.promoteReplicationInfoV2ReceiveCapability(publicKey, peerSession);
+		this._v2Receive.reAdvertiseLocalCapabilityForRecovery({
+			peerHash,
+			peerSession,
+			receiveEpoch,
+		});
+		this._v2Receive.ensureRequestProgress({
+			peerHash,
+			peerSession,
+			receiveEpoch,
+		});
+		this.scheduleReplicationInfoV2Recovery(publicKey);
+	}
+
+	/**
+	 * Inspect whether one public key's exact current connection generation can
+	 * supply persisted-receipt evidence. The returned object is frozen and never
+	 * exposes the internal PeerSession token. When `entries` are supplied, the
+	 * peer must also be present in a fresh leader plan for every entry.
+	 *
+	 * This is advisory preflight state. Persisted delivery repeats every
+	 * generation, leadership, ownership and storage check at receipt time; a
+	 * `ready` snapshot is never itself authority to dispose a source copy.
+	 */
+	async getPersistedReceiptPeerReadiness(
+		key: PublicSignKey,
+		options: PersistedReceiptPeerReadinessOptions<T, R> = {},
+	): Promise<PersistedReceiptPeerReadiness> {
+		return this.inspectPersistedReceiptPeerReadiness(key, options);
+	}
+
+	private async inspectPersistedReceiptPeerReadiness(
+		key: PublicSignKey,
+		options: PersistedReceiptPeerReadinessOptions<T, R>,
+		assertContinue?: () => void,
+	): Promise<PersistedReceiptPeerReadiness> {
+		// Capture and validate caller-owned planning input before consulting live
+		// peer state. Invalid options must not appear to work merely because the
+		// peer is currently absent, then fail later when the same session connects.
+		const entries = options.entries ? [...options.entries] : [];
+		const replicas =
+			options.replicas ??
+			(entries.length > 0 ? this.replicas.min.getValue(this) : undefined);
+		if (replicas !== undefined) {
+			if (!Number.isSafeInteger(replicas) || replicas <= 0) {
+				throw new RangeError(
+					"Persisted-receipt readiness replicas must be a positive integer",
+				);
+			}
+			checkMinReplicasLimit(replicas);
+		}
+
+		const peerHash = key.hashcode();
+		const captured = this.persistedReceiptReadinessCandidate(peerHash);
+		if ("status" in captured) {
+			return captured;
+		}
+		assertContinue?.();
+
+		if (entries.length > 0) {
+			const ownershipLifecycleController =
+				this.captureReplicationOwnershipLifecycle();
+			const ownershipRevision =
+				this._instanceLifecycle?._receiveOwnershipRevision ?? 0;
+			if (!this.isReceiveOwnershipSnapshotStable(ownershipRevision)) {
+				return this.pendingPersistedReceiptReadiness(
+					"ownership-changing",
+					captured.generation,
+				);
+			}
+			for (const entry of entries) {
+				assertContinue?.();
+				const leaders = await this.findLeadersFromEntry(
+					entry,
+					replicas!,
+					{ freshLeaderPlan: true },
+					ownershipLifecycleController,
+				);
+				assertContinue?.();
+				if (!this.isReceiveOwnershipSnapshotStable(ownershipRevision)) {
+					return this.pendingPersistedReceiptReadiness(
+						"ownership-changing",
+						captured.generation,
+					);
+				}
+				const current = this.persistedReceiptReadinessCandidate(peerHash);
+				if ("status" in current) {
+					return current;
+				}
+				if (
+					current.peerSession !== captured.peerSession ||
+					current.receiveEpoch !== captured.receiveEpoch ||
+					current.capabilitySession !== captured.capabilitySession
+				) {
+					return this.pendingPersistedReceiptReadiness(
+						"replication-state-pending",
+						current.generation,
+					);
+				}
+				if (!leaders.has(peerHash)) {
+					return this.pendingPersistedReceiptReadiness(
+						"not-entry-leader",
+						captured.generation,
+					);
+				}
+			}
+		}
+
+		assertContinue?.();
+		const current = this.persistedReceiptReadinessCandidate(peerHash);
+		if ("status" in current) {
+			return current;
+		}
+		if (
+			current.peerSession !== captured.peerSession ||
+			current.receiveEpoch !== captured.receiveEpoch ||
+			current.capabilitySession !== captured.capabilitySession
+		) {
+			return this.pendingPersistedReceiptReadiness(
+				"replication-state-pending",
+				current.generation,
+			);
+		}
+		if (
+			!this._v2Send.isLatestConfirmedForPeer({
+				peerHash,
+				peerSession: captured.peerSession,
+				receiverTransportSession: captured.capabilitySession,
+			})
+		) {
+			return this.pendingPersistedReceiptReadiness(
+				"replication-confirmation-pending",
+				captured.generation,
+			);
+		}
+		return Object.freeze({
+			status: "ready" as const,
+			generation: captured.generation,
+		});
+	}
+
+	/**
+	 * Wait for a public key's current (or replacement) connection generation to
+	 * become persisted-receipt ready. Transition listeners are installed before
+	 * the first asynchronous inspection, and a bounded recovery tick repairs
+	 * missed subscriber/capability wakes without retaining stale PeerSessions.
+	 * This waiter is advisory only; the following persisted delivery remains the
+	 * operation that proves the requested remote durability quorum.
+	 */
+	async waitForPersistedReceiptPeerReadiness(
+		key: PublicSignKey,
+		options: WaitForPersistedReceiptPeerReadinessOptions<T, R> = {},
+	): Promise<PersistedReceiptPeerReady> {
+		if (this.closed) {
+			throw new ClosedError();
+		}
+		const timeoutMs = options.timeout ?? this.waitForReplicatorTimeout;
+		if (
+			!Number.isSafeInteger(timeoutMs) ||
+			timeoutMs <= 0 ||
+			timeoutMs > MAX_PERSISTED_DELIVERY_TIMEOUT_MS
+		) {
+			throw new RangeError(
+				`Persisted-receipt readiness timeout must be an integer from 1 to ${MAX_PERSISTED_DELIVERY_TIMEOUT_MS} milliseconds`,
+			);
+		}
+		if (options.signal?.aborted) {
+			throw options.signal.reason instanceof Error
+				? options.signal.reason
+				: new AbortError("Persisted-receipt readiness wait aborted");
+		}
+
+		// Capture caller-owned inputs before reserving a waiter slot. A throwing
+		// iterator/key implementation must not strand capacity permanently.
+		const entries = options.entries ? [...options.entries] : undefined;
+		const inspectOptions: PersistedReceiptPeerReadinessOptions<T, R> = {
+			...(entries ? { entries } : {}),
+			...(options.replicas === undefined ? {} : { replicas: options.replicas }),
+		};
+		const peerHash = key.hashcode();
+		const waiterSet = this._persistedReceiptReadinessWaiters;
+		if (waiterSet.size >= MAX_PERSISTED_RECEIPT_READINESS_WAITERS) {
+			throw new RangeError(
+				`Too many pending persisted-receipt readiness waits (maximum ${MAX_PERSISTED_RECEIPT_READINESS_WAITERS})`,
+			);
+		}
+		const waiterToken = {};
+		waiterSet.add(waiterToken);
+		const deadline = Date.now() + timeoutMs;
+		const closeSignal = this._closeController.signal;
+		const operationController = new AbortController();
+		const operationSignal = AbortSignal.any(
+			[options.signal, closeSignal, operationController.signal].filter(
+				(value): value is AbortSignal => value !== undefined,
+			),
+		);
+		const deferred = pDefer<PersistedReceiptPeerReady>();
+		let settled = false;
+		let checkScheduled = false;
+		let checkInFlight = false;
+		let rerun = false;
+		let recoveryTimer: ReturnType<typeof setTimeout> | undefined;
+		let confirmationController: AbortController | undefined;
+		let lastSnapshot: PersistedReceiptPeerReadiness | undefined;
+		const createTimeoutError = () => {
+			const suffix = lastSnapshot
+				? ` (last status: ${lastSnapshot.status}${
+						"reason" in lastSnapshot ? `/${lastSnapshot.reason}` : ""
+					})`
+				: "";
+			return new TimeoutError(
+				`Timeout waiting for persisted-receipt readiness from ${peerHash}${suffix}`,
+			);
+		};
+
+		const cleanup = () => {
+			waiterSet.delete(waiterToken);
+			this.events.removeEventListener(
+				"persisted-receipt:readiness",
+				onReadinessChange,
+			);
+			this.events.removeEventListener("replication:change", onRoleChange);
+			this.events.removeEventListener("replicator:mature", onRoleChange);
+			options.signal?.removeEventListener("abort", onCallerAbort);
+			closeSignal.removeEventListener("abort", onClose);
+			if (recoveryTimer) {
+				clearTimeout(recoveryTimer);
+				recoveryTimer = undefined;
+			}
+			confirmationController?.abort(
+				new AbortError("Persisted-receipt readiness generation changed"),
+			);
+			confirmationController = undefined;
+			operationController.abort(
+				new AbortError("Persisted-receipt readiness wait settled"),
+			);
+		};
+		const resolve = (snapshot: PersistedReceiptPeerReady) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			deferred.resolve(snapshot);
+		};
+		const reject = (error: unknown) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			deferred.reject(
+				error instanceof Error ? error : new Error(String(error)),
+			);
+		};
+		const onCallerAbort = () =>
+			reject(
+				options.signal?.reason instanceof Error
+					? options.signal.reason
+					: new AbortError("Persisted-receipt readiness wait aborted"),
+			);
+		const onClose = () => reject(new ClosedError());
+		const continueWait = () => {
+			if (settled) return false;
+			if (closeSignal.aborted) {
+				onClose();
+				return false;
+			}
+			if (options.signal?.aborted) {
+				onCallerAbort();
+				return false;
+			}
+			if (Date.now() >= deadline) {
+				reject(createTimeoutError());
+				return false;
+			}
+			return true;
+		};
+		const assertInspectionCurrent = () => {
+			if (!continueWait()) {
+				throw new AbortError("Persisted-receipt readiness wait settled");
+			}
+		};
+		const armRecoveryTick = () => {
+			if (settled || recoveryTimer) return;
+			const delayMs = Math.max(
+				50,
+				Math.min(1_000, this.waitForReplicatorRequestIntervalMs),
+			);
+			recoveryTimer = setTimeout(() => {
+				recoveryTimer = undefined;
+				if (!continueWait()) return;
+				this.nudgePersistedReceiptPeerReadiness(key);
+				scheduleCheck();
+			}, delayMs);
+			recoveryTimer.unref?.();
+		};
+		const runCheck = async () => {
+			checkScheduled = false;
+			if (!continueWait()) return;
+			if (checkInFlight) {
+				rerun = true;
+				return;
+			}
+			checkInFlight = true;
+			try {
+				let snapshot = await this.inspectPersistedReceiptPeerReadiness(
+					key,
+					inspectOptions,
+					assertInspectionCurrent,
+				);
+				lastSnapshot = snapshot;
+				if (!continueWait()) return;
+				if (rerun) return;
+				if (snapshot.status === "ready") {
+					// A wake observed while the asynchronous inspection was running may
+					// already have invalidated this snapshot. Drain that coalesced wake
+					// before publishing readiness.
+					resolve(snapshot);
+					return;
+				}
+				if (
+					snapshot.status === "pending" &&
+					snapshot.reason === "replication-confirmation-pending"
+				) {
+					const target = this.persistedReceiptPeerSession(peerHash);
+					if (target) {
+						const currentConfirmationController = new AbortController();
+						confirmationController = currentConfirmationController;
+						try {
+							await this._v2Send.confirmLatestForPeer(
+								{
+									peerHash,
+									peerSession: target.peerSession,
+									receiverTransportSession: target.capabilitySession,
+								},
+								{
+									timeout: Math.max(1, deadline - Date.now()),
+									signal: AbortSignal.any([
+										operationSignal,
+										currentConfirmationController.signal,
+									]),
+								},
+							);
+						} catch (error) {
+							if (!continueWait()) return;
+							if (!(error instanceof AbortError)) {
+								throw error;
+							}
+							rerun = true;
+						} finally {
+							if (confirmationController === currentConfirmationController) {
+								confirmationController = undefined;
+							}
+						}
+						if (!continueWait()) return;
+						snapshot = await this.inspectPersistedReceiptPeerReadiness(
+							key,
+							inspectOptions,
+							assertInspectionCurrent,
+						);
+						lastSnapshot = snapshot;
+						if (!continueWait()) return;
+						if (rerun) return;
+						if (snapshot.status === "ready") {
+							resolve(snapshot);
+							return;
+						}
+					}
+				}
+				if (!continueWait()) return;
+				this.nudgePersistedReceiptPeerReadiness(key);
+			} catch (error) {
+				if (!settled) reject(error);
+			} finally {
+				checkInFlight = false;
+				if (!settled && rerun) {
+					rerun = false;
+					scheduleCheck();
+				} else {
+					armRecoveryTick();
+				}
+			}
+		};
+		const scheduleCheck = (interruptConfirmation = false) => {
+			if (settled) return;
+			if (recoveryTimer) {
+				clearTimeout(recoveryTimer);
+				recoveryTimer = undefined;
+			}
+			if (checkInFlight) {
+				rerun = true;
+				if (interruptConfirmation) {
+					confirmationController?.abort(
+						new AbortError(
+							"Persisted-receipt readiness changed during confirmation",
+						),
+					);
+				}
+				return;
+			}
+			if (checkScheduled) return;
+			checkScheduled = true;
+			void Promise.resolve().then(runCheck);
+		};
+		const onReadinessChange = (
+			event: CustomEvent<PersistedReceiptPeerReadinessEvent>,
+		) => {
+			if (event.detail.peerHash === peerHash) scheduleCheck(true);
+		};
+		const onRoleChange = (event: CustomEvent<ReplicationChangeEvent>) => {
+			if (
+				(entries?.length ?? 0) > 0 ||
+				event.detail.publicKey.hashcode() === peerHash
+			) {
+				scheduleCheck(true);
+			}
+		};
+
+		// Register wake sources before the first state inspection. EventTarget does
+		// not replay a transition that fired between an async check and registration.
+		this.events.addEventListener(
+			"persisted-receipt:readiness",
+			onReadinessChange,
+		);
+		this.events.addEventListener("replication:change", onRoleChange);
+		this.events.addEventListener("replicator:mature", onRoleChange);
+		options.signal?.addEventListener("abort", onCallerAbort, { once: true });
+		closeSignal.addEventListener("abort", onClose, { once: true });
+		if (options.signal?.aborted) {
+			onCallerAbort();
+		} else if (closeSignal.aborted) {
+			onClose();
+		} else {
+			scheduleCheck();
+		}
+
+		const timeout = setTimeout(() => reject(createTimeoutError()), timeoutMs);
+		timeout.unref?.();
+		return deferred.promise.finally(() => clearTimeout(timeout));
+	}
+
 	async waitForReplicator(
 		key: PublicSignKey,
 		options?: {
@@ -23497,19 +24527,28 @@ export class SharedLog<
 			timeout?: number;
 		},
 	) {
+		if (options?.signal?.aborted) {
+			throw new AbortError();
+		}
 		const deferred = pDefer<void>();
 		const timeoutMs = options?.timeout ?? this.waitForReplicatorTimeout;
 		const resolvedRoleAge = options?.eager
 			? undefined
 			: (options?.roleAge ?? (await this.getDefaultMinRoleAge()));
+		if (options?.signal?.aborted) {
+			throw new AbortError();
+		}
 
 		let settled = false;
 		let timer: ReturnType<typeof setTimeout> | undefined;
 		let requestTimer: ReturnType<typeof setTimeout> | undefined;
+		let checkInFlight = false;
+		let checkAgain = false;
 
 		const clear = () => {
-			this.events.removeEventListener("replicator:mature", check);
-			this.events.removeEventListener("replication:change", check);
+			checkAgain = false;
+			this.events.removeEventListener("replicator:mature", runCheck);
+			this.events.removeEventListener("replication:change", runCheck);
 			options?.signal?.removeEventListener("abort", onAbort);
 			if (timer != null) {
 				clearTimeout(timer);
@@ -23645,11 +24684,34 @@ export class SharedLog<
 				await iterator?.close();
 			}
 		};
+		const runCheck = () => {
+			if (settled) return;
+			if (checkInFlight) {
+				checkAgain = true;
+				return;
+			}
+			// Reserve synchronously before `check()` can dispatch/re-enter from an
+			// index implementation's first `next()` call.
+			checkInFlight = true;
+			void check()
+				.catch((error) =>
+					reject(error instanceof Error ? error : new Error(String(error))),
+				)
+				.finally(() => {
+					checkInFlight = false;
+					if (!settled && checkAgain) {
+						checkAgain = false;
+						runCheck();
+					}
+				});
+		};
 
+		// Register before the first asynchronous index read. EventTarget does not
+		// replay a maturity/change event that fires while that read is in flight.
+		this.events.addEventListener("replicator:mature", runCheck);
+		this.events.addEventListener("replication:change", runCheck);
 		requestReplicationInfo();
-		check();
-		this.events.addEventListener("replicator:mature", check);
-		this.events.addEventListener("replication:change", check);
+		runCheck();
 
 		return deferred.promise.finally(clear);
 	}
@@ -24866,6 +25928,7 @@ export class SharedLog<
 		options?: {
 			roleAge?: number;
 			candidates?: Iterable<string>;
+			freshLeaderPlan?: boolean;
 		},
 		ownershipLifecycleController = this.captureReplicationOwnershipLifecycle(),
 	): Promise<LeaderSelectionContext> {
@@ -25027,6 +26090,7 @@ export class SharedLog<
 		options?: {
 			roleAge?: number;
 			candidates?: Iterable<string>;
+			freshLeaderPlan?: boolean;
 		},
 		ownershipLifecycleController = this.captureReplicationOwnershipLifecycle(),
 	): Promise<Map<string, { intersecting: boolean }>> {
@@ -26537,6 +27601,7 @@ export class SharedLog<
 		if (!ownsSubscriptionEpoch()) {
 			return;
 		}
+		this.dispatchPersistedReceiptReadinessChange(peerHash);
 		// A reconnect can arrive before the previous exact-session recovery tick
 		// observes its stale session. Retire that job synchronously so it cannot
 		// suppress the replacement session's scheduler in the shared peer slot.
@@ -26709,6 +27774,7 @@ export class SharedLog<
 			publicKey,
 			replicationLifecycleController,
 		);
+		this.dispatchPersistedReceiptReadinessChange(peerHash);
 	}
 
 	private getClampedReplicas(customValue?: MinReplicas) {