@peerbit/shared-log 16.0.22 → 16.0.23

package/dist/src/index.js

@@ -575,6 +575,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;
@@ -1847,6 +1848,16 @@ let SharedLog = (() => {
         // parallel map so existing capability-number consumers remain unchanged.
         _peerSyncCapabilitySessions;
         _peerSyncCapabilityTimestamps;
+        // 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.
+        _persistedReceiptReadinessGenerations;
+        _persistedReceiptReadinessGenerationPrefix;
+        _persistedReceiptReadinessGenerationCounter;
+        _persistedReceiptReadinessWaiters;
         _persistedReceiptStorage;
         _persistedReceiptRequestsInFlight;
         _persistedReceiptRequestsInFlightTotal;
@@ -2121,6 +2132,10 @@ let 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;
@@ -2898,14 +2913,20 @@ let SharedLog = (() => {
                         timestamp < previous.timestamp) {
                         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, {
@@ -2914,16 +2935,23 @@ let 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;
             }
             const previousSession = this._peerSyncCapabilitySessions.get(peerHash);
@@ -2943,6 +2971,9 @@ let SharedLog = (() => {
             const generationAdvanced = !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(peerHash, previousTimestamp === undefined ||
@@ -2956,6 +2987,9 @@ let SharedLog = (() => {
                 // recovery re-solicitation may restart from the base interval.
                 this.resetReplicationInfoV2RecoveryEscalation(peerHash);
             }
+            if (readinessChanged) {
+                this.dispatchPersistedReceiptReadinessChange(peerHash);
+            }
             return true;
         }
         promoteReplicationInfoV2ReceiveCapability(target, peerSession) {
@@ -3227,16 +3261,102 @@ let SharedLog = (() => {
             }
             return this.sendFusedRawExchangeHeadsPlan(plan, to, options);
         }
+        persistedReceiptReadinessGeneration(peerSession, receiveEpoch, capabilitySession) {
+            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;
+        }
+        pendingPersistedReceiptReadiness(reason, generation) {
+            return Object.freeze({
+                status: "pending",
+                reason,
+                ...(generation === undefined ? {} : { generation }),
+            });
+        }
+        unsupportedPersistedReceiptReadiness(reason, generation) {
+            return Object.freeze({
+                status: "unsupported",
+                reason,
+                generation,
+            });
+        }
+        dispatchPersistedReceiptReadinessChange(peerHash) {
+            this.events.dispatchEvent(new CustomEvent("persisted-receipt:readiness", { detail: Object.freeze({ peerHash }) }));
+        }
+        persistedReceiptReadinessCandidate(peerHash) {
+            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,
+            };
+        }
         persistedReceiptPeerSession(peerHash) {
+            // 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 (capabilitySession == null ||
+            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) !==
@@ -5188,8 +5308,11 @@ let 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
@@ -5377,7 +5500,10 @@ let SharedLog = (() => {
                 removalCallCompleted = true;
             }
             finally {
-                releaseReceiveCleanupGate?.();
+                if (releaseReceiveCleanupGate) {
+                    releaseReceiveCleanupGate();
+                    this.dispatchPersistedReceiptReadinessChange(keyHash);
+                }
                 if (replicationInfoRecoveryEpochAdvanced &&
                     ownsReplicationOwnershipLifecycle() &&
                     ownsReplicationLifecycle() &&
@@ -11037,6 +11163,10 @@ let 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;
@@ -12302,6 +12432,7 @@ let SharedLog = (() => {
             }
             this.cleanupPendingIHavePeer(peerHash);
             this.cleanupCheckedPrunePeer(peerHash, ownershipLifecycleController, this._checkedPrune);
+            this.dispatchPersistedReceiptReadinessChange(peerHash);
         }
         cleanupPendingIHavePeer(peerHash) {
             for (const [hash, pending] of this._pendingIHave) {
@@ -12324,6 +12455,7 @@ let SharedLog = (() => {
                     receiveEpoch,
                 });
             }
+            this.dispatchPersistedReceiptReadinessChange(peerHash);
         }
         async resolveCandidatePeersForHash(hash, options) {
             if (options?.signal?.aborted)
@@ -13497,6 +13629,7 @@ let SharedLog = (() => {
                 this._peerSyncCapabilities?.clear();
                 this._peerSyncCapabilitySessions?.clear();
                 this._peerSyncCapabilityTimestamps?.clear();
+                this._persistedReceiptReadinessGenerations = new WeakMap();
                 this._persistedReceiptStorage = undefined;
                 this._persistedReceiptRequestsInFlight?.clear();
                 this._persistedReceiptRequestsInFlightTotal = 0;
@@ -15612,10 +15745,12 @@ let SharedLog = (() => {
                         return;
                     }
                     else if (msg instanceof ReplicationInfoV2AppliedMessage) {
-                        this._v2Send.acceptApplied(msg, {
+                        if (this._v2Send.acceptApplied(msg, {
                             from: context.from,
                             receiverTransportSession: context.message.header.session,
-                        });
+                        })) {
+                            this.dispatchPersistedReceiptReadinessChange(receiveFromHash);
+                        }
                         return;
                     }
                     else if (isReplicationInfoV2Message(msg)) {
@@ -16239,6 +16374,7 @@ let 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 {
@@ -16513,18 +16649,401 @@ let SharedLog = (() => {
             }
             throwIfInactive();
         }
+        nudgePersistedReceiptPeerReadiness(publicKey) {
+            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, options = {}) {
+            return this.inspectPersistedReceiptPeerReadiness(key, options);
+        }
+        async inspectPersistedReceiptPeerReadiness(key, options, assertContinue) {
+            // 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",
+                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, options = {}) {
+            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 = {
+                ...(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 !== undefined));
+            const deferred = pDefer();
+            let settled = false;
+            let checkScheduled = false;
+            let checkInFlight = false;
+            let rerun = false;
+            let recoveryTimer;
+            let confirmationController;
+            let lastSnapshot;
+            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) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                deferred.resolve(snapshot);
+            };
+            const reject = (error) => {
+                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) => {
+                if (event.detail.peerHash === peerHash)
+                    scheduleCheck(true);
+            };
+            const onRoleChange = (event) => {
+                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, options) {
+            if (options?.signal?.aborted) {
+                throw new AbortError();
+            }
             const deferred = pDefer();
             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;
             let requestTimer;
+            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);
@@ -16643,10 +17162,32 @@ let 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);
         }
         async waitForReplicators(options) {
@@ -18567,6 +19108,7 @@ let 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.
@@ -18709,6 +19251,7 @@ let SharedLog = (() => {
                 signal: replicationLifecycleController.signal,
             });
             this.scheduleReplicationInfoV2Recovery(publicKey, replicationLifecycleController);
+            this.dispatchPersistedReceiptReadinessChange(peerHash);
         }
         getClampedReplicas(customValue) {
             if (!customValue) {