@optimystic/db-core 0.13.5 → 0.14.1

package/src/reactivity/rotation.ts

@@ -0,0 +1,415 @@
+/**
+ * Reactivity — tail rotation lifecycle (`docs/reactivity.md` §Rotating tail anchor, §Tail rotation).
+ *
+ * `topicId = H(tailId ‖ "reactivity")` is derived per emission ({@link reactivityTopicId}). When the tail
+ * block fills (`block_fill_size` transactions, default 64) a new tail block is born and `tailId` — hence
+ * `topicId` — changes; the cohort-topic layer treats the new `topicId` as an **entirely new topic** (fresh
+ * tree, new ring coord). Reactivity manages the subscriber/replay-state migration explicitly. This module
+ * owns that lifecycle:
+ *
+ *  - **Pre-announce** — the block-filling commit's notification carries {@link RotationHintV1}; built here
+ *    by {@link buildRotationHint} and detected subscriber-side by {@link detectRotation}.
+ *  - **Block-fill tracking** — {@link BlockFillTracker} counts transactions in the current tail block and
+ *    fires anticipatory **warm-up** at `block_fill_size − warm_threshold` and the **filling** signal at
+ *    `block_fill_size` (the commit that carries the hint).
+ *  - **Drain** — {@link TailDrainGate} keeps the outgoing tail serving renewals/replays for `T_drain` while
+ *    bouncing *new* subscriptions with a `Promoted`-shaped {@link RotationRedirectV1} to the new tree.
+ *  - **Jittered re-registration** — {@link planReRegistration} / {@link planReRegistrationWave} schedule a
+ *    subscriber's move to the new `topicId` over `T_rejoin_jitter` (the cohort-topic {@link RejoinJitter}),
+ *    carrying its existing `lastRevision` (revisions are continuous across rotations).
+ *  - **Buffer-to-checkpoint handoff** — {@link buildRotationHandoffCheckpoint} folds the outgoing tail's
+ *    replay buffer into a final {@link CheckpointSummary} covering `[lastCheckpoint.toRevision + 1,
+ *    rotationRevision]`, the **only** state migrated across a rotation; {@link applyRotationHandoff} lands it
+ *    at the new tail so a `ResumeV1` spanning the rotation is recoverable.
+ *
+ * Forwarder draining is *emergent*: forwarders under the old tail watch their direct-subscriber count drop
+ * as subscribers re-register elsewhere and demote naturally per the cohort-topic demotion protocol (no
+ * state migrates; the new tree rebuilds via re-registration). It needs no code here.
+ *
+ * Coordination with [reactivity-backfill-resume-checkpoints]: that ticket owns the `ResumeReplyV1.TailRotated`
+ * variant and the `latestKnownTailId`-staleness classification; this ticket produces the handoff checkpoint
+ * and the rotation *condition*. The new tail's {@link PushState.inheritedCheckpoint} (set by
+ * {@link applyRotationHandoff}) is the seam the resume classifier consults to answer a checkpoint-window
+ * resume whose span crosses the rotation: `classifyResume`/`serveResume` now read it (after the rolling
+ * `checkpoint` misses) and serve the inherited summary, so a cross-rotation resume no longer falls to
+ * `out_of_window` (`docs/reactivity.md` §Resume, §Tail rotation step 5). The drain-window redirect a new
+ * subscription receives, {@link RotationRedirectV1}, is serialized by {@link validateRotationRedirectV1} and
+ * rides the recover reply envelope as `kind: "rotated"` ({@link import("./recover.js").RecoverReplyV1}).
+ */
+
+import { bytesToB64url, b64urlToBytes } from "../cohort-topic/wire/codec.js";
+import { createRingHash } from "../cohort-topic/ring-hash.js";
+import type { IRingHash } from "../cohort-topic/ports.js";
+import type { RejoinJitter } from "../cohort-topic/antiflood/jitter.js";
+import { BLOCK_FILL_SIZE_DEFAULT, T_DRAIN_MS, WARM_THRESHOLD_DEFAULT } from "./config.js";
+import { buildCheckpointSummary, type CheckpointSummary } from "./checkpoint.js";
+import { reactivityTopicId } from "./topic-anchor.js";
+import type { PushState } from "./push-state.js";
+import type { NotificationV1, RotationHintV1 } from "./wire.js";
+import { asObject, b64urlField, failWire, reqIntInRange, reqString, requireV1 } from "./wire-validate.js";
+
+// --- pre-announce + subscriber-side detection --------------------------------
+
+/**
+ * Build the rotation pre-announce embedded in the block-filling commit's notification. The new tail block
+ * id is known at the filling commit; the rotation becomes effective at the next revision, so
+ * `effectiveAtRevision = fillingRevision + 1` (`docs/reactivity.md` §Tail rotation, worked scenario:
+ * revision 5400 carries `{ newTailId: T_6, effectiveAtRevision: 5401 }`).
+ */
+export function buildRotationHint(newTailId: string, fillingRevision: number): RotationHintV1 {
+	return { newTailId, effectiveAtRevision: fillingRevision + 1 };
+}
+
+/** The subscriber-side rotation verdict for one delivered notification. */
+export interface RotationDetection {
+	/** True iff the subscriber's tree has rotated (delivered tail differs) or a rotation is pre-announced. */
+	readonly rotated: boolean;
+	/** The tail id to re-register under, base64url — present iff `rotated`. */
+	readonly newTailId?: string;
+	/**
+	 * True iff this is a **pre-announce**: the delivered `tailId` still matches `tailIdAtAttach`, but the
+	 * notification's `rotationHint.newTailId` names a different successor. (False when the delivered tail
+	 * already differs — the tree has *already* migrated.)
+	 */
+	readonly preAnnounced: boolean;
+}
+
+/**
+ * Detect tail rotation for a subscriber attached at `tailIdAtAttach` (base64url) from a delivered
+ * notification. Rotation is signaled when the delivered `tailId` **or** the `rotationHint.newTailId`
+ * differs from `tailIdAtAttach` (`docs/reactivity.md` §Rotating tail anchor). An already-rotated delivery
+ * (different `tailId`) takes precedence over a pre-announce.
+ */
+export function detectRotation(tailIdAtAttach: string, n: Pick<NotificationV1, "tailId" | "rotationHint">): RotationDetection {
+	if (n.tailId !== tailIdAtAttach) {
+		// The delivered notification rides the *new* tree already — a hard rotation, not a pre-announce.
+		return { rotated: true, newTailId: n.tailId, preAnnounced: false };
+	}
+	if (n.rotationHint !== undefined && n.rotationHint.newTailId !== tailIdAtAttach) {
+		return { rotated: true, newTailId: n.rotationHint.newTailId, preAnnounced: true };
+	}
+	return { rotated: false, preAnnounced: false };
+}
+
+// --- block-fill tracking (warm-up + filling signal) --------------------------
+
+/** The fill signal for one committed transaction in the current tail block. */
+export type BlockFillSignal =
+	/** Below the warm-up threshold — nothing to do. */
+	| { readonly kind: "none"; readonly count: number }
+	/**
+	 * Anticipatory warm-up: the block has reached `block_fill_size − warm_threshold` transactions with
+	 * `remaining` to go. The outgoing tail opportunistically biases FRET pre-dialing toward likely-successor
+	 * coords (best-effort; the next `tailId` is not yet knowable). No state migrates.
+	 */
+	| { readonly kind: "warmup"; readonly count: number; readonly remaining: number }
+	/**
+	 * The **block-filling** transaction: this commit's notification carries the {@link RotationHintV1} and
+	 * triggers the rotation. The tracker resets for the next block after emitting this.
+	 */
+	| { readonly kind: "filling"; readonly count: number };
+
+/** Construction inputs for a {@link BlockFillTracker}. */
+export interface BlockFillTrackerInit {
+	/** Transactions per block before the tail rotates (default {@link BLOCK_FILL_SIZE_DEFAULT}). */
+	readonly blockFillSize?: number;
+	/** Transactions remaining in the tail when anticipatory warm-up fires (default {@link WARM_THRESHOLD_DEFAULT}). */
+	readonly warmThreshold?: number;
+}
+
+/**
+ * Counts transactions committed into the current tail block and emits the {@link BlockFillSignal} that
+ * drives anticipatory warm-up and the block-filling rotation trigger (`docs/reactivity.md` §Tail rotation,
+ * §Anticipatory warm-up). One tracker per collection on the tail-cohort primary.
+ */
+export class BlockFillTracker {
+	readonly blockFillSize: number;
+	readonly warmThreshold: number;
+	private count = 0;
+
+	constructor(init: BlockFillTrackerInit = {}) {
+		const blockFillSize = init.blockFillSize ?? BLOCK_FILL_SIZE_DEFAULT;
+		const warmThreshold = init.warmThreshold ?? WARM_THRESHOLD_DEFAULT;
+		if (!Number.isInteger(blockFillSize) || blockFillSize < 1) {
+			throw new RangeError(`reactivity rotation: blockFillSize must be an integer >= 1, got ${blockFillSize}`);
+		}
+		if (!Number.isInteger(warmThreshold) || warmThreshold < 0 || warmThreshold >= blockFillSize) {
+			throw new RangeError(`reactivity rotation: warmThreshold must be an integer in 0..${blockFillSize - 1}, got ${warmThreshold}`);
+		}
+		this.blockFillSize = blockFillSize;
+		this.warmThreshold = warmThreshold;
+	}
+
+	/** Transactions committed into the current (not-yet-rotated) block. */
+	get transactionsInBlock(): number {
+		return this.count;
+	}
+
+	/** The fill count at which anticipatory warm-up fires (`block_fill_size − warm_threshold`). */
+	get warmAt(): number {
+		return this.blockFillSize - this.warmThreshold;
+	}
+
+	/**
+	 * Record one committed transaction and return its fill signal. Emits `warmup` exactly when the block
+	 * reaches `block_fill_size − warm_threshold`, and `filling` when it reaches `block_fill_size` — after
+	 * which the counter resets for the next block.
+	 */
+	onCommit(): BlockFillSignal {
+		this.count += 1;
+		if (this.count >= this.blockFillSize) {
+			const count = this.count;
+			this.count = 0; // a new tail block is born; start counting it
+			return { kind: "filling", count };
+		}
+		if (this.count === this.warmAt && this.warmThreshold > 0) {
+			return { kind: "warmup", count: this.count, remaining: this.blockFillSize - this.count };
+		}
+		return { kind: "none", count: this.count };
+	}
+
+	/** Reset the block counter (e.g. an externally-observed rotation the tracker did not drive). */
+	reset(): void {
+		this.count = 0;
+	}
+}
+
+// --- drain gate (old tail serves renewals/replays, bounces new subscriptions) -
+
+/** The kind of request arriving at the outgoing tail during its drain window. */
+export type DrainOp =
+	/** A *fresh* subscription (`lastKnownRev == 0` or a never-seen subscriber) — bounced to the new tree. */
+	| "new_subscribe"
+	/** A renewal of an existing registration — served through the drain. */
+	| "renew"
+	/** A replay/backfill/resume request — served through the drain. */
+	| "replay";
+
+/**
+ * A `Promoted`-shaped redirect to the rotated tree (`docs/reactivity.md` §Tail rotation step 2). Unlike the
+ * cohort-topic tier-based `Promoted`, this redirects to an entirely **new topic** — the new tail's tree at
+ * `coord_0(_, newTopicId)` — so it carries the successor's `newTailId` + derived `newTopicId`.
+ */
+export interface RotationRedirectV1 {
+	readonly v: 1;
+	readonly result: "rotated";
+	/** New tail block id the topic anchor rotated to, base64url. */
+	readonly newTailId: string;
+	/** `H(newTailId ‖ "reactivity")` — the new tree's topic id, base64url (the redirect target). */
+	readonly newTopicId: string;
+	/** Revision at which the rotation took effect. */
+	readonly effectiveAtRevision: number;
+}
+
+/**
+ * Narrow an already-parsed value to a {@link RotationRedirectV1}, throwing {@link CohortWireError} on any
+ * defect. The redirect rides the recover reply envelope as `kind: "rotated"`
+ * ({@link import("./recover.js").RecoverReplyV1}); it carries no signature — like the other recover reply
+ * variants it is an unauthenticated routing hint (the subscriber re-walks and verifies the new tree on
+ * arrival), so its trust comes from the new tree, not the redirect.
+ */
+export function validateRotationRedirectV1(value: unknown): RotationRedirectV1 {
+	const what = "RotationRedirectV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	if (obj["result"] !== "rotated") {
+		failWire(`${what}: field "result" must be "rotated"`);
+	}
+	return {
+		v: 1,
+		result: "rotated",
+		newTailId: b64urlField(reqString(obj, "newTailId", what), "newTailId", what),
+		newTopicId: b64urlField(reqString(obj, "newTopicId", what), "newTopicId", what),
+		effectiveAtRevision: reqIntInRange(obj, "effectiveAtRevision", what, 0),
+	};
+}
+
+/** The drain gate's decision for one inbound request. */
+export type DrainDecision =
+	/** Serve normally (renewals / replays during the drain window). */
+	| { readonly kind: "serve" }
+	/** Bounce to the new tree (a new subscription during the drain window). */
+	| { readonly kind: "redirect"; readonly redirect: RotationRedirectV1 }
+	/** The drain window has elapsed — the outgoing tail holds nothing; the caller re-registers from `d_max`. */
+	| { readonly kind: "drained" };
+
+/** Construction inputs for a {@link TailDrainGate}. */
+export interface TailDrainGateInit {
+	/** Unix ms the rotation took effect (drain starts here). */
+	readonly rotatedAt: number;
+	/** New tail block id the topic rotated to, base64url. */
+	readonly newTailId: string;
+	/** Revision at which the rotation took effect. */
+	readonly effectiveAtRevision: number;
+	/** Drain duration `T_drain` (ms, default {@link T_DRAIN_MS}). */
+	readonly tDrainMs?: number;
+	/** Ring hash for the `newTopicId` derivation (must match cohort-topic routing). Default db-core SHA-256. */
+	readonly hash?: IRingHash;
+}
+
+/**
+ * The outgoing tail's drain state machine. For `T_drain` after a rotation it accepts **renewals** and
+ * serves **replays**, but bounces **new subscriptions** with a {@link RotationRedirectV1} to the new tree;
+ * after `T_drain` it reports `drained` for everything (the subscriber re-registers from `d_max`).
+ */
+export class TailDrainGate {
+	readonly rotatedAt: number;
+	readonly tDrainMs: number;
+	private readonly redirect: RotationRedirectV1;
+
+	constructor(init: TailDrainGateInit) {
+		const tDrainMs = init.tDrainMs ?? T_DRAIN_MS;
+		if (!(tDrainMs > 0)) {
+			throw new RangeError(`reactivity rotation: tDrainMs must be > 0, got ${tDrainMs}`);
+		}
+		this.rotatedAt = init.rotatedAt;
+		this.tDrainMs = tDrainMs;
+		const hash = init.hash ?? createRingHash();
+		const newTopicId = bytesToB64url(reactivityTopicId(b64urlToBytes(init.newTailId), hash));
+		this.redirect = {
+			v: 1,
+			result: "rotated",
+			newTailId: init.newTailId,
+			newTopicId,
+			effectiveAtRevision: init.effectiveAtRevision,
+		};
+	}
+
+	/** Unix ms the drain window closes. */
+	get drainEndsAt(): number {
+		return this.rotatedAt + this.tDrainMs;
+	}
+
+	/** True while the outgoing tail is still draining (within `T_drain` of the rotation). */
+	isDraining(now: number): boolean {
+		return now < this.drainEndsAt;
+	}
+
+	/** The redirect this gate hands a new subscription (exposed for the redirect transport / tests). */
+	get rotationRedirect(): RotationRedirectV1 {
+		return this.redirect;
+	}
+
+	/**
+	 * Classify an inbound request. Within the drain window: `new_subscribe` → redirect, `renew`/`replay` →
+	 * serve. After the window: `drained` (the old tail has released its forwarder state).
+	 */
+	classify(op: DrainOp, now: number): DrainDecision {
+		if (!this.isDraining(now)) {
+			return { kind: "drained" };
+		}
+		return op === "new_subscribe" ? { kind: "redirect", redirect: this.redirect } : { kind: "serve" };
+	}
+}
+
+// --- jittered re-registration (subscriber moves to the new tree) -------------
+
+/** A subscriber's planned re-registration at the rotated tree. */
+export interface ReRegistrationPlan {
+	/** New tail block id (raw bytes) to attach under. */
+	readonly newTailId: Uint8Array;
+	/** `H(newTailId ‖ "reactivity")` (raw bytes) — the new tree's topic id to register at. */
+	readonly newTopicId: Uint8Array;
+	/** The subscriber's existing `lastRevision`, carried so revisions stay continuous across the rotation. */
+	readonly lastRevision: number;
+	/** Unix ms at which to fire the re-registration (jittered over `T_rejoin_jitter`). */
+	readonly fireAt: number;
+}
+
+/** Inputs shared by the single and wave re-registration planners. */
+interface ReRegistrationTarget {
+	/** The rotation hint (or any object carrying the successor `newTailId`), base64url. */
+	readonly hint: Pick<RotationHintV1, "newTailId">;
+	/** Ring hash for the `newTopicId` derivation. Default db-core SHA-256. */
+	readonly hash?: IRingHash;
+}
+
+/** Resolve `(newTailId, newTopicId)` raw bytes for a rotation target. */
+function resolveRotationTarget(target: ReRegistrationTarget): { newTailId: Uint8Array; newTopicId: Uint8Array } {
+	const newTailId = b64urlToBytes(target.hint.newTailId);
+	const newTopicId = reactivityTopicId(newTailId, target.hash ?? createRingHash());
+	return { newTailId, newTopicId };
+}
+
+/**
+ * Plan **one** subscriber's re-registration at the rotated tree: derive the new `topicId` from the hint's
+ * `newTailId`, carry the subscriber's `lastRevision`, and draw a jittered `fireAt` over `T_rejoin_jitter`
+ * via the cohort-topic {@link RejoinJitter} (`scheduleRejoin` — a uniform offset, decorrelating this
+ * subscriber's re-join from its peers).
+ */
+export function planReRegistration(opts: ReRegistrationTarget & { lastRevision: number; now: number; jitter: RejoinJitter }): ReRegistrationPlan {
+	const { newTailId, newTopicId } = resolveRotationTarget(opts);
+	return { newTailId, newTopicId, lastRevision: opts.lastRevision, fireAt: opts.jitter.scheduleRejoin(opts.now) };
+}
+
+/**
+ * Plan a **whole wave** of subscribers' re-registrations at the rotated tree. Uses the
+ * {@link RejoinJitter.scheduleWave} hard-bound staggering so any `T_rejoin_jitter`-long window holds at
+ * most the injected jitter's `capPromote` arrivals — the new tail never sees more than
+ * `capPromote / T_rejoin_jitter` re-registrations per second.
+ *
+ * **Caller contract:** rotation is governed by the *fast-promote* bound, so the host MUST build this `jitter`
+ * with `capPromote = cap_promote_fast` ({@link import("../cohort-topic/promotion.js").DEFAULT_CAP_PROMOTE_FAST}
+ * = 32), **not** the default `createRejoinJitter()` cap (the cohort-failure `cap_promote = 64`). With the
+ * default cap the wave bounds to 64/window and silently overruns the documented rotation burst ceiling
+ * (`docs/reactivity.md` §Tail rotation rotation-cost). Returns one plan per subscriber, ascending by `fireAt`.
+ */
+export function planReRegistrationWave(
+	opts: ReRegistrationTarget & { subscribers: readonly { readonly lastRevision: number }[]; now: number; jitter: RejoinJitter },
+): ReRegistrationPlan[] {
+	const { newTailId, newTopicId } = resolveRotationTarget(opts);
+	const fireAts = opts.jitter.scheduleWave(opts.subscribers.length, opts.now);
+	return opts.subscribers.map((s, i) => ({ newTailId, newTopicId, lastRevision: s.lastRevision, fireAt: fireAts[i]! }));
+}
+
+// --- buffer-to-checkpoint handoff (the only state migrated across a rotation) -
+
+/** The state migrated from the outgoing tail to the new tail on rotation. */
+export interface RotationHandoff {
+	/** The final checkpoint covering `[lastCheckpoint.toRevision + 1, rotationRevision]`. */
+	readonly checkpoint: CheckpointSummary;
+	/** The revision the rotation took effect at (the high edge the handoff checkpoint covers). */
+	readonly rotationRevision: number;
+}
+
+/**
+ * Fold the outgoing tail's replay buffer into the final {@link CheckpointSummary} handed to the new tail
+ * (`docs/reactivity.md` §Tail rotation step 5 — the **only** state migration across a rotation). The
+ * handoff covers `[lastCheckpoint.toRevision + 1, rotationRevision]`: the revisions still live in the
+ * replay ring (above the rolling checkpoint's high edge) up to the rotation revision. Returns `undefined`
+ * when the outgoing tail's ring is empty (nothing to migrate). Reuses the rolling checkpoint's own fold
+ * options so the merged digest is byte-identical to a steady-state checkpoint.
+ */
+export function buildRotationHandoffCheckpoint(state: PushState, opts: { rotationRevision?: number } = {}): RotationHandoff | undefined {
+	const ringLow = state.replayBuffer.lowRevision;
+	const ringHigh = state.replayBuffer.highRevision;
+	if (ringLow === undefined || ringHigh === undefined) {
+		return undefined; // nothing live in the ring to migrate
+	}
+	const rotationRevision = opts.rotationRevision ?? ringHigh;
+	// The handoff continues immediately above the rolling checkpoint's high edge; when no checkpoint has
+	// formed yet, that is the ring's low edge. The two windows stack, so `from` abuts `lastCheckpoint`.
+	const priorCheckpointTo = state.checkpoint.toRevision;
+	const from = priorCheckpointTo !== undefined ? priorCheckpointTo + 1 : ringLow;
+	const entries = state.replayBuffer.range(from, rotationRevision);
+	const checkpoint = buildCheckpointSummary(entries, state.checkpoint.foldOptions);
+	if (checkpoint === undefined) {
+		return undefined;
+	}
+	return { checkpoint, rotationRevision };
+}
+
+/**
+ * Land a {@link RotationHandoff} at the new tail's {@link PushState}: record the inherited checkpoint so a
+ * `ResumeV1` whose span crosses the rotation is recoverable from the new tail (the new tail "holds the old
+ * checkpoint", `docs/reactivity.md` §Tail rotation step 5). The handoff is a one-time migration — it does
+ * not feed the new tail's rolling checkpoint (that rolls from the new tree's own replay-ring eviction).
+ */
+export function applyRotationHandoff(newTailState: PushState, handoff: RotationHandoff): void {
+	newTailState.adoptRotationCheckpoint(handoff.checkpoint);
+}
+
+/** True iff `summary` covers `revision` (its inclusive `[fromRevision, toRevision]` span). */
+export function checkpointCovers(summary: CheckpointSummary, revision: number): boolean {
+	return revision >= summary.fromRevision && revision <= summary.toRevision;
+}

