@peerbit/shared-log 16.0.10 → 16.0.12

package/dist/src/index.js

@@ -405,6 +405,8 @@ 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 TOPIC_SUBSCRIBERS_CACHE_TTL_MS = 250;
+const LOCAL_REACHABLE_PEERS_CACHE_TTL_MS = 250;
+const LOCAL_REACHABLE_PEERS_MAX = 64;
 const LEADER_SELECTION_CONTEXT_CACHE_TTL_MS = 50;
 // Leader-plan results are invalidated structurally (replication:change,
 // replicator:mature, subscriber changes). The TTL bounds wall-clock maturity
@@ -427,6 +429,8 @@ const ADAPTIVE_REBALANCE_MIN_IDLE_AFTER_LOCAL_APPEND_MS = 10_000;
 // raw exchange message size the receive path is tuned for.
 const LIVE_RAW_GOSSIP_MAX_ENTRIES = 256;
 const LIVE_RAW_GOSSIP_MAX_BYTES = 128 * 1024;
+const GID_PEER_HISTORY_CLEANUP_BATCH_SIZE = 256;
+const GID_PEER_HISTORY_CLEANUP_PENDING_CAPACITY = 4096;
 const DEFAULT_DISTRIBUTION_DEBOUNCE_TIME = 500;
 const RECENT_REPAIR_DISPATCH_TTL_MS = 5_000;
 const REPAIR_SWEEP_ENTRY_BATCH_SIZE = 1_000;
