@optimystic/db-p2p 0.13.5 → 0.14.0

package/src/reactivity/subscriber-registry.ts

@@ -0,0 +1,96 @@
+/**
+ * Reactivity — node-level subscriber registry (the socket-delivery → subscription-manager seam).
+ *
+ * A {@link import("./subscription-manager.js").ReactivitySubscriptionManager} owns the verify/dedupe/deliver
+ * path for one subscription but is transport-agnostic: it exposes `onNotification(n)` and never touches a
+ * socket. This registry is the routing table that connects a socket-delivered {@link NotificationV1} to the
+ * right manager(s): the forwarder host's `deliverLocal(topicId, n)` looks topic up here and invokes every
+ * manager registered for it, and a constructed manager registers its `onNotification` keyed by the reactivity
+ * `topicId` it subscribed under.
+ *
+ * Keyed by topicId-base64url. A manager subscribes under `topicId = reactivityTopicId(reactivityTailBytes(
+ * tailId))` (the same anchor origination derives), so a notification's topic — derived by the forwarder host
+ * from the notification's tail anchor — routes to exactly the managers watching that tail's collection.
+ *
+ * **Scope.** This delivers socket-routed notifications into a manager that was *already constructed* and
+ * registered. Constructing the manager from a Quereus `Database.watch` (the application bridge) stays the
+ * backlog item `optimystic-network-reactive-watch-integration-test`; this registry is the plug it will use.
+ */
+
+import { bytesToB64url, type NotificationV1 } from "@optimystic/db-core";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-subscribers");
+
+/** A subscriber's inbound seam — a manager's `onNotification` (which returns a delivery outcome promise). */
+export type ReactivityNotificationHandler = (n: NotificationV1) => void | Promise<unknown>;
+
+/**
+ * The node's `topicId → subscriber handlers` table. Exposed on the node as `reactivitySubscribers` so a
+ * subscribe factory can register a {@link import("./subscription-manager.js").ReactivitySubscriptionManager}
+ * and have socket-delivered notifications routed to it.
+ */
+export class ReactivitySubscriberRegistry {
+	private readonly byTopic = new Map<string, Set<ReactivityNotificationHandler>>();
+
+	/**
+	 * Register `onNotification` to receive every notification the node delivers for `topicId`. Multiple
+	 * managers may register for one topic (each gets every notification). Returns an idempotent unregister.
+	 */
+	register(topicId: Uint8Array, onNotification: ReactivityNotificationHandler): () => void {
+		const key = bytesToB64url(topicId);
+		let handlers = this.byTopic.get(key);
+		if (handlers === undefined) {
+			handlers = new Set();
+			this.byTopic.set(key, handlers);
+		}
+		handlers.add(onNotification);
+		return (): void => this.unregister(topicId, onNotification);
+	}
+
+	/** Drop a previously-registered handler; idempotent (a no-op if it was never registered / already gone). */
+	unregister(topicId: Uint8Array, onNotification: ReactivityNotificationHandler): void {
+		const key = bytesToB64url(topicId);
+		const handlers = this.byTopic.get(key);
+		if (handlers === undefined) {
+			return;
+		}
+		handlers.delete(onNotification);
+		if (handlers.size === 0) {
+			this.byTopic.delete(key);
+		}
+	}
+
+	/**
+	 * Deliver `n` to every handler registered for `topicId` (the forwarder host's `deliverLocal` seam). Each
+	 * handler is isolated: a synchronous throw or a rejected delivery promise is logged, never propagated —
+	 * one faulty subscriber must not break delivery to the rest or the fan-out loop that called this.
+	 */
+	deliver(topicId: Uint8Array, n: NotificationV1): void {
+		const handlers = this.byTopic.get(bytesToB64url(topicId));
+		if (handlers === undefined) {
+			return;
+		}
+		// Snapshot: a handler that unregisters itself on delivery would otherwise mutate the live set.
+		for (const handler of [...handlers]) {
+			try {
+				const result = handler(n);
+				if (result instanceof Promise) {
+					result.catch((err: unknown) => log("subscriber delivery rejected (isolated) for rev=%d: %o", n.revision, err));
+				}
+			} catch (err) {
+				log("subscriber handler threw (isolated) for rev=%d: %o", n.revision, err);
+			}
+		}
+	}
+
+	/** Number of topics with at least one registered subscriber (diagnostic / test). */
+	get topicCount(): number {
+		return this.byTopic.size;
+	}
+
+	/** Whether any subscriber is registered for `topicId` (diagnostic / test). */
+	has(topicId: Uint8Array): boolean {
+		return this.byTopic.has(bytesToB64url(topicId));
+	}
+}