package/src/reactivity/subscriber.ts

@@ -0,0 +1,132 @@
+/**
+ * Reactivity — subscriber delivery path (`docs/reactivity.md` §Delivery).
+ *
+ * A subscriber receiving a notification:
+ *  1. **verifies** `sig` against the cached tail-cohort `MembershipCertV1` (the {@link NotificationVerifier}
+ *     owns the **one fetch-and-retry** on a stale cache);
+ *  2. checks `revision == lastRevision + 1`. If not, requests a backfill for the gap
+ *     `[lastRevision + 1, revision]` via the {@link requestBackfill} seam (the `BackfillV1` request shape
+ *     lands in [reactivity-backfill-resume-checkpoints]; this ticket only *detects* the gap and calls the
+ *     hook);
+ *  3. updates `lastRevision` once revisions are contiguous;
+ *  4. surfaces the notification to the application layer.
+ *
+ * Subscribers dedupe by `(collectionId, revision)`; duplicates from forwarder retries are discarded.
+ * A fresh subscription (`lastKnownRev == 0`, uninitialized) adopts the first verified notification as its
+ * baseline rather than demanding a backfill from revision 1.
+ */
+
+import type { NotificationV1 } from "./wire.js";
+import type { NotificationVerifier } from "./verify.js";
+
+/** The delivery outcome for one inbound notification. */
+export type DeliveryOutcome =
+	/** Verified and contiguous: surfaced to the application, `lastRevision` advanced. */
+	| "delivered"
+	/** `(collectionId, revision)` already delivered: discarded. */
+	| "duplicate"
+	/** Verified but ahead of `lastRevision + 1`: a backfill was requested; not yet surfaced. */
+	| "gap"
+	/** Signature did not verify (even after the one refetch): dropped. */
+	| "untrusted"
+	/** For a different collection than this subscription: ignored. */
+	| "foreign";
+
+/** Application sink + backfill seam for a {@link ReactivitySubscriber}. */
+export interface ReactivitySubscriberDeps {
+	/** Collection this subscription tracks, base64url (matches {@link NotificationV1.collectionId}). */
+	readonly collectionId: string;
+	/** Verifies inbound notifications (owns the single stale-cache refetch). */
+	readonly verifier: NotificationVerifier;
+	/** Surface a verified, contiguous notification to the application. */
+	readonly deliver: (n: NotificationV1) => void;
+	/**
+	 * Request a backfill for the inclusive revision gap `[from, to]`. The `BackfillV1` request/response
+	 * lands in [reactivity-backfill-resume-checkpoints]; the returned entries are fed back through
+	 * {@link ReactivitySubscriber.onNotification} to close the gap. Absent ⇒ the gap is recorded only.
+	 */
+	readonly requestBackfill?: (from: number, to: number) => void;
+	/** Last revision already held; `0` (default) ⇒ fresh subscribe, adopt the first notification as baseline. */
+	readonly lastKnownRev?: number;
+}
+
+/** Drives the subscriber-side verify → contiguity → deliver path for one collection. */
+export interface ReactivitySubscriber {
+	/** Last contiguously-delivered revision (`lastKnownRev` until the first delivery). */
+	readonly lastRevision: number;
+	/** Process one inbound notification; returns the {@link DeliveryOutcome}. */
+	onNotification(n: NotificationV1): Promise<DeliveryOutcome>;
+	/**
+	 * Advance the contiguity head to `revision` because a **verified parent checkpoint** summarized every
+	 * revision up to it (`docs/reactivity.md` §Parent checkpoint summaries). The subscriber then treats
+	 * `revision + 1` as the next contiguous revision, so the checkpoint's `recentEntries` replay without a
+	 * spurious gap/backfill for the digest-covered range. Only advances — never rewinds past delivered
+	 * state. The merged digest itself is applied by the application; this just moves the contiguity head.
+	 */
+	rebaseline(revision: number): void;
+}
+
+class CollectionSubscriber implements ReactivitySubscriber {
+	private last: number;
+	private initialized: boolean;
+
+	constructor(private readonly deps: ReactivitySubscriberDeps) {
+		const lastKnownRev = deps.lastKnownRev ?? 0;
+		this.last = lastKnownRev;
+		// A fresh subscribe (lastKnownRev == 0) has no baseline yet; the first verified notification sets it.
+		this.initialized = lastKnownRev > 0;
+	}
+
+	get lastRevision(): number {
+		return this.last;
+	}
+
+	rebaseline(revision: number): void {
+		// A verified checkpoint summarized everything up to `revision`; jump the head forward (never back).
+		if (!this.initialized || revision > this.last) {
+			this.last = revision;
+			this.initialized = true;
+		}
+	}
+
+	async onNotification(n: NotificationV1): Promise<DeliveryOutcome> {
+		if (n.collectionId !== this.deps.collectionId) {
+			return "foreign";
+		}
+		// Verify first (one fetch-and-retry is internal to the verifier). An untrusted notification is
+		// dropped before any (collectionId, revision) dedupe or lastRevision update.
+		const verdict = await this.deps.verifier.verify(n);
+		if (verdict !== "verified") {
+			return "untrusted";
+		}
+
+		// Fresh subscription: adopt the first verified notification as the contiguity baseline.
+		if (!this.initialized) {
+			this.initialized = true;
+			this.last = n.revision;
+			this.deps.deliver(n);
+			return "delivered";
+		}
+
+		// Dedupe by (collectionId, revision): anything at or below the contiguous head is already delivered.
+		if (n.revision <= this.last) {
+			return "duplicate";
+		}
+
+		// Contiguity check.
+		if (n.revision === this.last + 1) {
+			this.last = n.revision;
+			this.deps.deliver(n);
+			return "delivered";
+		}
+
+		// Gap: request the missing range (inclusive of `revision`); the backfilled entries re-enter here.
+		this.deps.requestBackfill?.(this.last + 1, n.revision);
+		return "gap";
+	}
+}
+
+/** Build a {@link ReactivitySubscriber} for one collection. */
+export function createReactivitySubscriber(deps: ReactivitySubscriberDeps): ReactivitySubscriber {
+	return new CollectionSubscriber(deps);
+}

