@peerbit/shared-log 16.0.9 → 16.0.11

package/src/index.ts

@@ -904,6 +904,7 @@ type PreparedPayloadCommitOnlyResult<T, R extends "u32" | "u64"> = {
 	entry: Entry<T>;
 	removed: ShallowOrFullEntry<T>[];
 	removedHashes?: string[];
+	removedGids?: string[];
 	appendCommit: PreparedLocalAppendCommit<R>;
 };
 
@@ -1407,6 +1408,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
@@ -1430,6 +1433,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;
 
 type LiveRawGossipBatch = {
 	to: string[];
@@ -1763,6 +1768,7 @@ type TrustedLowerLogNativePreparedCommit = {
 	hashDigestBytes?: Uint8Array;
 	trimmedEntries?: unknown[];
 	trimmedEntryHashes?: string[];
+	trimmedEntryGids?: string[];
 	nativeBlocksDeleted?: boolean;
 	nativeDeleteCleanupToken?: unknown;
 	nativeCommitOwnershipToken?: unknown;
@@ -1774,6 +1780,8 @@ type TrustedLowerLogNativePreparedCommit = {
 type TrustedLowerLogPreparedAppendResult<T> = {
 	entry: Entry<T>;
 	removed: ShallowOrFullEntry<T>[];
+	removedHashes?: string[];
+	removedGids?: string[];
 	change: Change<T>;
 	appendFacts: PreparedAppendFacts;
 };
@@ -1784,6 +1792,7 @@ type TrustedLowerLogCommitOnlyAppendResult<T> = {
 	shallowEntry: ShallowEntry;
 	removed: ShallowOrFullEntry<T>[];
 	removedHashes?: string[];
+	removedGids?: string[];
 	appendFacts: PreparedAppendFacts;
 	documentTrimmedHeadsProcessed?: boolean;
 	documentPreviousContext?: PreparedLocalAppendCommit<"u32">["documentPreviousContext"];
@@ -1795,6 +1804,7 @@ type TrustedLowerLogCommitOnlyAppendBatchResult<T> = {
 	materializeEntries: Array<() => Entry<T>>;
 	removed: ShallowOrFullEntry<T>[];
 	removedHashes?: string[];
+	removedGids?: string[];
 	appendFacts: PreparedAppendFacts[];
 	documentTrimmedHeadsProcessed?: boolean[];
 	nativeCommittedAppendFinalizer?: TrustedLowerLogNativeCommitFinalizer;
@@ -2082,17 +2092,19 @@ export class 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
@@ -2110,10 +2122,11 @@ export class 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
@@ -2121,6 +2134,14 @@ export class 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!: Map<string, Set<string>>;
+	private _gidPeerHistoryCleanupState!: {
+		history: Map<string, Set<string>>;
+		tail: Promise<void>;
+		pending: Set<string>;
+		draining: boolean;
+		highWater: number;
+		wake?: () => void;
+	};
 
 	private _onSubscriptionFn!: (arg: any) => any;
 	private _onUnsubscriptionFn!: (arg: any) => any;
@@ -3427,6 +3448,14 @@ export class SharedLog<
 		string,
 		{ expiresAt: number; keys: PublicSignKey[] }
 	>;
+	private _localReachablePeerHashesCache!: Map<
+		string,
+		{
+			expiresAt: number;
+			hashes?: string[];
+			inFlight?: Promise<string[]>;
+		}
+	>;
 	private _leaderSelectionContextCache?: {
 		expiresAt: number;
 		context: LeaderSelectionContext;
@@ -3744,6 +3773,7 @@ export class 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;
@@ -3766,6 +3796,7 @@ export class 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();
@@ -5134,6 +5165,93 @@ export class SharedLog<
 		);
 	}
 
+	private async _getLocalReachablePeerHashes(topic: string): Promise<string[]> {
+		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: number;
+			hashes?: string[];
+			inFlight?: Promise<string[]>;
+		} = { expiresAt: 0 };
+		const inFlight = (async () => {
+			const selfHash = this.node.identity.publicKey.hashcode();
+			const hashes: string[] = [];
+			const seen = new Set<string>();
+			const addHash = (hash: unknown) => {
+				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 as any;
+			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;
+		}
+	}
+
 	private async _getTopicSubscribers(
 		topic: string,
 	): Promise<PublicSignKey[] | undefined> {
@@ -5258,6 +5376,7 @@ export class SharedLog<
 		for (const topic of topics) {
 			if (!topic) continue;
 			this._topicSubscribersCache.delete(topic);
+			this._localReachablePeerHashesCache?.delete(topic);
 		}
 		this.invalidateLeaderSelectionContextCache();
 	}
@@ -10293,6 +10412,8 @@ export class SharedLog<
 	): Promise<{
 		entry: Entry<T>;
 		removed: ShallowOrFullEntry<T>[];
+		removedHashes?: string[];
+		removedGids?: string[];
 		appendCommit: PreparedLocalAppendCommit<R>;
 	}> {
 		this.throwIfNativeDurableCommitFailed();
@@ -10334,6 +10455,8 @@ export class SharedLog<
 			return {
 				entry: result.entry,
 				removed: result.removed,
+				removedHashes: result.removedHashes,
+				removedGids: result.removedGids,
 				appendCommit: nativePreparedCommit,
 			};
 		}
@@ -10400,6 +10523,8 @@ export class SharedLog<
 		return {
 			entry: result.entry,
 			removed: result.removed,
+			removedHashes: result.removedHashes,
+			removedGids: result.removedGids,
 			appendCommit: this.createPreparedLocalAppendCommitFromFacts(
 				result.appendFacts,
 				nativeAppendPlan,
@@ -10412,6 +10537,8 @@ export class SharedLog<
 			entry?: Entry<T>;
 			materializeEntry?: () => Entry<T>;
 			removed: ShallowOrFullEntry<T>[];
+			removedHashes?: string[];
+			removedGids?: string[];
 			change?: Change<T>;
 			appendFacts: PreparedAppendFacts;
 		},
@@ -10439,6 +10566,7 @@ export class SharedLog<
 
 		const plannedCoordinateDeleteHashes =
 			result.change?.removed.map((entry) => entry.hash) ??
+			result.removedHashes ??
 			result.removed.map((entry) => entry.hash);
 		const nativeAppendPlan = await this.planNativeLocalAppendFacts(
 			result.appendFacts,
@@ -10473,6 +10601,8 @@ export class SharedLog<
 						{
 							forgetNativeCoordinates:
 								!nativeAppendPlan.committedNativeCoordinateDeletes,
+							removedHashes: result.removedHashes,
+							removedGids: result.removedGids,
 							ownershipLifecycleController,
 						},
 					);
@@ -11257,6 +11387,7 @@ export class SharedLog<
 						},
 						removed: prepared.removed,
 						removedHashes: prepared.removedHashes,
+						removedGids: prepared.removedGids,
 						appendCommit,
 					};
 				};
@@ -11288,7 +11419,10 @@ export class SharedLog<
 				prepared.appendFacts,
 				prepared.removed,
 				prepared.materializeEntry,
-				{ removedHashes: prepared.removedHashes },
+				{
+					removedHashes: prepared.removedHashes,
+					removedGids: prepared.removedGids,
+				},
 			);
 			try {
 				await this.completeNativeStrictDurableTransaction(
@@ -11518,6 +11652,11 @@ export class SharedLog<
 					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;
@@ -11600,6 +11739,9 @@ export class SharedLog<
 						trimmedEntryHashes: useTrimmedHashesOnly
 							? backboneAppend.trimmedHashes
 							: undefined,
+						trimmedEntryGids: useTrimmedHashesOnly
+							? nativeTrimmedGids
+							: undefined,
 						nativeBlocksDeleted: commitBlocksInBackbone,
 						nativeDeleteCleanupToken,
 						documentPreviousContext: backboneAppend.documentPreviousContext,
@@ -11804,6 +11946,7 @@ export class SharedLog<
 							},
 							removed: prepared.removed,
 							removedHashes: prepared.removedHashes,
+							removedGids: prepared.removedGids,
 							appendCommit,
 						};
 					};
