@peerbit/shared-log 16.0.22 → 16.0.24

package/src/index.ts

@@ -322,6 +322,86 @@ type SharedLogServicesWithFanout = {
 const getSharedLogFanoutService = (services: unknown): FanoutTree | undefined =>
 	(services as SharedLogServicesWithFanout).fanout;
 
+const FANOUT_OPEN_METRICS = [
+	["joinReqSent", "joinReqSent"],
+	["joinAcceptReceived", "joinAcceptReceived"],
+	["joinRejectReceived", "joinRejectReceived"],
+	["bootstrapDialAttempts", "joinBootstrapDialAttempts"],
+	["bootstrapDialFailures", "joinBootstrapDialFailures"],
+	["candidateDialAttempts", "joinCandidateDialAttempts"],
+	["candidateDialFailures", "joinCandidateDialFailures"],
+	["connectedCandidateAttempts", "joinConnectedCandidateAttempts"],
+	["unconnectedCandidateAttempts", "joinUnconnectedCandidateAttempts"],
+	["joinReqTimeouts", "joinReqTimeouts"],
+	["deadlineExpirations", "joinDeadlineExpirations"],
+] as const;
+
+type FanoutOpenMetric = (typeof FANOUT_OPEN_METRICS)[number][0];
+type FanoutOpenMetricSnapshot = Record<FanoutOpenMetric, number>;
+
+const snapshotFanoutOpenMetrics = (
+	service: FanoutTree,
+	topic: string,
+	root: string,
+): FanoutOpenMetricSnapshot | undefined => {
+	try {
+		const metrics = (
+			service as FanoutTree & {
+				getChannelMetrics: (
+					topic: string,
+					root: string,
+				) => Record<string, number>;
+			}
+		).getChannelMetrics(topic, root);
+		return Object.fromEntries(
+			FANOUT_OPEN_METRICS.map(([name, source]) => [name, metrics[source] ?? 0]),
+		) as FanoutOpenMetricSnapshot;
+	} catch {
+		return;
+	}
+};
+
+const emitFanoutOpenProfile = (properties: {
+	profile?: SyncProfileFn;
+	startedAt: number;
+	service: FanoutTree;
+	topic: string;
+	root: string;
+	mode: "root" | "node";
+	outcome: "error" | "opened" | "joined";
+	timeoutMs?: number;
+	before?: FanoutOpenMetricSnapshot;
+}) => {
+	if (!properties.profile) return;
+	try {
+		const after = snapshotFanoutOpenMetrics(
+			properties.service,
+			properties.topic,
+			properties.root,
+		);
+		const deltas = Object.fromEntries(
+			FANOUT_OPEN_METRICS.map(([name]) => [
+				name,
+				(after?.[name] ?? 0) - (properties.before?.[name] ?? 0),
+			]),
+		) as FanoutOpenMetricSnapshot;
+		emitSyncProfileDuration(properties.profile, properties.startedAt, {
+			name: "sharedLog.open.fanout",
+			component: "shared-log",
+			messages: deltas.joinReqSent,
+			details: {
+				configured: true,
+				mode: properties.mode,
+				outcome: properties.outcome,
+				configuredTimeoutMs: properties.timeoutMs,
+				...deltas,
+			},
+		});
+	} catch {
+		// Diagnostics must not affect open correctness.
+	}
+};
+
 type PendingIHave<T> = {
 	resetTimeout: () => void;
 	requesting: Map<string, Uint8Array>;
@@ -471,6 +551,18 @@ export const logger = loggerFn("peerbit:shared-log");
 const warn = logger.newScope("warn");
 const traceLogger = logger.trace as typeof logger.trace & { enabled?: boolean };
 
+const emitAdvisorySyncProfileDuration = (
+	profile: SyncProfileFn | undefined,
+	startedAt: number,
+	event: Parameters<typeof emitSyncProfileDuration>[2],
+): void => {
+	try {
+		emitSyncProfileDuration(profile, startedAt, event);
+	} catch {
+		// Diagnostics must not change open or provider-resolution correctness.
+	}
+};
+
 const canUseOptionalNativeModuleImports = (): boolean => {
 	const scope = globalThis as {
 		ServiceWorkerGlobalScope?: unknown;
@@ -1752,6 +1844,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;
@@ -1793,6 +1950,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;
@@ -2167,6 +2325,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() {
@@ -2189,6 +2351,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<{
@@ -3742,6 +3910,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;
@@ -4099,6 +4284,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;
@@ -4242,16 +4433,38 @@ export class SharedLog<
 			});
 		channel.addEventListener("unicast", this._onFanoutUnicastFn);
 
+		const profile = this._logProperties?.sync?.profile;
+		const startedAt = syncProfileStart(profile);
+		const mode =
+			resolvedRoot === fanoutService.publicKeyHash ? "root" : "node";
+		const before = profile
+			? snapshotFanoutOpenMetrics(fanoutService, this.topic, resolvedRoot)
+			: undefined;
+		let outcome: "error" | "opened" | "joined" = "error";
 		try {
 			const channelOptions = this.getFanoutChannelOptions(options);
-			if (resolvedRoot === fanoutService.publicKeyHash) {
+			if (mode === "root") {
 				await channel.openAsRoot(channelOptions);
+				outcome = "opened";
 				return;
 			}
 			await channel.join(channelOptions, options.join);
+			outcome = "joined";
 		} catch (error) {
 			this._closeFanoutChannel();
 			throw error;
+		} finally {
+			emitFanoutOpenProfile({
+				profile,
+				startedAt,
+				service: fanoutService,
+				topic: this.topic,
+				root: resolvedRoot,
+				mode,
+				outcome,
+				timeoutMs: options.join?.timeoutMs,
+				before,
+			});
 		}
 	}
 
@@ -5061,15 +5274,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, {
@@ -5078,17 +5299,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;
 		}
 
@@ -5113,6 +5342,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(
@@ -5129,6 +5362,9 @@ export class SharedLog<
 			// recovery re-solicitation may restart from the base interval.
 			this.resetReplicationInfoV2RecoveryEscalation(peerHash);
 		}
+		if (readinessChanged) {
+			this.dispatchPersistedReceiptReadinessChange(peerHash);
+		}
 		return true;
 	}
 
@@ -5478,9 +5714,148 @@ 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);
@@ -5488,10 +5863,14 @@ export class SharedLog<
 			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) &
 				requiredCapabilities) !==
