@optimystic/db-core 0.13.4 → 0.14.0

package/src/reactivity/forwarder.ts

@@ -0,0 +1,87 @@
+/**
+ * Reactivity — forwarder receive path (`docs/reactivity.md` §Propagation).
+ *
+ * A receiving forwarder primary, for each inbound notification:
+ *  1. **verifies** the threshold signature against the tail cohort's `MembershipCertV1`;
+ *  2. runs the **dedupe** check (sliding `(revision, sigDigest)` window);
+ *  3. **appends** to the replay buffer;
+ *  4. **forwards the unmodified notification** to its own direct subscribers and child cohorts.
+ *
+ * This module owns steps 1–3 and the forward *decision* (step 4's transport — dialing each subscriber's
+ * primary and each child cohort — is the db-p2p binding). Forwarders never re-sign: a compromised
+ * forwarder can drop or delay, but cannot forge. An unverifiable notification is dropped **before**
+ * touching the dedupe set or buffer, so a forged payload can neither poison dedupe nor occupy a ring
+ * slot. The buffer + dedupe set are gossiped across the cohort by the host's gossip cadence (see
+ * {@link PushState}), so any member can serve a replay.
+ */
+
+import { dedupeKey, sigDigest } from "./notification.js";
+import type { PushState } from "./push-state.js";
+import type { NotificationV1 } from "./wire.js";
+import type { NotificationVerifier } from "./verify.js";
+import type { IRingHash } from "../cohort-topic/ports.js";
+
+/** The forwarder's decision for one inbound notification. */
+export type ForwardDecision =
+	/** Verified, fresh: append to buffer and fan out unmodified. */
+	| "forward"
+	/** Already in the dedupe set: drop silently (an honest retransmit or merge duplicate). */
+	| "duplicate"
+	/** Signature did not verify against the tail cohort: drop without buffering. */
+	| "untrusted";
+
+/** Drives the forwarder receive path over one collection's {@link PushState}. */
+export interface ReactivityForwarder {
+	/** The per-collection push state this forwarder serves. */
+	readonly state: PushState;
+	/**
+	 * Run verify → dedupe → append for one inbound notification, returning the forward decision. The
+	 * caller fans the *unmodified* notification out only on `"forward"`.
+	 */
+	receive(n: NotificationV1, now: number): Promise<ForwardDecision>;
+}
+
+/** Construction inputs for a {@link ReactivityForwarder}. */
+export interface ReactivityForwarderDeps {
+	readonly state: PushState;
+	readonly verifier: NotificationVerifier;
+	/** Ring hash for the `sigDigest` dedupe key (must match the verifier's). Default db-core SHA-256. */
+	readonly hash?: IRingHash;
+}
+
+class PushStateForwarder implements ReactivityForwarder {
+	readonly state: PushState;
+
+	constructor(private readonly deps: ReactivityForwarderDeps) {
+		this.state = deps.state;
+	}
+
+	async receive(n: NotificationV1, now: number): Promise<ForwardDecision> {
+		// 1. Verify end-to-end before any state mutation — a forged notification touches nothing.
+		const verdict = await this.deps.verifier.verify(n);
+		if (verdict !== "verified") {
+			return "untrusted";
+		}
+		// 2. Dedupe on `(revision, sigDigest)`. Already-seen → drop silently.
+		const digest = sigDigest(n.sig, this.deps.hash);
+		if (this.state.dedupe.observe(n.revision, digest) === "duplicate") {
+			return "duplicate";
+		}
+		// 3. Append the full signed notification to the replay ring (gossiped across the cohort).
+		this.state.replayBuffer.append({ revision: n.revision, payload: n, receivedAt: now });
+		if (n.revision > this.state.lastRevision) {
+			this.state.lastRevision = n.revision;
+		}
+		return "forward";
+	}
+}
+
+/** Build a {@link ReactivityForwarder} over a collection's {@link PushState} and a verifier. */
+export function createReactivityForwarder(deps: ReactivityForwarderDeps): ReactivityForwarder {
+	return new PushStateForwarder(deps);
+}
+
+/** The dedupe key a forwarder would compute for a notification (exposed for tests/diagnostics). */
+export function notificationDedupeKey(n: NotificationV1, hash?: IRingHash): string {
+	return dedupeKey(n.revision, n.sig, hash);
+}

