@peerbit/shared-log 12.3.5-cb91e7b → 13.0.0

package/dist/src/index.js

@@ -216,6 +216,20 @@ const RECALCULATE_PARTICIPATION_MIN_RELATIVE_CHANGE_WITH_CPU_LIMIT = 0.005;
 const RECALCULATE_PARTICIPATION_MIN_RELATIVE_CHANGE_WITH_MEMORY_LIMIT = 0.001;
 const RECALCULATE_PARTICIPATION_RELATIVE_DENOMINATOR_FLOOR = 1e-3;
 const DEFAULT_DISTRIBUTION_DEBOUNCE_TIME = 500;
+const RECENT_REPAIR_DISPATCH_TTL_MS = 5_000;
+const REPAIR_SWEEP_ENTRY_BATCH_SIZE = 1_000;
+const REPAIR_SWEEP_TARGET_BUFFER_SIZE = 1024;
+const FORCE_FRESH_RETRY_SCHEDULE_MS = [0, 1_000, 3_000, 7_000];
+const JOIN_WARMUP_RETRY_SCHEDULE_MS = [0, 1_000, 3_000];
+const toPositiveInteger = (value, fallback, label) => {
+    if (value == null) {
+        return fallback;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${label} must be a positive number`);
+    }
+    return Math.max(1, Math.floor(value));
+};
 const DEFAULT_SHARED_LOG_FANOUT_CHANNEL_OPTIONS = {
     msgRate: 30,
     msgSize: 1024,
@@ -305,6 +319,11 @@ let SharedLog = (() => {
         _requestIPruneResponseReplicatorSet; // tracks entry hash to peer hash
         _checkedPruneRetries;
         replicationChangeDebounceFn;
+        _repairRetryTimers;
+        _recentRepairDispatch;
+        _repairSweepRunning;
+        _repairSweepForceFreshPending;
+        _repairSweepAddedPeersPending;
         // regular distribution checks
         distributeQueue;
         syncronizer;
@@ -316,6 +335,7 @@ let SharedLog = (() => {
         waitForReplicatorRequestMaxAttempts;
         waitForPruneDelay;
         distributionDebounceTime;
+        repairSweepTargetBufferSize;
         replicationController;
         history;
         domain;
@@ -486,22 +506,23 @@ let SharedLog = (() => {
             const delivery = deliveryArg === undefined || deliveryArg === false
                 ? undefined
                 : deliveryArg === true
-                    ? {}
+                    ? { reliability: "ack" }
                     : deliveryArg;
             if (!delivery) {
                 return {
                     delivery: undefined,
+                    reliability: "best-effort",
                     requireRecipients: false,
-                    settleMin: undefined,
+                    minAcks: undefined,
                     wrap: undefined,
                 };
             }
-            const deliverySettle = delivery.settle ?? true;
+            const reliability = delivery.reliability ?? "ack";
             const deliveryTimeout = delivery.timeout;
             const deliverySignal = delivery.signal;
             const requireRecipients = delivery.requireRecipients === true;
-            const settleMin = typeof deliverySettle === "object" && Number.isFinite(deliverySettle.min)
-                ? Math.max(0, Math.floor(deliverySettle.min))
+            const minAcks = delivery.minAcks != null && Number.isFinite(delivery.minAcks)
+                ? Math.max(0, Math.floor(delivery.minAcks))
                 : undefined;
             const wrap = deliveryTimeout == null && deliverySignal == null
                 ? undefined
@@ -562,13 +583,83 @@ let SharedLog = (() => {
                 });
             return {
                 delivery,
+                reliability,
                 requireRecipients,
-                settleMin,
+                minAcks,
                 wrap,
             };
         }
+        async _getSortedRouteHints(targetHash) {
+            const pubsub = this.node.services.pubsub;
+            const maybeHints = await pubsub?.getUnifiedRouteHints?.(this.topic, targetHash);
+            const hints = Array.isArray(maybeHints) ? maybeHints : [];
+            const now = Date.now();
+            return hints
+                .filter((hint) => hint.expiresAt == null || hint.expiresAt > now)
+                .sort((a, b) => {
+                const rankA = a.kind === "directstream-ack" ? 0 : 1;
+                const rankB = b.kind === "directstream-ack" ? 0 : 1;
+                if (rankA !== rankB) {
+                    return rankA - rankB;
+                }
+                const costA = a.kind === "directstream-ack"
+                    ? a.distance
+                    : Math.max(0, (a.route?.length ?? 1) - 1);
+                const costB = b.kind === "directstream-ack"
+                    ? b.distance
+                    : Math.max(0, (b.route?.length ?? 1) - 1);
+                if (costA !== costB) {
+                    return costA - costB;
+                }
+                return (b.updatedAt ?? 0) - (a.updatedAt ?? 0);
+            });
+        }
+        async _sendAckWithUnifiedHints(properties) {
+            const { peer, message, payload, fanoutUnicastOptions } = properties;
+            const hints = await this._getSortedRouteHints(peer);
+            const hasDirectHint = hints.some((hint) => hint.kind === "directstream-ack");
+            const fanoutHint = hints.find((hint) => hint.kind === "fanout-token");
+            if (hasDirectHint) {
+                try {
+                    await this.rpc.send(message, {
+                        mode: new AcknowledgeDelivery({
+                            redundancy: 1,
+                            to: [peer],
+                        }),
+                    });
+                    return;
+                }
+                catch {
+                    // Fall back to fanout token/direct fanout unicast below.
+                }
+            }
+            if (fanoutHint && this._fanoutChannel) {
+                try {
+                    await this._fanoutChannel.unicastAck(fanoutHint.route, payload, fanoutUnicastOptions);
+                    return;
+                }
+                catch {
+                    // Fall back below.
+                }
+            }
+            if (this._fanoutChannel) {
+                try {
+                    await this._fanoutChannel.unicastToAck(peer, payload, fanoutUnicastOptions);
+                    return;
+                }
+                catch {
+                    // Fall back below.
+                }
+            }
+            await this.rpc.send(message, {
+                mode: new AcknowledgeDelivery({
+                    redundancy: 1,
+                    to: [peer],
+                }),
+            });
+        }
         async _appendDeliverToReplicators(entry, minReplicasValue, leaders, selfHash, isLeader, deliveryArg) {
-            const { delivery, requireRecipients, settleMin, wrap } = this._parseDeliveryOptions(deliveryArg);
+            const { delivery, reliability, requireRecipients, minAcks, wrap } = this._parseDeliveryOptions(deliveryArg);
             const pending = [];
             const track = (promise) => {
                 pending.push(wrap ? wrap(promise) : promise);
@@ -580,7 +671,28 @@ let SharedLog = (() => {
                 await this._mergeLeadersFromGidReferences(message, minReplicasValue, leaders);
                 const leadersForDelivery = delivery ? new Set(leaders.keys()) : undefined;
                 const set = this.addPeersToGidPeerHistory(entry.meta.gid, leaders.keys());
-                const hasRemotePeers = set.has(selfHash) ? set.size > 1 : set.size > 0;
+                let hasRemotePeers = set.has(selfHash) ? set.size > 1 : set.size > 0;
+                const allowSubscriberFallback = this.syncronizer instanceof SimpleSyncronizer ||
+                    (this.compatibility ?? Number.MAX_VALUE) < 10;
+                if (!hasRemotePeers && allowSubscriberFallback) {
+                    try {
+                        const subscribers = await this._getTopicSubscribers(this.topic);
+                        if (subscribers && subscribers.length > 0) {
+                            for (const subscriber of subscribers) {
+                                const hash = subscriber.hashcode();
+                                if (hash === selfHash) {
+                                    continue;
+                                }
+                                set.add(hash);
+                                leadersForDelivery?.add(hash);
+                            }
+                            hasRemotePeers = set.has(selfHash) ? set.size > 1 : set.size > 0;
+                        }
+                    }
+                    catch {
+                        // Best-effort only; keep discovered recipients as-is.
+                    }
+                }
                 if (!hasRemotePeers) {
                     if (requireRecipients) {
                         throw new NoPeersError(this.rpc.topic);
@@ -617,7 +729,9 @@ let SharedLog = (() => {
                 let silentTo;
                 // Default delivery semantics: require enough remote ACKs to reach the requested
                 // replication degree (local append counts as 1).
-                const ackLimit = settleMin == null ? Math.max(0, minReplicasValue - 1) : settleMin;
+                const defaultMinAcks = Math.max(0, minReplicasValue - 1);
+                const ackLimitRaw = reliability === "ack" ? (minAcks ?? defaultMinAcks) : 0;
+                const ackLimit = Math.max(0, Math.min(Math.floor(ackLimitRaw), orderedRemoteRecipients.length));
                 for (const peer of orderedRemoteRecipients) {
                     if (ackTo.length < ackLimit) {
                         ackTo.push(peer);
@@ -637,36 +751,11 @@ let SharedLog = (() => {
                     const payload = serialize(message);
                     for (const peer of ackTo) {
                         track((async () => {
-                            // Unified decision point:
-                            // - If we can prove a cheap direct path (connected or routed), use it.
-                            // - Otherwise, fall back to the fanout unicast ACK path (bounded overlay routing).
-                            // - If that fails, fall back to pubsub/RPC routing which may flood to discover routes.
-                            const pubsub = this.node.services.pubsub;
-                            const canDirectFast = Boolean(pubsub?.peers?.get?.(peer)?.isWritable) ||
-                                Boolean(pubsub?.routes?.isReachable?.(pubsub?.publicKeyHash, peer, 0));
-                            if (canDirectFast) {
-                                await this.rpc.send(message, {
-                                    mode: new AcknowledgeDelivery({
-                                        redundancy: 1,
-                                        to: [peer],
-                                    }),
-                                });
-                                return;
-                            }
-                            if (this._fanoutChannel) {
-                                try {
-                                    await this._fanoutChannel.unicastToAck(peer, payload, fanoutUnicastOptions);
-                                    return;
-                                }
-                                catch {
-                                    // fall back below
-                                }
-                            }
-                            await this.rpc.send(message, {
-                                mode: new AcknowledgeDelivery({
-                                    redundancy: 1,
-                                    to: [peer],
-                                }),
+                            await this._sendAckWithUnifiedHints({
+                                peer,
+                                message,
+                                payload,
+                                fanoutUnicastOptions,
                             });
                         })());
                     }
@@ -1159,6 +1248,13 @@ let SharedLog = (() => {
                 }
                 this.pendingMaturity.delete(keyHash);
             }
+            // Keep local sync/prune state consistent even when a peer disappears
+            // through replication-info updates without a topic unsubscribe event.
+            this.removePeerFromGidPeerHistory(keyHash);
+            this._recentRepairDispatch.delete(keyHash);
+            if (!isMe) {
+                this.syncronizer.onPeerDisconnected(keyHash);
+            }
             if (!isMe) {
                 this.rebalanceParticipationDebounced?.call();
             }
@@ -1522,6 +1618,181 @@ let SharedLog = (() => {
             }
             return set;
         }
+        dispatchMaybeMissingEntries(target, entries, options) {
+            if (entries.size === 0) {
+                return;
+            }
+            const now = Date.now();
+            let recentlyDispatchedByHash = this._recentRepairDispatch.get(target);
+            if (!recentlyDispatchedByHash) {
+                recentlyDispatchedByHash = new Map();
+                this._recentRepairDispatch.set(target, recentlyDispatchedByHash);
+            }
+            for (const [hash, ts] of recentlyDispatchedByHash) {
+                if (now - ts > RECENT_REPAIR_DISPATCH_TTL_MS) {
+                    recentlyDispatchedByHash.delete(hash);
+                }
+            }
+            const filteredEntries = options?.bypassRecentDedupe === true
+                ? new Map(entries)
+                : new Map();
+            if (options?.bypassRecentDedupe !== true) {
+                for (const [hash, entry] of entries) {
+                    const prev = recentlyDispatchedByHash.get(hash);
+                    if (prev != null && now - prev <= RECENT_REPAIR_DISPATCH_TTL_MS) {
+                        continue;
+                    }
+                    recentlyDispatchedByHash.set(hash, now);
+                    filteredEntries.set(hash, entry);
+                }
+            }
+            else {
+                for (const hash of entries.keys()) {
+                    recentlyDispatchedByHash.set(hash, now);
+                }
+            }
+            if (filteredEntries.size === 0) {
+                return;
+            }
+            const run = () => {
+                // For force-fresh churn repair we intentionally bypass rateless IBLT and
+                // use simple hash-based sync. This path is a directed "push these hashes
+                // to that peer" recovery flow; using simple sync here avoids occasional
+                // single-hash gaps seen with IBLT-oriented maybe-sync batches under churn.
+                if (options?.forceFreshDelivery &&
+                    this.syncronizer instanceof RatelessIBLTSynchronizer) {
+                    return Promise.resolve(this.syncronizer.simple.onMaybeMissingEntries({
+                        entries: filteredEntries,
+                        targets: [target],
+                    })).catch((error) => logger.error(error));
+                }
+                return Promise.resolve(this.syncronizer.onMaybeMissingEntries({
+                    entries: filteredEntries,
+                    targets: [target],
+                })).catch((error) => logger.error(error));
+            };
+            const retrySchedule = options?.retryScheduleMs && options.retryScheduleMs.length > 0
+                ? options.retryScheduleMs
+                : options?.forceFreshDelivery
+                    ? FORCE_FRESH_RETRY_SCHEDULE_MS
+                    : [0];
+            for (const delayMs of retrySchedule) {
+                if (delayMs === 0) {
+                    void run();
+                    continue;
+                }
+                const timer = setTimeout(() => {
+                    this._repairRetryTimers.delete(timer);
+                    if (this.closed) {
+                        return;
+                    }
+                    void run();
+                }, delayMs);
+                timer.unref?.();
+                this._repairRetryTimers.add(timer);
+            }
+        }
+        scheduleRepairSweep(options) {
+            if (options.forceFreshDelivery) {
+                this._repairSweepForceFreshPending = true;
+            }
+            for (const peer of options.addedPeers) {
+                this._repairSweepAddedPeersPending.add(peer);
+            }
+            if (!this._repairSweepRunning && !this.closed) {
+                this._repairSweepRunning = true;
+                void this.runRepairSweep();
+            }
+        }
+        async runRepairSweep() {
+            try {
+                while (!this.closed) {
+                    const forceFreshDelivery = this._repairSweepForceFreshPending;
+                    const addedPeers = new Set(this._repairSweepAddedPeersPending);
+                    this._repairSweepForceFreshPending = false;
+                    this._repairSweepAddedPeersPending.clear();
+                    if (!forceFreshDelivery && addedPeers.size === 0) {
+                        return;
+                    }
+                    const pendingByTarget = new Map();
+                    const flushTarget = (target) => {
+                        const entries = pendingByTarget.get(target);
+                        if (!entries || entries.size === 0) {
+                            return;
+                        }
+                        const isJoinWarmupTarget = addedPeers.has(target);
+                        const bypassRecentDedupe = isJoinWarmupTarget || forceFreshDelivery;
+                        this.dispatchMaybeMissingEntries(target, entries, {
+                            bypassRecentDedupe,
+                            retryScheduleMs: isJoinWarmupTarget
+                                ? JOIN_WARMUP_RETRY_SCHEDULE_MS
+                                : undefined,
+                            forceFreshDelivery,
+                        });
+                        pendingByTarget.delete(target);
+                    };
+                    const queueEntryForTarget = (target, entry) => {
+                        let set = pendingByTarget.get(target);
+                        if (!set) {
+                            set = new Map();
+                            pendingByTarget.set(target, set);
+                        }
+                        if (set.has(entry.hash)) {
+                            return;
+                        }
+                        set.set(entry.hash, entry);
+                        if (set.size >= this.repairSweepTargetBufferSize) {
+                            flushTarget(target);
+                        }
+                    };
+                    const iterator = this.entryCoordinatesIndex.iterate({});
+                    try {
+                        while (!this.closed && !iterator.done()) {
+                            const entries = await iterator.next(REPAIR_SWEEP_ENTRY_BATCH_SIZE);
+                            for (const entry of entries) {
+                                const entryReplicated = entry.value;
+                                const currentPeers = await this.findLeaders(entryReplicated.coordinates, entryReplicated, { roleAge: 0 });
+                                if (forceFreshDelivery) {
+                                    for (const [currentPeer] of currentPeers) {
+                                        if (currentPeer === this.node.identity.publicKey.hashcode()) {
+                                            continue;
+                                        }
+                                        queueEntryForTarget(currentPeer, entryReplicated);
+                                    }
+                                }
+                                if (addedPeers.size > 0) {
+                                    for (const peer of addedPeers) {
+                                        if (currentPeers.has(peer)) {
+                                            queueEntryForTarget(peer, entryReplicated);
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    finally {
+                        await iterator.close();
+                    }
+                    for (const target of [...pendingByTarget.keys()]) {
+                        flushTarget(target);
+                    }
+                }
+            }
+            catch (error) {
+                if (!isNotStartedError(error)) {
+                    logger.error(`Repair sweep failed: ${error?.message ?? error}`);
+                }
+            }
+            finally {
+                this._repairSweepRunning = false;
+                if (!this.closed &&
+                    (this._repairSweepForceFreshPending ||
+                        this._repairSweepAddedPeersPending.size > 0)) {
+                    this._repairSweepRunning = true;
+                    void this.runRepairSweep();
+                }
+            }
+        }
         async pruneDebouncedFnAddIfNotKeeping(args) {
             if (!this.keep || !(await this.keep(args.value.entry))) {
                 return this.pruneDebouncedFn.add(args);
@@ -1693,6 +1964,11 @@ let SharedLog = (() => {
             this._replicationInfoBlockedPeers = new Set();
             this._replicationInfoRequestByPeer = new Map();
             this._replicationInfoApplyQueueByPeer = new Map();
+            this._repairRetryTimers = new Set();
+            this._recentRepairDispatch = new Map();
+            this._repairSweepRunning = false;
+            this._repairSweepForceFreshPending = false;
+            this._repairSweepAddedPeersPending = new Set();
             this.coordinateToHash = new Cache({ max: 1e6, ttl: 1e4 });
             this.recentlyRebalanced = new Cache({ max: 1e4, ttl: 1e5 });
             this.uniqueReplicators = new Set();
@@ -1702,6 +1978,7 @@ let SharedLog = (() => {
             this.oldestOpenTime = this.openTime;
             this.distributionDebounceTime =
                 options?.distributionDebounceTime || DEFAULT_DISTRIBUTION_DEBOUNCE_TIME; // expect > 0
+            this.repairSweepTargetBufferSize = toPositiveInteger(options?.sync?.repairSweepTargetBufferSize, REPAIR_SWEEP_TARGET_BUFFER_SIZE, "sync.repairSweepTargetBufferSize");
             this.timeUntilRoleMaturity =
                 options?.timeUntilRoleMaturity ?? WAIT_FOR_ROLE_MATURITY;
             this.waitForReplicatorTimeout =
@@ -2298,6 +2575,14 @@ let SharedLog = (() => {
             clearInterval(this.interval);
             this.node.services.pubsub.removeEventListener("subscribe", this._onSubscriptionFn);
             this.node.services.pubsub.removeEventListener("unsubscribe", this._onUnsubscriptionFn);
+            for (const timer of this._repairRetryTimers) {
+                clearTimeout(timer);
+            }
+            this._repairRetryTimers.clear();
+            this._recentRepairDispatch.clear();
+            this._repairSweepRunning = false;
+            this._repairSweepForceFreshPending = false;
+            this._repairSweepAddedPeersPending.clear();
             for (const [_k, v] of this._pendingDeletes) {
                 v.clear();
                 v.promise.resolve(); // TODO or reject?
@@ -3219,19 +3504,33 @@ let SharedLog = (() => {
         async _waitForReplicators(cursors, entry, waitFor, options = { timeout: this.waitForReplicatorTimeout }) {
             const timeout = options.timeout ?? this.waitForReplicatorTimeout;
             return new Promise((resolve, reject) => {
+                let settled = false;
                 const removeListeners = () => {
                     this.events.removeEventListener("replication:change", roleListener);
                     this.events.removeEventListener("replicator:mature", roleListener); // TODO replication:change event  ?
                     this._closeController.signal.removeEventListener("abort", abortListener);
                 };
-                const abortListener = () => {
+                const settleResolve = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
                     removeListeners();
                     clearTimeout(timer);
-                    resolve(false);
+                    resolve(value);
                 };
-                const timer = setTimeout(async () => {
+                const settleReject = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
                     removeListeners();
-                    resolve(false);
+                    clearTimeout(timer);
+                    reject(error);
+                };
+                const abortListener = () => {
+                    settleResolve(false);
+                };
+                const timer = setTimeout(async () => {
+                    settleResolve(false);
                 }, timeout);
                 const check = async () => {
                     let leaderKeys = new Set();
@@ -3251,17 +3550,20 @@ let SharedLog = (() => {
                         }
                     }
                     options?.onLeader && leaderKeys.forEach(options.onLeader);
-                    removeListeners();
-                    clearTimeout(timer);
-                    resolve(leaders);
+                    settleResolve(leaders);
+                };
+                const runCheck = () => {
+                    void check().catch((error) => {
+                        settleReject(error);
+                    });
                 };
                 const roleListener = () => {
-                    check();
+                    runCheck();
                 };
                 this.events.addEventListener("replication:change", roleListener); // TODO replication:change event  ?
                 this.events.addEventListener("replicator:mature", roleListener); // TODO replication:change event  ?
                 this._closeController.signal.addEventListener("abort", abortListener);
-                check();
+                runCheck();
             });
         }
         async createCoordinates(entry, minReplicas) {
@@ -3386,8 +3688,8 @@ let SharedLog = (() => {
             const roleAge = options?.roleAge ?? (await this.getDefaultMinRoleAge()); // TODO -500 as is added so that i f someone else is just as new as us, then we treat them as mature as us. without -500 we might be slower syncing if two nodes starts almost at the same time
             const selfHash = this.node.identity.publicKey.hashcode();
             // Prefer `uniqueReplicators` (replicator cache) as soon as it has any data.
-            // Falling back to live pubsub subscribers can include non-replicators and can
-            // break delivery/availability when writers are not directly connected.
+            // If it is still warming up (for example, only contains self), supplement with
+            // current subscribers until we have enough candidates for this decision.
             let peerFilter = undefined;
             const selfReplicating = await this.isReplicating();
             if (this.uniqueReplicators.size > 0) {
@@ -3398,6 +3700,23 @@ let SharedLog = (() => {
                 else {
                     peerFilter.delete(selfHash);
                 }
+                try {
+                    const subscribers = await this._getTopicSubscribers(this.topic);
+                    if (subscribers && subscribers.length > 0) {
+                        for (const subscriber of subscribers) {
+                            peerFilter.add(subscriber.hashcode());
+                        }
+                        if (selfReplicating) {
+                            peerFilter.add(selfHash);
+                        }
+                        else {
+                            peerFilter.delete(selfHash);
+                        }
+                    }
+                }
+                catch {
+                    // Best-effort only; keep current peerFilter.
+                }
             }
             else {
                 try {
@@ -3505,9 +3824,20 @@ let SharedLog = (() => {
                 this._replicationInfoBlockedPeers.add(peerHash);
             }
             if (!subscribed) {
+                const wasReplicator = this.uniqueReplicators.has(peerHash);
+                try {
+                    // Unsubscribe can race with the peer's final replication reset message.
+                    // Proactively evict its ranges so leader selection doesn't keep stale owners.
+                    await this.removeReplicator(publicKey, { noEvent: true });
+                }
+                catch (error) {
+                    if (!isNotStartedError(error)) {
+                        throw error;
+                    }
+                }
                 // Emit replicator:leave at most once per (join -> leave) transition, even if we
                 // concurrently process unsubscribe + replication reset messages for the same peer.
-                const stoppedTransition = this.uniqueReplicators.delete(peerHash);
+                const stoppedTransition = wasReplicator;
                 this._replicatorJoinEmitted.delete(peerHash);
                 this.cancelReplicationInfoRequests(peerHash);
                 this.removePeerFromGidPeerHistory(peerHash);
@@ -3876,14 +4206,79 @@ let SharedLog = (() => {
                 ? changeOrChanges
                 : [changeOrChanges];
             const changes = batchedChanges.flat();
+            const selfHash = this.node.identity.publicKey.hashcode();
             // On removed ranges (peer leaves / shrink), gid-level history can hide
             // per-entry gaps. Force a fresh delivery pass for reassigned entries.
-            const forceFreshDelivery = changes.some((change) => change.type === "removed");
+            const forceFreshDelivery = changes.some((change) => change.type === "removed" && change.range.hash !== selfHash);
             const gidPeersHistorySnapshot = new Map();
+            const dedupeCutoff = Date.now() - RECENT_REPAIR_DISPATCH_TTL_MS;
+            for (const [target, hashes] of this._recentRepairDispatch) {
+                for (const [hash, ts] of hashes) {
+                    if (ts <= dedupeCutoff) {
+                        hashes.delete(hash);
+                    }
+                }
+                if (hashes.size === 0) {
+                    this._recentRepairDispatch.delete(target);
+                }
+            }
             const changed = false;
+            const replacedPeers = new Set();
+            for (const change of changes) {
+                if (change.type === "replaced" && change.range.hash !== selfHash) {
+                    replacedPeers.add(change.range.hash);
+                }
+            }
+            const addedPeers = new Set();
+            for (const change of changes) {
+                if (change.type === "added" || change.type === "replaced") {
+                    const hash = change.range.hash;
+                    if (hash !== selfHash) {
+                        // Range updates can reassign entries to an existing peer shortly after it
+                        // already received a subset. Avoid suppressing legitimate follow-up repair.
+                        this._recentRepairDispatch.delete(hash);
+                    }
+                }
+                if (change.type === "added") {
+                    const hash = change.range.hash;
+                    if (hash !== selfHash && !replacedPeers.has(hash)) {
+                        addedPeers.add(hash);
+                    }
+                }
+            }
             try {
                 const uncheckedDeliver = new Map();
-                for await (const entryReplicated of toRebalance(changes, this.entryCoordinatesIndex, this.recentlyRebalanced)) {
+                const flushUncheckedDeliverTarget = (target) => {
+                    const entries = uncheckedDeliver.get(target);
+                    if (!entries || entries.size === 0) {
+                        return;
+                    }
+                    const isJoinWarmupTarget = addedPeers.has(target);
+                    const bypassRecentDedupe = isJoinWarmupTarget || forceFreshDelivery;
+                    this.dispatchMaybeMissingEntries(target, entries, {
+                        bypassRecentDedupe,
+                        retryScheduleMs: isJoinWarmupTarget
+                            ? JOIN_WARMUP_RETRY_SCHEDULE_MS
+                            : undefined,
+                        forceFreshDelivery,
+                    });
+                    uncheckedDeliver.delete(target);
+                };
+                const queueUncheckedDeliver = (target, entry) => {
+                    let set = uncheckedDeliver.get(target);
+                    if (!set) {
+                        set = new Map();
+                        uncheckedDeliver.set(target, set);
+                    }
+                    if (set.has(entry.hash)) {
+                        return;
+                    }
+                    set.set(entry.hash, entry);
+                    if (set.size >= this.repairSweepTargetBufferSize) {
+                        flushUncheckedDeliverTarget(target);
+                    }
+                };
+                for await (const entryReplicated of toRebalance(changes, this.entryCoordinatesIndex, this.recentlyRebalanced, { forceFresh: forceFreshDelivery })) {
                     if (this.closed) {
                         break;
                     }
@@ -3909,14 +4304,7 @@ let SharedLog = (() => {
                             continue;
                         }
                         if (!oldPeersSet?.has(currentPeer)) {
-                            let set = uncheckedDeliver.get(currentPeer);
-                            if (!set) {
-                                set = new Map();
-                                uncheckedDeliver.set(currentPeer, set);
-                            }
-                            if (!set.has(entryReplicated.hash)) {
-                                set.set(entryReplicated.hash, entryReplicated);
-                            }
+                            queueUncheckedDeliver(currentPeer, entryReplicated);
                         }
                     }
                     if (oldPeersSet) {
@@ -3942,11 +4330,13 @@ let SharedLog = (() => {
                         this.removePruneRequestSent(entryReplicated.hash);
                     }
                 }
-                for (const [target, entries] of uncheckedDeliver) {
-                    this.syncronizer.onMaybeMissingEntries({
-                        entries,
-                        targets: [target],
-                    });
+                if (forceFreshDelivery || addedPeers.size > 0) {
+                    // Schedule a coalesced background sweep for churn/join windows instead of
+                    // scanning the whole index synchronously on each replication change.
+                    this.scheduleRepairSweep({ forceFreshDelivery, addedPeers });
+                }
+                for (const target of [...uncheckedDeliver.keys()]) {
+                    flushUncheckedDeliverTarget(target);
                 }
                 return changed;
             }
@@ -3965,6 +4355,7 @@ let SharedLog = (() => {
             }
             const fromHash = evt.detail.from.hashcode();
             this._replicationInfoBlockedPeers.add(fromHash);
+            this._recentRepairDispatch.delete(fromHash);
             // Keep a per-peer timestamp watermark when we observe an unsubscribe. This
             // prevents late/out-of-order replication-info messages from re-introducing
             // stale segments for a peer that has already left the topic.
@@ -3982,7 +4373,7 @@ let SharedLog = (() => {
             }
             this.remoteBlocks.onReachable(evt.detail.from);
             this._replicationInfoBlockedPeers.delete(evt.detail.from.hashcode());
-            return this.handleSubscriptionChange(evt.detail.from, evt.detail.topics, true);
+            await this.handleSubscriptionChange(evt.detail.from, evt.detail.topics, true);
         }
         async rebalanceParticipation() {
             // update more participation rate to converge to the average expected rate or bounded by