@optimystic/db-core 0.22.0 → 0.24.0

package/src/reactivity/push-state.ts

@@ -1,310 +1,310 @@
-/**
- * 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 { asObject, b64urlField, failWire as fail, reqFiniteNumber, reqString } from "../cohort-topic/wire/primitives.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) ---
-// Generic structural primitives (fail/asObject/reqString/reqFiniteNumber/b64urlField) are imported from
-// cohort-topic/wire/primitives.js; only `reqInt` stays local — it is a range-free integer check (no
-// lower bound), unlike the shared `reqIntInRange`, so folding it in would change behavior.
-
-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 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) };
-}
+/**
+ * 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 { asObject, b64urlField, failWire as fail, reqFiniteNumber, reqString } from "../cohort-topic/wire/primitives.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) ---
+// Generic structural primitives (fail/asObject/reqString/reqFiniteNumber/b64urlField) are imported from
+// cohort-topic/wire/primitives.js; only `reqInt` stays local — it is a range-free integer check (no
+// lower bound), unlike the shared `reqIntInRange`, so folding it in would change behavior.
+
+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 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) };
+}