package/src/reactivity/subscription-manager.ts

@@ -0,0 +1,450 @@
+/**
+ * Reactivity — subscription manager (db-p2p, wires to the cohort-topic substrate).
+ *
+ * Drives a subscriber's lifecycle against the participant-facing {@link CohortTopicService}: register at
+ * cohort-topic tier **T3 (luxury)** with the reactivity `appPayload`, renew to keep the registration
+ * alive within its TTL (Edge 60 s / Core 90 s), and withdraw by ceasing renewal — all the cohort-topic
+ * standard (`docs/reactivity.md` §Subscription). The reactivity-specific shape lives in db-core: the
+ * tail-anchored `topicId = H(tailId ‖ "reactivity")`, the {@link SubscribeAppPayloadV1}, and the
+ * subscriber-side verify/deliver path ({@link ReactivitySubscriber}).
+ *
+ * Inbound notifications are handed to {@link ReactivitySubscriptionManager.onNotification}, which runs
+ * the db-core delivery path (verify against the cached tail-cohort `MembershipCertV1` with one
+ * fetch-and-retry, revision-contiguity, gap → backfill seam, `(collectionId, revision)` dedupe, surface).
+ * The notification transport (the reactivity application protocol that delivers `NotificationV1` frames
+ * to a subscriber's primary) is the sibling tickets' concern; this manager owns attach + delivery logic.
+ */
+
+import {
+	Tier,
+	reactivityTopicId,
+	subscribeAppPayloadBytes,
+	subscriberTtlForProfile,
+	deltaMaxForProfile,
+	createNotificationVerifier,
+	createReactivitySubscriber,
+	createBackfillRequester,
+	createStickyCohortHintCache,
+	createRejoinJitter,
+	applyResumeReply,
+	detectRotation,
+	planReRegistration,
+	bytesToB64url,
+	type CohortTopicService,
+	type NodeProfile,
+	type NotificationV1,
+	type DeliveryOutcome,
+	type ReactivitySubscriber,
+	type NotificationVerifier,
+	type RegistrationHandle,
+	type BackfillV1,
+	type BackfillReplyV1,
+	type BackfillTransport,
+	type ResumeV1,
+	type ResumeReplyV1,
+	type ResumeApplyOutcome,
+	type StickyCohortHintCache,
+	type CheckpointSummary,
+	type RejoinJitter,
+	type ReRegistrationPlan,
+} from "@optimystic/db-core";
+import { RotationRedirectError } from "./recover-transport.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-subscription");
+
+/** Sends a {@link ResumeV1} to the serving cohort and awaits its classified {@link ResumeReplyV1}. */
+export type ResumeTransport = (req: ResumeV1) => Promise<ResumeReplyV1>;
+
+/**
+ * A detected tail rotation surfaced to the host so it can schedule the jittered re-registration timer
+ * (`docs/reactivity.md` §Tail rotation). The manager has already invalidated the sticky cohort-hint cache
+ * (the cached primary is under the old tree).
+ */
+export interface RotationNotice {
+	/** The new tail block id the topic rotated to, base64url. */
+	readonly newTailId: string;
+	/** True iff this was a pre-announce (`rotationHint` on a still-current-tail notification). */
+	readonly preAnnounced: boolean;
+	/** The jittered re-registration plan (new topicId + `fireAt` + carried `lastRevision`) for the host to schedule. */
+	readonly plan: ReRegistrationPlan;
+}
+
+/** Construction inputs for a {@link ReactivitySubscriptionManager}. */
+export interface ReactivitySubscriptionManagerOptions {
+	/** Participant-facing cohort-topic substrate API. */
+	readonly service: CohortTopicService;
+	/** Stable collection identity (the collection's id block id, raw bytes). */
+	readonly collectionId: Uint8Array;
+	/**
+	 * Tail block id at attach time (raw bytes); anchors the rotating topic (`reactivityTopicId` is applied to
+	 * it) and detects rotation.
+	 *
+	 * **Load-bearing encoding contract.** When a production subscribe factory converts a `BlockId` tail to
+	 * these bytes it MUST use `reactivityTailBytes(tailId)` (`reactivity/topic-bytes.ts`) — the SAME function
+	 * origination's membership gate uses — NOT db-core's `blockIdToBytes` (which `sha256`s first → a double
+	 * hash). Origination derives the topic's `coord_0` cohort from `reactivityTopicId(reactivityTailBytes(
+	 * tailId))`; if this side feeds differently-encoded bytes it subscribes to a *different* coord and
+	 * origination silently never reaches it (the `topic-bytes-encoding` spec pins the coord-equality).
+	 */
+	readonly tailIdAtAttach: Uint8Array;
+	/** Surface a verified, contiguous notification to the application. */
+	readonly deliver: (n: NotificationV1) => void;
+	/**
+	 * Explicit backfill seam — used only when {@link backfillTransport} is **not** supplied. When a
+	 * transport is given, the manager builds the db-core {@link createBackfillRequester} driver instead and
+	 * this is ignored.
+	 */
+	readonly requestBackfill?: (from: number, to: number) => void;
+	/**
+	 * Backfill RPC transport (the reactivity application protocol dialing the serving cohort). When
+	 * supplied, the manager wires the subscriber's gap-detection seam to the {@link BackfillV1} RPC,
+	 * replaying the reply through the delivery path. Requires {@link signBackfill}.
+	 */
+	readonly backfillTransport?: BackfillTransport;
+	/** Sign a {@link BackfillV1} over its unsigned image (subscriber peer key); base64url. */
+	readonly signBackfill?: (req: Omit<BackfillV1, "signature">) => string;
+	/** Resume RPC transport (mobile wake). When supplied, {@link resume} is available. Requires {@link signResume}. */
+	readonly resumeTransport?: ResumeTransport;
+	/** Sign a {@link ResumeV1} over its unsigned image (subscriber peer key); base64url. */
+	readonly signResume?: (req: Omit<ResumeV1, "signature">) => string;
+	/**
+	 * The subscriber's **real ring coordinate**, base64url (the `participantCoord` it registers under at the
+	 * cohort-topic tier), carried in the signed {@link ResumeV1}. The recover transport replies on the same
+	 * stream, so this is not used for reply routing today; still, the production factory should source it
+	 * correctly so the signed field is meaningful and a future out-of-band reply path is unblocked. Absent ⇒
+	 * the manager falls back to the collection id as a placeholder and logs (the signed field is then merely
+	 * a stable per-collection token, not the ring coord).
+	 */
+	readonly subscriberCoord?: string;
+	/**
+	 * Application-level re-attempts the backfill escalation makes after a **transport failure** before giving
+	 * up to a resume/chain-read (the sticky-hint dial + one cohort-walk fallback already live in the
+	 * transport, so this is a small outer retry). Default `1`. Distinct from the `available`-window underflow
+	 * path ({@link onBackfillUnderflow}), which escalates immediately without retrying.
+	 */
+	readonly backfillMaxRetries?: number;
+	/** Apply a verified checkpoint's merged digest on a `checkpoint_window` resume. */
+	readonly onCheckpointDigest?: (summary: CheckpointSummary) => void;
+	/** Chain-read + fresh subscribe fallback (out_of_window, or an untrusted checkpoint). */
+	readonly onChainRead?: (currentTailId: string | undefined, currentRevision: number | undefined) => void;
+	/** Re-register under the rotated tail (tail_rotated); also invalidates the sticky cohort-hint cache. */
+	readonly onTailRotated?: (newTailId: string, newRevisionAtRotation: number) => void;
+	/** Escalation when a backfill's `available` window fell past the gap's low edge (escalate to resume/chain). */
+	readonly onBackfillUnderflow?: (requested: { from: number; to: number }, available: { fromRevision: number; toRevision: number }) => void;
+	/** Sticky cohort-hint cache for one-RT resume after a flap; defaults to a fresh per-manager cache (Edge). */
+	readonly cohortHintCache?: StickyCohortHintCache;
+	/**
+	 * Tail-rotation observer (`docs/reactivity.md` §Tail rotation). Fired once per successor tail when an
+	 * inbound notification reveals a rotation (delivered `tailId` differs, or a `rotationHint` pre-announce):
+	 * the manager invalidates the sticky cohort-hint cache and hands the host a jittered re-registration plan
+	 * to schedule. Absent ⇒ rotation is detected and the cache invalidated, but no plan is surfaced.
+	 */
+	readonly onRotation?: (notice: RotationNotice) => void;
+	/** Re-registration jitter for the rotation plan's `fireAt`; defaults to the `T_rejoin_jitter` curve. */
+	readonly rejoinJitter?: RejoinJitter;
+	/** Unix-ms clock for resume timestamps (injected for deterministic tests). Default `Date.now`. */
+	readonly clock?: () => number;
+	/** Last revision already held; `0` (default) for a fresh subscribe. */
+	readonly lastKnownRev?: number;
+	/** Max delta bytes accepted; defaults to `0` on Edge, `delta_max` on Core via {@link profile}. */
+	readonly deltaMaxBytes?: number;
+	/** Subscription TTL (ms). Default: derived from {@link profile} (Core 90 s / Edge 60 s). */
+	readonly ttlMs?: number;
+	/** Node profile used to derive the TTL / delta budget when not given explicitly. */
+	readonly profile?: NodeProfile;
+}
+
+/** Wires one reactivity subscription to the cohort-topic substrate at tier T3. */
+export class ReactivitySubscriptionManager {
+	private readonly service: CohortTopicService;
+	private readonly collectionId: Uint8Array;
+	private readonly collectionIdB64: string;
+	private readonly tailIdAtAttach: Uint8Array;
+	private readonly topicId: Uint8Array;
+	private readonly ttlMs: number;
+	private readonly deltaMaxBytes: number;
+	private readonly lastKnownRev: number;
+	private readonly subscriber: ReactivitySubscriber;
+	private readonly verifier: NotificationVerifier;
+	private readonly options: ReactivitySubscriptionManagerOptions;
+	private readonly cohortHintCache: StickyCohortHintCache;
+	private readonly clock: () => number;
+	private readonly tailIdAtAttachB64: string;
+	private readonly rejoinJitter: RejoinJitter;
+	/** Resolved ring coordinate signed into a {@link ResumeV1} (real coord, or the collectionId placeholder). */
+	private readonly subscriberCoord: string;
+	/** True iff {@link subscriberCoord} fell back to the collectionId placeholder (no real coord supplied). */
+	private readonly subscriberCoordIsFallback: boolean;
+	/** The successor tail a rotation has already been surfaced for, so the notice fires once per rotation. */
+	private rotationHandledFor?: string;
+	/** Memoized db-core backfill driver (built on first gap, once `this.subscriber` is assigned). */
+	private backfillRequester?: (from: number, to: number) => Promise<BackfillReplyV1>;
+	private handle?: RegistrationHandle;
+
+	constructor(options: ReactivitySubscriptionManagerOptions) {
+		this.options = options;
+		this.service = options.service;
+		this.collectionId = options.collectionId;
+		this.collectionIdB64 = bytesToB64url(options.collectionId);
+		this.tailIdAtAttach = options.tailIdAtAttach;
+		this.topicId = reactivityTopicId(options.tailIdAtAttach);
+		this.ttlMs = options.ttlMs ?? (options.profile !== undefined ? subscriberTtlForProfile(options.profile) : undefined) ?? DEFAULT_SUBSCRIBER_TTL_MS;
+		this.deltaMaxBytes = options.deltaMaxBytes ?? (options.profile !== undefined ? deltaMaxForProfile(options.profile) : DEFAULT_EDGE_SAFE_DELTA_MAX);
+		this.lastKnownRev = options.lastKnownRev ?? 0;
+		this.cohortHintCache = options.cohortHintCache ?? createStickyCohortHintCache();
+		this.clock = options.clock ?? ((): number => Date.now());
+		this.tailIdAtAttachB64 = bytesToB64url(options.tailIdAtAttach);
+		this.rejoinJitter = options.rejoinJitter ?? createRejoinJitter();
+		this.subscriberCoordIsFallback = options.subscriberCoord === undefined;
+		this.subscriberCoord = options.subscriberCoord ?? this.collectionIdB64;
+		// Verify against the tail cohort's membership cert (the verifier owns the one fetch-and-retry).
+		this.verifier = createNotificationVerifier({ verifier: this.service.verifier(), tier: Tier.T3 });
+		this.subscriber = createReactivitySubscriber({
+			collectionId: this.collectionIdB64,
+			verifier: this.verifier,
+			deliver: options.deliver,
+			// Bind the seam to a method so it resolves the (possibly transport-backed) driver lazily —
+			// `this.subscriber` is not yet assigned during this very call.
+			requestBackfill: (from, to): void => this.onBackfillGap(from, to),
+			lastKnownRev: this.lastKnownRev,
+		});
+	}
+
+	/**
+	 * The subscriber detected a revision gap. When a {@link ReactivitySubscriptionManagerOptions.backfillTransport}
+	 * + signer are configured, drive the db-core {@link createBackfillRequester} (build → sign → send →
+	 * replay reply through delivery → underflow escalation, built lazily once); otherwise fall back to the
+	 * explicit {@link ReactivitySubscriptionManagerOptions.requestBackfill} callback (or no-op).
+	 */
+	private onBackfillGap(from: number, to: number): void {
+		const { backfillTransport, signBackfill } = this.options;
+		if (backfillTransport !== undefined && signBackfill !== undefined) {
+			if (this.backfillRequester === undefined) {
+				this.backfillRequester = createBackfillRequester({
+					collectionId: this.collectionIdB64,
+					sign: signBackfill,
+					transport: backfillTransport,
+					subscriber: this.subscriber,
+					clock: this.clock,
+					onUnderflow: this.options.onBackfillUnderflow,
+				});
+			}
+			// Fire-and-forget off the gap seam (NOT the deliver path — backfill is hint-only and must never
+			// block or fault commit/delivery). The driver resolves (no throw) on an `available`-window
+			// underflow — that path is handled by `onBackfillUnderflow`; only a genuine **transport failure**
+			// rejects, which escalates here. `escalateBackfill` never rejects, so nothing leaks as an
+			// unhandled rejection.
+			void this.backfillRequester(from, to).catch(() => { void this.escalateBackfill(from, to); });
+			return;
+		}
+		this.options.requestBackfill?.(from, to);
+	}
+
+	/**
+	 * A backfill RPC failed at the transport (the sticky-hint dial + cohort-walk fallback inside the
+	 * transport were already exhausted). Re-attempt up to {@link ReactivitySubscriptionManagerOptions.backfillMaxRetries}
+	 * times, then escalate to {@link resume} (when a resume transport is configured) and finally to
+	 * {@link ReactivitySubscriptionManagerOptions.onChainRead}. Never rejects (it runs detached off the gap
+	 * seam) and never touches the commit/delivery path.
+	 */
+	private async escalateBackfill(from: number, to: number): Promise<void> {
+		const max = this.options.backfillMaxRetries ?? DEFAULT_BACKFILL_MAX_RETRIES;
+		for (let attempt = 1; attempt <= max; attempt++) {
+			try {
+				await this.backfillRequester!(from, to);
+				return; // a re-attempt closed (or underflow-escalated) the gap
+			} catch (err) {
+				if (err instanceof RotationRedirectError) {
+					// The serving cohort's outgoing tail rotated: move to the new tree (no chain-read fallback).
+					this.honorRotationRedirect(err);
+					return;
+				}
+				log("backfill retry %d/%d for [%d,%d] failed: %o", attempt, max, from, to, err);
+			}
+		}
+		// Still failing after the bounded retries: fall back to a resume (a wider recovery window) when one is
+		// wired, else signal a chain read. Distinct from the underflow seam, which carries the held window.
+		if (this.options.resumeTransport !== undefined && this.options.signResume !== undefined) {
+			try {
+				await this.resume();
+				return;
+			} catch (err) {
+				log("backfill escalation to resume() failed for [%d,%d]: %o", from, to, err);
+			}
+		}
+		this.options.onChainRead?.(undefined, undefined);
+	}
+
+	/** The live registration handle, or `undefined` before the first {@link register}. */
+	get registration(): RegistrationHandle | undefined {
+		return this.handle;
+	}
+
+	/** Last contiguously-delivered revision. */
+	get lastRevision(): number {
+		return this.subscriber.lastRevision;
+	}
+
+	/** Register the subscriber at tier T3 with the reactivity `appPayload`. */
+	async register(): Promise<RegistrationHandle> {
+		const appPayload = subscribeAppPayloadBytes({
+			collectionId: bytesToB64url(this.collectionId),
+			tailIdAtAttach: bytesToB64url(this.tailIdAtAttach),
+			lastKnownRev: this.lastKnownRev,
+			deltaMaxBytes: this.deltaMaxBytes,
+		});
+		this.handle = await this.service.register({
+			topicId: this.topicId,
+			tier: Tier.T3,
+			appPayload,
+			ttl: this.ttlMs,
+		});
+		return this.handle;
+	}
+
+	/** Run one renewal cycle (keep-alive touch). No-op before the first {@link register}. */
+	async renew(): Promise<void> {
+		if (this.handle === undefined) {
+			return;
+		}
+		await this.service.renew(this.handle);
+	}
+
+	/** Withdraw: stop renewing and send a best-effort signed tombstone so the cohort frees the
+	 * registration immediately (TTL expiry remains the fallback if the primary is unreachable). */
+	async withdraw(): Promise<void> {
+		if (this.handle !== undefined) {
+			await this.service.withdraw(this.handle);
+		}
+	}
+
+	/**
+	 * Resume after a sleep/flap (`docs/reactivity.md` §Resume). Sends one {@link ResumeV1} from
+	 * `lastRevision + 1` to the serving cohort over the injected {@link ResumeTransport} and applies the
+	 * classified reply via the db-core {@link applyResumeReply}: a `backfill` / `checkpoint_window` reply
+	 * replays its entries through the delivery path (verified, deduped); `out_of_window` and an untrusted
+	 * checkpoint escalate to {@link ReactivitySubscriptionManagerOptions.onChainRead}; `tail_rotated`
+	 * escalates to {@link ReactivitySubscriptionManagerOptions.onTailRotated} and invalidates the sticky
+	 * cohort-hint cache (the cached primary is under the old tree). Throws if no resume transport/signer
+	 * was configured.
+	 *
+	 * The sticky cohort-hint cache (Edge) lets a resume after a brief flap dial the cached primary directly
+	 * for a one-RT recovery instead of re-walking from `d_max`; it is the transport's to consult via
+	 * {@link cohortHint}.
+	 */
+	async resume(): Promise<ResumeApplyOutcome> {
+		const { resumeTransport, signResume } = this.options;
+		if (resumeTransport === undefined || signResume === undefined) {
+			throw new Error("ReactivitySubscriptionManager.resume: no resumeTransport/signResume configured");
+		}
+		if (this.subscriberCoordIsFallback) {
+			log("resume: no real ring coordinate supplied; signing ResumeV1 with the collectionId as a placeholder subscriberCoord (collection=%s)", this.collectionIdB64);
+		}
+		const unsigned: Omit<ResumeV1, "signature"> = {
+			v: 1,
+			collectionId: this.collectionIdB64,
+			fromRevision: this.subscriber.lastRevision + 1,
+			latestKnownTailId: bytesToB64url(this.tailIdAtAttach),
+			subscriberCoord: this.subscriberCoord,
+			timestamp: this.clock(),
+		};
+		const req: ResumeV1 = { ...unsigned, signature: signResume(unsigned) };
+		let reply: ResumeReplyV1;
+		try {
+			reply = await resumeTransport(req);
+		} catch (err) {
+			if (err instanceof RotationRedirectError) {
+				// The resume reached the serving cohort's outgoing (draining) tail: honor the redirect (surface
+				// the rotation through onRotation, invalidate the sticky cache) and resolve as a tail rotation —
+				// never throw the redirect out to the caller / the gap seam's commit-delivery path.
+				this.honorRotationRedirect(err);
+				return "tail_rotated";
+			}
+			throw err;
+		}
+		return applyResumeReply(reply, {
+			subscriber: this.subscriber,
+			verifier: this.verifier,
+			onCheckpointDigest: this.options.onCheckpointDigest,
+			onChainRead: this.options.onChainRead,
+			onTailRotated: (newTailId, newRevisionAtRotation): void => {
+				// The cached primary is under the now-stale tree; drop it so the re-registration re-walks.
+				this.cohortHintCache.invalidate(this.collectionIdB64);
+				this.options.onTailRotated?.(newTailId, newRevisionAtRotation);
+			},
+		});
+	}
+
+	/** The sticky cohort-hint cache backing one-RT resume after a flap (Edge). */
+	get cohortHint(): StickyCohortHintCache {
+		return this.cohortHintCache;
+	}
+
+	/**
+	 * Run the db-core delivery path for one inbound notification, then check for tail rotation
+	 * (`docs/reactivity.md` §Tail rotation): a delivered `tailId` that differs from `tailIdAtAttach`, or a
+	 * `rotationHint` pre-announce, invalidates the sticky cohort-hint cache (the cached primary is under the
+	 * old tree) and surfaces a jittered re-registration plan via {@link ReactivitySubscriptionManagerOptions.onRotation}.
+	 * Fired at most once per successor tail.
+	 */
+	async onNotification(n: NotificationV1): Promise<DeliveryOutcome> {
+		const outcome = await this.subscriber.onNotification(n);
+		this.checkRotation(n);
+		return outcome;
+	}
+
+	/** Detect a tail rotation from an inbound notification and surface it once per successor tail. */
+	private checkRotation(n: NotificationV1): void {
+		const detection = detectRotation(this.tailIdAtAttachB64, n);
+		if (!detection.rotated || detection.newTailId === undefined) {
+			return;
+		}
+		this.surfaceRotation(detection.newTailId, detection.preAnnounced);
+	}
+
+	/**
+	 * Surface a rotation to the host **once per successor tail** (`docs/reactivity.md` §Tail rotation):
+	 * invalidate the sticky cohort-hint cache (the cached primary is under the now-stale tree, so a later
+	 * resume re-walks) and — when an {@link ReactivitySubscriptionManagerOptions.onRotation} observer is
+	 * configured — hand it a jittered re-registration plan carrying `lastRevision` (continuous across the
+	 * rotation). The single seam both the notification-driven detection ({@link checkRotation}) and the
+	 * recover-driven {@link RotationRedirectError} ({@link honorRotationRedirect}) end in; the
+	 * {@link rotationHandledFor} guard self-corrects across a chained OLD→A→B rotation.
+	 */
+	private surfaceRotation(newTailId: string, preAnnounced: boolean): void {
+		if (newTailId === this.rotationHandledFor) {
+			return; // already surfaced this successor
+		}
+		this.rotationHandledFor = newTailId;
+		// The cached primary is under the now-stale tree; drop it so the re-registration re-walks.
+		this.cohortHintCache.invalidate(this.collectionIdB64);
+		if (this.options.onRotation === undefined) {
+			return;
+		}
+		const plan = planReRegistration({
+			hint: { newTailId },
+			lastRevision: this.subscriber.lastRevision,
+			now: this.clock(),
+			jitter: this.rejoinJitter,
+		});
+		this.options.onRotation({ newTailId, preAnnounced, plan });
+	}
+
+	/**
+	 * Honor a recover-surfaced {@link RotationRedirectError}: the serving cohort's outgoing tail rotated and
+	 * bounced this request to the new tree. Route it through the **same** {@link surfaceRotation} seam a
+	 * delivered pre-announce uses (`preAnnounced: false`), so both the notify-driven and recover-driven
+	 * rotation paths converge on one `RotationNotice` for the host's re-registration scheduler to consume.
+	 */
+	private honorRotationRedirect(err: RotationRedirectError): void {
+		this.surfaceRotation(err.redirect.newTailId, false);
+	}
+}
+
+/** Default application-level backfill re-attempts after a transport failure before escalating to resume/chain. */
+const DEFAULT_BACKFILL_MAX_RETRIES = 1;
+/** Fallback subscriber TTL when neither `ttlMs` nor `profile` is supplied (Core default). */
+const DEFAULT_SUBSCRIBER_TTL_MS = 90_000;
+/** Edge-safe delta budget when neither `deltaMaxBytes` nor `profile` is supplied: decline deltas. */
+const DEFAULT_EDGE_SAFE_DELTA_MAX = 0;

