@peerbit/pubsub 5.4.9 → 5.4.12

package/src/index.ts

@@ -244,6 +244,31 @@ const TOPIC_ROOT_QUERY_ROUND_TIMEOUT_MS = 3_000;
 const TOPIC_ROOT_HOST_SCAN_TIMEOUT_MS = DEFAULT_TOPIC_ROOT_QUERY_TIMEOUT_MS;
 const TOPIC_ROOT_HOST_SCAN_CONCURRENCY = 8;
 const DIRECT_SHARD_ROOT_CONFIRM_TIMEOUT_MS = 2_000;
+const RELAY_ROOT_PREFLIGHT_TIMEOUT_MS = 2_000;
+const RELAY_ROOT_PREFLIGHT_REUSE_MS = 2_000;
+
+type RelayRootProbeResult = {
+	claim: TopicRootCandidateClaimRecord;
+	routes: string[];
+	status: "alive" | "failed" | "unknown";
+	observedAt: number;
+};
+type RelayRootProbeCohort = {
+	controller: AbortController;
+	users: Set<() => boolean>;
+	promise: Promise<ReadonlyMap<string, RelayRootProbeResult>>;
+	results?: ReadonlyMap<string, RelayRootProbeResult>;
+	lifecycleRevision: number;
+};
+type RelayRootRecoveryAttempt = {
+	cohort?: RelayRootProbeCohort;
+	policyDeadline?: number;
+};
+type TopicRootState = {
+	root?: string;
+	authoritative: boolean;
+	autoCandidate: boolean;
+};
 
 const DEFAULT_PUBSUB_FANOUT_CHANNEL_OPTIONS: Omit<
 	FanoutTreeChannelOptions,
@@ -341,6 +366,7 @@ type EnsureFanoutChannelOptions = {
 	root?: string;
 	rootCandidateGeneration?: string;
 	signal?: AbortSignal;
+	isCurrent?: () => boolean;
 };
 
 export type TopicControlPlaneComponents = DirectStreamComponents;
@@ -427,7 +453,7 @@ export class TopicControlPlane
 	private readonly hostShards: boolean;
 	private readonly shardRootCache = new Map<
 		string,
-		{ root: string; authoritative: boolean }
+		TopicRootState & { root: string }
 	>();
 	private readonly shardTopicCache = new Map<string, string>();
 	private readonly shardRefCounts = new Map<string, number>();
@@ -466,9 +492,9 @@ export class TopicControlPlane
 		string,
 		TopicRootCandidateClaimRecord
 	>();
-	// A directly observed departure makes only that origin's current lease
-	// ineffective locally. This is not a component-wide withdrawal: claims learned
-	// only through relays keep their existing lease semantics. Keeping the verified
+	private relayRootProbeCohort?: RelayRootProbeCohort;
+	// Locally observed unreachability makes only that origin's current lease
+	// ineffective locally. This is not a component-wide withdrawal. Keeping the verified
 	// bytes + replay floor prevents a relay from resurrecting the departed lease;
 	// the map is bounded by the same retained-origin cap as the claim map.
 	private readonly suppressedDepartedTopicRootCandidateClaims = new Map<
@@ -499,6 +525,38 @@ export class TopicControlPlane
 	private _onFanoutPeerUnreachable?: (
 		ev: CustomEvent<{ topic: string; root: string; publicKeyHash: string }>,
 	) => void;
+	private readonly onFanoutAttached = (
+		ev: CustomEvent<{ topic: string; root: string }>,
+	) => {
+		const st = this.fanoutChannels.get(ev.detail.topic);
+		if (!st || st.root !== ev.detail.root) return;
+		// A successful publish before attachment may have had no listeners.
+		// Coalesce attachment bursts, retaining one trailing pass during a send.
+		st.announceDirty = true;
+		if (st.announceTask) return;
+		const revision = this.topicControlPlaneLifecycleRevision;
+		st.announceTask = Promise.resolve()
+			.then(async () => {
+				await st.join;
+				while (
+					st.announceDirty &&
+					this.isFanoutChannelCurrent(ev.detail.topic, st.channel, revision)
+				) {
+					st.announceDirty = false;
+					await this.announceShardSubscriptions(ev.detail.topic, revision);
+				}
+			})
+			.catch(logErrorIfStarted)
+			.finally(() => {
+				st.announceTask = undefined;
+				if (
+					st.announceDirty &&
+					this.isFanoutChannelCurrent(ev.detail.topic, st.channel, revision)
+				) {
+					this.onFanoutAttached(ev);
+				}
+			});
+	};
 
 	private fanoutChannels = new Map<
 		string,
@@ -511,12 +569,15 @@ export class TopicControlPlane
 			ephemeral: boolean;
 			lastUsedAt: number;
 			idleCloseTimeout?: ReturnType<typeof setTimeout>;
+			announceDirty?: boolean;
+			announceTask?: Promise<void>;
 		}
 	>();
 	private ensureFanoutChannelInFlight = new Map<
 		string,
 		{
 			abortController: AbortController;
+			isCurrent: () => boolean;
 			candidateGeneration: string;
 			lifecycleRevision: number;
 			opening: Promise<void>;
@@ -742,6 +803,8 @@ export class TopicControlPlane
 			"fanout:peer-unreachable",
 			this._onFanoutPeerUnreachable as any,
 		);
+		this.fanout.addEventListener("fanout:joined", this.onFanoutAttached);
+		this.fanout.addEventListener("fanout:child-joined", this.onFanoutAttached);
 		await super.start();
 		if (this.autoTopicRootCandidates) {
 			let retryDelayMs = 0;
@@ -790,6 +853,11 @@ export class TopicControlPlane
 				this._onFanoutPeerUnreachable as any,
 			);
 		}