package/src/reactivity/subscription.ts

@@ -0,0 +1,66 @@
+/**
+ * Reactivity — subscriber-side subscription state (`docs/reactivity.md` §Subscription).
+ *
+ * Subscribing to a collection is an **ordinary cohort-topic registration** at tier T3 with a reactivity
+ * `appPayload`: `topicId = H(currentTailId(C) ‖ "reactivity")`, the configured TTL (Edge 60 s / Core 90 s),
+ * and the cohort-topic walk-toward-root / willingness / promotion / TTL-renewal all reused unchanged.
+ * This module owns only the subscriber-side bookkeeping struct and the `appPayload` builder; the db-p2p
+ * subscription manager drives the cohort-topic `RegisterV1`.
+ *
+ * `tailIdAtAttach` is the subscriber-side detector for tail rotation (the whole-tree migration the
+ * rotation ticket handles); `cohortEpoch` detects membership drift within the topic.
+ */
+
+import { encodeSubscribeAppPayload, type SubscribeAppPayloadV1 } from "./wire.js";
+
+/** Subscriber-side live state for one active subscription (`docs/reactivity.md` §Subscriber-side state). */
+export interface ActiveSubscription {
+	/** Stable collection identity. */
+	readonly collectionId: Uint8Array;
+	/** Current tail-anchored topic id. */
+	readonly topicId: Uint8Array;
+	/** Tail block id at registration time — detects tail rotation. */
+	readonly tailIdAtAttach: Uint8Array;
+	/** Serving cohort member. */
+	primary: Uint8Array;
+	/** Warm-failover cohort members. */
+	backups: Uint8Array[];
+	/** Cohort member hint set for fast re-attach. */
+	cohortHint: Uint8Array[];
+	/** Cohort epoch for membership-drift detection. */
+	cohortEpoch: Uint8Array;
+	/** Last contiguously-delivered revision. */
+	lastRevision: number;
+	/** Unix ms of the last delivery. */
+	lastDeliveredAt: number;
+	/** Unix ms the subscription attached. */
+	attachedAt: number;
+}
+
+/** Parameters for building a subscribe `appPayload`. */
+export interface SubscribeParams {
+	/** Collection id, base64url. */
+	readonly collectionId: string;
+	/** Tail block id at attach time, base64url. */
+	readonly tailIdAtAttach: string;
+	/** Last revision already held; `0` for a fresh subscribe. */
+	readonly lastKnownRev?: number;
+	/** Max delta bytes accepted; `0` declines deltas (Edge). */
+	readonly deltaMaxBytes: number;
+}
+
+/** Build the validated {@link SubscribeAppPayloadV1} for a subscription. */
+export function buildSubscribeAppPayload(params: SubscribeParams): SubscribeAppPayloadV1 {
+	return {
+		kind: "reactivity",
+		collectionId: params.collectionId,
+		tailIdAtAttach: params.tailIdAtAttach,
+		lastKnownRev: params.lastKnownRev ?? 0,
+		deltaMaxBytes: params.deltaMaxBytes,
+	};
+}
+
+/** Build the opaque `RegisterV1.appPayload` bytes for a subscription. */
+export function subscribeAppPayloadBytes(params: SubscribeParams): Uint8Array {
+	return encodeSubscribeAppPayload(buildSubscribeAppPayload(params));
+}