package/src/reactivity/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Reactivity — push-based change notifications on the cohort-topic substrate.
+ *
+ * See `docs/reactivity.md`. This module lands the reactivity hot path — the rotating tail-anchored topic,
+ * the subscribe `appPayload`, notification origination (reusing the commit cert unchanged), the forwarder
+ * receive path (verify → dedupe → buffer → forward), the `W`-entry replay ring with cohort gossip, the
+ * sliding `(revision, sigDigest)` dedupe window, and subscriber-side verify/deliver with gap detection
+ * ([reactivity-origination-replay-delivery]) — plus **recovery beyond the live stream**
+ * ([reactivity-backfill-resume-checkpoints]): the {@link ./backfill.js} RPC served from the replay ring,
+ * the rolling parent {@link ./checkpoint.js} stacked below it, and the four-variant {@link ./resume.js}
+ * protocol for mobile wake — plus **tail rotation, slow-subscriber backpressure, and Edge/Core policy**
+ * ([reactivity-rotation-backpressure-policy]): the {@link ./rotation.js} lifecycle (pre-announce, drain,
+ * jittered re-registration, buffer-to-checkpoint handoff, warm-up), the per-subscriber drop-oldest
+ * {@link ./backpressure.js}, and the {@link ./policy.js} Edge-subscriber-only / `delta_max` gate.
+ */
+
+export * from "./config.js";
+export * from "./topic-anchor.js";
+export * from "./wire.js";
+export * from "./notification.js";
+export * from "./dedupe.js";
+export * from "./replay-buffer.js";
+export * from "./checkpoint.js";
+export * from "./backpressure.js";
+export * from "./push-state.js";
+export * from "./verify.js";
+export * from "./forwarder.js";
+export * from "./subscriber.js";
+export * from "./subscription.js";
+export * from "./backfill.js";
+export * from "./resume.js";
+export * from "./recover.js";
+export * from "./rotation.js";
+export * from "./policy.js";

package/src/reactivity/notification.ts