+		this.fanout.removeEventListener("fanout:joined", this.onFanoutAttached);
+		this.fanout.removeEventListener(
+			"fanout:child-joined",
+			this.onFanoutAttached,
+		);
 		for (const st of this.fanoutChannels.values()) {
 			this.clearFanoutIdleClose(st);
 			try {
@@ -862,32 +930,34 @@ export class TopicControlPlane
 			this.rebuildAutoTopicRootCandidatesFromClaims(BigInt(Date.now()), {
 				immediate: hadSignedPeer !== hasSignedPeer,
 			});
-			if (peer.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1) {
-				const sendWhenOutboundReady = () => {
-					if (
-						!this.autoTopicRootCandidates ||
-						this.peers.get(publicKey.hashcode()) !== peer
-					) {
-						return;
-					}
-					void this.sendAutoTopicRootCandidates([peer]).catch(() => {});
-				};
-				if (peer.isWritable) {
-					void this.sendAutoTopicRootCandidates([peer]).catch(() => {});
-				}
-				if (existingPeer !== peer) {
-					peer.addEventListener("stream:outbound", sendWhenOutboundReady);
-					peer.addEventListener(
-						"close",
-						() =>
-							peer.removeEventListener(
-								"stream:outbound",
-								sendWhenOutboundReady,
-							),
-						{ once: true },
-					);
-				}
+		}
+		const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
+		const sendWhenOutboundReady = () => {
+			if (
+				!this.isTopicControlPlaneActive(lifecycleRevision) ||
+				this.peers.get(publicKey.hashcode()) !== peer
+			)
+				return;
+			if (
+				this.autoTopicRootCandidates &&
+				peer.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1
+			) {
+				void this.sendAutoTopicRootCandidates([peer]).catch(() => {});
 			}
+			void this.announceDirectSubscriptions(
+				[...this.subscriptions.keys()],
+				[peer],
+			).catch(logErrorIfStarted);
+		};
+		if (peer.isWritable) sendWhenOutboundReady();
+		if (existingPeer !== peer) {
+			peer.addEventListener("stream:outbound", sendWhenOutboundReady);
+			peer.addEventListener(
+				"close",
+				() =>
+					peer.removeEventListener("stream:outbound", sendWhenOutboundReady),
+				{ once: true },
+			);
 		}
 		return peer;
 	}
@@ -911,16 +981,10 @@ export class TopicControlPlane
 			this.signedTopicRootCandidateClaims.has(hash)
 		) {
 			const claim = this.signedTopicRootCandidateClaims.get(hash)!;
-			const suppressed =
-				this.suppressedDepartedTopicRootCandidateClaims.get(hash);
-			suppressedDepartedOrigin =
-				!suppressed ||
-				suppressed.timestamp !== claim.timestamp ||
-				!bytesEqual(suppressed.bytes, claim.bytes);
-			this.suppressedDepartedTopicRootCandidateClaims.set(hash, {
-				bytes: claim.bytes,
-				timestamp: claim.timestamp,
-			});
+			suppressedDepartedOrigin = this.suppressTopicRootCandidateClaim(
+				hash,
+				claim,
+			);
 		}
 		if (
 			this.autoTopicRootCandidates &&
@@ -973,6 +1037,10 @@ export class TopicControlPlane
 	}
 
 	private clearSignedTopicRootCandidateState() {
+		this.relayRootProbeCohort?.controller.abort(
+			new AbortError("topic root candidate recovery stopped"),
+		);
+		this.relayRootProbeCohort = undefined;
 		this.clearTopicRootCandidateClaimTimer();
 		this.signedTopicRootCandidateClaims.clear();
 		this.suppressedDepartedTopicRootCandidateClaims.clear();
@@ -1348,6 +1416,329 @@ export class TopicControlPlane
 		);
 	}
 
