@optimystic/db-core 0.13.5 → 0.14.0

package/dist/src/reactivity/rotation.d.ts

@@ -0,0 +1,283 @@
+/**
+ * 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 type { IRingHash } from "../cohort-topic/ports.js";
+import type { RejoinJitter } from "../cohort-topic/antiflood/jitter.js";
+import { type CheckpointSummary } from "./checkpoint.js";
+import type { PushState } from "./push-state.js";
+import type { NotificationV1, RotationHintV1 } from "./wire.js";
+/**
+ * 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 declare function buildRotationHint(newTailId: string, fillingRevision: number): RotationHintV1;
+/** 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 declare function detectRotation(tailIdAtAttach: string, n: Pick<NotificationV1, "tailId" | "rotationHint">): RotationDetection;
+/** 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 declare class BlockFillTracker {
+    readonly blockFillSize: number;
+    readonly warmThreshold: number;
+    private count;
+    constructor(init?: BlockFillTrackerInit);
+    /** Transactions committed into the current (not-yet-rotated) block. */
+    get transactionsInBlock(): number;
+    /** The fill count at which anticipatory warm-up fires (`block_fill_size − warm_threshold`). */
+    get warmAt(): number;
+    /**
+     * 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;
+    /** Reset the block counter (e.g. an externally-observed rotation the tracker did not drive). */
+    reset(): void;
+}
+/** 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 declare function validateRotationRedirectV1(value: unknown): RotationRedirectV1;
+/** 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 declare class TailDrainGate {
+    readonly rotatedAt: number;
+    readonly tDrainMs: number;
+    private readonly redirect;
+    constructor(init: TailDrainGateInit);
+    /** Unix ms the drain window closes. */
+    get drainEndsAt(): number;
+    /** True while the outgoing tail is still draining (within `T_drain` of the rotation). */
+    isDraining(now: number): boolean;
+    /** The redirect this gate hands a new subscription (exposed for the redirect transport / tests). */
+    get rotationRedirect(): RotationRedirectV1;
+    /**
+     * 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;
+}
+/** 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;
+}
+/**
+ * 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 declare function planReRegistration(opts: ReRegistrationTarget & {
+    lastRevision: number;
+    now: number;
+    jitter: RejoinJitter;
+}): ReRegistrationPlan;
+/**
+ * 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 declare function planReRegistrationWave(opts: ReRegistrationTarget & {
+    subscribers: readonly {
+        readonly lastRevision: number;
+    }[];
+    now: number;
+    jitter: RejoinJitter;
+}): ReRegistrationPlan[];
+/** 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 declare function buildRotationHandoffCheckpoint(state: PushState, opts?: {
+    rotationRevision?: number;
+}): RotationHandoff | undefined;
+/**
+ * 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 declare function applyRotationHandoff(newTailState: PushState, handoff: RotationHandoff): void;
+/** True iff `summary` covers `revision` (its inclusive `[fromRevision, toRevision]` span). */
+export declare function checkpointCovers(summary: CheckpointSummary, revision: number): boolean;
+export {};
+//# sourceMappingURL=rotation.d.ts.map

package/dist/src/reactivity/rotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.d.ts","sourceRoot":"","sources":["../../../src/reactivity/rotation.ts"],"names":[],"mappings":"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"}

package/dist/src/reactivity/rotation.js

@@ -0,0 +1,265 @@
+/**
+ * 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 { BLOCK_FILL_SIZE_DEFAULT, T_DRAIN_MS, WARM_THRESHOLD_DEFAULT } from "./config.js";
+import { buildCheckpointSummary } from "./checkpoint.js";
+import { reactivityTopicId } from "./topic-anchor.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, fillingRevision) {
+    return { newTailId, effectiveAtRevision: fillingRevision + 1 };
+}
+/**
+ * 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, n) {
+    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 };
+}
+/**
+ * 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 {
+    blockFillSize;
+    warmThreshold;
+    count = 0;
+    constructor(init = {}) {
+        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() {
+        return this.count;
+    }
+    /** The fill count at which anticipatory warm-up fires (`block_fill_size − warm_threshold`). */
+    get warmAt() {
+        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() {
+        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() {
+        this.count = 0;
+    }
+}
+/**
+ * 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) {
+    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 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 {
+    rotatedAt;
+    tDrainMs;
+    redirect;
+    constructor(init) {
+        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() {
+        return this.rotatedAt + this.tDrainMs;
+    }
+    /** True while the outgoing tail is still draining (within `T_drain` of the rotation). */
+    isDraining(now) {
+        return now < this.drainEndsAt;
+    }
+    /** The redirect this gate hands a new subscription (exposed for the redirect transport / tests). */
+    get rotationRedirect() {
+        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, now) {
+        if (!this.isDraining(now)) {
+            return { kind: "drained" };
+        }
+        return op === "new_subscribe" ? { kind: "redirect", redirect: this.redirect } : { kind: "serve" };
+    }
+}
+/** Resolve `(newTailId, newTopicId)` raw bytes for a rotation target. */
+function resolveRotationTarget(target) {
+    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) {
+    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) {
+    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] }));
+}
+/**
+ * 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, opts = {}) {
+    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, handoff) {
+    newTailState.adoptRotationCheckpoint(handoff.checkpoint);
+}
+/** True iff `summary` covers `revision` (its inclusive `[fromRevision, toRevision]` span). */
+export function checkpointCovers(summary, revision) {
+    return revision >= summary.fromRevision && revision <= summary.toRevision;
+}
+//# sourceMappingURL=rotation.js.map

package/dist/src/reactivity/rotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.js","sourceRoot":"","sources":["../../../src/reactivity/rotation.ts"],"names":[],"mappings":"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"}

package/dist/src/reactivity/subscriber.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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;
+}
+/** Build a {@link ReactivitySubscriber} for one collection. */
+export declare function createReactivitySubscriber(deps: ReactivitySubscriberDeps): ReactivitySubscriber;
+//# sourceMappingURL=subscriber.d.ts.map

package/dist/src/reactivity/subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber.d.ts","sourceRoot":"","sources":["../../../src/reactivity/subscriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,yDAAyD;AACzD,MAAM,MAAM,eAAe;AAC1B,qFAAqF;AACnF,WAAW;AACb,+DAA+D;GAC7D,WAAW;AACb,4FAA4F;GAC1F,KAAK;AACP,sEAAsE;GACpE,WAAW;AACb,kEAAkE;GAChE,SAAS,CAAC;AAEb,2EAA2E;AAC3E,MAAM,WAAW,wBAAwB;IACxC,oGAAoG;IACpG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9D,6GAA6G;IAC7G,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wFAAwF;AACxF,MAAM,WAAW,oBAAoB;IACpC,sFAAsF;IACtF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,cAAc,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5D;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AA8DD,+DAA+D;AAC/D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAE/F"}