@@ -0,0 +1,123 @@
+/**
+ * Reactivity — notification origination (`docs/reactivity.md` §Notification origination).
+ *
+ * The tail cohort's primary for a collection is, by construction, the transaction-layer tail-cluster:
+ * the cohort-topic primary at `coord_0(_, topicId)` where `topicId = H(tailId ‖ "reactivity")`. As soon
+ * as the commit's threshold signature is assembled, it emits a {@link NotificationV1} whose `sig` is
+ * **bit-for-bit** the commit certificate's threshold signature — reactivity never re-signs.
+ *
+ * This module is the pure assembler. The local-change-notifier bridge ([local-change-notifier-bridge])
+ * supplies the {@link CollectionChangeEvent} and the pass-through {@link CommitCert}; db-p2p's
+ * origination manager calls {@link buildNotificationV1} with those plus the per-emission context
+ * (`tailId`, `timestamp`, the per-collection `deltaMaxBytes`) and fans the result out. Crypto-free: it
+ * copies `commitCert.thresholdSig` and `commitCert.signers` through unchanged.
+ */
+
+import { createRingHash } from "../cohort-topic/ring-hash.js";
+import { bytesToB64url } from "../cohort-topic/wire/codec.js";
+import type { IRingHash } from "../cohort-topic/ports.js";
+import type { CollectionChangeEvent, CommitCert } from "../transactor/change-notifier.js";
+import type { NotificationV1, RotationHintV1 } from "./wire.js";
+
+const utf8 = new TextEncoder();
+
+/** Per-emission context the origination point supplies alongside the bridge's event + cert. */
+export interface OriginationContext {
+	/** Current tail block id (base64url) the reactivity topic is anchored on. */
+	readonly tailId: string;
+	/** Emission timestamp (unix ms). */
+	readonly timestamp: number;
+	/**
+	 * Per-collection delta budget (bytes). `0` ⇒ omit `delta` entirely (Edge profile, or a collection
+	 * that declines deltas). Origination MUST respect a `deltaMaxBytes` of `0` by omitting the field.
+	 */
+	readonly deltaMaxBytes: number;
+	/** Optional bounded delta (raw bytes); included only when within `deltaMaxBytes` and `> 0`. */
+	readonly delta?: Uint8Array;
+	/** Tail-rotation pre-announce to embed (rotation ticket supplies it). */
+	readonly rotationHint?: RotationHintV1;
+	/**
+	 * Map a {@link CommitCert} signer (the cluster's peer-id string keying its commit vote) to the
+	 * base64url cohort member-id bytes the subscriber's membership verifier compares against. Default:
+	 * identity (the signer is already base64url) — db-p2p supplies `s ⇒ bytesToB64url(peerIdToBytes(s))`.
+	 */
+	readonly encodeSigner?: (signer: string) => string;
+}
+
+/**
+ * Assemble the {@link NotificationV1} for one committed change, reusing the commit cert's threshold
+ * signature unchanged.
+ *
+ * `digest` carries the commit-vote **signed payload** the threshold signature was computed over —
+ * `commitCert.signedPayload`, the cluster's per-member `utf8(commitHash + ":approve")` byte image,
+ * identical across all approving signers. Because the verifier recomputes the cohort threshold check over
+ * exactly these bytes (`payload = b64urlToBytes(n.digest)`), a subscriber's **real** Ed25519
+ * threshold-verify over `digest` reproduces the signed image and succeeds — the cluster↔reactivity
+ * integration seam is **closed** (no pass-crypto stub required). The hint-only contract still holds for
+ * the optional `delta`: deltas are advisory; the digest + threshold signature are the authoritative proof.
+ */
+export function buildNotificationV1(event: CollectionChangeEvent, commitCert: CommitCert, ctx: OriginationContext): NotificationV1 {
+	const encodeSigner = ctx.encodeSigner ?? ((s: string): string => s);
+	const notification: NotificationV1 = {
+		v: 1,
+		collectionId: event.collectionId,
+		tailId: ctx.tailId,
+		revision: event.rev,
+		digest: bytesToB64url(commitCert.signedPayload),
+		timestamp: ctx.timestamp,
+		sig: bytesToB64url(commitCert.thresholdSig),
+		signers: commitCert.signers.map(encodeSigner),
+	};
+	if (ctx.deltaMaxBytes > 0 && ctx.delta !== undefined && ctx.delta.length <= ctx.deltaMaxBytes) {
+		notification.delta = bytesToB64url(ctx.delta);
+	}
+	if (ctx.rotationHint !== undefined) {
+		notification.rotationHint = ctx.rotationHint;
+	}
+	// An invalidation change event carries a typed marker the subscriber uses to distinguish a reversal
+	// from an ordinary commit (drop derived results + resubmit, vs. refresh). It rides the same path and
+	// reuses the invalidation's commit cert as `sig` — see {@link CollectionChangeEvent.invalidation}.
+	if (event.invalidation) {
+		notification.invalidation = true;
+		if (event.invalidatedActionId !== undefined) {
+			notification.invalidatedActionId = event.invalidatedActionId;
+		}
+	}
+	return notification;
+}
+
+/**
+ * Compact, stable digest of a notification's signature for the dedupe key `(revision, sigDigest)`
+ * (`docs/reactivity.md` §Per-revision dedupe). Hashing the signature bytes keeps the key bounded and
+ * distinguishes two distinct threshold sigs that legitimately share a revision during partition merge.
+ */
+export function sigDigest(sig: string, hash: IRingHash = createRingHash()): string {
+	return bytesToB64url(hash.H(utf8.encode(sig)));
+}
+
+/** The dedupe-set key for a notification: `${revision}:${sigDigest(sig)}`. */
+export function dedupeKey(revision: number, sig: string, hash?: IRingHash): string {
+	return `${revision}:${sigDigest(sig, hash)}`;
+}
+
+/**
+ * Collapse a batch of inbound notifications to the distinct **invalidated action ids** a client must act
+ * on, in first-seen order. A single dispute can fan out several invalidation notifications — one per
+ * cascade child (`docs/right-is-right.md` §Read-Dependency Cascade) — and a client holding dependents of
+ * several may receive several; coalescing by `invalidatedActionId` lets it drop + resubmit each affected
+ * unit exactly once instead of once per notification. Notifications that are not invalidations (ordinary
+ * commits) and invalidations missing an `invalidatedActionId` are ignored here — the former drive a plain
+ * refresh, the latter still surface the reverted state on the next authoritative read. A hint-layer helper:
+ * the client still verifies against committed state.
+ */
+export function coalesceInvalidatedActionIds(notifications: Iterable<NotificationV1>): string[] {
+	const seen = new Set<string>();
+	const ordered: string[] = [];
+	for (const n of notifications) {
+		if (n.invalidation && n.invalidatedActionId !== undefined && !seen.has(n.invalidatedActionId)) {
+			seen.add(n.invalidatedActionId);
+			ordered.push(n.invalidatedActionId);
+		}
+	}
+	return ordered;
+}