@@ -11930,6 +12073,7 @@ export class SharedLog<
 						{
 							forgetNativeCoordinates: false,
 							removedHashes: prepared.removedHashes,
+							removedGids: prepared.removedGids,
 						},
 					);
 					try {
@@ -11976,6 +12120,7 @@ export class SharedLog<
 					materializeEntry: () => Entry<T>;
 					removed: ShallowOrFullEntry<T>[];
 					removedHashes?: string[];
+					removedGids?: string[];
 					appendFacts: PreparedAppendFacts;
 			  }
 			| undefined,
@@ -11998,6 +12143,7 @@ export class SharedLog<
 					result.materializeEntry,
 					{
 						removedHashes: result.removedHashes,
+						removedGids: result.removedGids,
 						ownershipLifecycleController,
 					},
 				);
@@ -12027,6 +12173,7 @@ export class SharedLog<
 							},
 							removed: result.removed,
 							removedHashes: result.removedHashes,
+							removedGids: result.removedGids,
 							appendCommit: this.createPreparedLocalAppendCommitFromFacts(
 								result.appendFacts,
 							),
@@ -12040,6 +12187,7 @@ export class SharedLog<
 				},
 				removed: result.removed,
 				removedHashes: result.removedHashes,
+				removedGids: result.removedGids,
 				appendCommit: this.createPreparedLocalAppendCommitFromFacts(
 					result.appendFacts,
 				),