package/src/reactivity/topic-bytes.ts

@@ -0,0 +1,37 @@
+/**
+ * Reactivity — the one pinned `BlockId` → raw tail-bytes encoding, shared by origination and subscription.
+ *
+ * `reactivityTopicId` (db-core) hashes `H(tailBytes ‖ "reactivity")` to derive the topic's `coord_0`
+ * cohort. Origination (the cohort-change membership gate, {@link
+ * import("../cohort-topic/reactivity-membership-gate.js").createReactivitySelfMembershipGate}) and the
+ * subscriber side (the production subscribe factory that converts a `BlockId` `tailIdAtAttach` to the bytes
+ * {@link import("./subscription-manager.js").ReactivitySubscriptionManager} feeds `reactivityTopicId`) MUST
+ * feed it the **same** bytes for a given tail, or they resolve different coords and origination silently
+ * never reaches subscribers (green tests, dead feature).
+ *
+ * This module is that single source of truth: `reactivityTailBytes(tailId) = TextEncoder().encode(tailId)`,
+ * the synchronous block-id→bytes convention the rest of db-p2p already uses for ring hashing of tail ids
+ * (`cluster/client.ts`, `repo/client.ts`). db-core's async `blockIdToBytes` (which `sha256`s the utf8 bytes
+ * first) is deliberately NOT used: it would (a) double-hash relative to the spec's `H(tailId ‖ "reactivity")`
+ * and (b) force the synchronous origination gate to become async.
+ *
+ * It lives in the reactivity surface (not buried in the gate) so the subscribe path and the gate import the
+ * exact same function rather than re-deriving the encoding independently. The
+ * `cohort-topic/reactivity-membership-gate.ts` module re-exports it for its existing callers.
+ */
+
+import type { BlockId } from "@optimystic/db-core";
+
+const utf8 = new TextEncoder();
+
+/**
+ * The pinned `BlockId` → raw tail bytes encoding fed into `reactivityTopicId`: the **raw** utf8 bytes of the
+ * tail block-id string (NOT a pre-hashed routing key, NOT db-core's double-hashing `blockIdToBytes`).
+ *
+ * Load-bearing: origination and the subscriber side must call this **same** function for a given tail (see
+ * the module doc) — a mismatch resolves different `coord_0`s and origination silently never reaches
+ * subscribers. The `topic-bytes-encoding` spec pins the coord-equality both ways.
+ */
+export function reactivityTailBytes(tailId: BlockId): Uint8Array {
+	return utf8.encode(tailId);
+}