+	private suppressTopicRootCandidateClaim(
+		origin: string,
+		claim: TopicRootCandidateClaimRecord,
+	): boolean {
+		if (
+			!this.autoTopicRootCandidates ||
+			origin === this.publicKeyHash ||
+			this.peers.has(origin) ||
+			this.signedTopicRootCandidateClaims.get(origin) !== claim ||
+			this.isDepartedTopicRootCandidateClaimSuppressed(origin, claim)
+		)
+			return false;
+		this.suppressedDepartedTopicRootCandidateClaims.set(origin, {
+			bytes: claim.bytes,
+			timestamp: claim.timestamp,
+		});
+		return true;
+	}
+
+	private topicRootRouteObservations(origin: string): string[] {
+		return this.routes
+			.getRouteHints(this.publicKeyHash, origin)
+			.map((hint) =>
+				JSON.stringify([hint.nextHop, hint.session, hint.updatedAt]),
+			);
+	}
+
+	private createRelayRootProbeCohort(
+		claims: Array<[string, TopicRootCandidateClaimRecord]>,
+	): RelayRootProbeCohort {
+		const previous = this.relayRootProbeCohort?.results;
+		const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
+		const controller = new AbortController();
+		const users = new Set<() => boolean>();
+		const deadline = new AbortError("relay root reachability deadline reached");
+		const timer = setTimeout(
+			() => controller.abort(deadline),
+			RELAY_ROOT_PREFLIGHT_TIMEOUT_MS,
+		);
+		timer.unref?.();
+		let resolveRetry!: () => void;
+		const retryBoundary = new Promise<void>((resolve) => {
+			resolveRetry = resolve;
+		});
+		const retryTimer = setTimeout(
+			resolveRetry,
+			RELAY_ROOT_PREFLIGHT_TIMEOUT_MS / 2,
+		);
+		retryTimer.unref?.();
+		const captured = claims.map(([origin, claim]) => ({
+			origin,
+			claim,
+			routes: this.topicRootRouteObservations(origin),
+		}));
+		const cohort: RelayRootProbeCohort = {
+			controller,
+			users,
+			lifecycleRevision,
+			promise: Promise.resolve()
+				.then(async () => {
+					const outcomes = await Promise.all(
+						captured.map(async ({ origin, claim, routes }) => {
+							const cached = previous?.get(origin);
+							if (
+								cached?.claim === claim &&
+								cached.status === "alive" &&
+								performance.now() - cached.observedAt <
+									RELAY_ROOT_PREFLIGHT_REUSE_MS
+							)
+								return [origin, { ...cached, routes }] as const;
+							const winner = new AbortController();
+							const signals = linkAbortSignals([
+								controller.signal,
+								winner.signal,
+							]);
+							let alive = false;
+							let resolveAlive!: (status: "alive") => void;
+							const firstSuccess = new Promise<"alive">((resolve) => {
+								resolveAlive = resolve;
+							});
+							const probe = async (
+								retry: boolean,
+							): Promise<RelayRootProbeResult["status"]> => {
+								const signal = signals.signal;
+								let submitted = false;
+								try {
+									if (retry) await withAbort(retryBoundary, signal);
+									throwIfAborted(signal);
+									if (alive) return "alive";
+									const message = await withAbort(
+										this.createMessage(undefined, {
+											mode: new AcknowledgeDelivery({
+												to: [origin],
+												redundancy: 1,
+											}),
+											priority: 1,
+											responsePriority: 1,
+										}),
+										signal,
+									);
+									// Signers may ignore cancellation. Fence the send continuation.
+									throwIfAborted(signal);
+									if (alive) return "alive";
+									if (
+										!this.isTopicControlPlaneActive(lifecycleRevision) ||
+										![...users].some((current) => current())
+									) {
+										return "unknown";
+									}
+									// No transport neighbor is local readiness, not proof of origin death.
+									if (this.peers.size === 0) return "unknown";
+									submitted = true;
+									await withAbort(
+										this.publishMessage(
+											this.publicKey,
+											message,
+											undefined,
+											undefined,
+											signal,
+										),
+										signal,
+									);
+									throwIfAborted(signal);
+									alive = true;
+									resolveAlive("alive");
+									return "alive";
+								} catch (error) {
+									if (
+										submitted &&
+										(error === deadline || error instanceof DeliveryError)
+									)
+										return "failed";
+									else if (!signal.aborted) throw error;
+									return "unknown";
+								}
+							};
+							// Hedge once at the shared midpoint without discarding the first
+							// authenticated ACK wait: a 1.5s first reply is still timely.
+							let status: RelayRootProbeResult["status"];
+							try {
+								status = await Promise.race([
+									firstSuccess,
+									Promise.all([probe(false), probe(true)]).then((results) =>
+										results.includes("unknown")
+											? ("unknown" as const)
+											: ("failed" as const),
+									),
+								]);
+							} finally {
+								winner.abort(new AbortError("origin probe settled"));
+								signals.clear();
+							}
+							return [
+								origin,
+								{ claim, routes, status, observedAt: performance.now() },
+							] as const;
+						}),
+					);
+					cohort.results = new Map(outcomes);
+					return cohort.results;
+				})
+				.finally(() => {
+					clearTimeout(timer);
+					clearTimeout(retryTimer);
+					controller.abort(new AbortError("relay root probes settled"));
+				}),
+		};
+		this.relayRootProbeCohort = cohort;
+		return cohort;
+	}
+
+	private async preflightRelayRootCandidates(
+		shardTopic: string,
+		attempt: RelayRootRecoveryAttempt,
+		signal: AbortSignal | undefined,
+		isCurrent: () => boolean,
+		localPolicyOnly = false,
+	): Promise<boolean> {
+		throwIfAborted(signal);
+		const revision = this.topicControlPlaneLifecycleRevision;
+		const current = () =>
+			isCurrent() && this.isTopicControlPlaneActive(revision);
+		if (!current()) throw new AbortError("obsolete relay root recovery");
+		if (
+			!this.autoTopicRootCandidates ||
+			this.maybeDisableAutoTopicRootCandidatesIfExternallyConfigured()
+		)
+			return false;
+		const claims = [...this.signedTopicRootCandidateClaims.entries()]
+			.filter(
+				([origin, claim]) =>
+					origin !== this.publicKeyHash &&
+					!this.peers.has(origin) &&
+					!this.isDepartedTopicRootCandidateClaimSuppressed(origin, claim),
+			)
+			.slice(0, TOPIC_ROOT_CANDIDATES_MAX);
+		if (claims.length === 0) return false;
+		const shared = this.relayRootProbeCohort;
+		const cohort = (attempt.cohort ??=
+			shared &&
+			(shared.results
+				? shared.users.size > 0
+				: !shared.controller.signal.aborted) &&
+			shared.lifecycleRevision === revision
+				? shared
+				: this.createRelayRootProbeCohort(claims));
+		cohort.users.add(current);
+		let held = true;
+		const release = () => {
+			if (!held) return;
+			held = false;
+			cohort.users.delete(current);
+			if (cohort.users.size === 0 && !cohort.results) {
+				cohort.controller.abort(
+					new AbortError("relay root recovery cancelled"),
+				);
+			}
+		};
+		signal?.addEventListener("abort", release, { once: true });
+		try {
+			const outcomes = await withAbort(cohort.promise, signal);
+			throwIfAborted(signal);
+			if (!current()) throw new AbortError("obsolete relay root recovery");
+
+			// Policy setters do not share the candidate generation. Re-read configured
+			// roots/resolvers/trackers after observation; a stalled policy is unknown,
+			// never evidence authorizing local suppression.
+			attempt.policyDeadline ??=
+				performance.now() + RELAY_ROOT_PREFLIGHT_TIMEOUT_MS;
+			return await this.withRelayRootPolicyDeadline(
+				attempt,
+				signal,
+				async (policySignal) => {
+					const configured = await withAbort(
+						localPolicyOnly
+							? this.topicRootControlPlane.resolveLocalTopicRoot(shardTopic, {
+									signal: policySignal,
+								})
+							: this.topicRootControlPlane.resolveTrackedTopicRoot(shardTopic, {
+									signal: policySignal,
+								}),
+						policySignal,
+					);
+					throwIfAborted(policySignal);
+					if (!current()) throw new AbortError("obsolete relay root recovery");
+					this.shardRootCache.delete(shardTopic);
+					if (
+						configured ||
+						this.topicRootControlPlane.getTopicRoot(shardTopic) ||
+						!this.autoTopicRootCandidates ||
+						this.maybeDisableAutoTopicRootCandidatesIfExternallyConfigured()
+					)
+						return true;
+					let changed = false;
+					let unknown = false;
+					for (const [origin, claim] of claims) {
+						if (
+							this.peers.has(origin) ||
+							this.isDepartedTopicRootCandidateClaimSuppressed(origin, claim)
+						)
+							continue;
+						const observed = outcomes.get(origin);
+						if (
+							this.signedTopicRootCandidateClaims.get(origin) !== claim ||
+							observed?.claim !== claim
+						) {
+							unknown = true;
+							continue;
+						}
+						const freshRoute =
+							this.routes.isReachable(this.publicKeyHash, origin) &&
+							this.topicRootRouteObservations(origin).some(
+								(route) => !observed.routes.includes(route),
+							);
+						if (freshRoute || observed.status === "alive") continue;
+						if (observed.status === "unknown") unknown = true;
+						else
+							changed =
+								this.suppressTopicRootCandidateClaim(origin, claim) || changed;
+					}
+					if (changed)
+						this.rebuildAutoTopicRootCandidatesFromClaims(BigInt(Date.now()), {
+							immediate: true,
+						});
+					if (unknown)
+						throw new DeliveryError(
+							"Relay root reachability could not be established",
+						);
+					return true;
+				},
+			);
+		} finally {
+			signal?.removeEventListener("abort", release);
+			release();
+		}
+	}
+
+	private async withRelayRootPolicyDeadline<T>(
+		attempt: RelayRootRecoveryAttempt,
+		signal: AbortSignal | undefined,
+		resolve: (signal: AbortSignal | undefined) => Promise<T>,
+	): Promise<T> {
+		// Ordinary initial resolution retains its existing contract. Only work
+		// following a probe shares the one additional policy budget, including retries.
+		if (attempt.policyDeadline === undefined) return resolve(signal);
+		throwIfAborted(signal);
+		const remaining = attempt.policyDeadline - performance.now();
+		const deadline = new AbortError(
+			"relay root policy recheck deadline reached",
+		);
+		if (remaining <= 0) throw deadline;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(deadline), remaining);
+		timer.unref?.();
+		const signals = linkAbortSignals([signal, controller.signal]);
+		try {
+			return await withAbort(resolve(signals.signal), signals.signal);
+		} finally {
+			clearTimeout(timer);
+			signals.clear();
+		}
+	}
+
 	private canAdvanceTopicRootCandidateClaimReplayFloor(
 		origin: string,
 		timestamp: bigint,
@@ -1425,6 +1816,7 @@ export class TopicControlPlane
 		rawClaim: Uint8Array,
 		outerPeerHash: string,
 		expectedPeer?: PeerStreams,
+		batchUpdate?: { immediate: boolean },
 	): Promise<boolean> {
 		const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
 		if (
@@ -1470,7 +1862,12 @@ export class TopicControlPlane
 			return false;
 		}
 
-		this.rebuildAutoTopicRootCandidatesFromClaims(now);
+		if (batchUpdate) {
+			if (this.pruneExpiredTopicRootCandidateClaims(now))
+				batchUpdate.immediate = true;
+		} else {
+			this.rebuildAutoTopicRootCandidatesFromClaims(now);
+		}
 		const retained = this.signedTopicRootCandidateClaims.get(origin);
 		if (
 			outerPeerHash === origin &&
@@ -1490,7 +1887,9 @@ export class TopicControlPlane
 			// monotonic acceptance deadline. A current authenticated origin stream is
 			// sufficient liveness evidence; do not advance the floor or lease.
 			this.suppressedDepartedTopicRootCandidateClaims.delete(origin);
-			this.rebuildAutoTopicRootCandidatesFromClaims(now, { immediate: true });
+			if (batchUpdate) batchUpdate.immediate = true;
+			else
+				this.rebuildAutoTopicRootCandidatesFromClaims(now, { immediate: true });
 			return false;
 		}
 
@@ -1785,29 +2184,25 @@ export class TopicControlPlane
 
 		// Ensure shard overlays are joined using the current root mapping (may
 		// migrate channels if roots changed), then re-announce subscriptions.
-		await Promise.all(
+		const results = await Promise.allSettled(
 			[...byShard.entries()].map(async ([shardTopic, userTopics]) => {
 				if (userTopics.length === 0) return;
-				await this.ensureFanoutChannel(shardTopic, { ephemeral: false });
-
-				const msg = new Subscribe({
-					topics: userTopics,
-					requestSubscribers: true,
-				});
-				const embedded = await this.createMessage(
-					this.encodePubSubMessage(msg),
-					{
-						mode: new AnyWhere(),
-						priority: 1,
-						skipRecipientValidation: true,
-					} as any,
+				const owners = userTopics.map(
+					(topic) => [topic, this.subscriptions.get(topic)] as const,
 				);
-				const st = this.fanoutChannels.get(shardTopic);
-				if (!st) return;
-				await st.channel.publish(toUint8Array(embedded.bytes()));
-				this.touchFanoutChannel(shardTopic, st.channel, lifecycleRevision);
+				await this.ensureFanoutChannel(shardTopic, {
+					ephemeral: false,
+					isCurrent: () =>
+						owners.some(
+							([topic, owner]) =>
+								owner && this.subscriptions.get(topic) === owner,
+						),
+				});
+				await this.announceShardSubscriptions(shardTopic, lifecycleRevision);
 			}),
 		);
+		const failure = results.find((result) => result.status === "rejected");
+		if (failure?.status === "rejected") throw failure.reason;
 	}
 
 	private isTrackedTopic(topic: string) {
@@ -1821,15 +2216,16 @@ export class TopicControlPlane
 	private untrackTopic(topic: string) {
 		const peers = this.topics.get(topic);
 		this.topics.delete(topic);
-		if (!peers) return;
-		for (const peerHash of peers.keys()) {
+		for (const peerHash of peers?.keys() ?? []) {
 			this.peerToTopic.get(peerHash)?.delete(topic);
-			this.lastSubscriptionMessages.get(peerHash)?.delete(topic);
 			if (!this.peerToTopic.get(peerHash)?.size) {
 				this.peerToTopic.delete(peerHash);
-				this.lastSubscriptionMessages.delete(peerHash);
 			}
 		}
+		for (const [peerHash, messages] of this.lastSubscriptionMessages) {
+			messages.delete(topic);
+			if (messages.size === 0) this.lastSubscriptionMessages.delete(peerHash);
+		}
 	}
 
 	private initializePeer(publicKey: PublicSignKey) {
@@ -1853,11 +2249,26 @@ export class TopicControlPlane
 			this.lastSubscriptionMessages.get(oldest)?.delete(topic);
 			if (!this.peerToTopic.get(oldest)?.size) {
 				this.peerToTopic.delete(oldest);
+			}
+			if (!this.lastSubscriptionMessages.get(oldest)?.size) {
 				this.lastSubscriptionMessages.delete(oldest);
 			}
 		}
 	}
 
+	private pruneUnsubscribedWatermarks(topic: string) {
+		let remaining = this.subscriberCacheMaxEntries;
+		for (const [peerHash, messages] of [
+			...this.lastSubscriptionMessages,
+		].reverse()) {
+			if (!messages.has(topic) || this.topics.get(topic)?.has(peerHash))
+				continue;
+			if (remaining-- > 0) continue;
+			messages.delete(topic);
+			if (messages.size === 0) this.lastSubscriptionMessages.delete(peerHash);
+		}
+	}
+
 	private getSubscriptionOverlap(topics?: string[]) {
 		const subscriptions: string[] = [];
 		if (topics) {
@@ -2183,7 +2594,7 @@ export class TopicControlPlane
 	private normalizePeerTopicRootState(
 		topic: string,
 		root: string,
-	): { root: string; authoritative: boolean } {
+	): TopicRootState & { root: string } {
 		const deterministic =
 			this.topicRootControlPlane.resolveDeterministicTopicRoot(topic);
 		if (
@@ -2192,9 +2603,16 @@ export class TopicControlPlane
 			deterministic &&
 			root !== deterministic
 		) {
-			return { root: deterministic, authoritative: false };
+			return { root: deterministic, authoritative: false, autoCandidate: true };
 		}
-		return { root, authoritative: true };
+		return {
+			root,
+			authoritative: true,
+			autoCandidate:
+				this.autoTopicRootCandidates &&
+				topic.startsWith(this.shardTopicPrefix) &&
+				root === deterministic,
+		};
 	}
 
 	private async resolveTopicRootState(
@@ -2202,19 +2620,20 @@ export class TopicControlPlane
 		options?: TopicRootResolutionOptions & {
 			queryConnectedPeers?: boolean;
 		},
-	): Promise<{ root?: string; authoritative: boolean }> {
+	): Promise<TopicRootState> {
 		throwIfAborted(options?.signal);
 		const tracked = await this.topicRootControlPlane.resolveTrackedTopicRoot(
 			topic,
 			options,
 		);
 		if (tracked) {
-			return { root: tracked, authoritative: true };
+			return { root: tracked, authoritative: true, autoCandidate: false };
 		}
 		if (options?.queryConnectedPeers === false) {
 			return {
 				root: this.topicRootControlPlane.resolveDeterministicTopicRoot(topic),
 				authoritative: false,
+				autoCandidate: this.autoTopicRootCandidates,
 			};
 		}
 
@@ -2290,6 +2709,7 @@ export class TopicControlPlane
 		return {
 			root: this.topicRootControlPlane.resolveDeterministicTopicRoot(topic),
 			authoritative: false,
+			autoCandidate: this.autoTopicRootCandidates,
 		};
 	}
 
@@ -2313,7 +2733,11 @@ export class TopicControlPlane
 		options?: TopicRootResolutionOptions & {
 			queryConnectedPeers?: boolean;
 		},
-	): Promise<{ root: string; candidateGeneration: string }> {
+	): Promise<{
+		root: string;
+		candidateGeneration: string;
+		autoCandidate: boolean;
+	}> {
 		const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
 		for (;;) {
 			throwIfAborted(options?.signal);
@@ -2336,7 +2760,11 @@ export class TopicControlPlane
 					? undefined
 					: this.shardRootCache.get(shardTopic);
 			if (cached && (cached.authoritative || !hasConnectedTrackers)) {
-				return { root: cached.root, candidateGeneration };
+				return {
+					root: cached.root,
+					candidateGeneration,
+					autoCandidate: cached.autoCandidate,
+				};
 			}
 
 			const resolved = await this.resolveTopicRootState(shardTopic, options);
@@ -2352,15 +2780,16 @@ export class TopicControlPlane
 			if (resolved.authoritative || !hasConnectedTrackers) {
 				this.shardRootCache.set(
 					shardTopic,
-					resolved as {
-						root: string;
-						authoritative: boolean;
-					},
+					resolved as TopicRootState & { root: string },
 				);
 			} else {
 				this.shardRootCache.delete(shardTopic);
 			}
-			return { root: resolved.root, candidateGeneration };
+			return {
+				root: resolved.root,
+				candidateGeneration,
+				autoCandidate: resolved.autoCandidate,
+			};
 		}
 	}
 
@@ -2393,6 +2822,11 @@ export class TopicControlPlane
 		pubsubMessage: PubSubMessage,
 		signal?: AbortSignal,
 	) {
+		const revision = this.topicControlPlaneLifecycleRevision;
+		const isCurrent = () =>
+			this.isTopicControlPlaneActive(revision) &&
+			this.peers.get(peer.publicKey.hashcode()) === peer;
+		if (!isCurrent()) return;
 		const embedded = await this.createMessage(
 			this.encodePubSubMessage(pubsubMessage),
 			{
@@ -2404,12 +2838,13 @@ export class TopicControlPlane
 				skipRecipientValidation: true,
 			} as any,
 		);
+		if (!isCurrent()) return;
 		await this.publishMessage(
 			this.publicKey,
 			embedded,
 			[peer],
 			undefined,
-			signal,
+			signal ?? this.topicRootResolutionAbortController.signal,
 		);
 	}
 
@@ -2548,6 +2983,7 @@ export class TopicControlPlane
 			this.shardRootCache.set(shardTopic, {
 				root: resolved.root,
 				authoritative: true,
+				autoCandidate: resolved.autoCandidate,
 			});
 		}
 		return resolved.root;
@@ -2555,20 +2991,55 @@ export class TopicControlPlane
 
 	private async resolveQueryableTopicRoot(
 		topic: string,
+		isCurrent: () => boolean = () => true,
 	): Promise<string | undefined> {
 		const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
 		const lifecycleSignal = this.topicRootResolutionAbortController.signal;
+		const recovery: RelayRootRecoveryAttempt = {};
 		return this.withTopicRootCandidateResolution(
 			async ({ candidateGeneration, signal }) => {
 				throwIfAborted(signal);
 				this.assertTopicControlPlaneActive(lifecycleRevision);
-				const root = await this.topicRootControlPlane.resolveCanonicalTopicRoot(
-					topic,
-					{
+				if (!isCurrent()) throw new AbortError("obsolete topic root query");
+				// Incoming queries retain canonical directory semantics: never ask
+				// trackers here, since a tracker may itself query this peer.
+				const resolveCanonical = () =>
+					this.withRelayRootPolicyDeadline(
+						recovery,
 						signal,
-					},
-				);
+						async (policySignal) => {
+							const local =
+								await this.topicRootControlPlane.resolveLocalTopicRoot(topic, {
+									signal: policySignal,
+								});
+							return {
+								root:
+									local ??
+									this.topicRootControlPlane.resolveDeterministicTopicRoot(
+										topic,
+									),
+								autoCandidate: !local && this.autoTopicRootCandidates,
+							};
+						},
+					);
+				let resolved = await resolveCanonical();
+				if (resolved.autoCandidate && topic.startsWith(this.shardTopicPrefix)) {
+					if (
+						await this.preflightRelayRootCandidates(
+							topic,
+							recovery,
+							signal,
+							isCurrent,
+							true,
+						)
+					) {
+						throwIfAborted(signal);
+						resolved = await resolveCanonical();
+					}
+				}
+				const root = resolved.root;
 				this.assertTopicControlPlaneActive(lifecycleRevision);
+				if (!isCurrent()) throw new AbortError("obsolete topic root query");
 				if (root !== this.publicKeyHash) {
 					return root;
 				}
@@ -2698,8 +3169,11 @@ export class TopicControlPlane
 	): Promise<void> {
 		const topic = shardTopic.toString();
 		const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
+		const recovery: RelayRootRecoveryAttempt = {};
 		for (;;) {
 			this.assertTopicControlPlaneActive(lifecycleRevision);
+			if (options?.isCurrent?.() === false)
+				throw new AbortError("obsolete fanout channel owner");
 			if (options?.signal?.aborted) {
 				throw (
 					options.signal.reason ??
@@ -2710,13 +3184,20 @@ export class TopicControlPlane
 			const active = this.ensureFanoutChannelInFlight.get(topic);
 			if (
 				active?.candidateGeneration === candidateGeneration &&
-				active.lifecycleRevision === lifecycleRevision
+				active.lifecycleRevision === lifecycleRevision &&
+				active.isCurrent()
 			) {
 				try {
 					await withAbort(active.opening, options?.signal);
 				} catch (error) {
 					if (options?.signal?.aborted) throw error;
 					this.assertTopicControlPlaneActive(lifecycleRevision);
+					if (
+						candidateGeneration === this.getTopicRootCandidateGeneration() &&
+						!active.abortController.signal.aborted &&
+						active.isCurrent()
+					)
+						throw error;
 				}
 				await withAbort(active.settled, options?.signal);
 				if (this.ensureFanoutChannelInFlight.get(topic) === active) {
@@ -2750,11 +3231,21 @@ export class TopicControlPlane
 				});
 			}
 
-			const opening = this.ensureFanoutChannelOnce(
-				topic,
-				{ ...options, signal: abortController.signal },
-				lifecycleRevision,
-				candidateGeneration,
+			// Publish the opening identity before even a synchronously resolved root
+			// can enter its guarded recovery/creation continuation.
+			const opening = Promise.resolve().then(() =>
+				this.ensureFanoutChannelOnce(
+					topic,
+					{ ...options, signal: abortController.signal },
+					lifecycleRevision,
+					candidateGeneration,
+					recovery,
+					() =>
+						this.ensureFanoutChannelInFlight.get(topic)?.abortController ===
+							abortController &&
+						!abortController.signal.aborted &&
+						options?.isCurrent?.() !== false,
+				),
 			);
 			let resolveSettled!: () => void;
 			const settled = new Promise<void>((resolve) => {
@@ -2762,6 +3253,7 @@ export class TopicControlPlane
 			});
 			const inFlight = {
 				abortController,
+				isCurrent: () => options?.isCurrent?.() !== false,
 				candidateGeneration,
 				lifecycleRevision,
 				opening,
@@ -2806,6 +3298,8 @@ export class TopicControlPlane
 		options: EnsureFanoutChannelOptions | undefined,
 		lifecycleRevision: number,
 		candidateGeneration: string,
+		recovery: RelayRootRecoveryAttempt = {},
+		isOpeningCurrent: () => boolean = () => true,
 	): Promise<void> {
 		this.assertTopicControlPlaneActive(lifecycleRevision);
 		if (candidateGeneration !== this.getTopicRootCandidateGeneration()) return;
@@ -2827,15 +3321,19 @@ export class TopicControlPlane
 		this.assertTopicControlPlaneActive(lifecycleRevision);
 		let resolvedGeneration = candidateGeneration;
 		let root = suppliedRoot;
+		let autoCandidate = false;
+		const resolveRoot = () =>
+			this.withRelayRootPolicyDeadline(recovery, options?.signal, (signal) =>
+				this.resolveShardRootState(t, { signal }),
+			);
 		const existing = this.fanoutChannels.get(t);
 		if (existing) {
 			if (!root) {
-				const resolved = await this.resolveShardRootState(t, {
-					signal: options?.signal,
-				});
+				const resolved = await resolveRoot();
 				this.assertTopicControlPlaneActive(lifecycleRevision);
 				root = resolved.root;
 				resolvedGeneration = resolved.candidateGeneration;
+				autoCandidate = resolved.autoCandidate;
 			}
 			if (
 				resolvedGeneration !== candidateGeneration ||
@@ -2876,21 +3374,45 @@ export class TopicControlPlane
 		}
 
 		if (!root) {
-			const resolved = await this.resolveShardRootState(t, {
-				signal: options?.signal,
-			});
+			const resolved = await resolveRoot();
 			this.assertTopicControlPlaneActive(lifecycleRevision);
 			root = resolved.root;
 			resolvedGeneration = resolved.candidateGeneration;
+			autoCandidate = resolved.autoCandidate;
+		}
+		if (
+			autoCandidate &&
+			(await this.preflightRelayRootCandidates(
+				t,
+				recovery,
+				options?.signal,
+				isOpeningCurrent,
+			))
+		) {
+			throwIfAborted(options?.signal);
+			if (candidateGeneration !== this.getTopicRootCandidateGeneration())
+				return;
+			const resolved = await resolveRoot();
+			root = resolved.root;
+			resolvedGeneration = resolved.candidateGeneration;
+			autoCandidate = resolved.autoCandidate;
+		}
+		if (
+			suppliedRoot !== undefined ||
+			!this.autoTopicRootCandidates ||
+			autoCandidate
+		) {
+			root = await this.confirmDirectShardRoot(
+				t,
+				root,
+				resolvedGeneration,
+				lifecycleRevision,
+				options?.signal,
+			);
 		}
-		root = await this.confirmDirectShardRoot(
-			t,
-			root,
-			resolvedGeneration,
-			lifecycleRevision,
-			options?.signal,
-		);
 		this.assertTopicControlPlaneActive(lifecycleRevision);
+		if (!isOpeningCurrent())
+			throw new AbortError("obsolete fanout channel owner");
 		if (
 			resolvedGeneration !== candidateGeneration ||
 			candidateGeneration !== this.getTopicRootCandidateGeneration()
@@ -3218,6 +3740,117 @@ export class TopicControlPlane
 		return this.debounceSubscribeAggregator.add({ key: topic });
 	}
 
+	private async announceShardSubscriptions(
+		shardTopic: string,
+		lifecycleRevision: number,
+	) {
+		const st = this.fanoutChannels.get(shardTopic);
+		if (!st) return;
+		let topics = [...this.subscriptions.entries()].filter(
+			([topic]) => this.getShardTopicForUserTopic(topic) === shardTopic,
+		);
+		while (
+			topics.length > 0 &&
+			this.isFanoutChannelCurrent(shardTopic, st.channel, lifecycleRevision)
+		) {
+			const embedded = await this.createMessage(
+				this.encodePubSubMessage(
+					new Subscribe({
+						topics: topics.map(([topic]) => topic),
+						requestSubscribers: true,
+					}),
+				),
+				{
+					mode: new AnyWhere(),
+					priority: 1,
+					skipRecipientValidation: true,
+				} as any,
+			);
+			if (
+				!this.isFanoutChannelCurrent(shardTopic, st.channel, lifecycleRevision)
+			)
+				return;
+			const current = topics.filter(
+				([topic, sub]) => this.subscriptions.get(topic) === sub,
+			);
+			if (current.length !== topics.length) {
+				// Never announce a subscription removed while signing. This retry
+				// only shrinks the original batch, so churn cannot extend it forever.
+				topics = current;
+				continue;
+			}
+			await st.channel.publish(toUint8Array(embedded.bytes()));
+			if (
+				this.isFanoutChannelCurrent(shardTopic, st.channel, lifecycleRevision)
+			) {
+				this.touchFanoutChannel(shardTopic, st.channel, lifecycleRevision);
+			}
+			return;
+		}
+	}
+
+	private async announceDirectSubscriptions(
+		topics: string[],
+		peers = [...this.peers.values()],
+		subscribed = true,
+	) {
+		const revision = this.topicControlPlaneLifecycleRevision;
+		const signal = this.topicRootResolutionAbortController.signal;
+		const subscriptions = new Map(
+			topics.map((topic) => [topic, this.subscriptions.get(topic)]),
+		);
+		const isCurrentTopic = (topic: string) =>
+			subscribed
+				? subscriptions.get(topic) != null &&
+					this.subscriptions.get(topic) === subscriptions.get(topic)
+				: !this.subscriptions.has(topic);
+		await Promise.all(
+			peers
+				.map(async (peer) => {
+					const isCurrent = () =>
+						this.isTopicControlPlaneActive(revision) &&
+						this.peers.get(peer.publicKey.hashcode()) === peer &&
+						peer.isWritable;
+					let currentTopics = topics.filter(isCurrentTopic);
+					while (isCurrent() && currentTopics.length > 0) {
+						const embedded = await this.createMessage(
+							this.encodePubSubMessage(
+								subscribed
+									? new Subscribe({
+											topics: currentTopics,
+											requestSubscribers: true,
+										})
+									: new Unsubscribe({ topics: currentTopics }),
+							),
+							{
+								mode: new SilentDelivery({
+									to: [peer.publicKey.hashcode()],
+									redundancy: 1,
+								}),
+								priority: 1,
+								skipRecipientValidation: true,
+							} as any,
+						);
+						if (!isCurrent()) return;
+						const remaining = currentTopics.filter(isCurrentTopic);
+						if (remaining.length !== currentTopics.length) {
+							currentTopics = remaining;
+							continue;
+						}
+						await this.publishMessage(
+							this.publicKey,
+							embedded,
+							[peer],
+							undefined,
+							signal,
+						);
+						return;
+					}
+				})
+				.map((task) => task.catch(logErrorIfStarted)),
+		);
+	}
+
 	private async _subscribe(
 		topics: { key: string; counter: number }[],
 		lifecycleRevision = this.topicControlPlaneLifecycleRevision,
@@ -3227,7 +3860,6 @@ export class TopicControlPlane
 		if (topics.length === 0) return;
 
 		const byShard = new Map<string, string[]>();
-		const joins: Promise<void>[] = [];
 		for (const { key: topic, counter } of topics) {
 			let prev = this.subscriptions.get(topic);
 			if (prev) {
@@ -3245,46 +3877,35 @@ export class TopicControlPlane
 				shardTopic,
 				(this.shardRefCounts.get(shardTopic) ?? 0) + 1,
 			);
-			joins.push(this.ensureFanoutChannel(shardTopic));
 		}
 
-		await Promise.all(joins);
-		if (!this.isTopicControlPlaneActive(lifecycleRevision)) return;
+		// Neighbours can use different root policies. Discover them independently
+		// of shard joins, without adopting or overriding either peer's root policy.
+		void this.announceDirectSubscriptions([...byShard.values()].flat()).catch(
+			logErrorIfStarted,
+		);
 
-		// Announce subscriptions per shard overlay.
-		await Promise.all(
-			[...byShard.entries()].map(async ([shardTopic, userTopics]) => {
-				if (userTopics.length === 0) return;
-				const st = this.fanoutChannels.get(shardTopic);
-				if (!st)
-					throw new Error(`Fanout channel missing for shard: ${shardTopic}`);
-				const msg = new Subscribe({
-					topics: userTopics,
-					requestSubscribers: true,
+		const results = await Promise.allSettled(
+			[...byShard.keys()].map(async (shardTopic) => {
+				const owners = byShard
+					.get(shardTopic)!
+					.map((topic) => [topic, this.subscriptions.get(topic)] as const);
+				await this.ensureFanoutChannel(shardTopic, {
+					isCurrent: () =>
+						owners.some(
+							([topic, owner]) =>
+								owner && this.subscriptions.get(topic) === owner,
+						),
 				});
-				const embedded = await this.createMessage(
-					this.encodePubSubMessage(msg),
-					{
-						mode: new AnyWhere(),
-						priority: 1,
-						skipRecipientValidation: true,
-					} as any,
-				);
-				if (
-					!this.isFanoutChannelCurrent(
-						shardTopic,
-						st.channel,
-						lifecycleRevision,
-					)
-				)
-					return;
-				await st.channel.publish(toUint8Array(embedded.bytes()));
-				if (
-					this.isFanoutChannelCurrent(shardTopic, st.channel, lifecycleRevision)
-				)
-					this.touchFanoutChannel(shardTopic, st.channel, lifecycleRevision);
+				await this.announceShardSubscriptions(shardTopic, lifecycleRevision);
 			}),
 		);
+		const failure = results.find((result) => result.status === "rejected");
+		if (failure?.status === "rejected") {
+			if (this.isTopicControlPlaneActive(lifecycleRevision))
+				this.scheduleReconcileShardOverlays();
+			throw failure.reason;
+		}
 	}
 
 	async unsubscribe(
@@ -3325,6 +3946,12 @@ export class TopicControlPlane
 		const next = (this.shardRefCounts.get(shardTopic) ?? 0) - 1;
 		if (next <= 0) {
 			this.shardRefCounts.delete(shardTopic);
+			const opening = this.ensureFanoutChannelInFlight.get(shardTopic);
+			if (opening && !opening.isCurrent()) {
+				opening.abortController.abort(
+					new AbortError("last shard subscription removed"),
+				);
+			}
 		} else {
 			this.shardRefCounts.set(shardTopic, next);
 		}
@@ -3345,12 +3972,18 @@ export class TopicControlPlane
 
 		const byShard = new Map<string, string[]>();
 		for (const { key: topic } of topics) {
-			// If the topic got re-subscribed before this debounced batch ran, skip.
+			// A pending reopen must not erase the previous departure: its Subscribe
+			// shares the transport session and would otherwise only refresh the cache.
 			if (this.subscriptions.has(topic)) continue;
 			const shardTopic = this.getShardTopicForUserTopic(topic);
 			byShard.set(shardTopic, [...(byShard.get(shardTopic) ?? []), topic]);
 		}
 
+		void this.announceDirectSubscriptions(
+			[...byShard.values()].flat(),
+			undefined,
+			false,
+		).catch(logErrorIfStarted);
 		await Promise.all(
 			[...byShard.entries()].map(async ([shardTopic, userTopics]) => {
 				if (userTopics.length === 0) return;
@@ -3848,6 +4481,18 @@ export class TopicControlPlane
 
 	public override onPeerUnreachable(publicKeyHash: string) {
 		super.onPeerUnreachable(publicKeyHash);
+		const claim = this.signedTopicRootCandidateClaims.get(publicKeyHash);
+		if (
+			this.isTopicControlPlaneActive(this.topicControlPlaneLifecycleRevision) &&
+			!this.maybeDisableAutoTopicRootCandidatesIfExternallyConfigured() &&
+			claim &&
+			!this.routes.isReachable(this.publicKeyHash, publicKeyHash) &&
+			this.suppressTopicRootCandidateClaim(publicKeyHash, claim)
+		) {
+			this.rebuildAutoTopicRootCandidatesFromClaims(BigInt(Date.now()), {
+				immediate: true,
+			});
+		}
 		const key = this.peerKeyHashToPublicKey.get(publicKeyHash);
 		if (!key) {
 			return;
@@ -4206,16 +4851,24 @@ export class TopicControlPlane
 		stream: PeerStreams;
 	}): Promise<void> {
 		const { pubsubMessage, message, from, stream } = input;
-		const isDirectRootControl =
+		if (
+			(pubsubMessage instanceof Subscribe ||
+				pubsubMessage instanceof Unsubscribe) &&
+			this.peers.get(stream.publicKey.hashcode()) !== stream
+		)
+			return;
+		const isBoundDirectControl =
 			pubsubMessage instanceof TopicRootCandidates ||
 			pubsubMessage instanceof TopicRootCandidateClaims ||
 			pubsubMessage instanceof TopicRootQuery ||
-			pubsubMessage instanceof TopicRootQueryResponse;
-		const directRootSigner = isDirectRootControl
+			pubsubMessage instanceof TopicRootQueryResponse ||
+			pubsubMessage instanceof Subscribe ||
+			pubsubMessage instanceof Unsubscribe;
+		const directRootSigner = isBoundDirectControl
 			? message.header.signatures?.publicKeys[0]
 			: undefined;
 		if (
-			isDirectRootControl &&
+			isBoundDirectControl &&
 			(!directRootSigner || !directRootSigner.equals(stream.publicKey))
 		) {
 			return;
@@ -4238,6 +4891,8 @@ export class TopicControlPlane
 				return;
 			}
 			const imported: Uint8Array[] = [];
+			const batchUpdate = { immediate: false };
+			const revision = this.topicControlPlaneLifecycleRevision;
 			const outerPeerHash = stream.publicKey.hashcode();
 			for (const claim of pubsubMessage.claims) {
 				if (
@@ -4245,13 +4900,24 @@ export class TopicControlPlane
 						claim,
 						outerPeerHash,
 						stream,
+						batchUpdate,
 					)
 				) {
 					imported.push(claim);
 				}
 			}
+			if (
+				!this.isTopicControlPlaneActive(revision) ||
+				this.peers.get(outerPeerHash) !== stream
+			)
+				return;
+			if (imported.length > 0 || batchUpdate.immediate) {
+				this.rebuildAutoTopicRootCandidatesFromClaims(
+					BigInt(Date.now()),
+					batchUpdate,
+				);
+			}
 			if (imported.length > 0) {
-				this.rebuildAutoTopicRootCandidatesFromClaims();
 				// Relay the exact nested claims; no relay signature is substituted for
 				// their origin signatures.
 				void this.sendSignedTopicRootCandidateClaims(
@@ -4265,7 +4931,10 @@ export class TopicControlPlane
 		}
 
 		if (pubsubMessage instanceof TopicRootQuery) {
-			const root = await this.resolveQueryableTopicRoot(pubsubMessage.topic);
+			const root = await this.resolveQueryableTopicRoot(
+				pubsubMessage.topic,
+				() => this.peers.get(from.hashcode()) === stream,
+			);
 			await this.sendDirectControlMessage(
 				stream,
 				new TopicRootQueryResponse({
@@ -4351,6 +5020,11 @@ export class TopicControlPlane
 			return;
 		}
 
+		if (pubsubMessage instanceof Unsubscribe) {
+			this.processUnsubscribeMessage(message, pubsubMessage, from);
+			return;
+		}
+
 		if (pubsubMessage instanceof GetSubscribers) {
 			const overlap = this.getSubscriptionOverlap(pubsubMessage.topics);
 			if (overlap.length === 0) return;
@@ -4376,6 +5050,45 @@ export class TopicControlPlane
 		}
 	}
 
+	private processUnsubscribeMessage(
+		message: DataMessage,
+		unsubscribe: Unsubscribe,
+		from: PublicSignKey,
+	) {
+		const senderKey = from.hashcode();
+		const relevantTopics = unsubscribe.topics.filter((topic) =>
+			this.isTrackedTopic(topic),
+		);
+		if (
+			!relevantTopics.length ||
+			!this.subscriptionMessageIsLatest(message, unsubscribe, relevantTopics)
+		)
+			return;
+		const changed: string[] = [];
+		for (const topic of relevantTopics) {
+			if (this.topics.get(topic)?.delete(senderKey)) {
+				changed.push(topic);
+				this.peerToTopic.get(senderKey)?.delete(topic);
+			}
+		}
+		if (!this.peerToTopic.get(senderKey)?.size) {
+			this.peerToTopic.delete(senderKey);
+		}
+		// Independent direct/shard paths may deliver an older Subscribe later.
+		// Retain recent unsubscribe floors, bounded separately from live subscribers.
+		const messages = this.lastSubscriptionMessages.get(senderKey)!;
+		this.lastSubscriptionMessages.delete(senderKey);
+		this.lastSubscriptionMessages.set(senderKey, messages);
+		for (const topic of relevantTopics) this.pruneUnsubscribedWatermarks(topic);
+		if (changed.length > 0) {
+			this.dispatchEvent(
+				new CustomEvent<UnsubcriptionEvent>("unsubscribe", {
+					detail: new UnsubcriptionEvent(from, changed, "remote-unsubscribe"),
+				}),
+			);
+		}
+	}
+
 	private async processShardPubSubMessage(input: {
 		pubsubMessage: PubSubMessage;
 		message: DataMessage;
@@ -4462,41 +5175,7 @@ export class TopicControlPlane
 		}
 
 		if (pubsubMessage instanceof Unsubscribe) {
-			const sender = from;
-			const senderKey = sender.hashcode();
-			const relevantTopics = pubsubMessage.topics.filter((t) =>
-				this.isTrackedTopic(t),
-			);
-
-			if (
-				relevantTopics.length > 0 &&
-				this.subscriptionMessageIsLatest(message, pubsubMessage, relevantTopics)
-			) {
-				const changed: string[] = [];
-				for (const topic of relevantTopics) {
-					const peers = this.topics.get(topic);
-					if (!peers) continue;
-					if (peers.delete(senderKey)) {
-						changed.push(topic);
-						this.peerToTopic.get(senderKey)?.delete(topic);
-					}
-				}
-				if (!this.peerToTopic.get(senderKey)?.size) {
-					this.peerToTopic.delete(senderKey);
-					this.lastSubscriptionMessages.delete(senderKey);
-				}
-				if (changed.length > 0) {
-					this.dispatchEvent(
-						new CustomEvent<UnsubcriptionEvent>("unsubscribe", {
-							detail: new UnsubcriptionEvent(
-								sender,
-								changed,
-								"remote-unsubscribe",
-							),
-						}),
-					);
-				}
-			}
+			this.processUnsubscribeMessage(message, pubsubMessage, from);
 			return;
 		}
 
@@ -4615,6 +5294,7 @@ export class TopicControlPlane
 			!(pubsubMessage instanceof TopicRootQuery) &&
 			!(pubsubMessage instanceof GetSubscribers) &&
 			!(pubsubMessage instanceof Subscribe) &&
+			!(pubsubMessage instanceof Unsubscribe) &&
 			!(pubsubMessage instanceof TopicRootQueryResponse)
 		) {
 			return true;