@@ -12070,6 +12218,7 @@ export class SharedLog<
 			materializeEntry: () => Entry<T>;
 			removed: ShallowOrFullEntry<T>[];
 			removedHashes?: string[];
+			removedGids?: string[];
 			appendFacts: PreparedAppendFacts;
 		},
 		options: SharedAppendOptions<T> | undefined,
@@ -12122,6 +12271,7 @@ export class SharedLog<
 			materializeEntry: () => Entry<T>;
 			removed: ShallowOrFullEntry<T>[];
 			removedHashes?: string[];
+			removedGids?: string[];
 			appendFacts: PreparedAppendFacts;
 		},
 		minReplicasValue: number,
@@ -12147,6 +12297,7 @@ export class SharedLog<
 			},
 			removed: result.removed,
 			removedHashes: result.removedHashes,
+			removedGids: result.removedGids,
 			appendCommit: nativePreparedCommit,
 		};
 	}
@@ -12157,6 +12308,7 @@ export class SharedLog<
 			materializeEntry?: () => Entry<T>;
 			removed: ShallowOrFullEntry<T>[];
 			removedHashes?: string[];
+			removedGids?: string[];
 			change?: Change<T>;
 			appendFacts: PreparedAppendFacts;
 		},
@@ -12208,6 +12360,7 @@ export class SharedLog<
 							forgetNativeCoordinates:
 								!nativeAppendPlan.committedNativeCoordinateDeletes,
 							removedHashes: result.removedHashes,
+							removedGids: result.removedGids,
 							ownershipLifecycleController,
 						},
 					);
@@ -12290,6 +12443,7 @@ export class SharedLog<
 			materializeEntry: () => Entry<T>;
 			removed: ShallowOrFullEntry<T>[];
 			removedHashes?: string[];
+			removedGids?: string[];
 			appendFacts: PreparedAppendFacts;
 		},
 		options: SharedAppendOptions<T> | undefined,
@@ -12310,6 +12464,8 @@ export class SharedLog<
 					return result.entry;
 				},
 				removed: result.removed,
+				removedHashes: result.removedHashes,
+				removedGids: result.removedGids,
 				appendCommit: nativePreparedCommit,
 			};
 		}
@@ -12324,6 +12480,7 @@ export class SharedLog<
 					result.materializeEntry,
 					{
 						removedHashes: result.removedHashes,
+						removedGids: result.removedGids,
 						ownershipLifecycleController,
 					},
 				);
@@ -12385,6 +12542,7 @@ export class SharedLog<
 			},
 			removed: result.removed,
 			removedHashes: result.removedHashes,
+			removedGids: result.removedGids,
 			appendCommit: this.createPreparedLocalAppendCommitFromFacts(
 				result.appendFacts,
 				nativeAppendPlan,
@@ -12711,6 +12869,11 @@ export class SharedLog<
 						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,
@@ -13042,6 +13205,11 @@ export class SharedLog<
 				{
 					forgetNativeCoordinates: false,
 					removedHashes: plannedCoordinateDeleteHashes,
+					removedGids:
+						backboneAppend.trimmedGids ??
+						(backboneAppend.trimmed.length > 0
+							? backboneAppend.trimmed.map((entry) => entry.gid)
+							: undefined),
 				},
 			);
 			if (!runtimeOnlyCoordinates && this.remoteBlocks.hasNotifyStoredHook()) {
@@ -14495,6 +14663,7 @@ export class 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,
@@ -14715,31 +14884,73 @@ export class 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: string[] = [];
 				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.
 				}
 
-				// 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,
-					})) ?? []
-				);
+				const selected: string[] = [];
+				const selectedSet = new Set<string>();
+				const add = (peer: string | undefined) => {
+					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]);
+				}
+				return selected;
 			},
 			watchProviders: fanoutService
 				? (cid, opts) =>
@@ -14783,6 +14994,7 @@ export class SharedLog<
 			})) > 0;
 
 		this._gidPeersHistory = new Map();
