@optimystic/db-p2p 0.13.5 → 0.14.1

package/src/reactivity/recover-transport.ts

@@ -0,0 +1,408 @@
+/**
+ * Reactivity recover RPC transport — the live libp2p backfill/resume recovery protocol
+ * (`docs/reactivity.md` §Backfill RPC, §Resume).
+ *
+ * This is the **pull** companion to the one-way notify transport: a subscriber that detected a gap (or
+ * woke from sleep) asks a serving cohort member "what did I miss?" and is brought current. The protocol is
+ * **request-reply** — one {@link RecoverRequestV1} frame out, one {@link RecoverReplyV1} frame back over a
+ * single stream — so it rides the cohort-topic {@link requestResponse} / {@link handleRequestResponse}
+ * helpers (NOT the one-way notify helpers, which would desync the dialer).
+ *
+ * Two pieces live here, both decoupled from the live node assembly so they unit-test in isolation:
+ *
+ *  - {@link Libp2pReactivityRecoverTransport} — the **outbound** side. Supplies the two db-core seams
+ *    (`BackfillTransport` / `ResumeTransport`) against one node: pick a target (sticky cohort-hint primary
+ *    first for the one-RT happy path, else a cohort-walk member), frame the request, exchange it over the
+ *    recover protocol, and return the inner reply. The wire exchange is injected as a {@link RecoverDialer}
+ *    so the target-selection + framing logic tests without a real socket; {@link createLibp2pRecoverDialer}
+ *    is the production libp2p-backed implementation.
+ *  - {@link createRecoverRequestHandler} / {@link registerRecoverHandler} — the **inbound** serve handler.
+ *    Decode (bounded) → verify the request's peer-key signature against the dialing peer → reject a
+ *    replay/stale request → resolve the live `PushState` → `serveBackfill` / `serveResume` → reply. Any
+ *    failure produces **no reply** (the stream aborts) rather than throwing out of the handler.
+ *
+ * ## Dial-target encoding bridge (load-bearing)
+ *
+ * The sticky {@link import("@optimystic/db-core").ReactivityCohortHint}`.primary` is **base64url of
+ * cohort member-id bytes** (`base64url(utf8(peerIdString))`), per its db-core JSDoc, whereas
+ * {@link requestResponse} needs a `peerIdFromString`-parseable peer-id **string**. Feeding the raw
+ * base64url straight to `peerIdFromString` throws → the dial is swallowed → recovery silently never
+ * reaches the cohort. {@link decodeCohortHintTarget} pins the conversion
+ * (`bytesToPeerIdString(b64urlToBytes(primary))`); the `resolveCohort` walk, by contrast, already returns
+ * peer-id strings (the cohort-topic `CohortPeerResolver` space) and is used as-is.
+ */
+
+import type { Libp2p } from "libp2p";
+import type { PeerId, PrivateKey } from "@libp2p/interface";
+import { peerIdFromString } from "@libp2p/peer-id";
+import {
+	b64urlToBytes,
+	bytesToB64url,
+	reactivityTopicId,
+	serveBackfill,
+	serveResume,
+	backfillSigningPayload,
+	resumeSigningPayload,
+	encodeRecoverRequestV1,
+	decodeRecoverRequestV1,
+	encodeRecoverReplyV1,
+	decodeRecoverReplyV1,
+	type BackfillV1,
+	type BackfillReplyV1,
+	type BackfillSignable,
+	type ResumeV1,
+	type ResumeSignable,
+	type RecoverKind,
+	type RecoverReplyV1,
+	type BackfillTransport,
+	type PushState,
+	type StickyCohortHintCache,
+	type CorrelationReplayGuard,
+	type RotationRedirectV1,
+} from "@optimystic/db-core";
+import { requestResponse, handleRequestResponse, DEFAULT_STREAM_MAX_BYTES } from "../cohort-topic/stream-util.js";
+import { verifyPeerSig, signPeerSig } from "../cohort-topic/peer-sig.js";
+import { peerIdToBytes, bytesToPeerIdString } from "../cohort-topic/peer-codec.js";
+import { PROTOCOL_REACTIVITY_RECOVER } from "./protocols.js";
+import type { ResumeTransport } from "./subscription-manager.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-recover");
+
+/**
+ * Decode a sticky-cohort-hint `primary` (base64url of member-id bytes = `base64url(utf8(peerIdString))`)
+ * back to the dialable peer-id string. The inverse trap of feeding the raw value to `peerIdFromString`
+ * (which expects a peer-id string, not base64url-of-its-utf8) — pinned by the dial-target encoding test.
+ */
+export function decodeCohortHintTarget(primary: string): string {
+	return bytesToPeerIdString(b64urlToBytes(primary));
+}
+
+// --- subscriber request signing (the manager's synchronous signer seam) ---
+
+/**
+ * The synchronous request-signing seam the production subscribe factory feeds a
+ * {@link import("./subscription-manager.js").ReactivitySubscriptionManager}: it builds a
+ * {@link BackfillV1} / {@link ResumeV1} signature (base64url) over the unsigned image.
+ */
+export interface RecoverRequestSigners {
+	/** Sign a {@link BackfillV1} over {@link backfillSigningPayload} of its unsigned image. */
+	readonly signBackfill: (unsigned: BackfillSignable) => string;
+	/** Sign a {@link ResumeV1} over {@link resumeSigningPayload} of its unsigned image. */
+	readonly signResume: (unsigned: ResumeSignable) => string;
+}
+
+/**
+ * Build the subscriber's recover request signers from the node's libp2p Ed25519 private key.
+ *
+ * This resolves the recover wiring's one design point: the subscription-manager `signBackfill` /
+ * `signResume` ports are **synchronous** (`(unsigned) => string`) — the db-core driver builds the
+ * unsigned image internally, so a pre-signed value is impossible — but libp2p `PrivateKey.sign` is
+ * **async**. Rather than make the seam (and `createBackfillRequester`'s `sign`, a db-core change) async,
+ * sign with the synchronous {@link signPeerSig} (noble, over the raw Ed25519 seed) over db-core's
+ * canonical signing payloads. The produced signature verifies on the serving side under
+ * {@link verifyPeerSig} over the same bytes (both noble, RFC8032), so the round trip is symmetric.
+ */
+export function createRecoverRequestSigners(privateKey: PrivateKey): RecoverRequestSigners {
+	return {
+		signBackfill: (unsigned: BackfillSignable): string => bytesToB64url(signPeerSig(privateKey, backfillSigningPayload(unsigned))),
+		signResume: (unsigned: ResumeSignable): string => bytesToB64url(signPeerSig(privateKey, resumeSigningPayload(unsigned))),
+	};
+}
+
+// --- outbound transport ---
+
+/**
+ * Thrown out of {@link Libp2pReactivityRecoverTransport.backfillTransport} / `resumeTransport` when the
+ * dialed cohort answered with a `kind: "rotated"` recover reply: the outgoing tail this request reached has
+ * rotated and is draining, so it bounced the request to the new tree (`docs/reactivity.md` §Tail rotation).
+ * It carries the {@link RotationRedirectV1} so the subscription manager can move itself to the successor.
+ *
+ * A `kind: "rotated"` reply is **terminal** for the cohort-walk — the dialed member spoke authoritatively for
+ * the cohort, so the transport stops rather than falling through to the next target (contrast a *dial
+ * failure*, which still falls through). The subscriber honors it like a notification-driven rotation.
+ */
+export class RotationRedirectError extends Error {
+	/** The drain-window redirect the serving cohort returned (`newTailId` / `newTopicId` / `effectiveAtRevision`). */
+	readonly redirect: RotationRedirectV1;
+	constructor(redirect: RotationRedirectV1) {
+		super(`reactivity recover: cohort rotated to tail ${redirect.newTailId} (effectiveAtRevision ${redirect.effectiveAtRevision})`);
+		this.name = "RotationRedirectError";
+		this.redirect = redirect;
+	}
+}
+
+/** The wire exchange seam: open the recover protocol to `target`, send `frame`, return the bounded reply. */
+export interface RecoverDialer {
+	/** Exchange one request frame for one reply frame with `target` (peer-id string). Rejects on a dial failure. */
+	exchange(target: string, frame: Uint8Array): Promise<Uint8Array>;
+}
+
+/** Build the production libp2p-backed {@link RecoverDialer} over {@link requestResponse}. */
+export function createLibp2pRecoverDialer(node: Libp2p, recoverProtocol: string = PROTOCOL_REACTIVITY_RECOVER, maxBytes: number = DEFAULT_STREAM_MAX_BYTES): RecoverDialer {
+	return {
+		exchange: (target, frame) => requestResponse(node, peerIdFromString(target), recoverProtocol, frame, maxBytes),
+	};
+}
+
+/** Construction inputs for a {@link Libp2pReactivityRecoverTransport}. */
+export interface Libp2pReactivityRecoverTransportOptions {
+	/** Wire exchange (e.g. {@link createLibp2pRecoverDialer} over the live node). */
+	readonly dialer: RecoverDialer;
+	/** This node's peer-id string (`node.peerId.toString()`); never dialed — a co-located serve is the node wiring's. */
+	readonly selfPeerId: string;
+	/** Sticky cohort-hint cache, shared with the subscription manager (the one-RT primary for the happy path). */
+	readonly cohortHintCache: StickyCohortHintCache;
+	/** FRET cohort-walk fallback: a topic id → dialable cohort member peer-id strings. */
+	readonly resolveCohort: (topicId: Uint8Array) => string[];
+	/** Per-frame ceiling for encode/decode; default {@link DEFAULT_STREAM_MAX_BYTES}. */
+	readonly maxBytes?: number;
+}
+
+/**
+ * The outbound recover transport: one instance per node, exposing the two db-core function seams against it.
+ * Each returned transport dials the **sticky primary first** (one round trip after a brief flap), falling
+ * back to a **cohort-walk** member on a dial failure (any member that holds the topic's gossiped `PushState`
+ * can answer). A kind mismatch or all-targets-failed surfaces as a rejection so the caller's retry/escalation
+ * policy (the subscription manager's backfill escalation, or `manager.resume()`'s caller) takes over.
+ */
+export class Libp2pReactivityRecoverTransport {
+	private readonly dialer: RecoverDialer;
+	private readonly selfPeerId: string;
+	private readonly cohortHintCache: StickyCohortHintCache;
+	private readonly resolveCohort: (topicId: Uint8Array) => string[];
+	private readonly maxBytes: number;
+
+	constructor(options: Libp2pReactivityRecoverTransportOptions) {
+		this.dialer = options.dialer;
+		this.selfPeerId = options.selfPeerId;
+		this.cohortHintCache = options.cohortHintCache;
+		this.resolveCohort = options.resolveCohort;
+		this.maxBytes = options.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+	}
+
+	/** The db-core {@link BackfillTransport} for `(topicId, collectionId)` — frames + dials a signed {@link BackfillV1}. */
+	backfillTransport(topicId: Uint8Array, collectionId: string): BackfillTransport {
+		return async (req: BackfillV1): Promise<BackfillReplyV1> => {
+			const frame = encodeRecoverRequestV1({ v: 1, kind: "backfill", backfill: req }, this.maxBytes);
+			const reply = await this.exchange("backfill", frame, topicId, collectionId);
+			if (reply.backfillReply === undefined) {
+				throw new Error("reactivity recover: backfill reply missing its body");
+			}
+			return reply.backfillReply;
+		};
+	}
+
+	/** The {@link ResumeTransport} for `(topicId, collectionId)` — frames + dials a signed {@link ResumeV1}. */
+	resumeTransport(topicId: Uint8Array, collectionId: string): ResumeTransport {
+		return async (req: ResumeV1) => {
+			const frame = encodeRecoverRequestV1({ v: 1, kind: "resume", resume: req }, this.maxBytes);
+			const reply = await this.exchange("resume", frame, topicId, collectionId);
+			if (reply.resumeReply === undefined) {
+				throw new Error("reactivity recover: resume reply missing its body");
+			}
+			return reply.resumeReply;
+		};
+	}
+
+	/**
+	 * Exchange one recover frame with the first reachable target: sticky primary, then each cohort-walk
+	 * member. A **dial failure** falls through to the next candidate; a successful dial is **terminal** (the
+	 * member answered for the cohort) — a `kind: "rotated"` redirect throws {@link RotationRedirectError}, and
+	 * a reply decoding to the wrong `kind` is a protocol error. Throws when no candidate succeeds.
+	 */
+	private async exchange(kind: RecoverKind, frame: Uint8Array, topicId: Uint8Array, collectionId: string): Promise<RecoverReplyV1> {
+		const targets = this.selectTargets(topicId, collectionId);
+		if (targets.length === 0) {
+			throw new Error("reactivity recover: no serving cohort target resolved");
+		}
+		let lastErr: unknown;
+		for (const target of targets) {
+			let replyFrame: Uint8Array;
+			try {
+				replyFrame = await this.dialer.exchange(target, frame);
+			} catch (err) {
+				lastErr = err; // dial failure → fall back to the next candidate (sticky → walk)
+				log("recover dial to %s failed, trying next target: %o", target, err);
+				continue;
+			}
+			const reply = decodeRecoverReplyV1(replyFrame, this.maxBytes); // a decode failure here is terminal
+			// A rotated cohort answered authoritatively: surface the redirect and stop the walk (terminal, never
+			// a fallthrough — the dialed member spoke for the cohort).
+			if (reply.kind === "rotated") {
+				throw new RotationRedirectError(reply.rotated!);
+			}
+			if (reply.kind !== kind) {
+				throw new Error(`reactivity recover: reply kind "${reply.kind}" does not match request kind "${kind}"`);
+			}
+			return reply;
+		}
+		throw lastErr ?? new Error("reactivity recover: all targets failed");
+	}
+
+	/**
+	 * Ordered dial candidates for a recover: the sticky primary (decoded from its base64url-of-bytes form)
+	 * first, then the cohort-walk members. Self is never dialed (a co-located serve is the node wiring's
+	 * concern), and duplicates collapse.
+	 */
+	private selectTargets(topicId: Uint8Array, collectionId: string): string[] {
+		const seen = new Set<string>();
+		const targets: string[] = [];
+		const add = (target: string | undefined): void => {
+			if (target === undefined || target === this.selfPeerId || seen.has(target)) {
+				return;
+			}
+			seen.add(target);
+			targets.push(target);
+		};
+		const hint = this.cohortHintCache.get(collectionId);
+		if (hint?.primary !== undefined) {
+			try {
+				add(decodeCohortHintTarget(hint.primary));
+			} catch (err) {
+				log("recover: malformed sticky primary for %s, skipping to cohort-walk: %o", collectionId, err);
+			}
+		}
+		for (const member of this.resolveCohort(topicId)) {
+			add(member);
+		}
+		return targets;
+	}
+}
+
+// --- inbound serve handler ---
+
+/** Live `PushState` resolvers + replay guard the recover serve handler dispatches against. */
+export interface RecoverServeDeps {
+	/** Resolve the served `PushState` for an exact reactivity topic id (resume's stale-tail lookup). */
+	readonly pushStateFor: (topicId: Uint8Array) => PushState | undefined;
+	/** Resolve the served `PushState` for a collection id — the current tail (backfill, and rotated resume). */
+	readonly pushStateForCollection: (collectionId: string) => PushState | undefined;
+	/** Node-level freshness + anti-replay gate keyed on the request signature bytes. */
+	readonly replayGuard: CorrelationReplayGuard;
+	/**
+	 * The drain-window redirect for a request that reached an **outgoing (rotated)** tail still in its drain
+	 * window, or `undefined` if the resolved topic never rotated / has drained. The node wiring binds this to
+	 * `ReactivityForwarderHost.rotationRedirectFor`, resolving the old topic from the request: for **resume**
+	 * the request carries `topicId = reactivityTopicId(latestKnownTailId)`; for **backfill** (no `topicId`)
+	 * the binding resolves the collection's current served topic. When it returns a redirect the serve replies
+	 * `kind: "rotated"` instead of serving data, moving the subscriber to the new tree. Absent ⇒ never redirect.
+	 */
+	readonly rotationFor?: (req: { topicId?: Uint8Array; collectionId: string }, now: number) => RotationRedirectV1 | undefined;
+	/** Unix-ms clock for the replay-guard window. Default `Date.now`. */
+	readonly clock?: () => number;
+	/** Per-frame decode ceiling; default {@link DEFAULT_STREAM_MAX_BYTES}. */
+	readonly maxBytes?: number;
+}
+
+/**
+ * Verify the request's peer-key signature against the dialing peer, then admit it through the freshness +
+ * anti-replay guard. The dialing peer's id **is** the signer (no signer-id field on the wire); the signature
+ * bytes are the anti-replay key (globally unique + authenticated). Returns `false` (reject, no reply) on a
+ * bad signature, a stale/future timestamp, or a replay.
+ */
+function verifyAndAdmit(deps: RecoverServeDeps, signerId: string, payload: Uint8Array, signatureB64: string, timestamp: number, now: number): boolean {
+	const signature = b64urlToBytes(signatureB64);
+	if (!verifyPeerSig(signerId, payload, signature)) {
+		log("recover serve: signature verification failed for %s (no reply)", signerId);
+		return false;
+	}
+	if (!deps.replayGuard.accept(signature, peerIdToBytes(signerId), timestamp, now)) {
+		log("recover serve: replay/stale request from %s (no reply)", signerId);
+		return false;
+	}
+	return true;
+}
+
+/**
+ * Serve a backfill from the collection's current served tail, or `undefined` if this node serves none. When
+ * the node serves **only** the outgoing (draining) tail, `rotationFor` returns the drain redirect and the
+ * reply is `kind: "rotated"` instead — a best-effort secondary path (the primary mechanism for an active
+ * subscriber is notify-driven detection). Once both tails coexist `pushStateForCollection` resolves the new
+ * tail, so the redirect is emitted only while the old tail is the sole served state (see §Tail rotation).
+ */
+function serveBackfillReply(deps: RecoverServeDeps, req: BackfillV1, now: number): Uint8Array | undefined {
+	const maxBytes = deps.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+	const redirect = deps.rotationFor?.({ collectionId: req.collectionId }, now);
+	if (redirect !== undefined) {
+		return encodeRecoverReplyV1({ v: 1, kind: "rotated", rotated: redirect }, maxBytes);
+	}
+	const ps = deps.pushStateForCollection(req.collectionId);
+	if (ps === undefined) {
+		return undefined; // not a serving member for this collection → no reply (subscriber walks/chain-reads)
+	}
+	const backfillReply = serveBackfill(ps.replayBuffer, req, ps.collectionId);
+	return encodeRecoverReplyV1({ v: 1, kind: "backfill", backfillReply }, maxBytes);
+}
+
+/**
+ * Serve a resume against the live `PushState`. A resume reaching the **outgoing (draining)** tail — its
+ * `latestKnownTailId` anchors a topic this node has marked rotated — is answered with the drain redirect
+ * (`kind: "rotated"`), moving the subscriber to the new tree. Otherwise prefer the exact topic the request's
+ * `latestKnownTailId` anchors (so a non-rotated subscriber classifies into backfill/checkpoint/out_of_window);
+ * if this node no longer serves that tail's topic, fall back to the collection's current tail so the cohort
+ * can still answer `tail_rotated` (its `currentTailId` differs from the request's stale tail) or, for a span
+ * that crosses a rotation, serve from the new tail's `inheritedCheckpoint`. `undefined` ⇒ no served state.
+ */
+function serveResumeReply(deps: RecoverServeDeps, req: ResumeV1, now: number): Uint8Array | undefined {
+	const maxBytes = deps.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+	const staleTopic = reactivityTopicId(b64urlToBytes(req.latestKnownTailId));
+	const redirect = deps.rotationFor?.({ topicId: staleTopic, collectionId: req.collectionId }, now);
+	if (redirect !== undefined) {
+		return encodeRecoverReplyV1({ v: 1, kind: "rotated", rotated: redirect }, maxBytes);
+	}
+	const ps = deps.pushStateFor(staleTopic) ?? deps.pushStateForCollection(req.collectionId);
+	if (ps === undefined) {
+		return undefined;
+	}
+	const resumeReply = serveResume(req, {
+		buffer: ps.replayBuffer,
+		checkpoint: ps.checkpoint,
+		inheritedCheckpoint: ps.inheritedCheckpoint,
+		currentTailId: ps.tailIdAtJoin,
+		currentRevision: ps.lastRevision,
+		rotationRevision: ps.lastRevision,
+		expectedCollectionId: ps.collectionId,
+	});
+	return encodeRecoverReplyV1({ v: 1, kind: "resume", resumeReply }, maxBytes);
+}
+
+/**
+ * Build the recover serve callback for {@link handleRequestResponse}: it returns the reply frame, or
+ * `undefined` for **no reply** (a decode/verify/replay/resolve failure aborts the stream). It never throws
+ * out of the handler.
+ */
+export function createRecoverRequestHandler(deps: RecoverServeDeps): (frame: Uint8Array, fromPeer: PeerId) => Promise<Uint8Array | undefined> {
+	const maxBytes = deps.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+	const clock = deps.clock ?? ((): number => Date.now());
+	return (frame: Uint8Array, fromPeer: PeerId): Promise<Uint8Array | undefined> => {
+		try {
+			const req = decodeRecoverRequestV1(frame, maxBytes);
+			const signerId = fromPeer.toString();
+			const now = clock();
+			if (req.kind === "backfill") {
+				const b = req.backfill;
+				if (b === undefined || !verifyAndAdmit(deps, signerId, backfillSigningPayload(b), b.signature, b.timestamp, now)) {
+					return Promise.resolve(undefined);
+				}
+				return Promise.resolve(serveBackfillReply(deps, b, now));
+			}
+			const r = req.resume;
+			if (r === undefined || !verifyAndAdmit(deps, signerId, resumeSigningPayload(r), r.signature, r.timestamp, now)) {
+				return Promise.resolve(undefined);
+			}
+			return Promise.resolve(serveResumeReply(deps, r, now));
+		} catch (err) {
+			// A malformed/foreign request (decode failure, foreign collectionId from serve*) must never throw
+			// out of the stream handler: log + no reply (the stream aborts, the subscriber falls back).
+			log("recover serve: dropping request (no reply): %o", err);
+			return Promise.resolve(undefined);
+		}
+	};
+}
+
+/** Register the inbound recover protocol handler on `node` (request-reply over the recover protocol). */
+export function registerRecoverHandler(node: Libp2p, protocol: string, deps: RecoverServeDeps): void {
+	const maxBytes = deps.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+	handleRequestResponse(node, protocol, createRecoverRequestHandler(deps), maxBytes);
+}

