@peerbit/pubsub 5.2.11 → 5.3.1

package/src/index.ts

@@ -28,6 +28,7 @@ import {
 	type DirectStreamComponents,
 	type DirectStreamOptions,
 	type PeerStreams,
+	type RustTopicControl,
 } from "@peerbit/stream";
 import {
 	AcknowledgeAnyWhere,
@@ -64,12 +65,30 @@ import type {
 import { TopicRootControlPlane } from "./topic-root-control-plane.js";
 
 export * from "./fanout-tree.js";
+// The complete /peerbit/fanout-tree/0.5.0 wire codec and the
+// parent-upgrade decision module (the TS references the native rust-core
+// implementations are parity-tested against).
+export * as fanoutWire from "./fanout-tree-codec.js";
+export * as fanoutParentUpgrade from "./fanout-tree-parent-upgrade.js";
 export * from "./fanout-channel.js";
 export * from "./topic-root-control-plane.js";
 export { toUint8Array } from "./bytes.js";
 
 export const logger = loggerFn("peerbit:transport:topic-control-plane");
 const warn = logger.newScope("warn");
+
+const utf8Encoder = new TextEncoder();
+/**
+ * Offset of the `data` bytes inside a borsh-serialized `PubSubData`
+ * (variant byte + topics vec + strict bool + data length prefix).
+ */
+const preEncodedPubSubDataOffset = (topics: string[]): number => {
+	let offset = 1 + 4; // variant + topics vec length
+	for (const topic of topics) {
+		offset += 4 + utf8Encoder.encode(topic).byteLength;
+	}
+	return offset + 1 + 4; // strict + data length prefix
+};
 const logError = (e?: { message: string }) => {
 	logger.error(e?.message);
 };
@@ -119,6 +138,7 @@ const AUTO_TOPIC_ROOT_CANDIDATES_MAX = 64;
 // Topic-root queries may need to wait for the responder to finish opening an
 // outbound stream back to the requester after an inbound-only dial.
 const DEFAULT_TOPIC_ROOT_QUERY_TIMEOUT_MS = 12_000;
+const DIRECT_SHARD_ROOT_CONFIRM_TIMEOUT_MS = 2_000;
 
 const DEFAULT_PUBSUB_FANOUT_CHANNEL_OPTIONS: Omit<
 	FanoutTreeChannelOptions,
@@ -238,6 +258,21 @@ export class TopicControlPlane
 	public subscriptions: Map<string, { counter: number }>;
 	// Local topics requested via debounced subscribe, not yet applied in `subscriptions`.
 	private pendingSubscriptions: Set<string>;
+	/**
+	 * Per-shard batching of Subscribe{requestSubscribers} responses. When many
+	 * peers announce subscriptions in a burst (group subscribe), answering each
+	 * announcer with a routed unicast is quadratic in subscriber count and
+	 * melts the fanout route-resolution machinery (#983); a short window lets
+	 * one broadcast answer all concurrent announcers instead.
+	 */
+	private pendingSubscriberResponses: Map<
+		string,
+		{
+			targets: Set<string>;
+			topics: Set<string>;
+			timer: ReturnType<typeof setTimeout>;
+		}
+	> = new Map();
 	public lastSubscriptionMessages: Map<
 		string,
 		Map<string, { session: bigint; timestamp: bigint }>
@@ -246,6 +281,13 @@ export class TopicControlPlane
 	public readonly topicRootControlPlane: TopicRootControlPlane;
 	public readonly subscriberCacheMaxEntries: number;
 	public readonly fanout: FanoutTree;
+	// Native topic-control components of the rust-core DirectStream engine
+	// (`@peerbit/network-rust`). When set, the PubSubMessage codec, the topic
+	// hashing behind shard mapping and root selection, the root-directory
+	// state and the subscribe-state convergence rules run natively; the
+	// observable subscription maps and all events stay unchanged. Unset (the
+	// default) leaves every code path as-is.
+	private readonly nativeTopicControl?: RustTopicControl;
 
 	private debounceSubscribeAggregator: DebouncedAccumulatorCounterMap;
 	private debounceUnsubscribeAggregator: DebouncedAccumulatorCounterMap;
@@ -253,10 +295,7 @@ export class TopicControlPlane
 	private readonly shardCount: number;
 	private readonly shardTopicPrefix: string;
 	private readonly hostShards: boolean;
-	private readonly shardRootCache = new Map<
-		string,
-		{ root: string; authoritative: boolean }
-	>();
+	private readonly shardRootCache = new Map<string, { root: string; authoritative: boolean }>();
 	private readonly shardTopicCache = new Map<string, string>();
 	private readonly shardRefCounts = new Map<string, number>();
 	private readonly pinnedShards = new Set<string>();
@@ -325,6 +364,12 @@ export class TopicControlPlane
 
 		this.topicRootControlPlane =
 			props?.topicRootControlPlane || new TopicRootControlPlane();
+		this.nativeTopicControl = this.rustCore?.topicControl;
+		if (this.nativeTopicControl) {
+			this.topicRootControlPlane.adoptNativeDirectoryState(
+				this.nativeTopicControl.createRootDirectoryState(),
+			);
+		}
 		this.dispatchEventOnSelfPublish =
 			props?.dispatchEventOnSelfPublish || false;
 
@@ -393,12 +438,18 @@ export class TopicControlPlane
 		this.debounceSubscribeAggregator = debouncedAccumulatorSetCounter(
 			(set) => this._subscribe([...set.values()]),
 			props?.subscriptionDebounceDelay ?? 50,
+			(error) =>
+				logger.error(`Debounced subscribe failed: ${error?.message ?? error}`),
 		);
 		// NOTE: Unsubscribe should update local state immediately and batch only the
 		// best-effort network announcements to avoid teardown stalls (program close).
 		this.debounceUnsubscribeAggregator = debouncedAccumulatorSetCounter(
 			(set) => this._announceUnsubscribe([...set.values()]),
 			props?.subscriptionDebounceDelay ?? 50,
+			(error) =>
+				logger.error(
+					`Debounced unsubscribe announce failed: ${error?.message ?? error}`,
+				),
 		);
 	}
 
@@ -497,6 +548,10 @@ export class TopicControlPlane
 
 		this.subscriptions.clear();
 		this.pendingSubscriptions.clear();
+		for (const entry of this.pendingSubscriberResponses.values()) {
+			clearTimeout(entry.timer);
+		}
+		this.pendingSubscriberResponses.clear();
 		this.topics.clear();
 		this.peerToTopic.clear();
 		this.lastSubscriptionMessages.clear();
@@ -611,6 +666,12 @@ export class TopicControlPlane
 	}
 
 	private normalizeAutoTopicRootCandidates(candidates: string[]): string[] {
+		if (this.nativeTopicControl) {
+			return this.nativeTopicControl.normalizeAutoCandidates(
+				candidates,
+				this.publicKeyHash,
+			);
+		}
 		const unique = new Set<string>();
 		for (const c of candidates) {
 			if (!c) continue;
@@ -680,7 +741,7 @@ export class TopicControlPlane
 		if (candidates.length === 0) return;
 
 		const msg = new TopicRootCandidates({ candidates });
-		const embedded = await this.createMessage(toUint8Array(msg.bytes()), {
+		const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
 			mode: new AnyWhere(),
 			priority: 1,
 			skipRecipientValidation: true,
@@ -776,7 +837,7 @@ export class TopicControlPlane
 					topics: userTopics,
 					requestSubscribers: true,
 				});
-				const embedded = await this.createMessage(toUint8Array(msg.bytes()), {
+				const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
 					mode: new AnyWhere(),
 					priority: 1,
 					skipRecipientValidation: true,
@@ -925,12 +986,118 @@ export class TopicControlPlane
 		const t = topic.toString();
 		const cached = this.shardTopicCache.get(t);
 		if (cached) return cached;
-		const index = topicHash32(t) % this.shardCount;
-		const shardTopic = `${this.shardTopicPrefix}${index}`;
+		const shardTopic = this.nativeTopicControl
+			? this.nativeTopicControl.shardTopic(
+					t,
+					this.shardCount,
+					this.shardTopicPrefix,
+				)
+			: `${this.shardTopicPrefix}${topicHash32(t) % this.shardCount}`;
 		this.shardTopicCache.set(t, shardTopic);
 		return shardTopic;
 	}
 
+	/**
+	 * Serialize a control-plane message (borsh `PubSubMessage`); rust-core
+	 * mode encodes natively (byte-identical, covered by the parity suite).
+	 */
+	private encodePubSubMessage(message: PubSubMessage): Uint8Array {
+		const native = this.nativeTopicControl;
+		if (native) {
+			if (message instanceof PubSubData) {
+				return native.encodePubSubData(
+					message.topics,
+					message.strict,
+					message.data,
+				);
+			}
+			if (message instanceof Subscribe) {
+				return native.encodeSubscribe(
+					message.topics,
+					message.requestSubscribers,
+				);
+			}
+			if (message instanceof Unsubscribe) {
+				return native.encodeUnsubscribe(message.topics);
+			}
+			if (message instanceof GetSubscribers) {
+				return native.encodeGetSubscribers(message.topics);
+			}
+			if (message instanceof TopicRootCandidates) {
+				return native.encodeTopicRootCandidates(message.candidates);
+			}
+			if (message instanceof PeerUnavailable) {
+				return native.encodePeerUnavailable(
+					message.publicKeyHash,
+					message.session,
+					message.timestamp,
+					message.topics,
+				);
+			}
+			if (message instanceof TopicRootQuery) {
+				return native.encodeTopicRootQuery(message.requestId, message.topic);
+			}
+			if (message instanceof TopicRootQueryResponse) {
+				return native.encodeTopicRootQueryResponse(
+					message.requestId,
+					message.topic,
+					message.root,
+				);
+			}
+		}
+		return toUint8Array(message.bytes());
+	}
+
+	/**
+	 * Parse a control-plane payload; rust-core mode decodes natively into the
+	 * same message classes (decode failures throw either way, so callers keep
+	 * their fallback behavior).
+	 */
+	private decodePubSubMessage(bytes: Uint8Array): PubSubMessage {
+		const native = this.nativeTopicControl;
+		if (native) {
+			const decoded = native.decodePubSubMessage(bytes);
+			switch (decoded.type) {
+				case "data":
+					return new PubSubData({
+						topics: decoded.topics,
+						data: decoded.data,
+						strict: decoded.strict,
+					});
+				case "subscribe":
+					return new Subscribe({
+						topics: decoded.topics,
+						requestSubscribers: decoded.requestSubscribers,
+					});
+				case "unsubscribe":
+					return new Unsubscribe({ topics: decoded.topics });
+				case "get-subscribers":
+					return new GetSubscribers({ topics: decoded.topics });
+				case "topic-root-candidates":
+					return new TopicRootCandidates({ candidates: decoded.candidates });
+				case "peer-unavailable":
+					return new PeerUnavailable({
+						publicKeyHash: decoded.publicKeyHash,
+						session: decoded.session,
+						timestamp: decoded.timestamp,
+						topics: decoded.topics,
+					});
+				case "topic-root-query":
+					return new TopicRootQuery({
+						requestId: decoded.requestId,
+						topic: decoded.topic,
+					});
+				case "topic-root-query-response":
+					return new TopicRootQueryResponse({
+						requestId: decoded.requestId,
+						topic: decoded.topic,
+						root: decoded.root,
+					});
+			}
+		}
+		return PubSubMessage.from(bytes);
+	}
+
 	private async resolveTopicRootState(
 		topic: string,
 	): Promise<{ root?: string; authoritative: boolean }> {
@@ -1024,7 +1191,7 @@ export class TopicControlPlane
 		peer: PeerStreams,
 		pubsubMessage: PubSubMessage,
 	) {
-		const embedded = await this.createMessage(toUint8Array(pubsubMessage.bytes()), {
+		const embedded = await this.createMessage(this.encodePubSubMessage(pubsubMessage), {
 			mode: new SilentDelivery({
 				to: [peer.publicKey.hashcode()],
 				redundancy: 1,
@@ -1051,6 +1218,7 @@ export class TopicControlPlane
 	private async queryTopicRootFromPeer(
 		peer: PeerStreams,
 		topic: string,
+		timeoutMs = DEFAULT_TOPIC_ROOT_QUERY_TIMEOUT_MS,
 	): Promise<string | undefined> {
 		if (!this.started || this.stopping) return undefined;
 
@@ -1059,7 +1227,7 @@ export class TopicControlPlane
 			const timer = setTimeout(() => {
 				this.pendingTopicRootQueries.delete(requestId);
 				resolve(undefined);
-			}, DEFAULT_TOPIC_ROOT_QUERY_TIMEOUT_MS);
+			}, Math.max(1, Math.floor(timeoutMs)));
 			timer.unref?.();
 			this.pendingTopicRootQueries.set(requestId, { topic, resolve, timer });
 		});
@@ -1081,6 +1249,33 @@ export class TopicControlPlane
 		return responsePromise;
 	}
 
+	private async confirmDirectShardRoot(
+		shardTopic: string,
+		root: string,
+		signal?: AbortSignal,
+	): Promise<string> {
+		if (root === this.publicKeyHash) return root;
+		const rootPeer = this.peers.get(root);
+		if (!rootPeer) return root;
+
+		const confirmation = await withAbort(
+			this.queryTopicRootFromPeer(
+				rootPeer,
+				shardTopic,
+				DIRECT_SHARD_ROOT_CONFIRM_TIMEOUT_MS,
+			),
+			signal,
+		);
+		if (!confirmation) return root;
+		if (confirmation !== root) {
+			this.shardRootCache.set(shardTopic, {
+				root: confirmation,
+				authoritative: true,
+			});
+		}
+		return confirmation;
+	}
+
 	private async resolveQueryableTopicRoot(
 		topic: string,
 	): Promise<string | undefined> {
@@ -1137,6 +1332,7 @@ export class TopicControlPlane
 			signal?: AbortSignal;
 		},
 	): Promise<void> {
+		if (!this.started) throw new NotStartedError();
 		const t = shardTopic.toString();
 		const pin = options?.pin === true;
 		const wantEphemeral = options?.ephemeral === true;
@@ -1166,6 +1362,7 @@ export class TopicControlPlane
 		}
 
 		root = root ?? (await this.resolveShardRoot(t));
+		root = await this.confirmDirectShardRoot(t, root, options?.signal);
 		const channel = new FanoutChannel(this.fanout, { topic: t, root });
 
 		const onPayload = (payload: Uint8Array) => {
@@ -1186,7 +1383,7 @@ export class TopicControlPlane
 
 			let pubsubMessage: PubSubMessage;
 			try {
-				pubsubMessage = PubSubMessage.from(dm.data);
+				pubsubMessage = this.decodePubSubMessage(dm.data);
 			} catch {
 				return;
 			}
@@ -1232,6 +1429,9 @@ export class TopicControlPlane
 				this.seenCache.add(msgId, seen ? seen + 1 : 1);
 				if (seen) return;
 
+				// fanout-delivered frames bypass the inbound stream decode, so
+				// the nested envelope is verified natively here when possible
+				this.seedNativeWireVerification(dm, payload);
 				if ((await this.verifyAndProcess(dm)) === false) {
 					return;
 				}
@@ -1295,9 +1495,9 @@ export class TopicControlPlane
 					// ignore
 				}
 				try {
-					channel.close();
+					await channel.leave({ notifyParent: false, kickChildren: false });
 				} catch {
-					// ignore
+					channel.close();
 				}
 				throw error;
 			}
@@ -1419,7 +1619,7 @@ export class TopicControlPlane
 					topics: userTopics,
 					requestSubscribers: true,
 				});
-				const embedded = await this.createMessage(toUint8Array(msg.bytes()), {
+				const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
 					mode: new AnyWhere(),
 					priority: 1,
 					skipRecipientValidation: true,
@@ -1498,7 +1698,7 @@ export class TopicControlPlane
 				// Announce first.
 				try {
 					const msg = new Unsubscribe({ topics: userTopics });
-					const embedded = await this.createMessage(toUint8Array(msg.bytes()), {
+					const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
 						mode: new AnyWhere(),
 						priority: 1,
 						skipRecipientValidation: true,
@@ -1571,7 +1771,7 @@ export class TopicControlPlane
 						timestamp: batch.timestamp,
 						topics: batch.topics,
 					});
-					const embedded = await this.createMessage(toUint8Array(msg.bytes()), {
+					const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
 						mode: new AnyWhere(),
 						priority: 1,
 						skipRecipientValidation: true,
@@ -1601,7 +1801,7 @@ export class TopicControlPlane
 				timestamp: 0n,
 				topics: [],
 			});
-			const embedded = await this.createMessage(toUint8Array(msg.bytes()), {
+			const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
 				mode: new AnyWhere(),
 				priority: 1,
 				skipRecipientValidation: true,
@@ -1702,7 +1902,7 @@ export class TopicControlPlane
 				const persistent = (this.shardRefCounts.get(shardTopic) ?? 0) > 0;
 				await this.ensureFanoutChannel(shardTopic, { ephemeral: !persistent });
 
-				const embedded = await this.createMessage(toUint8Array(msg.bytes()), {
+				const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
 					mode: new AnyWhere(),
 					priority: 1,
 					skipRecipientValidation: true,
@@ -1754,10 +1954,13 @@ export class TopicControlPlane
 			const msg = data
 				? new PubSubData({ topics: topicsAll, data, strict: true })
 				: undefined;
-			const message = await this.createMessage(msg?.bytes(), {
-				...options,
-				skipRecipientValidation: this.dispatchEventOnSelfPublish,
-			});
+			const message = await this.createMessage(
+				msg ? this.encodePubSubMessage(msg) : undefined,
+				{
+					...options,
+					skipRecipientValidation: this.dispatchEventOnSelfPublish,
+				},
+			);
 
 			if (msg) {
 				this.dispatchEvent(
@@ -1800,7 +2003,7 @@ export class TopicControlPlane
 		}
 
 		const msg = new PubSubData({ topics: topicsAll, data, strict: false });
-		const embedded = await this.createMessage(toUint8Array(msg.bytes()), {
+		const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
 			mode: new AnyWhere(),
 			priority: options?.priority,
 			responsePriority: options?.responsePriority,
@@ -1862,6 +2065,76 @@ export class TopicControlPlane
 		return embedded.id;
 	}
 
+	/**
+	 * Publish a pre-encoded `PubSubData` payload to explicit recipients.
+	 *
+	 * `payload` must be the exact borsh serialization of
+	 * `new PubSubData({ topics, data, strict: true })` — callers that encode
+	 * the payload elsewhere (e.g. the shared-log fused send path serializing
+	 * inside wasm) hand the finished bytes here so the wrapping `PubSubData`
+	 * copy of the regular `publish` path is skipped. Everything else matches
+	 * the explicit-recipient branch of {@link publish}: the payload becomes a
+	 * signed `DataMessage` delivered over DirectStream.
+	 */
+	async publishPreEncodedData(
+		payload: Uint8Array,
+		properties: {
+			topics: string[];
+		},
+		options: {
+			mode: SilentDelivery | AcknowledgeDelivery;
+		} & { client?: string } & PriorityOptions &
+			ResponsePriorityOptions &
+			ExpiresAtOptions &
+			IdOptions &
+			WithExtraSigners & { signal?: AbortSignal },
+	): Promise<Uint8Array | undefined> {
+		if (!this.started) throw new NotStartedError();
+		if (!options?.mode || !deliveryModeHasReceiver(options.mode)) {
+			throw new Error(
+				"publishPreEncodedData requires a delivery mode with explicit recipients",
+			);
+		}
+
+		const message = await this.createMessage(payload, {
+			...options,
+			skipRecipientValidation: this.dispatchEventOnSelfPublish,
+		});
+
+		this.dispatchEvent(
+			new CustomEvent("publish", {
+				detail: new PublishEvent({
+					client: options?.client,
+					data: new PubSubData({
+						topics: properties.topics,
+						data: payload.subarray(
+							preEncodedPubSubDataOffset(properties.topics),
+						),
+						strict: true,
+					}),
+					message,
+				}),
+			}),
+		);
+
+		const silentDelivery = options.mode instanceof SilentDelivery;
+		try {
+			await this.publishMessage(
+				this.publicKey,
+				message,
+				undefined,
+				undefined,
+				options?.signal,
+			);
+		} catch (error) {
+			if (error instanceof DeliveryError && silentDelivery !== false) {
+				return message.id;
+			}
+			throw error;
+		}
+		return message.id;
+	}
+
 	public onPeerSession(key: PublicSignKey, _session: number): void {
 		if (!Number.isFinite(_session) || _session < 0) {
 			return;
@@ -1999,23 +2272,44 @@ export class TopicControlPlane
 		timestamp: bigint,
 		relevantTopics: string[],
 	) {
-		for (const topic of relevantTopics) {
-			const last = this.lastSubscriptionMessages
-				.get(subscriberKey)
-				?.get(topic);
-			if (!last) {
-				continue;
-			}
-			if (last.session > session) {
-				return false;
+		if (this.nativeTopicControl) {
+			const lasts: bigint[] = [];
+			for (const topic of relevantTopics) {
+				const last = this.lastSubscriptionMessages
+					.get(subscriberKey)
+					?.get(topic);
+				if (last) {
+					lasts.push(last.session, last.timestamp);
+				}
 			}
 			if (
-				timestamp !== 0n &&
-				last.session === session &&
-				last.timestamp > timestamp
+				!this.nativeTopicControl.subscriptionIsLatest(
+					BigUint64Array.from(lasts),
+					session,
+					timestamp,
+				)
 			) {
 				return false;
 			}
+		} else {
+			for (const topic of relevantTopics) {
+				const last = this.lastSubscriptionMessages
+					.get(subscriberKey)
+					?.get(topic);
+				if (!last) {
+					continue;
+				}
+				if (last.session > session) {
+					return false;
+				}
+				if (
+					timestamp !== 0n &&
+					last.session === session &&
+					last.timestamp > timestamp
+				) {
+					return false;
+				}
+			}
 		}
 
 		for (const topic of relevantTopics) {
@@ -2032,6 +2326,23 @@ export class TopicControlPlane
 		return true;
 	}
 
+	/**
+	 * `Subscribe` replaces tracked subscription data for new subscribers or
+	 * strictly newer sessions; equal/older sessions only refresh cache order.
+	 */
+	private subscribeShouldReplace(
+		existing: SubscriptionData | undefined,
+		session: bigint,
+	): boolean {
+		if (this.nativeTopicControl) {
+			return this.nativeTopicControl.subscribeShouldReplace(
+				existing?.session,
+				session,
+			);
+		}
+		return !existing || existing.session < session;
+	}
+
 	private subscriptionMessageIsLatest(
 		message: DataMessage,
 		_pubsubMessage: Subscribe | Unsubscribe,
@@ -2046,6 +2357,78 @@ export class TopicControlPlane
 		);
 	}
 
+	/**
+	 * Answer Subscribe{requestSubscribers} announces without letting bursts go
+	 * quadratic (#983). Leading edge: the first announcer is answered
+	 * immediately with a targeted unicast — a lone joiner sees no added
+	 * latency. Announcers arriving within the trailing window that this opens
+	 * are batched and answered with ONE broadcast, instead of S(S-1) routed
+	 * unicasts whose cold route resolutions flood the shard tree.
+	 */
+	private queueSubscriberResponse(
+		shardTopic: string,
+		targetHash: string,
+		topics: string[],
+	) {
+		let entry = this.pendingSubscriberResponses.get(shardTopic);
+		if (!entry) {
+			const created = {
+				targets: new Set<string>(),
+				topics: new Set<string>(),
+				timer: setTimeout(
+					() => {
+						this.pendingSubscriberResponses.delete(shardTopic);
+						if (created.targets.size === 0) return;
+						void this.flushSubscriberResponses(shardTopic, created).catch(
+							logErrorIfStarted,
+						);
+					},
+					150 + Math.floor(Math.random() * 150),
+				),
+			};
+			this.pendingSubscriberResponses.set(shardTopic, created);
+			// Leading edge: respond to the burst opener right away.
+			void this.flushSubscriberResponses(shardTopic, {
+				targets: new Set([targetHash]),
+				topics: new Set(topics),
+			}).catch(logErrorIfStarted);
+			return;
+		}
+		entry.targets.add(targetHash);
+		for (const t of topics) entry.topics.add(t);
+	}
+
+	private async flushSubscriberResponses(
+		shardTopic: string,
+		entry: { targets: Set<string>; topics: Set<string> },
+	) {
+		if (!this.started) return;
+		// Re-filter: our subscriptions may have changed within the window.
+		const topics = this.getSubscriptionOverlap([...entry.topics]);
+		if (topics.length === 0) return;
+		const response = new Subscribe({
+			topics,
+			requestSubscribers: false,
+		});
+		const embedded = await this.createMessage(
+			this.encodePubSubMessage(response),
+			{
+				mode: new AnyWhere(),
+				priority: 1,
+				skipRecipientValidation: true,
+			} as any,
+		);
+		const payload = toUint8Array(embedded.bytes());
+		const [firstTarget] = entry.targets;
+		if (entry.targets.size === 1 && firstTarget) {
+			await this.sendFanoutUnicastOrBroadcast(shardTopic, firstTarget, payload);
+			return;
+		}
+		const st = this.fanoutChannels.get(shardTopic);
+		if (!st) return;
+		await st.channel.publishMaybe(payload);
+	}
+
 	private async sendFanoutUnicastOrBroadcast(
 		shardTopic: string,
 		targetHash: string,
@@ -2127,7 +2510,7 @@ export class TopicControlPlane
 					this.initializePeer(sender);
 
 					const existing = peers.get(senderKey);
-					if (!existing || existing.session < message.header.session) {
+					if (this.subscribeShouldReplace(existing, message.header.session)) {
 						peers.delete(senderKey);
 						peers.set(
 							senderKey,
@@ -2140,7 +2523,7 @@ export class TopicControlPlane
 						changed.push(topic);
 					} else {
 						peers.delete(senderKey);
-						peers.set(senderKey, existing);
+						peers.set(senderKey, existing!);
 					}
 
 					if (!existing) {
@@ -2236,7 +2619,7 @@ export class TopicControlPlane
 					this.initializePeer(sender);
 
 					const existing = peers.get(senderKey);
-					if (!existing || existing.session < message.header.session) {
+					if (this.subscribeShouldReplace(existing, message.header.session)) {
 						peers.delete(senderKey);
 						peers.set(
 							senderKey,
@@ -2249,7 +2632,7 @@ export class TopicControlPlane
 						changed.push(topic);
 					} else {
 						peers.delete(senderKey);
-						peers.set(senderKey, existing);
+						peers.set(senderKey, existing!);
 					}
 
 					if (!existing) {
@@ -2270,24 +2653,7 @@ export class TopicControlPlane
 			if (pubsubMessage.requestSubscribers) {
 				const overlap = this.getSubscriptionOverlap(pubsubMessage.topics);
 				if (overlap.length > 0) {
-					const response = new Subscribe({
-						topics: overlap,
-						requestSubscribers: false,
-					});
-					const embedded = await this.createMessage(
-						toUint8Array(response.bytes()),
-						{
-							mode: new AnyWhere(),
-							priority: 1,
-							skipRecipientValidation: true,
-						} as any,
-					);
-					const payload = toUint8Array(embedded.bytes());
-					await this.sendFanoutUnicastOrBroadcast(
-						shardTopic,
-						senderKey,
-						payload,
-					);
+					this.queueSubscriberResponse(shardTopic, senderKey, overlap);
 				}
 			}
 			return;
@@ -2406,7 +2772,7 @@ export class TopicControlPlane
 				requestSubscribers: false,
 			});
 			const embedded = await this.createMessage(
-				toUint8Array(response.bytes()),
+				this.encodePubSubMessage(response),
 				{
 					mode: new AnyWhere(),
 					priority: 1,
@@ -2432,7 +2798,7 @@ export class TopicControlPlane
 
 		let pubsubMessage: PubSubMessage;
 		try {
-			pubsubMessage = PubSubMessage.from(message.data);
+			pubsubMessage = this.decodePubSubMessage(message.data);
 		} catch {
 			return super.onDataMessage(from, stream, message, seenBefore);
 		}