+		this.resetGidPeerHistoryCleanupState();
 		const replicationChangeOwnershipLifecycleController =
 			this.captureReplicationOwnershipLifecycle();
 		let replicationChangeDebounceFn!: typeof this.replicationChangeDebounceFn;
@@ -16112,73 +16324,99 @@ export class 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: string[] | undefined;
-		const replicatorCandidates = [...this.uniqueReplicators].filter(
-			(p) => p !== self,
-		);
-		if (replicatorCandidates.length > 0) {
-			candidates = replicatorCandidates;
-		} 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.
-			}
+		const evidenceTiers: readonly Iterable<string>[] = [
+			confirmed ?? [],
+			contacted ?? [],
+			this.uniqueReplicators,
+		];
 
-			if (!candidates || candidates.length === 0) {
-				const peerMap = (this.node.services.pubsub as any)?.peers;
-				if (peerMap?.keys) {
-					candidates = [...peerMap.keys()];
+		// 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: string[][] = [[], [], []];
+		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: string[] = [];
+		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;
+		}
+		const liveKnownSet = new Set(liveKnown);
+		const liveOnly = pickDeterministicSubset(
+			reachable.filter((peer) => !liveKnownSet.has(peer)),
+			(seed ^ 0x85ebca6b) >>> 0,
+			maxPeers,
+		);
+		const historicalOnly: string[] = [];
+		const historicalSeen = new Set<string>();
+		for (let tier = 0; tier < evidenceTiers.length; tier++) {
+			const available: string[] = [];
+			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 as any)?.components
-					?.connectionManager;
-				const connections = connectionManager?.getConnections?.() ?? [];
-				const connectionHashes: string[] = [];
-				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() {
@@ -16580,6 +16818,9 @@ export class SharedLog<
 			(removed) => removed.hash,
 		);
 		this.onEntryRemovedHashes(deferredCoordinateDeleteHashes);
+		this.scheduleDeadGidPeerHistoryReclaim(
+			change.removed.map((removed) => removed.meta.gid),
+		);
 		if (options?.forgetNativeCoordinates === false) {
 			this._coordinates.forgetResidentCoordinateStateForHashes(
 				deferredCoordinateDeleteHashes,
@@ -16610,6 +16851,7 @@ export class SharedLog<
 		options?: {
 			forgetNativeCoordinates?: boolean;
 			removedHashes?: string[];
+			removedGids?: string[];
 			ownershipLifecycleController?: AbortController;
 		},
 	): string[] | undefined {
@@ -16630,6 +16872,11 @@ export class 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,
@@ -16663,9 +16910,135 @@ export class SharedLog<
 			}
 			this.onEntryRemoved(removed.hash);
 		}
+		this.scheduleDeadGidPeerHistoryReclaim(
+			removedEntries.map((removed) => removed.meta.gid),
+		);
 		return undefined;
 	}
 
+	private async reclaimDeadGidPeerHistory(
+		gids: Iterable<string> | undefined,
+		history = this._gidPeersHistory,
+	): Promise<void> {
+		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);
+			}
+		}
+	}
+
+	private resetGidPeerHistoryCleanupState(): void {
+		this._gidPeerHistoryCleanupState = {
+			history: this._gidPeersHistory,
+			tail: Promise.resolve(),
+			pending: new Set(),
+			draining: false,
+			highWater: 0,
+		};
+	}
+
+	private scheduleDeadGidPeerHistoryReclaim(
+		gids: Iterable<string> | undefined,
+	): void {
+		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!: () => void;
+		const batchReady = new Promise<void>((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: Entry<T>) {
 		try {
 			if (!entry.meta.data) {
@@ -17213,6 +17586,7 @@ export class SharedLog<
 			this.recentlyRebalanced?.clear();
 			this.uniqueReplicators?.clear();
 			this._topicSubscribersCache?.clear();
+			this._localReachablePeerHashesCache?.clear();
 			this._closeController.abort();
 			clearInterval(this.interval);
 			this._liveness?.stopReplicatorLivenessSweep();
@@ -24678,7 +25052,8 @@ export class SharedLog<
 
 	async rebalanceAll(options?: { clearCache?: boolean }) {
 		if (options?.clearCache) {
-			this._gidPeersHistory.clear();
+			this._gidPeersHistory = new Map();
+			this.resetGidPeerHistoryCleanupState();
 			this._nativeSharedLogState?.clearGidPeers();
 			this._nativeBackbone?.clearGidPeers();
 		}
@@ -25262,9 +25637,11 @@ export class 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,