@@ -678,17 +682,19 @@ let SharedLog = (() => {
         // GROWTH SHAPE. Rows are released by `deleteGidPeerHistory` on the two prune
         // paths, by `removePeerFromGidPeerHistory` once a gid's last peer drops (the
         // routine disconnect outcome), by `rebalanceAll({ clearCache: true })`, and
-        // wholesale on close/reset. Nothing on the TRIM path releases a row, so a
-        // node that bounds its log with trim rather than prune accumulates one row
-        // per distinct gid it has ever held. A gid names a graph, not an entry: an
+        // wholesale on close/reset. Trim now carries compact distinct removed-gid
+        // facts beside its hash-only result. After the lower mutation commits, a
+        // coalesced cleanup checks authoritative local-head liveness and drops a row
+        // only when no sibling remains. A gid names a graph, not an entry: an
         // entry with `meta.next` inherits `min(next.meta.gid)` (see
         // packages/log/src/entry-v0.ts), so document updates fold into the gid of
         // the first put and the row count tracks distinct chain roots -- distinct
         // document ids -- rather than entry count. Insert-only workloads mint a
-        // fresh gid per append and so do grow one row per entry. Merges are a
-        // smaller second source: when a join links two graphs the losing entries
-        // keep their own `meta.gid` on disk, and shared-log does not subscribe to
-        // the log's `onGidRemoved`, so the shadowed gid's row lingers too.
+        // fresh gid per append and so do grow one row per entry. Merge-shadowed gids
+        // are a separate, smaller source that still needs a fast-path-compatible
+        // post-commit metadata seam. Registering the lower log's `onGidRemoved` hook
+        // here would disable native prepared, commit-only, and batch append paths, so
+        // this bounded slice deliberately addresses trim only.
         //
         // WHY TRIM DOES NOT SIMPLY CALL `deleteGidPeerHistory` AS WELL. Both prune
         // callers delete a whole row from a single entry's gid, and under the
@@ -706,10 +712,11 @@ let SharedLog = (() => {
         // on the common path, paying for the freed memory in repeated re-delivery of
         // entries that are still here. That trade is not worth it.
         //
-        // Bounding this correctly requires a per-gid count of locally held entries,
-        // dropping the row only when it reaches zero -- a real reverse index, not a
-        // one-line delete. Deliberately not built: the growth is bounded by distinct
-        // gids, and the cheap version is a bandwidth regression.
+        // Cleanup work is coalesced, checked in bounded batches, and capped at 4096
+        // pending gids. Saturation forgets the overflowing suppression row
+        // immediately. That bounded fallback can cause redundant delivery for a live
+        // sibling, but missing history is deliberately correctness-safe as described
+        // above; it cannot affect ownership, quorum, or retained data.
         //
         // Existing, deliberate imprecision: under the time domain the coordinate is
         // `meta.clock.timestamp.wallTime` (replication-domain-time.ts) and is
@@ -717,6 +724,7 @@ let SharedLog = (() => {
         // and prune's whole-row delete is already over-eager there. The cost is the
         // same bounded extra traffic, never a wrong prune.
         _gidPeersHistory;
+        _gidPeerHistoryCleanupState;
         _onSubscriptionFn;
         _onUnsubscriptionFn;
         _subscriptionChangeCallbacks;
@@ -1729,6 +1737,7 @@ let SharedLog = (() => {
         _appendBackfillPendingByTarget;
         _repairMetrics;
         _topicSubscribersCache;
+        _localReachablePeerHashesCache;
         _leaderSelectionContextCache;
         _leaderPlanCache;
         // Sync capability bits advertised by peers (SyncCapabilitiesMessage), keyed
@@ -1960,6 +1969,7 @@ let SharedLog = (() => {
             this._receiveHandlerDrainByPeer = new Map();
             this._openingSyncCapabilitiesByPeer = new Map();
             this._gidPeersHistory = new Map();
+            this.resetGidPeerHistoryCleanupState();
             this._repairRetryTimers = new Set();
             this._recentRepairDispatch = new Map();
             this._repairSweepRunning = false;
@@ -1979,6 +1989,7 @@ let SharedLog = (() => {
             this._joinAuthoritativeRepairPeersByDelay = new Map();
             this._appendBackfillPendingByTarget = new Map();
             this._topicSubscribersCache = new Map();
+            this._localReachablePeerHashesCache = new Map();
             this._peerSyncCapabilities = new Map();
             this._peerSyncCapabilitySessions = new Map();
             this._peerSyncCapabilityTimestamps = new Map();
@@ -3045,6 +3056,88 @@ let SharedLog = (() => {
             return (fanoutService?.getPublicKey?.(hash) ??
                 this.node.services.pubsub.getPublicKey(hash));
         }
+        async _getLocalReachablePeerHashes(topic) {
+            const cache = (this._localReachablePeerHashesCache ??= new Map());
+            const cached = cache.get(topic);
+            if (cached?.hashes && cached.expiresAt > Date.now()) {
+                return cached.hashes.slice();
+            }
+            if (cached?.inFlight) {
+                return (await cached.inFlight).slice();
+            }
+            const entry = { expiresAt: 0 };
+            const inFlight = (async () => {
+                const selfHash = this.node.identity.publicKey.hashcode();
+                const hashes = [];
+                const seen = new Set();
+                const addHash = (hash) => {
+                    if (typeof hash !== "string" ||
+                        hash.length === 0 ||
+                        hash === selfHash ||
+                        seen.has(hash) ||
+                        hashes.length >= LOCAL_REACHABLE_PEERS_MAX) {
+                        return;
+                    }
+                    seen.add(hash);
+                    hashes.push(hash);
+                };
+                const pubsub = this.node.services.pubsub;
+                const peerMap = pubsub?.peers;
+                if (peerMap?.entries) {
+                    for (const [hash, peer] of peerMap.entries()) {
+                        addHash(peer?.publicKey?.hashcode?.());
+                        addHash(hash);
+                        if (hashes.length >= LOCAL_REACHABLE_PEERS_MAX)
+                            break;
+                    }
+                }
+                if (hashes.length < LOCAL_REACHABLE_PEERS_MAX) {
+                    const connectionManager = pubsub?.components?.connectionManager;
+                    for (const conn of connectionManager?.getConnections?.() ?? []) {
+                        const peerId = conn?.remotePeer;
+                        if (!peerId)
+                            continue;
+                        try {
+                            addHash(getPublicKeyFromPeerId(peerId).hashcode());
+                        }
+                        catch {
+                            // Best-effort only.
+                        }
+                        if (hashes.length >= LOCAL_REACHABLE_PEERS_MAX)
+                            break;
+                    }
+                }
+                if (hashes.length < LOCAL_REACHABLE_PEERS_MAX) {
+                    try {
+                        for (const subscriber of (await pubsub.getSubscribers(topic)) ?? []) {
+                            addHash(subscriber?.hashcode?.());
+                            if (hashes.length >= LOCAL_REACHABLE_PEERS_MAX)
+                                break;
+                        }
+                    }
+                    catch {
+                        // Local reachability is best-effort.
+                    }
+                }
+                return hashes;
+            })();
+            entry.inFlight = inFlight;
+            cache.set(topic, entry);
+            try {
+                const hashes = await inFlight;
+                if (cache.get(topic) === entry) {
+                    entry.hashes = hashes;
+                    entry.expiresAt = Date.now() + LOCAL_REACHABLE_PEERS_CACHE_TTL_MS;
+                    entry.inFlight = undefined;
+                }
+                return hashes.slice();
+            }
+            catch (error) {
+                if (cache.get(topic) === entry)
+                    cache.delete(topic);
+                throw error;
+            }
+        }
         async _getTopicSubscribers(topic) {
             const cached = this._topicSubscribersCache.get(topic);
             if (cached && cached.expiresAt > Date.now()) {
@@ -3158,6 +3251,7 @@ let SharedLog = (() => {
                 if (!topic)
                     continue;
                 this._topicSubscribersCache.delete(topic);
+                this._localReachablePeerHashesCache?.delete(topic);
             }
             this.invalidateLeaderSelectionContextCache();
         }
@@ -6728,6 +6822,8 @@ let SharedLog = (() => {
                 return {
                     entry: result.entry,
                     removed: result.removed,
+                    removedHashes: result.removedHashes,
+                    removedGids: result.removedGids,
                     appendCommit: nativePreparedCommit,
                 };
             }
@@ -6777,6 +6873,8 @@ let SharedLog = (() => {
             return {
                 entry: result.entry,
                 removed: result.removed,
+                removedHashes: result.removedHashes,
+                removedGids: result.removedGids,
                 appendCommit: this.createPreparedLocalAppendCommitFromFacts(result.appendFacts, nativeAppendPlan),
             };
         }
@@ -6792,6 +6890,7 @@ let SharedLog = (() => {
                 return undefined;
             }
             const plannedCoordinateDeleteHashes = result.change?.removed.map((entry) => entry.hash) ??
+                result.removedHashes ??
                 result.removed.map((entry) => entry.hash);
             const nativeAppendPlan = await this.planNativeLocalAppendFacts(result.appendFacts, properties.minReplicasValue, {
                 deleteHashes: plannedCoordinateDeleteHashes.length > 0
@@ -6811,6 +6910,8 @@ let SharedLog = (() => {
                     })
                     : this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(result.appendFacts, result.removed, () => this.materializePreparedAppendResultEntry(result), {
                         forgetNativeCoordinates: !nativeAppendPlan.committedNativeCoordinateDeletes,
+                        removedHashes: result.removedHashes,
+                        removedGids: result.removedGids,
                         ownershipLifecycleController,
                     });
                 await this._coordinates.persistPreparedCoordinate({
@@ -7286,6 +7387,7 @@ let SharedLog = (() => {
                             },
                             removed: prepared.removed,
                             removedHashes: prepared.removedHashes,
+                            removedGids: prepared.removedGids,
                             appendCommit,
                         };
                     };
@@ -7308,7 +7410,10 @@ let SharedLog = (() => {
                 // `rollback` can no longer fire. Nothing downstream rolls back
                 // (the retire below only warns), so the token is terminal here.
                 this._coordinates.settleResidentCoordinateSnapshot(lowerPublicationRollback?.coordinateEntries);
-                this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(prepared.appendFacts, prepared.removed, prepared.materializeEntry, { removedHashes: prepared.removedHashes });
+                this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(prepared.appendFacts, prepared.removed, prepared.materializeEntry, {
+                    removedHashes: prepared.removedHashes,
+                    removedGids: prepared.removedGids,
+                });
                 try {
                     await this.completeNativeStrictDurableTransaction(nativeStrictTransaction);
                 }
@@ -7451,6 +7556,10 @@ let SharedLog = (() => {
                     const useTrimmedHashesOnly = properties?.resolveTrimmedEntries === false;
                     const nativeTrimmedHashes = backboneAppend.trimmedHashes ??
                         backboneAppend.trimmed.map((entry) => entry.hash);
+                    const nativeTrimmedGids = backboneAppend.trimmedGids ??
+                        (backboneAppend.trimmed.length > 0
+                            ? backboneAppend.trimmed.map((entry) => entry.gid)
+                            : undefined);
                     const committedHash = backboneAppend.entry.cid ?? backboneAppend.entry.hash;
                     const committedNext = backboneAppend.entry.next ?? next;
                     nativeCoordinateRollback =
@@ -7511,6 +7620,9 @@ let SharedLog = (() => {
                         trimmedEntryHashes: useTrimmedHashesOnly
                             ? backboneAppend.trimmedHashes
                             : undefined,
+                        trimmedEntryGids: useTrimmedHashesOnly
+                            ? nativeTrimmedGids
+                            : undefined,
                         nativeBlocksDeleted: commitBlocksInBackbone,
                         nativeDeleteCleanupToken,
                         documentPreviousContext: backboneAppend.documentPreviousContext,
@@ -7659,6 +7771,7 @@ let SharedLog = (() => {
                             },
                             removed: prepared.removed,
                             removedHashes: prepared.removedHashes,
+                            removedGids: prepared.removedGids,
                             appendCommit,
                         };
                     };
@@ -7751,6 +7864,7 @@ let SharedLog = (() => {
                     this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(prepared.appendFacts, prepared.removed, prepared.materializeEntry, {
                         forgetNativeCoordinates: false,
                         removedHashes: prepared.removedHashes,
+                        removedGids: prepared.removedGids,
                     });
                     try {
                         await this.completeNativeStrictDurableTransaction(nativeStrictTransaction);
@@ -7789,6 +7903,7 @@ let SharedLog = (() => {
             if (this.shouldDeferHeadCoordinatePersistence(options)) {
                 const deferredCoordinateDeleteHashes = this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(result.appendFacts, result.removed, result.materializeEntry, {
                     removedHashes: result.removedHashes,
+                    removedGids: result.removedGids,
                     ownershipLifecycleController,
                 });
                 const deleteHashes = deferredCoordinateDeleteHashes &&
@@ -7809,6 +7924,7 @@ let SharedLog = (() => {
                             },
                             removed: result.removed,
                             removedHashes: result.removedHashes,
+                            removedGids: result.removedGids,
                             appendCommit: this.createPreparedLocalAppendCommitFromFacts(result.appendFacts),
                         };
                     });
@@ -7819,6 +7935,7 @@ let SharedLog = (() => {
                     },
                     removed: result.removed,
                     removedHashes: result.removedHashes,
+                    removedGids: result.removedGids,
                     appendCommit: this.createPreparedLocalAppendCommitFromFacts(result.appendFacts),
                 };
             }
@@ -7867,6 +7984,7 @@ let SharedLog = (() => {
                 },
                 removed: result.removed,
                 removedHashes: result.removedHashes,
+                removedGids: result.removedGids,
                 appendCommit: nativePreparedCommit,
             };
         }
@@ -7894,6 +8012,7 @@ let SharedLog = (() => {
                     : this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(result.appendFacts, result.removed, () => this.materializePreparedAppendResultEntry(result), {
                         forgetNativeCoordinates: !nativeAppendPlan.committedNativeCoordinateDeletes,
                         removedHashes: result.removedHashes,
+                        removedGids: result.removedGids,
                         ownershipLifecycleController,
                     });
                 await this._coordinates.persistPreparedCoordinateNativeTransaction({
@@ -7949,6 +8068,8 @@ let SharedLog = (() => {
                         return result.entry;
                     },
                     removed: result.removed,
+                    removedHashes: result.removedHashes,
+                    removedGids: result.removedGids,
                     appendCommit: nativePreparedCommit,
                 };
             }
@@ -7958,6 +8079,7 @@ let SharedLog = (() => {
                 deferredCoordinateDeleteHashes =
                     this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(result.appendFacts, result.removed, result.materializeEntry, {
                         removedHashes: result.removedHashes,
+                        removedGids: result.removedGids,
                         ownershipLifecycleController,
                     });
                 nativeAppendPlan = await this.planNativeLocalAppendFacts(result.appendFacts, minReplicasValue, undefined, ownershipLifecycleController);
@@ -8000,6 +8122,7 @@ let SharedLog = (() => {
                 },
                 removed: result.removed,
                 removedHashes: result.removedHashes,
+                removedGids: result.removedGids,
                 appendCommit: this.createPreparedLocalAppendCommitFromFacts(result.appendFacts, nativeAppendPlan),
             };
         }
@@ -8198,6 +8321,10 @@ let SharedLog = (() => {
                         getBytes: (hash) => backbone.blocks.get(hash),
                         nativeIndexMutationLockOwner: nativeStrictTransaction?.lowerHashMutationLockOwner,
                         trimmedEntryHashes: append.trimmedHashes,
+                        trimmedEntryGids: append.trimmedGids ??
+                            (append.trimmed.length > 0
+                                ? append.trimmed.map((entry) => entry.gid)
+                                : undefined),
                         nativeBlocksDeleted: true,
                         nativeDeleteCleanupToken,
                         documentTrimmedHeadsProcessed: append.documentTrimmedHeadsProcessed,
@@ -8428,6 +8555,10 @@ let SharedLog = (() => {
                 this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(facts, [], appended.materializeEntries[i], {
                     forgetNativeCoordinates: false,
                     removedHashes: plannedCoordinateDeleteHashes,
+                    removedGids: backboneAppend.trimmedGids ??
+                        (backboneAppend.trimmed.length > 0
+                            ? backboneAppend.trimmed.map((entry) => entry.gid)
+                            : undefined),
                 });
                 if (!runtimeOnlyCoordinates && this.remoteBlocks.hasNotifyStoredHook()) {
                     this.remoteBlocks.notifyStoredDeferred(facts.hash);
@@ -9362,6 +9493,7 @@ let SharedLog = (() => {
             this._appendBackfillPendingByTarget = new Map();
             this._repairMetrics = createRepairMetrics();
             this._topicSubscribersCache = new Map();
+            this._localReachablePeerHashesCache = new Map();
             this._leaderSelectionContextCache = undefined;
             this._leaderPlanCache = new LeaderPlanCache({
                 max: LEADER_PLAN_CACHE_MAX,
@@ -9515,27 +9647,57 @@ let SharedLog = (() => {
                 // compatible eager path with bounded validation and storage budgets.
                 eagerBlocks: options?.eagerBlocks ?? false,
                 resolveProviders: async (cid, opts) => {
-                    // 1) tracker-backed provider directory (best-effort, bounded)
+                    const maxPeers = 8;
+                    const localCandidates = (await this.resolveCandidatePeersForHash(cid, {
+                        signal: opts?.signal,
+                        maxPeers,
+                    })) ?? [];
+                    if (opts?.signal?.aborted)
+                        return [];
+                    const locallyReachable = new Set(await this._getLocalReachablePeerHashes(this.topic));
+                    const confirmed = this._checkedPrune.getConfirmedReplicators(cid);
+                    const contacted = this._checkedPrune.getContactedReplicators(cid);
+                    const hasLiveCandidate = localCandidates.some((peer) => locallyReachable.has(peer) &&
+                        (confirmed?.has(peer) ||
+                            contacted?.has(peer) ||
+                            this.uniqueReplicators.has(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;
+                    }
+                    let directoryProviders = [];
                     try {
-                        const providers = await fanoutService?.queryProviders(blockProviderNamespace(cid), {
-                            want: 8,
-                            timeoutMs: 2_000,
-                            queryTimeoutMs: 500,
-                            bootstrapMaxPeers: 2,
-                            signal: opts?.signal,
-                        });
-                        if (providers && providers.length > 0)
-                            return providers;
+                        directoryProviders =
+                            (await fanoutService?.queryProviders(blockProviderNamespace(cid), {
+                                want: maxPeers,
+                                timeoutMs: 2_000,
+                                queryTimeoutMs: 500,
+                                bootstrapMaxPeers: 2,
+                                signal: opts?.signal,
+                            })) ?? [];
                     }
                     catch {
-                        // ignore discovery failures
+                        // Ignore discovery failures; local evidence remains usable.
+                    }
+                    const selected = [];
+                    const selectedSet = new Set();
+                    const add = (peer) => {
+                        if (!peer ||
+                            selectedSet.has(peer) ||
+                            selected.length >= maxPeers) {
+                            return;
+                        }
+                        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]);
                     }
-                    // 2) reuse the same per-hash / replicator / subscriber fallback used by
-                    // entry loads so block retries can widen beyond stale explicit hints.
-                    return ((await this.resolveCandidatePeersForHash(cid, {
-                        signal: opts?.signal,
-                        maxPeers: 8,
-                    })) ?? []);
+                    return selected;
                 },
                 watchProviders: fanoutService
                     ? (cid, opts) => fanoutService.watchProviders(blockProviderNamespace(cid), {
@@ -9572,6 +9734,7 @@ let SharedLog = (() => {
                 ],
             })) > 0;
             this._gidPeersHistory = new Map();
+            this.resetGidPeerHistoryCleanupState();
             const replicationChangeOwnershipLifecycleController = this.captureReplicationOwnershipLifecycle();
             let replicationChangeDebounceFn;
             replicationChangeDebounceFn = debounceAggregationChanges(async (change) => {
@@ -10566,70 +10729,82 @@ let SharedLog = (() => {
             if (options?.signal?.aborted)
                 return undefined;
             const maxPeers = options?.maxPeers ?? 8;
+            if (maxPeers <= 0)
+                return undefined;
             const self = this.node.identity.publicKey.hashcode();
             const seed = hashToSeed32(hash);
-            const hinted = this._checkedPrune.getConfirmedReplicators(hash);
-            if (hinted && hinted.size > 0) {
-                const peers = [...hinted].filter((p) => p !== self);
-                return peers.length > 0
-                    ? pickDeterministicSubset(peers, seed, maxPeers)
-                    : undefined;
-            }
+            // Replication/provider knowledge deliberately outlives a transport session.
+            // That is useful for repair, but it must not fill the bounded fetch target set
+            // with departed peers while a reachable holder is available. The local
+            // snapshot performs no tracker/provider discovery or key resolution.
+            const reachable = await this._getLocalReachablePeerHashes(this.topic);
+            if (options?.signal?.aborted)
+                return undefined;
+            const reachableSet = new Set(reachable);
+            const confirmed = this._checkedPrune.getConfirmedReplicators(hash);
             const contacted = this._checkedPrune.getContactedReplicators(hash);
-            if (contacted && contacted.size > 0) {
-                const peers = [...contacted].filter((p) => p !== self);
-                return peers.length > 0
-                    ? pickDeterministicSubset(peers, seed, maxPeers)
-                    : undefined;
-            }
-            let candidates;
-            const replicatorCandidates = [...this.uniqueReplicators].filter((p) => p !== self);
-            if (replicatorCandidates.length > 0) {
-                candidates = replicatorCandidates;
+            const evidenceTiers = [
+                confirmed ?? [],
+                contacted ?? [],
+                this.uniqueReplicators,
+            ];
+            // Peers supported by both current transport state and provider history are
+            // the strongest signal. Afterwards alternate live-only and historical-only
+            // evidence so either source can widen a saturated bounded set. Derive the
+            // live intersection from the bounded reachability snapshot; never clone or
+            // scan an unbounded historical replicator set per missing block.
+            const liveEvidenceTiers = [[], [], []];
+            for (const peer of reachable) {
+                if (confirmed?.has(peer))
+                    liveEvidenceTiers[0].push(peer);
+                else if (contacted?.has(peer))
+                    liveEvidenceTiers[1].push(peer);
+                else if (this.uniqueReplicators.has(peer))
+                    liveEvidenceTiers[2].push(peer);
+            }
+            const liveKnown = [];
+            for (let tier = 0; tier < liveEvidenceTiers.length; tier++) {
+                liveKnown.push(...pickDeterministicSubset(liveEvidenceTiers[tier], (seed ^ Math.imul(tier + 1, 0x9e3779b1)) >>> 0, maxPeers - liveKnown.length));
+                if (liveKnown.length >= maxPeers)
+                    break;
             }
-            else {
-                try {
-                    const subscribers = await this._getTopicSubscribers(this.topic);
-                    const subscriberCandidates = subscribers?.map((k) => k.hashcode()).filter((p) => p !== self) ?? [];
-                    candidates =
-                        subscriberCandidates.length > 0 ? subscriberCandidates : undefined;
-                }
-                catch {
-                    // Best-effort only.
-                }
-                if (!candidates || candidates.length === 0) {
-                    const peerMap = this.node.services.pubsub?.peers;
-                    if (peerMap?.keys) {
-                        candidates = [...peerMap.keys()];
+            const liveKnownSet = new Set(liveKnown);
+            const liveOnly = pickDeterministicSubset(reachable.filter((peer) => !liveKnownSet.has(peer)), (seed ^ 0x85ebca6b) >>> 0, maxPeers);
+            const historicalOnly = [];
+            const historicalSeen = new Set();
+            for (let tier = 0; tier < evidenceTiers.length; tier++) {
+                const available = [];
+                let inspected = 0;
+                for (const peer of evidenceTiers[tier]) {
+                    if (inspected++ >= LOCAL_REACHABLE_PEERS_MAX)
+                        break;
+                    if (!peer ||
+                        peer === self ||
+                        reachableSet.has(peer) ||
+                        historicalSeen.has(peer)) {
+                        continue;
                     }
+                    historicalSeen.add(peer);
+                    available.push(peer);
                 }
-                if (!candidates || candidates.length === 0) {
-                    const connectionManager = this.node.services.pubsub?.components
-                        ?.connectionManager;
-                    const connections = connectionManager?.getConnections?.() ?? [];
-                    const connectionHashes = [];
-                    for (const conn of connections) {
-                        const peerId = conn?.remotePeer;
-                        if (!peerId)
-                            continue;
-                        try {
-                            connectionHashes.push(getPublicKeyFromPeerId(peerId).hashcode());
-                        }
-                        catch {
-                            // Best-effort only.
-                        }
-                    }
-                    if (connectionHashes.length > 0) {
-                        candidates = connectionHashes;
-                    }
+                historicalOnly.push(...pickDeterministicSubset(available, (seed ^ Math.imul(tier + 5, 0x9e3779b1)) >>> 0, maxPeers - historicalOnly.length));
+                if (historicalOnly.length >= maxPeers)
+                    break;
+            }
+            const selected = liveKnown.slice(0, maxPeers);
+            let liveIndex = 0;
+            let historicalIndex = 0;
+            while (selected.length < maxPeers &&
+                (liveIndex < liveOnly.length || historicalIndex < historicalOnly.length)) {
+                if (liveIndex < liveOnly.length) {
+                    selected.push(liveOnly[liveIndex++]);
+                }
+                if (selected.length < maxPeers &&
+                    historicalIndex < historicalOnly.length) {
+                    selected.push(historicalOnly[historicalIndex++]);
                 }
             }
-            if (!candidates || candidates.length === 0)
-                return undefined;
-            const peers = candidates.filter((p) => p !== self);
-            if (peers.length === 0)
-                return undefined;
-            return pickDeterministicSubset(peers, seed, maxPeers);
+            return selected.length > 0 ? selected : undefined;
         }
         async getMemoryUsage() {
             return this.log.blocks.size();
@@ -10953,6 +11128,7 @@ let SharedLog = (() => {
             }
             const deferredCoordinateDeleteHashes = change.removed.map((removed) => removed.hash);
             this.onEntryRemovedHashes(deferredCoordinateDeleteHashes);
+            this.scheduleDeadGidPeerHistoryReclaim(change.removed.map((removed) => removed.meta.gid));
             if (options?.forgetNativeCoordinates === false) {
                 this._coordinates.forgetResidentCoordinateStateForHashes(deferredCoordinateDeleteHashes);
             }
@@ -10982,6 +11158,9 @@ let SharedLog = (() => {
                 ? normalizedHashValues(removedHashes)
                 : removed.map((entry) => entry.hash);
             this.onEntryRemovedHashes(deferredCoordinateDeleteHashes);
+            this.scheduleDeadGidPeerHistoryReclaim(removed.length > 0
+                ? removed.map((entry) => entry.meta.gid)
+                : options?.removedGids);
             if (options?.forgetNativeCoordinates === false) {
                 this._coordinates.forgetResidentCoordinateStateForHashes(deferredCoordinateDeleteHashes);
             }
@@ -11001,8 +11180,128 @@ let SharedLog = (() => {
                 }
                 this.onEntryRemoved(removed.hash);
             }
+            this.scheduleDeadGidPeerHistoryReclaim(removedEntries.map((removed) => removed.meta.gid));
             return undefined;
         }
+        async reclaimDeadGidPeerHistory(gids, history = this._gidPeersHistory) {
+            if (!gids)
+                return;
+            const candidates = [...new Set(gids)].filter((gid) => history === this._gidPeersHistory && !!gid && history.has(gid));
+            if (candidates.length === 0)
+                return;
+            const hasHeads = await this.hasAnyHeadForGidSets(candidates.map((gid) => [gid]));
+            if (history !== this._gidPeersHistory)
+                return;
+            for (let index = 0; index < candidates.length; index++) {
+                const gid = candidates[index];
+                if (!hasHeads[index] && history.has(gid)) {
+                    this.deleteGidPeerHistory(gid);
+                }
+            }
+        }
+        resetGidPeerHistoryCleanupState() {
+            this._gidPeerHistoryCleanupState = {
+                history: this._gidPeersHistory,
+                tail: Promise.resolve(),
+                pending: new Set(),
+                draining: false,
+                highWater: 0,
+            };
+        }
+        scheduleDeadGidPeerHistoryReclaim(gids) {
+            if (!gids)
+                return;
+            const state = this._gidPeerHistoryCleanupState;
+            const history = state.history;
+            for (const gid of gids) {
+                if (!gid || !history.has(gid))
+                    continue;
+                if (state.pending.has(gid))
+                    continue;
+                if (state.pending.size >= GID_PEER_HISTORY_CLEANUP_PENDING_CAPACITY) {
+                    // History is only a suppression memo. Under sustained synchronous
+                    // production, forgetting an overflow row is the bounded, safe fallback:
+                    // it can cause redundant delivery but cannot affect ownership or data.
+                    this.deleteGidPeerHistory(gid);
+                    continue;
+                }
+                state.pending.add(gid);
+            }
+            state.highWater = Math.max(state.highWater, state.pending.size);
+            if (state.pending.size === 0)
+                return;
+            // A macrotask gate lets sequential awaited appends coalesce; a Promise
+            // microtask runs before the caller can enqueue the next trimmed gid. The
+            // fixed early-wake threshold also amortizes latest-only (retain=1) logs,
+            // while the separate pending cap remains the absolute memory bound.
+            const wakeThreshold = GID_PEER_HISTORY_CLEANUP_BATCH_SIZE;
+            if (state.draining) {
+                if (state.pending.size >= wakeThreshold)
+                    state.wake?.();
+                return;
+            }
+            state.draining = true;
+            let wake;
+            const batchReady = new Promise((resolve) => {
+                let settled = false;
+                let cancel = () => { };
+                wake = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cancel();
+                    if (state.wake === wake)
+                        state.wake = undefined;
+                    resolve();
+                };
+                state.wake = wake;
+                if (typeof setImmediate === "function") {
+                    const handle = setImmediate(wake);
+                    cancel = () => clearImmediate(handle);
+                }
+                else {
+                    const handle = setTimeout(wake, 0);
+                    cancel = () => clearTimeout(handle);
+                }
+            });
+            if (state.pending.size >= wakeThreshold)
+                wake();
+            const drain = state.tail
+                .then(async () => {
+                await batchReady;
+                while (history === this._gidPeersHistory) {
+                    const batch = [...state.pending].slice(0, GID_PEER_HISTORY_CLEANUP_BATCH_SIZE);
+                    if (batch.length === 0)
+                        break;
+                    for (const gid of batch)
+                        state.pending.delete(gid);
+                    try {
+                        await this.reclaimDeadGidPeerHistory(batch, history);
+                    }
+                    catch (error) {
+                        warn(`Failed to reclaim gid peer history: ${String(error)}`);
+                        if (history === this._gidPeersHistory) {
+                            for (const gid of batch)
+                                this.deleteGidPeerHistory(gid);
+                        }
+                    }
+                }
+            })
+                .catch((error) => {
+                warn(`Failed to reclaim gid peer history: ${String(error)}`);
+            });
+            state.tail = drain.finally(() => {
+                state.draining = false;
+                if (history !== this._gidPeersHistory) {
+                    state.pending.clear();
+                }
+                if (history === this._gidPeersHistory &&
+                    state.pending.size > 0 &&
+                    state === this._gidPeerHistoryCleanupState) {
+                    this.scheduleDeadGidPeerHistoryReclaim([]);
+                }
+            });
+        }
         async canAppend(entry) {
             try {
                 if (!entry.meta.data) {
@@ -11460,6 +11759,7 @@ let SharedLog = (() => {
                 this.recentlyRebalanced?.clear();
                 this.uniqueReplicators?.clear();
                 this._topicSubscribersCache?.clear();
+                this._localReachablePeerHashesCache?.clear();
                 this._closeController.abort();
                 clearInterval(this.interval);
                 this._liveness?.stopReplicatorLivenessSweep();
@@ -17033,7 +17333,8 @@ let SharedLog = (() => {
         }
         async rebalanceAll(options) {
             if (options?.clearCache) {
-                this._gidPeersHistory.clear();
+                this._gidPeersHistory = new Map();
+                this.resetGidPeerHistoryCleanupState();
                 this._nativeSharedLogState?.clearGidPeers();
                 this._nativeBackbone?.clearGidPeers();
             }
@@ -17446,9 +17747,11 @@ let SharedLog = (() => {
             }
             const fromHash = evt.detail.from.hashcode();
             const subscriptionEpoch = this._peerSessions.rotate(fromHash, "opening");
-            this.remoteBlocks.onReachable(evt.detail.from);
             this._peerSessions.blockReplicationInfo(fromHash);
             this.invalidateSharedLogTopicSubscribersCache();
+            // Invalidate the local reachability snapshot before waking block reads;
+            // their forced resolver runs synchronously from the reachable event.
+            this.remoteBlocks.onReachable(evt.detail.from);
             await this.handleSubscriptionChange(evt.detail.from, evt.detail.topics, true, subscriptionEpoch, evt.detail.session);
         }
         async rebalanceParticipation(ownershipLifecycleController = this.captureReplicationOwnershipLifecycle(), rebalanceParticipationDebounced = this.rebalanceParticipationDebounced) {