@optimystic/db-p2p 0.13.4 → 0.14.0

package/src/protocol-client.ts

@@ -7,6 +7,39 @@ import { createLogger } from './logger.js';
 
 const log = createLogger('protocol-client');
 
+/**
+ * Thrown when the per-peer dial deadline expires before a stream is established.
+ * Distinct from a libp2p dial failure (no route, refused, etc.) so the
+ * batch-retry loop and diagnostic surfaces can identify a slow/unreachable peer
+ * specifically. `.code === DIAL_TIMEOUT_ERROR_CODE`.
+ */
+export const DIAL_TIMEOUT_ERROR_CODE = 'DIAL_TIMEOUT';
+
+export class DialTimeoutError extends Error {
+	readonly code = DIAL_TIMEOUT_ERROR_CODE;
+	constructor(peer: string, protocol: string, ms: number) {
+		super(`dial timeout: peer=${peer} protocol=${protocol} after ${ms}ms`);
+		this.name = 'DialTimeoutError';
+	}
+}
+
+/**
+ * Thrown when a peer dialed successfully but the response-read deadline expired
+ * before it wrote a reply (it connected, then went silent). Distinct from
+ * {@link DialTimeoutError} (never connected) and from a parent cancellation
+ * (`options.signal`), so callers/diagnostics can tell "peer went quiet" apart
+ * from "peer was unreachable" and "we cancelled". `.code === RESPONSE_TIMEOUT_ERROR_CODE`.
+ */
+export const RESPONSE_TIMEOUT_ERROR_CODE = 'RESPONSE_TIMEOUT';
+
+export class ResponseTimeoutError extends Error {
+	readonly code = RESPONSE_TIMEOUT_ERROR_CODE;
+	constructor(peer: string, protocol: string, ms: number) {
+		super(`response timeout: peer=${peer} protocol=${protocol} after ${ms}ms`);
+		this.name = 'ResponseTimeoutError';
+	}
+}
+
 /** Base class for clients that communicate via a libp2p protocol */
 export class ProtocolClient {
 	constructor(
@@ -17,27 +50,91 @@ export class ProtocolClient {
 	protected async processMessage<T>(
 		message: unknown,
 		protocol: string,
-		options?: { signal?: AbortSignal; correlationId?: string }
+		options?: { signal?: AbortSignal; correlationId?: string; dialTimeoutMs?: number; responseTimeoutMs?: number }
 	): Promise<T> {
 		const peer = this.peerId.toString();
 		const cid = options?.correlationId;
 		log('dial peer=%s protocol=%s%s', peer, protocol, cid ? ` cid=${cid}` : '');
 		const t0 = Date.now();
 
+		// Per-peer dial deadline. When set, an unreachable peer fails fast so the
+		// caller can re-pick a different coordinator — independent of any overall
+		// transaction budget the caller may also be enforcing.
+		const dialTimeoutMs = options?.dialTimeoutMs;
+		const dialController = dialTimeoutMs && dialTimeoutMs > 0 ? new AbortController() : undefined;
+		let dialTimer: ReturnType<typeof setTimeout> | undefined;
+		const onParentAbort = () => dialController?.abort(options?.signal?.reason);
+		if (dialController) {
+			dialTimer = setTimeout(() => {
+				dialController.abort(new DialTimeoutError(peer, protocol, dialTimeoutMs!));
+			}, dialTimeoutMs);
+			if (options?.signal) {
+				if (options.signal.aborted) dialController.abort(options.signal.reason);
+				else options.signal.addEventListener('abort', onParentAbort, { once: true });
+			}
+		}
+		const dialSignal = dialController?.signal ?? options?.signal;
+
 		let stream: Libp2pStream;
 		try {
 			stream = await this.peerNetwork.connect(
 				this.peerId,
 				protocol,
-				{ signal: options?.signal }
+				{ signal: dialSignal }
 			) as unknown as Libp2pStream;
 		} catch (err) {
-			log('dial:fail peer=%s protocol=%s ms=%d%s', peer, protocol, Date.now() - t0, cid ? ` cid=${cid}` : '');
+			const elapsed = Date.now() - t0;
+			// If the dial AbortController fired due to our own timer, surface the
+			// dial-timeout error rather than the underlying AbortError so callers
+			// can distinguish "peer was slow" from "user/parent cancelled".
+			if (dialController?.signal.aborted && dialController.signal.reason instanceof DialTimeoutError) {
+				log('dial:timeout peer=%s protocol=%s ms=%d%s', peer, protocol, elapsed, cid ? ` cid=${cid}` : '');
+				throw dialController.signal.reason;
+			}
+			const errCode = (err as { code?: unknown })?.code;
+			const errMessage = err instanceof Error ? err.message : String(err);
+			const truncatedMsg = errMessage.length > 200 ? errMessage.slice(0, 200) + '…' : errMessage;
+			log('dial:fail peer=%s protocol=%s ms=%d code=%s msg=%s%s',
+				peer, protocol, elapsed,
+				typeof errCode === 'string' && errCode.length > 0 ? errCode : 'none',
+				truncatedMsg,
+				cid ? ` cid=${cid}` : ''
+			);
 			throw err;
+		} finally {
+			if (dialTimer) clearTimeout(dialTimer);
+			if (options?.signal) options.signal.removeEventListener('abort', onParentAbort);
 		}
 		log('dial:ok peer=%s ms=%d%s', peer, Date.now() - t0, cid ? ` cid=${cid}` : '');
 
+		// Per-peer response deadline. The dial controller is already cleared once a
+		// stream is established, so a peer that connects but then never writes a frame
+		// (and never closes the stream) would hang the `first(...)` read below forever.
+		// Setting a timer alone is not enough — the underlying `for await` over the
+		// libp2p stream keeps awaiting regardless. The decisive action is to actively
+		// `stream.abort(...)`, which rejects the stream's async iterator and unblocks
+		// the read. A parent `options.signal` abort is forwarded the same way so a
+		// cancelled caller tears the stream down rather than leaking it. When neither
+		// `responseTimeoutMs` nor `signal` is supplied, no cap is imposed — preserving
+		// every existing caller (mirrors how omitting `dialTimeoutMs` imposes no dial cap).
+		const responseTimeoutMs = options?.responseTimeoutMs;
+		let responseTimer: ReturnType<typeof setTimeout> | undefined;
+		let responseTimeoutError: ResponseTimeoutError | undefined;
+		const onParentAbortResponse = () => {
+			try { stream.abort(options?.signal?.reason ?? new Error('aborted')); } catch { /* already torn down */ }
+		};
 		try {
+			if (responseTimeoutMs && responseTimeoutMs > 0) {
+				responseTimer = setTimeout(() => {
+					responseTimeoutError = new ResponseTimeoutError(peer, protocol, responseTimeoutMs);
+					try { stream.abort(responseTimeoutError); } catch { /* already torn down */ }
+				}, responseTimeoutMs);
+			}
+			if (options?.signal) {
+				if (options.signal.aborted) onParentAbortResponse();
+				else options.signal.addEventListener('abort', onParentAbortResponse, { once: true });
+			}
+
 			// Send the request using length-prefixed encoding
 			const encoded = pipe(
 				[new TextEncoder().encode(JSON.stringify(message))],
@@ -65,11 +162,28 @@ export class ProtocolClient {
 				}
 			) as AsyncIterable<T>;
 
-			const result = await first(() => source, () => { throw new Error('No response received') });
+			let result: T;
+			try {
+				result = await first(() => source, () => { throw new Error('No response received') });
+			} catch (err) {
+				// Aborting the stream (our timer or a parent abort) surfaces here as an
+				// iterator error. Translate it so callers see why the read ended.
+				if (responseTimeoutError) {
+					log('response:timeout peer=%s protocol=%s ms=%d%s', peer, protocol, Date.now() - t0, cid ? ` cid=${cid}` : '');
+					throw responseTimeoutError;
+				}
+				if (options?.signal?.aborted) {
+					throw options.signal.reason;
+				}
+				throw err;
+			}
 			log('response peer=%s protocol=%s ms=%d%s', peer, protocol, Date.now() - t0, cid ? ` cid=${cid}` : '');
 			return result;
 		} finally {
-			await stream.close();
+			if (responseTimer) clearTimeout(responseTimer);
+			if (options?.signal) options.signal.removeEventListener('abort', onParentAbortResponse);
+			// Closing an already-aborted stream must be safe.
+			try { await stream.close(); } catch { /* already torn down */ }
 		}
 	}
 }

package/src/reactivity/forwarder-host.ts

@@ -0,0 +1,438 @@
+/**
+ * Reactivity — forwarder **host** orchestrator (`docs/reactivity.md` §Propagation, §Slow-subscriber
+ * backpressure, §Per-cohort policy).
+ *
+ * This is the piece that turns the in-process forward *decision* (db-core's {@link ReactivityForwarder})
+ * into live fan-out over the {@link ReactivityNotifyTransport}. For one {@link NotificationV1} — whether
+ * locally originated (the change-bridge's `emit` seam binds to {@link ReactivityForwarderHost.ingest}) or
+ * inbound off a dial ({@link ReactivityForwarderHost.onInbound}) — it:
+ *
+ *  1. lazily instantiates the per-collection {@link PushState} + forwarder behind the Edge policy gate
+ *     ({@link instantiateForwarderPushState}: `undefined` on an Edge node ⇒ this node never forwards);
+ *  2. runs the db-core receive path (verify → dedupe → buffer) and stops on `"duplicate"` / `"untrusted"`;
+ *  3. on `"forward"`, fans the **unmodified** frame out to every direct subscriber (through the
+ *     per-subscriber bounded queue, so a slow/dead subscriber's drops never stall the rest) and every
+ *     child cohort.
+ *
+ * It owns the per-subscriber dequeue→dial delivery loop, the bounded-queue backpressure interaction,
+ * subscriber-queue eviction (the memory bound — a departed subscriber's queue is reclaimed lazily each
+ * fan-out round), and per-topic serialization so the replay ring + dedupe set never interleave across two
+ * concurrent notifications for the same collection.
+ *
+ * **Subscriber-id space.** `selfPeerId`, the {@link ReactivityForwarderHostDeps.directSubscribers} output,
+ * the {@link CohortRef.primary} child targets, and every {@link ReactivityNotifyTransport.send} target are
+ * the **same** string space (it is also the `perSubscriberQueue` key). This host is agnostic to the concrete
+ * encoding so long as it is consistent across all four seams; the **transport** pins which space —
+ * {@link import("./notify-transport.js").Libp2pReactivityNotifyTransport.send} calls `peerIdFromString`, so
+ * the space is the **canonical peer-id string** (NOT base64url-of-member-bytes — that would silently fail
+ * `peerIdFromString` and never dial). The {@link reactivityDirectSubscribers} adapter and the node-wiring
+ * layer ([reactivity-notification-transport]) therefore both emit peer-id strings.
+ *
+ * This module deliberately touches neither the libp2p node assembly ([reactivity-notification-transport])
+ * nor gossip ([reactivity-pushstate-gossip]); it depends only on the transport interface + db-core logic,
+ * so it is unit-testable with a fake transport.
+ */
+
+import {
+	reactivityTopicId,
+	b64urlToBytes,
+	bytesToB64url,
+	createReactivityForwarder,
+	instantiateForwarderPushState,
+	decodeSubscribeAppPayload,
+	TailDrainGate,
+	type NotificationV1,
+	type PeerRef,
+	type NodeProfile,
+	type PushState,
+	type PushStateInit,
+	type CohortRef,
+	type NotificationVerifier,
+	type ReactivityForwarder,
+	type RegistrationRecord,
+	type RotationRedirectV1,
+} from "@optimystic/db-core";
+import type { ReactivityNotifyTransport } from "./notify-transport.js";
+import { bytesToPeerIdString } from "../cohort-topic/peer-codec.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-forwarder-host");
+
+/**
+ * The reactivity topic id a notification belongs to: `H(tailId ‖ "reactivity")` over the notification's
+ * tail anchor. Kept in one place so it matches origination's `reactivityTailBytes` encoding and the
+ * subscriber/forwarder verifier's coord derivation byte-for-byte (both decode `tailId` as base64url first).
+ */
+export function reactivityNotificationTopicId(n: NotificationV1): Uint8Array {
+	return reactivityTopicId(b64urlToBytes(n.tailId));
+}
+
+/** The minimal cohort read the {@link reactivityDirectSubscribers} adapter needs (a {@link CoordEngine} satisfies it). */
+export interface ReactivityRecordSource {
+	/** This cohort's locally-known direct registration records for `topicId`. */
+	records(topicId: Uint8Array): readonly RegistrationRecord[];
+}
+
+/**
+ * The direct-subscriber **peer-id strings** for a reactivity topic, read from a cohort's
+ * {@link RegistrationRecord} set: a record carries a subscriber iff its opaque `appState` decodes to a
+ * reactivity {@link import("@optimystic/db-core").SubscribeAppPayloadV1}. `record.participantId` is the
+ * subscriber's dialable member id (db-core's `service` pins `participantId = self`), carried as
+ * `peerIdToBytes(peerId) = utf8(peerIdString)`; this decodes it back to the canonical peer-id string via
+ * {@link bytesToPeerIdString} so the value is both the `transport.send` dial target (which calls
+ * `peerIdFromString`) and the `perSubscriberQueue` key. **The whole host runs in this peer-id-string space**
+ * — `selfPeerId`, `resolveChildPrimary`, and every `send` target must agree, or a base64url-vs-peer-id
+ * mismatch is a silent no-dial. A record whose `appState` is absent or decodes to a non-reactivity payload
+ * (e.g. a matchmaking registration sharing the cohort store) is skipped.
+ */
+export function reactivityDirectSubscribers(source: ReactivityRecordSource, topicId: Uint8Array): string[] {
+	const out: string[] = [];
+	for (const record of source.records(topicId)) {
+		if (record.appState === undefined) {
+			continue;
+		}
+		try {
+			decodeSubscribeAppPayload(record.appState); // throws on a non-reactivity / malformed payload
+		} catch {
+			continue; // not a reactivity subscriber — leave the record to its own application
+		}
+		out.push(bytesToPeerIdString(record.participantId));
+	}
+	return out;
+}
+
+/** Construction inputs for a {@link ReactivityForwarderHost}. */
+export interface ReactivityForwarderHostDeps {
+	/** One-way notification transport (unicast send + inbound subscribe); fan-out dials each target through it. */
+	readonly transport: ReactivityNotifyTransport;
+	/** This node's member id, base64url — never dialed; a co-located subscriber is delivered in-process. */
+	readonly selfPeerId: string;
+	/** Node profile; gates {@link PushState} instantiation (Edge ⇒ subscriber-only, never forwards). */
+	readonly profile: NodeProfile;
+	/** Build the per-collection {@link PushStateInit} on first ingest for a topic this node serves. */
+	readonly pushStateInit: (topicId: Uint8Array, n: NotificationV1) => PushStateInit;
+	/** The notification verifier for a topic (a db-core `createNotificationVerifier` over the host's service verifier, T3). */
+	readonly verifierFor: (topicId: Uint8Array) => NotificationVerifier;
+	/** Direct-subscriber member ids (base64url) for a topic — e.g. {@link reactivityDirectSubscribers} over the cohort. */
+	readonly directSubscribers: (topicId: Uint8Array) => string[];
+	/** Resolve a child cohort's dialable primary when {@link CohortRef.primary} is absent (e.g. a FRET resolver). */
+	readonly resolveChildPrimary?: (ref: CohortRef) => string | undefined;
+	/**
+	 * Route an inbound notification to a co-located subscription manager, when this node also subscribes the
+	 * topic. **Must be idempotent on `(collectionId, revision)`**: on the {@link ReactivityForwarderHost.onInbound}
+	 * path a node that is both a cohort member *and* a subscriber invokes this **twice** for the same
+	 * notification — once in the subscriber role (directly) and once in the forwarder role (when `self` is in
+	 * {@link directSubscribers}, via `fanOut`'s self-delivery). The db-core subscriber's `(collectionId,
+	 * revision)` dedupe (`createReactivitySubscriber`) collapses the second call to a no-op, so a correctly
+	 * wired manager delivers exactly once; a sink without that dedupe would double-deliver.
+	 */
+	readonly deliverLocal?: (topicId: Uint8Array, n: NotificationV1) => void;
+	/** Wall clock (unix ms) stamped on `receive`. Default `Date.now`. */
+	readonly clock?: () => number;
+}
+
+/** A topic this node forwards: its live {@link PushState} and the forwarder driving the receive path over it. */
+interface ServedTopic {
+	readonly pushState: PushState;
+	readonly forwarder: ReactivityForwarder;
+}
+
+/**
+ * The reactivity fan-out orchestrator. Build one per node; it serves every reactivity topic the node is a
+ * cohort member for, lazily instantiating per-collection state on first ingest. Bind
+ * {@link ReactivityForwarderHost.ingest} to the origination `emit` seam and
+ * {@link ReactivityForwarderHost.onInbound} to the transport's inbound subscribe.
+ */
+export class ReactivityForwarderHost {
+	private readonly transport: ReactivityNotifyTransport;
+	private readonly selfPeerId: string;
+	private readonly profile: NodeProfile;
+	private readonly pushStateInit: (topicId: Uint8Array, n: NotificationV1) => PushStateInit;
+	private readonly verifierFor: (topicId: Uint8Array) => NotificationVerifier;
+	private readonly directSubscribers: (topicId: Uint8Array) => string[];
+	private readonly resolveChildPrimary?: (ref: CohortRef) => string | undefined;
+	private readonly deliverLocal?: (topicId: Uint8Array, n: NotificationV1) => void;
+	private readonly clock: () => number;
+
+	/** Per-topic served state. `ServedTopic` ⇒ forwards; `null` ⇒ resolved subscriber-only (Edge); absent ⇒ unresolved. */
+	private readonly served = new Map<string, ServedTopic | null>();
+	/** Per-topic serialization tail: an ingest chains onto its topic's prior ingest so the ring/dedupe never interleave. */
+	private readonly ingestTails = new Map<string, Promise<void>>();
+	/**
+	 * Per **old-topic** drain gate: set by {@link markRotated} when this node observes the collection's tail
+	 * rotate, keyed by the outgoing tail's topicId (base64url). For `T_drain` after the rotation
+	 * {@link rotationRedirectFor} answers a recover request reaching the outgoing tail with the gate's
+	 * {@link RotationRedirectV1} ("this moved — go to the new tree"); once the window closes the entry is
+	 * evicted along with the topic's served `PushState`.
+	 */
+	private readonly rotationGates = new Map<string, TailDrainGate>();
+
+	constructor(deps: ReactivityForwarderHostDeps) {
+		this.transport = deps.transport;
+		this.selfPeerId = deps.selfPeerId;
+		this.profile = deps.profile;
+		this.pushStateInit = deps.pushStateInit;
+		this.verifierFor = deps.verifierFor;
+		this.directSubscribers = deps.directSubscribers;
+		this.resolveChildPrimary = deps.resolveChildPrimary;
+		this.deliverLocal = deps.deliverLocal;
+		this.clock = deps.clock ?? ((): number => Date.now());
+	}
+
+	/**
+	 * Local origination emit **and** the inbound forwarder path: receive → forward → fan-out for one
+	 * notification on `topicId`. Ingests for one topic run strictly in sequence (verify is async and the
+	 * replay ring + dedupe set must not interleave); ingests for different topics proceed concurrently.
+	 * Never rejects — a fan-out fault can never surface as a commit failure on the origination seam.
+	 */
+	ingest(topicId: Uint8Array, n: NotificationV1): Promise<void> {
+		const key = this.topicKey(topicId);
+		const prev = this.ingestTails.get(key) ?? Promise.resolve();
+		// Run regardless of the prior ingest's outcome; `ingestSerialized` isolates its own throws, so the
+		// chain never accumulates a rejection that would leak out of a later `ingest`.
+		const next = prev.then(
+			() => this.ingestSerialized(topicId, n, key),
+			() => this.ingestSerialized(topicId, n, key),
+		);
+		this.ingestTails.set(key, next);
+		return next;
+	}
+
+	/** One serialized ingest: resolve served state, run receive, fan out on `"forward"`. Isolates all throws. */
+	private async ingestSerialized(topicId: Uint8Array, n: NotificationV1, key: string): Promise<void> {
+		try {
+			const served = this.resolveServed(topicId, n, key);
+			if (served === null) {
+				return; // Edge / subscriber-only: this node never forwards (delivery rides onInbound → deliverLocal).
+			}
+			const decision = await served.forwarder.receive(n, this.clock());
+			if (decision !== "forward") {
+				return; // "duplicate" (already buffered) or "untrusted" (dropped before any state mutation).
+			}
+			this.fanOut(topicId, served.pushState, n);
+		} catch (err) {
+			log("ingest failed for topic=%s rev=%d (isolated): %o", key, n.revision, err);
+		}
+	}
+
+	/**
+	 * Inbound notify dial: run the **subscriber** role (in-process delivery to a co-located manager) and the
+	 * **forwarder** role (receive + fan-out) as applicable. A node that is both a cohort member and a
+	 * subscriber does both — the forwarder dedupe + the subscriber's `(collectionId, revision)` dedupe keep
+	 * it idempotent. Never rejects.
+	 */
+	async onInbound(_from: PeerRef, n: NotificationV1): Promise<void> {
+		let topicId: Uint8Array;
+		try {
+			topicId = reactivityNotificationTopicId(n);
+		} catch (err) {
+			log("onInbound: undecodable tailId on rev=%d (dropped): %o", n.revision, err);
+			return;
+		}
+		// Subscriber role first: deliver in-process to a co-located subscription manager, if any.
+		this.deliverInProcess(topicId, n);
+		// Forwarder role: ingest self-gates (Edge ⇒ no PushState; a non-member ⇒ empty fan-out).
+		await this.ingest(topicId, n);
+	}
+
+	/** The live {@link PushState} for a served topic, or `undefined` (Edge, or not yet ingested). Test/diagnostic. */
+	pushStateFor(topicId: Uint8Array): PushState | undefined {
+		const served = this.served.get(this.topicKey(topicId));
+		return served === undefined || served === null ? undefined : served.pushState;
+	}
+
+	/**
+	 * Every live forwarder {@link PushState} this node currently serves: the topics it has ingested at least
+	 * one notification for and instantiated state behind the Edge gate (subscriber-only `null`s and
+	 * not-yet-ingested topics are skipped). The push-state-gossip driver iterates these each round to
+	 * broadcast convergence state to each collection's cohort, so a member that missed an origin dial still
+	 * ends up holding the replay entry.
+	 */
+	livePushStates(): PushState[] {
+		const out: PushState[] = [];
+		for (const served of this.served.values()) {
+			if (served !== null) {
+				out.push(served.pushState);
+			}
+		}
+		return out;
+	}
+
+	/**
+	 * The live {@link PushState} this node serves for `collectionId` (base64url), or `undefined` if none.
+	 * The served map is keyed by **topicId**, but a backfill request carries only a collectionId and a
+	 * resume that lost its tail must still resolve the collection's current tail — so this scans for the
+	 * served topic whose `PushState.collectionId` matches. Across a tail-rotation **drain window** a
+	 * collection can briefly have two served topics (the outgoing and incoming tail); the one with the
+	 * highest `lastRevision` is the current tail, so that is the one returned. (The precise drain-window
+	 * redirect choreography is `reactivity-tail-rotation-transport`'s; this picks the current tail.)
+	 */
+	pushStateForCollection(collectionId: string): PushState | undefined {
+		let best: PushState | undefined;
+		for (const served of this.served.values()) {
+			if (served === null || served.pushState.collectionId !== collectionId) {
+				continue;
+			}
+			if (best === undefined || served.pushState.lastRevision > best.lastRevision) {
+				best = served.pushState;
+			}
+		}
+		return best;
+	}
+
+	/**
+	 * Record that the topic anchored on `oldTopicId` has **rotated** to a successor tail, starting a
+	 * {@link TailDrainGate} so the outgoing tail bounces recover requests to the new tree for `T_drain`
+	 * (`docs/reactivity.md` §Tail rotation step 2). db-core derives the redirect's `newTopicId` internally via
+	 * `reactivityTopicId(newTailId)`. The trigger is origination observing the collection's `event.tailId`
+	 * change ({@link reactivity-rotation-host-wiring-e2e}); this seam is called directly in unit tests.
+	 *
+	 * **Idempotent / chained.** A second `markRotated` for the **same** successor is a no-op; a `markRotated`
+	 * to a **later** successor (higher `effectiveAtRevision`) replaces the gate — so a chained OLD→A→B rotation
+	 * advances the redirect to the most recent successor and restarts its drain window from `now`. An earlier
+	 * (or equal) successor leaves the existing gate untouched.
+	 */
+	markRotated(oldTopicId: Uint8Array, redirect: { newTailId: string; effectiveAtRevision: number }, now: number): void {
+		const key = this.topicKey(oldTopicId);
+		const existing = this.rotationGates.get(key);
+		if (existing !== undefined && redirect.effectiveAtRevision <= existing.rotationRedirect.effectiveAtRevision) {
+			return; // same or earlier successor — the gate already points at this-or-a-later tail.
+		}
+		this.rotationGates.set(key, new TailDrainGate({
+			rotatedAt: now,
+			newTailId: redirect.newTailId,
+			effectiveAtRevision: redirect.effectiveAtRevision,
+		}));
+	}
+
+	/**
+	 * The drain-window redirect for a recover request that reached the outgoing tail anchored on `oldTopicId`,
+	 * or `undefined` if this topic never rotated / its drain window has elapsed. While the gate is draining
+	 * (`isDraining(now)`) returns its {@link RotationRedirectV1}; once `T_drain` closes, evicts the gate **and**
+	 * the topic's served `PushState` (the old tail originates nothing further — this also reclaims the
+	 * `served` / `ingestTails` maps the 12.31 review flagged as un-evicted on rotation) and returns `undefined`,
+	 * so the next request gets no reply and the subscriber re-walks / chain-reads.
+	 */
+	rotationRedirectFor(oldTopicId: Uint8Array, now: number): RotationRedirectV1 | undefined {
+		const key = this.topicKey(oldTopicId);
+		const gate = this.rotationGates.get(key);
+		if (gate === undefined) {
+			return undefined;
+		}
+		if (gate.isDraining(now)) {
+			return gate.rotationRedirect;
+		}
+		// Drain window closed: the outgoing tail is done. Drop the gate and reclaim its served state so the
+		// per-topic maps don't leak across rotations.
+		this.rotationGates.delete(key);
+		this.served.delete(key);
+		this.ingestTails.delete(key);
+		return undefined;
+	}
+
+	/**
+	 * Fan the unmodified frame out: reconcile (GC) departed-subscriber queues, enqueue per-subscriber
+	 * (drop-oldest under pressure), drain each queue and deliver (self in-process, others dialed, per-target
+	 * isolated), then dial each resolved child cohort. One slow/dead target never blocks the loop for the rest.
+	 */
+	private fanOut(topicId: Uint8Array, pushState: PushState, n: NotificationV1): void {
+		const subscriberIds = this.directSubscribers(topicId);
+
+		// Memory bound: drop any per-subscriber queue whose id left the live set (departed / TTL-expired /
+		// withdrawn). The map can never grow past the live subscriber set + the current round (lazy GC, so it
+		// shrinks at most one fan-out round late) — this satisfies the `subscribers × queue_max × size` bound.
+		this.reconcileQueues(pushState, subscriberIds);
+
+		// Enqueue onto each subscriber's bounded queue (a slow subscriber's drop-oldest isolates to its queue).
+		pushState.enqueueForSubscribers(subscriberIds, n);
+
+		// Drain + deliver per subscriber, isolated: one dead subscriber's dial never stalls the others.
+		for (const subId of subscriberIds) {
+			const queue = pushState.perSubscriberQueue.peekQueue(subId);
+			if (queue === undefined) {
+				continue;
+			}
+			for (const m of queue.drain()) {
+				this.deliverTo(topicId, subId, m);
+			}
+		}
+
+		// Child cohorts get the unmodified frame (forwarders never re-sign). No-op until the parent/child link
+		// lands ([cohort-topic-parent-child-link]) populates `childCohorts`.
+		for (const ref of pushState.childCohorts) {
+			const target = ref.primary ?? this.resolveChildPrimary?.(ref);
+			if (target !== undefined && target !== this.selfPeerId) {
+				this.dispatch(target, n);
+			}
+		}
+	}
+
+	/** Reclaim the queues of subscribers no longer in the live set (lazy, one round late). */
+	private reconcileQueues(pushState: PushState, subscriberIds: readonly string[]): void {
+		const live = new Set(subscriberIds);
+		// Snapshot the keys: `remove` mutates the backing map, which would invalidate a live iterator.
+		for (const id of [...pushState.perSubscriberQueue.subscribers()]) {
+			if (!live.has(id)) {
+				pushState.perSubscriberQueue.remove(id);
+			}
+		}
+	}
+
+	/** Deliver one notification to one subscriber: self in-process, everyone else over the transport. */
+	private deliverTo(topicId: Uint8Array, subId: string, n: NotificationV1): void {
+		if (subId === this.selfPeerId) {
+			this.deliverInProcess(topicId, n);
+		} else {
+			this.dispatch(subId, n);
+		}
+	}
+
+	/** Route to a co-located subscription manager, isolating a throwing subscriber from the rest of the fan-out. */
+	private deliverInProcess(topicId: Uint8Array, n: NotificationV1): void {
+		if (this.deliverLocal === undefined) {
+			return;
+		}
+		try {
+			this.deliverLocal(topicId, n);
+		} catch (err) {
+			log("local delivery threw (isolated) for rev=%d: %o", n.revision, err);
+		}
+	}
+
+	/** Fire one unicast send, isolated: a synchronous throw or a rejection is swallowed, never the loop's concern. */
+	private dispatch(target: string, n: NotificationV1): void {
+		let pending: Promise<void>;
+		try {
+			pending = this.transport.send(target, n);
+		} catch (err) {
+			log("notify send to %s threw synchronously (isolated): %o", target, err);
+			return;
+		}
+		void pending.catch((err: unknown) => {
+			log("notify send to %s rejected (isolated): %o", target, err);
+		});
+	}
+
+	/** Resolve (instantiating once, behind the Edge gate) the served state for a topic. */
+	private resolveServed(topicId: Uint8Array, n: NotificationV1, key: string): ServedTopic | null {
+		const existing = this.served.get(key);
+		if (existing !== undefined) {
+			return existing; // a `ServedTopic` or a remembered `null` (Edge / subscriber-only)
+		}
+		const pushState = instantiateForwarderPushState(this.profile, this.pushStateInit(topicId, n));
+		if (pushState === undefined) {
+			this.served.set(key, null); // Edge node: remember it never forwards this topic.
+			return null;
+		}
+		const served: ServedTopic = {
+			pushState,
+			forwarder: createReactivityForwarder({ state: pushState, verifier: this.verifierFor(topicId) }),
+		};
+		this.served.set(key, served);
+		return served;
+	}
+
+	private topicKey(topicId: Uint8Array): string {
+		return bytesToB64url(topicId);
+	}
+}

package/src/reactivity/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Reactivity — db-p2p wiring to the cohort-topic substrate.
+ *
+ * The db-core `reactivity` module owns the wire codecs, topic anchor, config, origination assembler,
+ * forwarder/dedupe/replay logic, and subscriber-side verify/deliver; these managers bind that to the
+ * participant-facing `CohortTopicService` (subscribe/renew/withdraw at tier T3) and install the
+ * `onLocalCommit` origination hook. See `docs/reactivity.md` §Subscription / §Notification origination.
+ */
+
+export * from "./topic-bytes.js";
+export * from "./protocols.js";
+export * from "./notify-transport.js";
+export * from "./recover-transport.js";
+export * from "./subscription-manager.js";
+export * from "./rotation-rereg-scheduler.js";
+export * from "./origination-manager.js";
+export * from "./forwarder-host.js";
+export * from "./push-state-gossip.js";
+export * from "./subscriber-registry.js";