package/src/reactivity/policy.ts

@@ -0,0 +1,79 @@
+/**
+ * Reactivity — per-cohort Edge/Core policy (`docs/reactivity.md` §Per-cohort policy).
+ *
+ * Reactivity is **T3 (luxury)** at the cohort-topic layer. Two consequences are enforced here, the
+ * authoritative home for the reactivity producer-side policy:
+ *
+ *  1. **Edge nodes never serve as reactivity forwarders** — only as subscribers. A T3 *consumer* is fine
+ *     on Edge (a phone wants notifications); a T3 *producer* is off in the Edge profile. The willingness
+ *     check ({@link import("../cohort-topic/willingness.js")}) already declines T3 admission on an Edge
+ *     node because `edgeProfile().willingTiers` excludes {@link Tier.T3}; this module adds the *reactivity*
+ *     gate at the point a node decides whether to instantiate a {@link PushState} / become a forwarder, so
+ *     the decision is explicit and testable rather than implicit in cohort admission.
+ *  2. **`delta_max` is Edge 0 / Core 4096** — the authoritative plumbing the origination ticket only
+ *     *consumed*. Re-exported here from {@link import("./config.js")} so the policy surface is singular.
+ *
+ * The per-cohort topic budget (`topics_max`) bounds the collections a cohort serves; reactivity needs no
+ * admission policy beyond the cohort-topic default, so it is not re-implemented here.
+ */
+
+import { Tier, type NodeProfile } from "../cohort-topic/tiers.js";
+import { deltaMaxForProfile } from "./config.js";
+import { PushState, type PushStateInit } from "./push-state.js";
+
+/**
+ * Whether a node with `profile` may serve as a reactivity **forwarder** (T3 producer). `true` only when
+ * the profile is willing to forward T3 — Core by default, an operator-narrowable Core, never Edge.
+ * Equivalent to `profile.willingTiers.has(Tier.T3)`: Edge's willing set is `{T0, T1}`, so this is `false`
+ * on every Edge node and on a Core node an operator has restricted away from T3.
+ */
+export function mayServeAsReactivityForwarder(profile: NodeProfile): boolean {
+	return profile.willingTiers.has(Tier.T3);
+}
+
+/** A subscriber-only node (Edge, or a Core narrowed off T3) attempted to instantiate a reactivity forwarder. */
+export class ReactivityForwarderForbiddenError extends Error {
+	constructor(readonly profileKind: NodeProfile["kind"]) {
+		super(`reactivity: a ${profileKind} node that does not forward T3 cannot instantiate a forwarder (subscriber-only)`);
+		this.name = "ReactivityForwarderForbiddenError";
+	}
+}
+
+/**
+ * Instantiate a forwarder {@link PushState} **only if** `profile` may forward T3. Returns `undefined` for a
+ * subscriber-only node (Edge, or a Core narrowed off T3) — the caller does not become a forwarder, leaving
+ * it a pure subscriber. This is the explicit gate the §Per-cohort policy "Edge nodes never serve as
+ * reactivity forwarders" rule names; a node consults it before allocating any per-collection push state.
+ */
+export function instantiateForwarderPushState(profile: NodeProfile, init: PushStateInit): PushState | undefined {
+	return mayServeAsReactivityForwarder(profile) ? new PushState(init) : undefined;
+}
+
+/**
+ * Like {@link instantiateForwarderPushState} but **throws** {@link ReactivityForwarderForbiddenError} on a
+ * subscriber-only node, for call sites that treat an Edge forwarder attempt as a programming error rather
+ * than a silent no-op (e.g. a host wiring that should never route forwarder duty to an Edge node).
+ */
+export function requireForwarderPushState(profile: NodeProfile, init: PushStateInit): PushState {
+	if (!mayServeAsReactivityForwarder(profile)) {
+		throw new ReactivityForwarderForbiddenError(profile.kind);
+	}
+	return new PushState(init);
+}
+
+/**
+ * The effective reactivity producer policy for a node profile: whether it may forward, and its `delta_max`
+ * budget (Edge 0 — reject inbound `delta`, re-read the chain; Core 4096). The single struct a host reads to
+ * configure reactivity on a node (`docs/reactivity.md` §Per-cohort policy, §Delta payloads).
+ */
+export interface ReactivityNodePolicy {
+	/** Whether this node may instantiate a forwarder / become a T3 producer. */
+	readonly mayForward: boolean;
+	/** `delta_max` (bytes): Core 4096, Edge 0 (declines deltas). */
+	readonly deltaMaxBytes: number;
+}
+
+/** Resolve the {@link ReactivityNodePolicy} for a profile (forwarder eligibility + `delta_max`). */
+export function reactivityNodePolicy(profile: NodeProfile): ReactivityNodePolicy {
+	return { mayForward: mayServeAsReactivityForwarder(profile), deltaMaxBytes: deltaMaxForProfile(profile) };
+}