package/src/reactivity/rotation-rereg-scheduler.ts

@@ -0,0 +1,256 @@
+/**
+ * Reactivity — tail-rotation re-registration timer host seam (`docs/reactivity.md` §Tail rotation step 3).
+ *
+ * The {@link import("./subscription-manager.js").ReactivitySubscriptionManager} surfaces a
+ * {@link import("./subscription-manager.js").RotationNotice} **once per successor tail** (both the
+ * notify-driven pre-announce and the recover-driven `RotationRedirectError` converge on the same
+ * `surfaceRotation` seam), but it neither schedules the timer nor performs the move. This host component
+ * does: it consumes a notice, schedules a one-shot timer for `max(0, plan.fireAt - now())`, and on fire
+ * invokes an injected `reRegister(plan)` seam that re-subscribes the watcher at the rotated tree. The node
+ * composition that constructs the manager + binds this scheduler to its `onRotation` observer lives in
+ * `reactivity-rotation-host-wiring-e2e`; this module is the standalone, unit-testable piece.
+ *
+ * **Where the stagger lives.** The spread that keeps the new tail from being flooded is entirely in
+ * `plan.fireAt`, drawn by the **manager's** `rejoinJitter`. This scheduler only *consumes* `plan.fireAt`; it
+ * never sees the jitter. The manager uses the *single*-subscriber planner `planReRegistration` →
+ * `RejoinJitter.scheduleRejoin`, which draws a **uniform** offset `now + ⌊U[0, T_rejoin_jitter)⌋` — so the
+ * load-bearing knob for this path is the **window** `T_rejoin_jitter` (default 30 s), not a `capPromote`. Each
+ * subscriber jitters independently, giving the new tail an inbound rate of ≈ `subscribers / T_rejoin_jitter`
+ * in expectation; the burst is absorbed on the *receiving* side by the new tail cohort's `cap_promote_fast`
+ * fast-promotion (a cohort-topic promotion mechanism — see `docs/reactivity.md` §Tail rotation rotation-cost
+ * and the Worked scenario), which is independent of the jitter's `capPromote`.
+ *
+ * Note that `RejoinJitter`'s `capPromote` is consulted **only** by the *wave* planner
+ * `scheduleWave` / `planReRegistrationWave` (a single host staggering a whole wave with a hard per-window
+ * ceiling — used by the mesh harness, not by the production manager). If the composing site
+ * (`reactivity-rotation-host-wiring-e2e`) ever switches the manager onto the wave planner, *then* it must
+ * build the jitter as `createRejoinJitter({ capPromote: DEFAULT_CAP_PROMOTE_FAST })` (= 32), since the default
+ * `createRejoinJitter()` cap is the cohort-failure `cap_promote = 64`. For the current single-planner path,
+ * setting `capPromote` has **no effect** on `fireAt`.
+ *
+ * **Determinism.** An injected `setTimer(fn, delayMs) => cancel` and `now()` clock make the scheduler
+ * testable with a fake clock (no wall clock). They default to a production binding: an **unref'd**
+ * `setTimeout`/`clearTimeout` and `Date.now`. The unref is load-bearing — an idle re-registration timer must
+ * not pin an otherwise-idle process, mirroring the push-state-gossip driver's unref'd timer
+ * ({@link import("./push-state-gossip.js").ReactivityPushStateGossipDriver}).
+ *
+ * **Idempotence.** De-duped by successor `newTopicId` (base64url): a second notice for a successor already
+ * scheduled or fired is ignored. The manager already fires once per successor (its `rotationHandledFor`
+ * guard), but a redirect and a pre-announce can surface the **same** successor near-simultaneously, so the
+ * scheduler is independently idempotent. The de-dupe ledger (`seen`) survives the timer fire (so a late
+ * re-surface of an already-fired successor stays a no-op), which on the normal schedule→fire path would let it
+ * grow without bound across a long-lived, fast-rotating subscription. It is therefore **bounded**: capped at
+ * `SEEN_LEDGER_CAP` entries with oldest-first eviction (insertion order), and eviction **never** drops a key
+ * still in `pending` — that would break the "every pending key ∈ `seen`" invariant and could let a duplicate
+ * notice for a pending successor arm a second timer over the live one. A re-surface older than the cap (≥ cap
+ * distinct successors later) degrades to at most one harmless, idempotent re-register.
+ *
+ * **Chained rotation OLD→A→B** before A's timer fires → A and B are distinct successors → two independent
+ * timers; **both may fire**. Re-registering at A and then immediately rotating A→B is self-correcting via the
+ * manager's `rotationHandledFor` guard, so a superseded timer is intentionally **not** cancelled (a
+ * superseded re-register is harmless and rare).
+ */
+
+import { bytesToB64url, type ReRegistrationPlan } from "@optimystic/db-core";
+import type { RotationNotice } from "./subscription-manager.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-rotation-rereg");
+
+/**
+ * Upper bound on the idempotence ledger (`seen`). Far above any realistic count of *concurrently-pending*
+ * successors (single digits: 1 in the normal case, a handful across a chained rotation), so it never evicts a
+ * still-live entry in practice while keeping the ledger's memory to tens of KB of short base64url strings at the
+ * ceiling. Tunable — raising it widens the late-re-surface de-dupe window at a proportional memory cost.
+ * Exported for the regression test that asserts the bound; production callers don't read it.
+ */
+export const SEEN_LEDGER_CAP = 1024;
+
+/** Cancel handle returned by an injected timer; cancels a not-yet-fired timer (safe no-op after fire/cancel). */
+export type RotationTimerCancel = () => void;
+
+/**
+ * Production timer binding: a one-shot `setTimeout` whose handle is **unref'd** so a pending re-registration
+ * never keeps an otherwise-idle process alive. The returned handle clears the timeout (idempotent — clearing
+ * an already-fired/cleared timeout is a no-op).
+ */
+function defaultSetTimer(fn: () => void, delayMs: number): RotationTimerCancel {
+	const handle = setTimeout(fn, delayMs);
+	// Node timers keep the event loop alive; an idle rotation timer must not pin a process (mirror push-state gossip).
+	(handle as { unref?: () => void }).unref?.();
+	return (): void => clearTimeout(handle);
+}
+
+/** Construction inputs for a {@link RotationReRegistrationScheduler}. */
+export interface RotationReRegistrationSchedulerOptions {
+	/**
+	 * Perform the actual move: re-subscribe the watcher at the rotated tree (the new `topicId`, carrying the
+	 * plan's `lastRevision`). A rejection is isolated + logged — a failed move must never throw out of the
+	 * timer callback. Not retried this pass (see the class doc).
+	 */
+	readonly reRegister: (plan: ReRegistrationPlan) => Promise<void>;
+	/**
+	 * Schedule a one-shot timer; returns a cancel handle. Defaults to an **unref'd** `setTimeout`. Tests inject
+	 * a fake timer queue for determinism.
+	 */
+	readonly setTimer?: (fn: () => void, delayMs: number) => RotationTimerCancel;
+	/** Clock (Unix ms). Defaults to `Date.now`; tests inject a fake clock. */
+	readonly now?: () => number;
+}
+
+/**
+ * Hosts the per-successor one-shot timers that move a subscriber to the rotated tree. Construct one per
+ * subscription manager and bind {@link schedule} to the manager's
+ * {@link import("./subscription-manager.js").ReactivitySubscriptionManagerOptions.onRotation} observer.
+ *
+ * See the module doc for where the re-registration stagger actually lives (the manager's `rejoinJitter`; this
+ * scheduler only consumes `plan.fireAt`, it does not draw it).
+ */
+export class RotationReRegistrationScheduler {
+	private readonly reRegister: (plan: ReRegistrationPlan) => Promise<void>;
+	private readonly setTimer: (fn: () => void, delayMs: number) => RotationTimerCancel;
+	private readonly now: () => number;
+
+	/** Successors with a still-pending timer, keyed by base64url `newTopicId` → its cancel handle. */
+	private readonly pending = new Map<string, RotationTimerCancel>();
+	/**
+	 * Successors recently scheduled (pending **or** already fired) — the idempotence ledger that survives fire.
+	 * Insertion-ordered and **bounded** at {@link SEEN_LEDGER_CAP}: {@link evictSeenOverCap} drops the oldest
+	 * non-pending entries once over cap (never a still-pending key — see that method's doc).
+	 */
+	private readonly seen = new Set<string>();
+	private stopped = false;
+
+	constructor(options: RotationReRegistrationSchedulerOptions) {
+		this.reRegister = options.reRegister;
+		this.setTimer = options.setTimer ?? defaultSetTimer;
+		this.now = options.now ?? ((): number => Date.now());
+	}
+
+	/** Successors with a timer still pending (not yet fired/cancelled). Diagnostic / test seam. */
+	get pendingCount(): number {
+		return this.pending.size;
+	}
+
+	/**
+	 * Size of the idempotence ledger (pending + recently-fired-and-retained). Diagnostic / test seam; the
+	 * regression test asserts this stays ≤ {@link SEEN_LEDGER_CAP} under unbounded sequential rotations.
+	 */
+	get seenCount(): number {
+		return this.seen.size;
+	}
+
+	/**
+	 * Schedule the re-registration timer for a rotation notice. De-duped by successor `newTopicId`: a second
+	 * notice for an already-scheduled-or-fired successor is a no-op (a redirect and a pre-announce can surface
+	 * the same successor). The delay is `max(0, plan.fireAt - now())`, so a `fireAt` already in the past fires
+	 * on the next tick (clamped to 0, never negative). A no-op once {@link stop} has run.
+	 */
+	schedule(notice: RotationNotice): void {
+		if (this.stopped) {
+			return;
+		}
+		const key = bytesToB64url(notice.plan.newTopicId);
+		if (this.seen.has(key)) {
+			log("rotation re-registration already scheduled/fired for successor topic=%s — ignoring duplicate notice (preAnnounced=%s)", key, notice.preAnnounced);
+			return;
+		}
+		this.seen.add(key);
+		const delayMs = Math.max(0, notice.plan.fireAt - this.now());
+		const plan = notice.plan;
+		const cancel = this.setTimer((): void => {
+			this.fire(key, plan);
+		}, delayMs);
+		this.pending.set(key, cancel);
+		// Bound `seen` only AFTER the new key is in `pending`, so eviction sees it as live and never drops it (the
+		// "every pending key ∈ seen" invariant). Were this run before `pending.set`, the just-added key would be the
+		// one non-pending candidate whenever `pending` is at the cap, and would be wrongly evicted then immediately
+		// re-added to `pending` — a pending key absent from `seen`, which a duplicate notice could then re-arm over.
+		this.evictSeenOverCap();
+		log("scheduled rotation re-registration for successor topic=%s in %dms (preAnnounced=%s)", key, delayMs, notice.preAnnounced);
+	}
+
+	/**
+	 * Cancel a single pending timer (by successor `newTopicId`) or, when called with no argument, **all**
+	 * pending timers (teardown). Cancelling an already-fired or unknown successor is a safe no-op. A cancelled
+	 * successor is forgotten (dropped from the idempotence ledger), so a later notice for it would reschedule;
+	 * use {@link stop} for permanent teardown.
+	 */
+	cancel(newTopicId?: Uint8Array): void {
+		if (newTopicId === undefined) {
+			for (const cancelTimer of this.pending.values()) {
+				cancelTimer();
+			}
+			this.pending.clear();
+			this.seen.clear();
+			return;
+		}
+		const key = bytesToB64url(newTopicId);
+		const cancelTimer = this.pending.get(key);
+		if (cancelTimer !== undefined) {
+			cancelTimer();
+			this.pending.delete(key);
+		}
+		this.seen.delete(key);
+	}
+
+	/**
+	 * Stop the scheduler permanently (teardown): cancel every pending timer and refuse all further scheduling
+	 * and firing. A timer that races `stop` (its callback already queued) finds the `stopped` gate and never
+	 * invokes `reRegister`. Idempotent.
+	 */
+	stop(): void {
+		this.stopped = true;
+		for (const cancelTimer of this.pending.values()) {
+			cancelTimer();
+		}
+		this.pending.clear();
+		this.seen.clear();
+	}
+
+	/**
+	 * Bound the idempotence ledger: evict the oldest entries (insertion order) that are **not** still pending,
+	 * until back within {@link SEEN_LEDGER_CAP}. Never evicts a pending key — that would break the "every pending
+	 * key ∈ `seen`" invariant and could double-fire a successor whose later duplicate notice then re-armed a timer
+	 * over the live one. If every over-cap entry is somehow still pending (`pending.size > cap` — not reachable in
+	 * practice, since pending successors are the most recently scheduled), the loop bails and the ledger is left to
+	 * grow with `pending` this round; it returns within cap as soon as those timers fire and a later schedule runs.
+	 */
+	private evictSeenOverCap(): void {
+		while (this.seen.size > SEEN_LEDGER_CAP) {
+			let evicted = false;
+			for (const key of this.seen) { // insertion order: oldest first
+				if (!this.pending.has(key)) {
+					this.seen.delete(key);
+					log("rotation re-registration ledger at cap (%d) — evicted oldest fired successor topic=%s", SEEN_LEDGER_CAP, key);
+					evicted = true;
+					break;
+				}
+			}
+			if (!evicted) {
+				break;
+			}
+		}
+	}
+
+	/** Timer callback: drop the pending entry, then invoke the isolated re-registration (unless stopped). */
+	private fire(key: string, plan: ReRegistrationPlan): void {
+		this.pending.delete(key);
+		if (this.stopped) {
+			return; // stop() raced the timer callback — no move after teardown.
+		}
+		// A failed move must never throw out of the timer callback — an escaping throw / unhandled rejection
+		// would surface on the host event loop. Guard BOTH a rejected promise and a (mis-implemented) seam that
+		// throws synchronously. `seen` retains the key so a duplicate notice still no-ops. No retry this pass —
+		// and because `seen` keeps the key, a re-notice for this *same* successor is deduped (the manager's
+		// `rotationHandledFor` already holds it too), so the recovery backstop for a failed move is the
+		// subscriber's normal recover/re-walk path, not a re-detected rotation to the same tail.
+		try {
+			void this.reRegister(plan).catch((err: unknown) => {
+				log("rotation re-registration rejected for successor topic=%s (isolated, not retried): %o", key, err);
+			});
+		} catch (err) {
+			log("rotation re-registration threw synchronously for successor topic=%s (isolated): %o", key, err);
+		}
+	}
+}