@@ -8181,8 +8560,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
@@ -8423,7 +8805,10 @@ export class SharedLog<
 			});
 			removalCallCompleted = true;
 		} finally {
-			releaseReceiveCleanupGate?.();
+			if (releaseReceiveCleanupGate) {
+				releaseReceiveCleanupGate();
+				this.dispatchPersistedReceiptReadinessChange(keyHash);
+			}
 			if (
 				replicationInfoRecoveryEpochAdvanced &&
 				ownsReplicationOwnershipLifecycle() &&
@@ -16817,6 +17202,8 @@ export class SharedLog<
 			(this.node as unknown as NodeWithSharedLogNativeDefaults)
 				.sharedLogNativeDefaults,
 		);
+		const openProfile = options?.sync?.profile;
+		const openStartedAt = syncProfileStart(openProfile);
 		this.replicas = {
 			min:
 				options?.replicas?.min != null
@@ -16904,6 +17291,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;
@@ -17041,6 +17434,7 @@ export class SharedLog<
 		this.keep = options?.keep;
 		this.pendingMaturity = new Map();
 
+		const localStateStartedAt = syncProfileStart(openProfile);
 		const id = sha256Base64Sync(this.log.id);
 		const [storage, logScope] = await Promise.all([
 			this.node.storage.sublevel(id),
@@ -17096,6 +17490,11 @@ export class SharedLog<
 		this._entryCoordinatesIndex = await replicationIndex.init({
 			schema: this.indexableDomain.constructorEntry,
 		});
+		emitAdvisorySyncProfileDuration(openProfile, localStateStartedAt, {
+			name: "sharedLog.open.localState",
+			component: "shared-log",
+		});
+		const blockStoreStartedAt = syncProfileStart(openProfile);
 		const deferStandaloneNativeRangePlanner =
 			!!options?.nativeBackbone && options.nativeRangePlanner == null;
 		await this.openNativeRangePlanner(
@@ -17146,6 +17545,14 @@ export class SharedLog<
 				storage as unknown as DurableBlockSublevelStore,
 			);
 		}
+		emitAdvisorySyncProfileDuration(openProfile, blockStoreStartedAt, {
+			name: "sharedLog.open.blockStore",
+			component: "shared-log",
+			details: {
+				nativeBackbone: this._nativeBackbone != null,
+				directoryConfigured: this.node.directory != null,
+			},
+		});
 		this.remoteBlocks = new RemoteBlocks({
 			local: localBlocks,
 			publish: (message, options) =>
@@ -17156,38 +17563,76 @@ export class SharedLog<
 			// compatible eager path with bounded validation and storage budgets.
 			eagerBlocks: options?.eagerBlocks ?? false,
 			resolveProviders: async (cid, opts) => {
+				const profile = this._logProperties?.sync?.profile;
 				const maxPeers = 8;
+				const excluded = new Set((opts?.exclude ?? []).slice(0, maxPeers));
+				const lookupPeers = opts?.refresh
+					? Math.min(maxPeers * 2, maxPeers + excluded.size)
+					: maxPeers;
+				const resolutionStartedAt = syncProfileStart(profile);
 				const localCandidates =
 					(await this.resolveCandidatePeersForHash(cid, {
 						signal: opts?.signal,
-						maxPeers,
+						maxPeers: lookupPeers,
 					})) ?? [];
-				if (opts?.signal?.aborted) return [];
+				const emitResolution = profile
+					? (
+							status: "aborted" | "local" | "directory",
+							targets: number,
+							directoryCandidates = 0,
+							reachableCandidates = 0,
+						) =>
+							emitAdvisorySyncProfileDuration(profile, resolutionStartedAt, {
+								name: "sharedLog.blocks.resolveProviders",
+								component: "shared-log",
+								count: targets,
+								targets,
+								details: {
+									status,
+									refresh: opts?.refresh === true,
+									excluded: excluded.size,
+									lookupPeers,
+									localCandidates: localCandidates.length,
+									directoryCandidates,
+									reachableCandidates,
+								},
+							})
+					: undefined;
+				if (opts?.signal?.aborted) {
+					emitResolution?.("aborted", 0);
+					return [];
+				}
 				const locallyReachable = new Set(
 					await this._getLocalReachablePeerHashes(this.topic),
 				);
+				if (opts?.signal?.aborted) {
+					emitResolution?.("aborted", 0, 0, locallyReachable.size);
+					return [];
+				}
 				const confirmed = this._checkedPrune.getConfirmedReplicators(cid);
 				const contacted = this._checkedPrune.getContactedReplicators(cid);
+				const hasProviderEvidence = (peer: string) =>
+					confirmed?.has(peer) === true ||
+					contacted?.has(peer) ||
+					this.uniqueReplicators.has(peer);
 				const hasLiveCandidate = localCandidates.some(
-					(peer) =>
-						locallyReachable.has(peer) &&
-						(confirmed?.has(peer) ||
-							contacted?.has(peer) ||
-							this.uniqueReplicators.has(peer)),
+					(peer) => locallyReachable.has(peer) && hasProviderEvidence(peer),
 				);
 
 				// Only reachability corroborated by provider/replicator evidence may
 				// bypass the initial CID lookup. Arbitrary bootstrap connections are
 				// useful fallbacks, but are not evidence that they hold this block.
 				if (hasLiveCandidate && !opts?.refresh) {
-					return localCandidates;
+					const selected = localCandidates.slice(0, maxPeers);
+					emitResolution?.("local", selected.length, 0, locallyReachable.size);
+					return selected;
 				}
 
 				let directoryProviders: string[] = [];
 				try {
 					const query = (namespace: string) =>
 						fanoutService?.queryProviders(namespace, {
-							want: maxPeers,
+							want: lookupPeers,
 							timeoutMs: 2_000,
 							queryTimeoutMs: 500,
 							bootstrapMaxPeers: 2,
@@ -17199,12 +17644,21 @@ export class SharedLog<
 					]);
 					for (const result of results) {
 						if (result.status === "fulfilled") {
-							directoryProviders.push(...result.value);
+							directoryProviders.push(...result.value.slice(0, lookupPeers));
 						}
 					}
 				} catch {
 					// Ignore discovery failures; local evidence remains usable.
 				}
+				if (opts?.signal?.aborted) {
+					emitResolution?.(
+						"aborted",
+						0,
+						directoryProviders.length,
+						locallyReachable.size,
+					);
+					return [];
+				}
 
 				const selected: string[] = [];
 				const selectedSet = new Set<string>();
@@ -17215,15 +17669,62 @@ export class SharedLog<
 					selectedSet.add(peer);
 					selected.push(peer);
 				};
-				for (
-					let index = 0;
-					selected.length < maxPeers &&
-					(index < localCandidates.length || index < directoryProviders.length);
-					index++
-				) {
-					add(localCandidates[index]);
-					add(directoryProviders[index]);
-				}
+				const append = (
+					providers: readonly string[],
+					includeExcluded: boolean,
+					predicate?: (provider: string) => boolean,
+				) => {
+					for (const provider of providers) {
+						if (selected.length >= maxPeers) return;
+						if (
+							excluded.has(provider) === includeExcluded &&
+							(!predicate || predicate(provider))
+						) {
+							add(provider);
+						}
+					}
+				};
+				const appendInterleaved = (includeExcluded: boolean) => {
+					for (
+						let index = 0;
+						selected.length < maxPeers &&
+						(index < localCandidates.length ||
+							index < directoryProviders.length);
+						index++
+					) {
+						const local = localCandidates[index];
+						if (local && excluded.has(local) === includeExcluded) add(local);
+						const directory = directoryProviders[index];
+						if (directory && excluded.has(directory) === includeExcluded) {
+							add(directory);
+						}
+					}
+				};
+				if (opts?.refresh) {
+					// Retry results are wider than the regular eight-peer window. Prefer
+					// untried reachable holders, then the remaining fresh directory
+					// evidence, without discarding attempted peers as bounded transient-
+					// failure fallbacks.
+					append(directoryProviders, false, (peer) =>
+						locallyReachable.has(peer),
+					);
+					append(
+						localCandidates,
+						false,
+						(peer) => locallyReachable.has(peer) && hasProviderEvidence(peer),
+					);
+					append(directoryProviders, false);
+					append(localCandidates, false);
+				} else {
+					appendInterleaved(false);
+				}
+				appendInterleaved(true);
+				emitResolution?.(
+					"directory",
+					selected.length,
+					directoryProviders.length,
+					locallyReachable.size,
+				);
 				return selected;
 			},
 			watchProviders: fanoutService
@@ -17271,7 +17772,13 @@ export class SharedLog<
 				: undefined,
 		});
 
-		const remoteBlocksStartPromise = this.remoteBlocks.start();
+		const remoteBlocksStartedAt = syncProfileStart(openProfile);
+		const remoteBlocksStartPromise = this.remoteBlocks.start().then(() => {
+			emitAdvisorySyncProfileDuration(openProfile, remoteBlocksStartedAt, {
+				name: "sharedLog.open.remoteBlocks",
+				component: "shared-log",
+			});
+		});
 		const hasIndexedReplicationInfo =
 			(await this.replicationIndex.count({
 				query: [
@@ -17487,6 +17994,7 @@ export class SharedLog<
 		// joins rely on: a replicate:false observer syncing a head whose parents
 		// are not local would fail block resolution, and Log.join treats that as
 		// recoverable and skips the entry without persisting anything.
+		const lowerLogStartedAt = syncProfileStart(openProfile);
 		await this.log.open(this.remoteBlocks, this.node.identity, {
 			keychain: this.node.services.keychain,
 			resolveRemotePeers: (hash, options) =>
@@ -17518,6 +18026,10 @@ export class SharedLog<
 			},
 			indexer: logIndex,
 		});
+		emitAdvisorySyncProfileDuration(openProfile, lowerLogStartedAt, {
+			name: "sharedLog.open.lowerLog",
+			component: "shared-log",
+		});
 		this._persistedReceiptStorage = this.resolvePersistedReceiptStorage();
 		try {
 			const recovered =
@@ -17582,6 +18094,7 @@ export class SharedLog<
 					this._onUnsubscription(event),
 				);
 			});
+		const communicationStartedAt = syncProfileStart(openProfile);
 		await Promise.all([
 			this.rpc.open({
 				queryType: TransportMessage,
@@ -17600,7 +18113,12 @@ export class SharedLog<
 				this._onUnsubscriptionFn,
 			),
 		]);
+		emitAdvisorySyncProfileDuration(openProfile, communicationStartedAt, {
+			name: "sharedLog.open.rpcSubscriptions",
+			component: "shared-log",
+		});
 
+		const providerChannelStartedAt = syncProfileStart(openProfile);
 		const fanoutOpenPromise = this._openFanoutChannel(options?.fanout);
 		// Mark previously-owned replication ranges as "new" only when they already exist.
 		// Fresh opens have nothing to touch here, so skip the extra scan/write entirely.
@@ -17608,6 +18126,11 @@ export class SharedLog<
 			? this.updateTimestampOfOwnedReplicationRanges()
 			: Promise.resolve();
 		await Promise.all([fanoutOpenPromise, updateOwnedReplicationPromise]);
+		emitAdvisorySyncProfileDuration(openProfile, providerChannelStartedAt, {
+			name: "sharedLog.open.providerAndOwnership",
+			component: "shared-log",
+			details: { indexedReplicationInfo: hasIndexedReplicationInfo },
+		});
 
 		// if we had a previous session with replication info, and new replication info dictates that we unreplicate
 		// we should do that. Otherwise if options is a unreplication we dont need to do anything because
@@ -17625,17 +18148,35 @@ export class SharedLog<
 				this.node.identity.publicKey,
 			));
 
+		const replicationStartedAt = syncProfileStart(openProfile);
+		let replicationAction: "replace" | "resume" | "reset";
 		if (hasIndexedReplicationInfo && isUnreplicationOptionsDefined) {
+			replicationAction = "replace";
 			await this.replicate(options?.replicate, { checkDuplicates: true });
 		} else if (canResumeReplication) {
+			replicationAction = "resume";
 			// dont do anthing since we are alread replicating stuff
 		} else {
+			replicationAction = "reset";
 			await this.replicate(options?.replicate, {
 				checkDuplicates: true,
 				reset: true,
 			});
 		}
+		emitAdvisorySyncProfileDuration(openProfile, replicationStartedAt, {
+			name: "sharedLog.open.replication",
+			component: "shared-log",
+			details: {
+				hadIndexedState: hasIndexedReplicationInfo,
+				action: replicationAction,
+			},
+		});
+		const synchronizerStartedAt = syncProfileStart(openProfile);
 		await this.syncronizer.open();
+		emitAdvisorySyncProfileDuration(openProfile, synchronizerStartedAt, {
+			name: "sharedLog.open.synchronizer",
+			component: "shared-log",
+		});
 
 		this.interval = setInterval(() => {
 			void this.rebalanceParticipationDebounced?.call();
@@ -17643,6 +18184,10 @@ export class SharedLog<
 
 		this._instanceLifecycle!.markOpenComplete();
 		this.scheduleReplicationStatusRefresh();
+		emitAdvisorySyncProfileDuration(openProfile, openStartedAt, {
+			name: "sharedLog.open.total",
+			component: "shared-log",
+		});
 	}
 
 	private toNativeReplicationRange(
@@ -18580,6 +19125,7 @@ export class SharedLog<
 			ownershipLifecycleController,
 			this._checkedPrune,
 		);
+		this.dispatchPersistedReceiptReadinessChange(peerHash);
 	}
 
 	private cleanupPendingIHavePeer(peerHash: string) {
@@ -18604,6 +19150,7 @@ export class SharedLog<
 				receiveEpoch,
 			});
 		}
+		this.dispatchPersistedReceiptReadinessChange(peerHash);
 	}
 
 	private async resolveCandidatePeersForHash(
@@ -20045,6 +20592,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;
@@ -22601,10 +23149,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(
@@ -23420,6 +23972,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);
@@ -23774,6 +24327,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?: {
@@ -23783,19 +24795,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);
@@ -23931,11 +24952,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);
 	}
@@ -26825,6 +27869,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.
@@ -26997,6 +28042,7 @@ export class SharedLog<
 			publicKey,
 			replicationLifecycleController,
 		);
+		this.dispatchPersistedReceiptReadinessChange(peerHash);
 	}
 
 	private getClampedReplicas(customValue?: MinReplicas) {