package/src/reactivity/push-state.ts

@@ -0,0 +1,343 @@
+/**
+ * Reactivity — forwarder-cohort `PushState` and its intra-cohort gossip codec
+ * (`docs/reactivity.md` §Forwarder-cohort state, §Replay window).
+ *
+ * A reactivity forwarder cohort holds the cohort-topic registration records (the direct-subscriber
+ * list **is** the `RegistrationRecord` set with `appPayload.kind == "reactivity"` — reactivity reads it,
+ * it does not duplicate it) plus this per-collection {@link PushState}: topic identity, parent/child
+ * cohort refs, the {@link ReplayBuffer} ring, the {@link DedupeWindow}, and `lastRevision`.
+ *
+ * `PushState` is gossiped within the cohort (over the cohort-topic gossip channel) so any member can
+ * serve a backfill/replay if the primary is unavailable. This module defines the **full** struct and its
+ * gossip codec so all three reactivity tickets share one definition. The rolling parent {@link checkpoint}
+ * (and its derived {@link parentCheckpoint} summary) is fed by replay-ring eviction
+ * ([reactivity-backfill-resume-checkpoints]); the `perSubscriberQueue` field carries the primary-local
+ * per-subscriber {@link SubscriberBackpressure} ([reactivity-rotation-backpressure-policy]). The
+ * backpressure map is **primary-local fan-out state, never gossiped** — it is absent from
+ * {@link PushStateGossipV1}; a handoff rebuilds it empty and the replay buffer covers the gap.
+ */
+
+import { bytesToB64url, b64urlToBytes, decodeCohortMessage, encodeCohortMessage, DEFAULT_MAX_MESSAGE_BYTES } from "../cohort-topic/wire/codec.js";
+import { CohortWireError } from "../cohort-topic/wire/validate.js";
+import { DEDUPE_WINDOW_DEFAULT, QUEUE_MAX_DEFAULT, W_DEFAULT } from "./config.js";
+import { createSubscriberBackpressure, type SubscriberBackpressure, type SubscriberEnqueueResult } from "./backpressure.js";
+import { RollingCheckpoint, type CheckpointSummary, type DeltaCoalesce, type DigestFold } from "./checkpoint.js";
+import { createDedupeWindow, type DedupeStateV1, type DedupeWindow } from "./dedupe.js";
+import { createReplayBuffer, type ReplayBuffer, type ReplayBufferStateV1, type RevisionEntry } from "./replay-buffer.js";
+import { validateNotificationV1, type NotificationV1 } from "./wire.js";
+
+/** A reference to a parent/child cohort in the reactivity tree (`tier-(d∓1)`). */
+export interface CohortRef {
+	/** The cohort's served ring coordinate, base64url. */
+	readonly coord: string;
+	/** The cohort's primary member id, base64url (when known). */
+	readonly primary?: string;
+}
+
+/** Construction inputs for a {@link PushState}. */
+export interface PushStateInit {
+	/** Collection id, base64url. */
+	readonly collectionId: string;
+	/** Reactivity topic id, base64url. */
+	readonly topicId: string;
+	/** Tail block id when this cohort joined the topic, base64url. */
+	readonly tailIdAtJoin: string;
+	/** Tier-`(d−1)` parent cohort (absent at the tail/root). */
+	readonly parentCohort?: CohortRef;
+	/** Tier-`(d+1)` child cohorts. */
+	readonly childCohorts?: CohortRef[];
+	/** Replay buffer depth `W` (default {@link W_DEFAULT}). */
+	readonly w?: number;
+	/** Dedupe-window span (default {@link DEDUPE_WINDOW_DEFAULT}). */
+	readonly dedupeWindow?: number;
+	/** Parent-checkpoint span `W_checkpoint` (default {@link import("./config.js").W_CHECKPOINT_DEFAULT}). */
+	readonly wCheckpoint?: number;
+	/** Per-subscriber bounded-queue depth `queue_max` (default {@link QUEUE_MAX_DEFAULT}). */
+	readonly queueMax?: number;
+	/** `delta_max` for the checkpoint's coalesced `mergedDelta`; `0` (default) ⇒ never emit a delta. */
+	readonly deltaMaxBytes?: number;
+	/** `mergedDigest` fold override (default: deterministic running hash over per-revision commit digests). */
+	readonly checkpointFold?: DigestFold;
+	/** `mergedDelta` coalescer override (default: ordered concatenation). */
+	readonly coalesceDeltas?: DeltaCoalesce;
+}
+
+/** The cohort-gossiped wire image of a {@link PushState}. */
+export interface PushStateGossipV1 {
+	v: 1;
+	collectionId: string;
+	topicId: string;
+	tailIdAtJoin: string;
+	parentCohort?: CohortRef;
+	childCohorts: CohortRef[];
+	lastRevision: number;
+	replayBuffer: ReplayBufferStateV1;
+	dedupe: DedupeStateV1;
+}
+
+/**
+ * Per-collection forwarder-cohort state. Owns the live {@link ReplayBuffer} and {@link DedupeWindow}
+ * components and the scalar identity/revision state; the reserved sibling-ticket fields hang off it.
+ */
+export class PushState {
+	readonly collectionId: string;
+	readonly topicId: string;
+	tailIdAtJoin: string;
+	parentCohort?: CohortRef;
+	childCohorts: CohortRef[];
+	readonly replayBuffer: ReplayBuffer;
+	readonly dedupe: DedupeWindow;
+	lastRevision: number;
+
+	/**
+	 * The rolling parent checkpoint ([reactivity-backfill-resume-checkpoints], `docs/reactivity.md`
+	 * §Parent checkpoint summaries). Fed by replay-ring eviction — as revisions retire from the `W`-deep
+	 * ring they roll into this `W_checkpoint`-span summary sitting immediately below the ring, so a resume
+	 * recovers `W + W_checkpoint` revisions in one round trip (the stacked-window semantics).
+	 */
+	readonly checkpoint: RollingCheckpoint;
+	/**
+	 * The forwarder primary's per-subscriber drop-oldest backpressure map
+	 * ([reactivity-rotation-backpressure-policy], `docs/reactivity.md` §Slow-subscriber backpressure).
+	 * Primary-local fan-out state — **not** gossiped, so it is absent from {@link PushStateGossipV1}.
+	 */
+	readonly perSubscriberQueue: SubscriberBackpressure;
+	/**
+	 * The checkpoint migrated from the **outgoing** tail when this cohort became the new tail across a
+	 * rotation ([reactivity-rotation-backpressure-policy], `docs/reactivity.md` §Tail rotation step 5). The
+	 * new tail "holds the old checkpoint" so a `ResumeV1` whose span crosses the rotation is recoverable;
+	 * `undefined` until a handoff lands via {@link adoptRotationCheckpoint}. Distinct from the live rolling
+	 * {@link checkpoint}, which rolls from this cohort's *own* replay-ring eviction.
+	 */
+	private inherited?: CheckpointSummary;
+
+	constructor(init: PushStateInit) {
+		this.collectionId = init.collectionId;
+		this.topicId = init.topicId;
+		this.tailIdAtJoin = init.tailIdAtJoin;
+		this.parentCohort = init.parentCohort;
+		this.childCohorts = init.childCohorts ?? [];
+		this.checkpoint = new RollingCheckpoint({
+			collectionId: init.collectionId,
+			span: init.wCheckpoint,
+			deltaMaxBytes: init.deltaMaxBytes,
+			fold: init.checkpointFold,
+			coalesceDeltas: init.coalesceDeltas,
+		});
+		// Wire the ring's low-edge eviction into the rolling checkpoint: a revision leaving the replay
+		// window is exactly a revision that should roll into the parent-checkpoint summary.
+		this.replayBuffer = createReplayBuffer(init.w ?? W_DEFAULT, (evicted) => this.checkpoint.retire(evicted));
+		this.dedupe = createDedupeWindow(init.dedupeWindow ?? DEDUPE_WINDOW_DEFAULT);
+		this.perSubscriberQueue = createSubscriberBackpressure(init.queueMax ?? QUEUE_MAX_DEFAULT);
+		this.lastRevision = -1;
+	}
+
+	/**
+	 * Fan one notification onto each subscriber's bounded queue (the primary's per-subscriber backpressure,
+	 * `docs/reactivity.md` §Slow-subscriber backpressure). Returns only the subscribers whose queue dropped
+	 * its oldest under pressure — a slow subscriber's drop never stalls fan-out to the rest of the cohort.
+	 */
+	enqueueForSubscribers(subscriberIds: Iterable<string>, n: NotificationV1): SubscriberEnqueueResult[] {
+		return this.perSubscriberQueue.fanOut(subscriberIds, n);
+	}
+
+	/** The checkpoint inherited from the outgoing tail on rotation, or `undefined` until a handoff lands. */
+	get inheritedCheckpoint(): CheckpointSummary | undefined {
+		return this.inherited;
+	}
+
+	/**
+	 * Land an outgoing tail's rotation handoff checkpoint on this (new tail) cohort
+	 * (`docs/reactivity.md` §Tail rotation step 5). Idempotent: a later handoff replaces only if it covers a
+	 * higher revision, so a re-delivered or older handoff never rewinds the inherited span.
+	 */
+	adoptRotationCheckpoint(summary: CheckpointSummary): void {
+		if (this.inherited === undefined || summary.toRevision > this.inherited.toRevision) {
+			this.inherited = summary;
+		}
+	}
+
+	/**
+	 * The current parent-checkpoint summary, or `undefined` until revisions have retired from the replay
+	 * ring (`docs/reactivity.md` §Parent checkpoint summaries). Re-derived from the live rolling checkpoint
+	 * on each read so it always reflects the latest retired range.
+	 */
+	get parentCheckpoint(): CheckpointSummary | undefined {
+		return this.checkpoint.summary();
+	}
+
+	/** Snapshot the gossipable slice for cohort replication. */
+	serializeGossip(): PushStateGossipV1 {
+		const out: PushStateGossipV1 = {
+			v: 1,
+			collectionId: this.collectionId,
+			topicId: this.topicId,
+			tailIdAtJoin: this.tailIdAtJoin,
+			childCohorts: this.childCohorts,
+			lastRevision: this.lastRevision,
+			replayBuffer: this.replayBuffer.serialize(),
+			dedupe: this.dedupe.serialize(),
+		};
+		if (this.parentCohort !== undefined) {
+			out.parentCohort = this.parentCohort;
+		}
+		return out;
+	}
+
+	/** Merge a peer member's gossiped state so the whole cohort converges (any member can then serve). */
+	mergeGossip(g: PushStateGossipV1): void {
+		if (g.collectionId !== this.collectionId || g.topicId !== this.topicId) {
+			return; // gossip for a different collection/topic is not ours to merge
+		}
+		this.replayBuffer.merge(g.replayBuffer);
+		this.dedupe.merge(g.dedupe);
+		if (g.lastRevision > this.lastRevision) {
+			this.lastRevision = g.lastRevision;
+		}
+		if (g.childCohorts.length > this.childCohorts.length) {
+			this.childCohorts = g.childCohorts;
+		}
+		if (this.parentCohort === undefined && g.parentCohort !== undefined) {
+			this.parentCohort = g.parentCohort;
+		}
+	}
+}
+
+// --- gossip codec (length-framed JSON, mirroring cohort-topic conventions) ---
+
+function fail(message: string): never {
+	throw new CohortWireError(message);
+}
+
+function asObject(value: unknown, what: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		fail(`${what}: expected an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function reqString(obj: Record<string, unknown>, key: string, what: string): string {
+	const value = obj[key];
+	if (typeof value !== "string") {
+		fail(`${what}: field "${key}" must be a string`);
+	}
+	return value;
+}
+
+function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
+	const value = obj[key];
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		fail(`${what}: field "${key}" must be a finite number`);
+	}
+	return value;
+}
+
+function reqInt(value: number, key: string, what: string): number {
+	if (!Number.isInteger(value)) {
+		fail(`${what}: field "${key}" must be an integer, got ${value}`);
+	}
+	return value;
+}
+
+function b64urlField(value: string, key: string, what: string): string {
+	try {
+		b64urlToBytes(value);
+	} catch {
+		fail(`${what}: field "${key}" is not valid base64url`);
+	}
+	return value;
+}
+
+function validateCohortRef(value: unknown, what: string): CohortRef {
+	const obj = asObject(value, what);
+	const coord = b64urlField(reqString(obj, "coord", what), "coord", what);
+	if (obj["primary"] !== undefined) {
+		return { coord, primary: b64urlField(reqString(obj, "primary", what), "primary", what) };
+	}
+	return { coord };
+}
+
+function validateRevisionEntry(value: unknown, what: string): RevisionEntry {
+	const obj = asObject(value, what);
+	return {
+		revision: reqInt(reqFiniteNumber(obj, "revision", what), "revision", what),
+		payload: validateNotificationV1(obj["payload"]),
+		receivedAt: reqFiniteNumber(obj, "receivedAt", what),
+	};
+}
+
+function validateReplayBufferState(value: unknown, what: string): ReplayBufferStateV1 {
+	const obj = asObject(value, what);
+	const entries = obj["entries"];
+	if (!Array.isArray(entries)) {
+		fail(`${what}: field "entries" must be an array`);
+	}
+	return {
+		capacity: reqInt(reqFiniteNumber(obj, "capacity", what), "capacity", what),
+		entries: entries.map((e) => validateRevisionEntry(e, `${what}.entry`)),
+	};
+}
+
+function validateDedupeState(value: unknown, what: string): DedupeStateV1 {
+	const obj = asObject(value, what);
+	const entries = obj["entries"];
+	if (!Array.isArray(entries)) {
+		fail(`${what}: field "entries" must be an array`);
+	}
+	return {
+		highestRevision: reqInt(reqFiniteNumber(obj, "highestRevision", what), "highestRevision", what),
+		entries: entries.map((e) => {
+			const eo = asObject(e, `${what}.entry`);
+			return { key: reqString(eo, "key", `${what}.entry`), revision: reqInt(reqFiniteNumber(eo, "revision", `${what}.entry`), "revision", `${what}.entry`) };
+		}),
+	};
+}
+
+/** Narrow an already-parsed value to {@link PushStateGossipV1}, throwing on any defect. */
+export function validatePushStateGossipV1(value: unknown): PushStateGossipV1 {
+	const what = "PushStateGossipV1";
+	const obj = asObject(value, what);
+	if (obj["v"] !== 1) {
+		fail(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
+	}
+	const childCohorts = obj["childCohorts"];
+	if (!Array.isArray(childCohorts)) {
+		fail(`${what}: field "childCohorts" must be an array`);
+	}
+	const out: PushStateGossipV1 = {
+		v: 1,
+		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
+		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		tailIdAtJoin: b64urlField(reqString(obj, "tailIdAtJoin", what), "tailIdAtJoin", what),
+		childCohorts: childCohorts.map((c) => validateCohortRef(c, `${what}.childCohort`)),
+		lastRevision: reqInt(reqFiniteNumber(obj, "lastRevision", what), "lastRevision", what),
+		replayBuffer: validateReplayBufferState(obj["replayBuffer"], `${what}.replayBuffer`),
+		dedupe: validateDedupeState(obj["dedupe"], `${what}.dedupe`),
+	};
+	if (obj["parentCohort"] !== undefined) {
+		out.parentCohort = validateCohortRef(obj["parentCohort"], `${what}.parentCohort`);
+	}
+	return out;
+}
+
+/** Encode a {@link PushStateGossipV1} as a length-prefixed UTF-8 JSON frame. */
+export function encodePushStateGossipV1(msg: PushStateGossipV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
+	return encodeCohortMessage(validatePushStateGossipV1(msg), maxMessageBytes);
+}
+
+/** Decode a length-prefixed {@link PushStateGossipV1} frame. */
+export function decodePushStateGossipV1(bytes: Uint8Array, maxMessageBytes?: number): PushStateGossipV1 {
+	return validatePushStateGossipV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+/** Round-trip helper for `bytesToB64url` consumers wanting the raw coord bytes of a {@link CohortRef}. */
+export function cohortRefCoordBytes(ref: CohortRef): Uint8Array {
+	return b64urlToBytes(ref.coord);
+}
+
+/** Build a {@link CohortRef} from raw coord (and optional primary) bytes. */
+export function makeCohortRef(coord: Uint8Array, primary?: Uint8Array): CohortRef {
+	return primary !== undefined
+		? { coord: bytesToB64url(coord), primary: bytesToB64url(primary) }
+		: { coord: bytesToB64url(coord) };
+}