@optimystic/db-core 0.13.4 → 0.14.0

package/src/reactivity/checkpoint.ts

@@ -0,0 +1,308 @@
+/**
+ * Reactivity — parent checkpoint summaries (`docs/reactivity.md` §Parent checkpoint summaries).
+ *
+ * A `W`-revision replay buffer is too shallow for a phone asleep overnight. To extend recoverable range
+ * without ballooning replay memory, every parent forwarder cohort (and the tail cohort) maintains a
+ * rolling {@link CheckpointSummary} over the `W_checkpoint` revisions sitting **immediately below** the
+ * replay ring's low edge — the two windows *stack*, so a single round trip recovers `W + W_checkpoint`
+ * revisions (the authoritative stacked semantics, `docs/reactivity.md` §Replay window). As revisions
+ * retire from the ring, the forwarder feeds them to {@link RollingCheckpoint.retire}; the checkpoint
+ * rolls its `toRevision` forward and trims its low edge to span `W_checkpoint`.
+ *
+ * The checkpoint is a **hint summary, not a chain replacement**. Two design questions the ticket asks to
+ * resolve, decided here:
+ *
+ *  - **`mergedDigest` semantics (resolved → system-level deterministic fold, per-collection override).**
+ *    `NotificationV1.digest` carries the commit-vote signed payload `utf8(commitHash + ":approve")` —
+ *    the exact bytes the commit threshold signature was computed over (see
+ *    `packages/db-core/src/reactivity/notification.ts`). It is per-revision deterministic and identical
+ *    across cohort members, so the default `mergedDigest` — a deterministic running fold over the
+ *    per-revision digests in revision order ({@link defaultDigestFold}) — converges under gossip and the
+ *    application can compare it against its own expectation. A collection MAY override the fold
+ *    ({@link RollingCheckpointInit.fold}, e.g. a KV collection folding changed-key sets). The merged
+ *    digest is **not** cryptographically verified — it is a hint; the cryptographic anchor is the
+ *    bracketing endpoints (below).
+ *
+ *  - **`mergedDelta` vs `delta_max` (resolved → omit when oversize, never split).** The per-revision
+ *    deltas are coalesced ({@link RollingCheckpointInit.coalesceDeltas}, default concatenation) only when
+ *    the coalesced result fits within `delta_max`; otherwise `mergedDelta` is omitted entirely and the
+ *    subscriber relies on `mergedDigest` + the resume's `recentEntries`, or falls back to a chain read. No
+ *    multi-frame splitting — a checkpoint is a bounded hint.
+ *
+ * The **bracketing endpoints** are carried as the two full endpoint {@link NotificationV1}s
+ * ({@link CheckpointSummary.bracketingEntries}). A bare signature is not independently verifiable — to
+ * verify an endpoint is a real committed revision a subscriber needs the signed payload (the commit
+ * digest) and the signers, which the full notification carries. {@link verifyCheckpointEndpoints} runs
+ * the standard {@link NotificationVerifier} over both endpoints (proving they are real committed
+ * revisions) and checks their revisions equal `fromRevision`/`toRevision`; a forged endpoint is rejected.
+ */
+
+import { createRingHash } from "../cohort-topic/ring-hash.js";
+import { bytesToB64url, b64urlToBytes } from "../cohort-topic/wire/codec.js";
+import type { IRingHash } from "../cohort-topic/ports.js";
+import type { VerifyResult } from "../cohort-topic/membership/verifier.js";
+import { W_CHECKPOINT_DEFAULT } from "./config.js";
+import type { RevisionEntry } from "./replay-buffer.js";
+import type { NotificationVerifier } from "./verify.js";
+import { asObject, b64urlField, failWire, reqIntInRange, reqString } from "./wire-validate.js";
+import { validateNotificationV1, type NotificationV1 } from "./wire.js";
+
+/**
+ * A parent checkpoint summary over `[fromRevision, toRevision]` (`docs/reactivity.md`
+ * §Parent checkpoint summaries). All byte fields base64url; `bracketingEntries` is exactly the two
+ * endpoint notifications, the verifiable anchor.
+ */
+export interface CheckpointSummary {
+	/** Collection id, base64url. */
+	readonly collectionId: string;
+	/** Inclusive low edge of the summarized range. */
+	readonly fromRevision: number;
+	/** Inclusive high edge of the summarized range (`toRevision - fromRevision + 1 ≈ W_checkpoint`). */
+	readonly toRevision: number;
+	/** Deterministic fold of the per-revision commit digests across the range, base64url (a hint). */
+	readonly mergedDigest: string;
+	/** Optional coalesced delta, base64url; omitted when the coalesced size exceeds `delta_max`. */
+	readonly mergedDelta?: string;
+	/** The two endpoint notifications (at `fromRevision` and `toRevision`) — the verifiable proof. */
+	readonly bracketingEntries: readonly [NotificationV1, NotificationV1];
+}
+
+/** A fold of per-revision commit digests into one summary digest (`docs/reactivity.md` `mergedDigest`). */
+export type DigestFold = (perRevisionDigests: readonly Uint8Array[]) => Uint8Array;
+
+/** Coalesce per-revision deltas into one bounded delta (`docs/reactivity.md` `mergedDelta`). */
+export type DeltaCoalesce = (perRevisionDeltas: readonly Uint8Array[]) => Uint8Array;
+
+/**
+ * The default system-level `mergedDigest` fold: a deterministic running hash
+ * `acc₀ = H(∅); accᵢ = H(accᵢ₋₁ ‖ digestᵢ)` over the per-revision commit digests in revision order.
+ * Order-dependent and reproducible, so every cohort member folds to identical bytes (gossip converges).
+ */
+export function defaultDigestFold(hash: IRingHash = createRingHash()): DigestFold {
+	return (digests: readonly Uint8Array[]): Uint8Array => {
+		let acc = hash.H(new Uint8Array(0));
+		for (const digest of digests) {
+			const input = new Uint8Array(acc.length + digest.length);
+			input.set(acc, 0);
+			input.set(digest, acc.length);
+			acc = hash.H(input);
+		}
+		return acc;
+	};
+}
+
+/** The default delta coalescer: ordered concatenation of the per-revision delta bytes. */
+export function defaultDeltaCoalesce(deltas: readonly Uint8Array[]): Uint8Array {
+	const total = deltas.reduce((n, d) => n + d.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const d of deltas) {
+		out.set(d, offset);
+		offset += d.length;
+	}
+	return out;
+}
+
+/** The fold/coalesce knobs shared by the rolling checkpoint and the rotation handoff. */
+export interface CheckpointFoldOptions {
+	/** Collection id the summarized entries belong to, base64url. */
+	readonly collectionId: string;
+	/** `mergedDigest` fold over the per-revision commit digests. */
+	readonly fold: DigestFold;
+	/** `mergedDelta` coalescer over the per-revision deltas. */
+	readonly coalesceDeltas: DeltaCoalesce;
+	/** `delta_max`: omit `mergedDelta` when the coalesced size exceeds this. `0` ⇒ never emit a delta. */
+	readonly deltaMaxBytes: number;
+}
+
+/**
+ * Coalesce the per-revision deltas of `ordered`, returning the base64url result only when it fits within
+ * `deltaMaxBytes`. Omitted (`undefined`) when no entry carries a delta, when `deltaMaxBytes <= 0`, or when
+ * the coalesced size would exceed `deltaMaxBytes` (the resolved omit-when-oversize policy — never split).
+ */
+export function coalesceMergedDelta(ordered: readonly RevisionEntry[], coalesceDeltas: DeltaCoalesce, deltaMaxBytes: number): string | undefined {
+	if (deltaMaxBytes <= 0) {
+		return undefined;
+	}
+	const deltas: Uint8Array[] = [];
+	for (const e of ordered) {
+		if (e.payload.delta !== undefined) {
+			deltas.push(b64urlToBytes(e.payload.delta));
+		}
+	}
+	if (deltas.length === 0) {
+		return undefined;
+	}
+	const coalesced = coalesceDeltas(deltas);
+	return coalesced.length > deltaMaxBytes ? undefined : bytesToB64url(coalesced);
+}
+
+/**
+ * Build a {@link CheckpointSummary} over `orderedEntries` (ascending by revision) — the shared fold the
+ * rolling checkpoint and the rotation buffer-to-checkpoint handoff both use. Returns `undefined` for an
+ * empty range. The two endpoints are carried as the full notifications (the verifiable anchor); the merged
+ * digest is the deterministic fold over the per-revision commit digests; the coalesced delta is included
+ * only when it fits within `deltaMaxBytes`.
+ */
+export function buildCheckpointSummary(orderedEntries: readonly RevisionEntry[], opts: CheckpointFoldOptions): CheckpointSummary | undefined {
+	if (orderedEntries.length === 0) {
+		return undefined;
+	}
+	const digests = orderedEntries.map((e) => b64urlToBytes(e.payload.digest));
+	const mergedDigest = bytesToB64url(opts.fold(digests));
+	const first = orderedEntries[0]!.payload;
+	const last = orderedEntries[orderedEntries.length - 1]!.payload;
+	const summary: CheckpointSummary = {
+		collectionId: opts.collectionId,
+		fromRevision: first.revision,
+		toRevision: last.revision,
+		mergedDigest,
+		bracketingEntries: [first, last],
+	};
+	const mergedDelta = coalesceMergedDelta(orderedEntries, opts.coalesceDeltas, opts.deltaMaxBytes);
+	return mergedDelta !== undefined ? { ...summary, mergedDelta } : summary;
+}
+
+/** Construction inputs for a {@link RollingCheckpoint}. */
+export interface RollingCheckpointInit {
+	/** Collection id, base64url (must match the entries retired into it). */
+	readonly collectionId: string;
+	/** Checkpoint span `W_checkpoint` (default {@link W_CHECKPOINT_DEFAULT}). */
+	readonly span?: number;
+	/** Ring hash for the default digest fold. Default db-core SHA-256. */
+	readonly hash?: IRingHash;
+	/** `mergedDigest` fold (default {@link defaultDigestFold} over the injected hash). */
+	readonly fold?: DigestFold;
+	/** `mergedDelta` coalescer (default {@link defaultDeltaCoalesce}). */
+	readonly coalesceDeltas?: DeltaCoalesce;
+	/** `delta_max`: omit `mergedDelta` when the coalesced size exceeds this. `0` ⇒ never emit a delta. */
+	readonly deltaMaxBytes?: number;
+}
+
+/**
+ * The rolling `W_checkpoint`-span parent checkpoint. Retains up to `span` retired {@link RevisionEntry}s
+ * (the documented per-cohort checkpoint memory cost) so it can fold a real `mergedDigest`, coalesce a
+ * `mergedDelta`, and carry the two endpoint notifications. It always covers the `span` revisions just
+ * below the replay ring's low edge.
+ */
+export class RollingCheckpoint {
+	readonly collectionId: string;
+	readonly span: number;
+	private readonly hash: IRingHash;
+	private readonly fold: DigestFold;
+	private readonly coalesceDeltas: DeltaCoalesce;
+	private readonly deltaMaxBytes: number;
+	/** revision → retired entry; trimmed to the highest `span` revisions. */
+	private readonly byRevision = new Map<number, RevisionEntry>();
+
+	constructor(init: RollingCheckpointInit) {
+		const span = init.span ?? W_CHECKPOINT_DEFAULT;
+		if (!Number.isInteger(span) || span < 1) {
+			throw new RangeError(`reactivity checkpoint: span must be an integer >= 1, got ${span}`);
+		}
+		this.collectionId = init.collectionId;
+		this.span = span;
+		this.hash = init.hash ?? createRingHash();
+		this.fold = init.fold ?? defaultDigestFold(this.hash);
+		this.coalesceDeltas = init.coalesceDeltas ?? defaultDeltaCoalesce;
+		this.deltaMaxBytes = init.deltaMaxBytes ?? 0;
+	}
+
+	/** Number of retired revisions currently summarized. */
+	get size(): number {
+		return this.byRevision.size;
+	}
+
+	/** Lowest summarized revision, or `undefined` when empty. */
+	get fromRevision(): number | undefined {
+		return this.size === 0 ? undefined : Math.min(...this.byRevision.keys());
+	}
+
+	/** Highest summarized revision, or `undefined` when empty. */
+	get toRevision(): number | undefined {
+		return this.size === 0 ? undefined : Math.max(...this.byRevision.keys());
+	}
+
+	/** True iff `revision` is within the checkpoint's covered range. */
+	covers(revision: number): boolean {
+		const from = this.fromRevision;
+		const to = this.toRevision;
+		return from !== undefined && to !== undefined && revision >= from && revision <= to;
+	}
+
+	/**
+	 * Fold one revision retired from the replay ring into the checkpoint. Entries arrive as the ring
+	 * evicts its low edge; the checkpoint trims to its highest `span` revisions so it tracks the window
+	 * immediately below the ring. A retransmit at an already-summarized revision replaces in place.
+	 */
+	retire(entry: RevisionEntry): void {
+		if (entry.payload.collectionId !== this.collectionId) {
+			return; // an entry for a different collection is not ours to summarize
+		}
+		this.byRevision.set(entry.revision, entry);
+		while (this.byRevision.size > this.span) {
+			this.byRevision.delete(Math.min(...this.byRevision.keys()));
+		}
+	}
+
+	/** The retired entries, ascending by revision. */
+	private orderedEntries(): RevisionEntry[] {
+		return [...this.byRevision.values()].sort((a, b) => a.revision - b.revision);
+	}
+
+	/** The fold/coalesce knobs this checkpoint applies — reused by the rotation handoff for an identical fold. */
+	get foldOptions(): CheckpointFoldOptions {
+		return { collectionId: this.collectionId, fold: this.fold, coalesceDeltas: this.coalesceDeltas, deltaMaxBytes: this.deltaMaxBytes };
+	}
+
+	/** Build the {@link CheckpointSummary} over the currently-summarized range, or `undefined` if empty. */
+	summary(): CheckpointSummary | undefined {
+		return buildCheckpointSummary(this.orderedEntries(), this.foldOptions);
+	}
+}
+
+/**
+ * Verify a checkpoint's bracketing endpoints are real committed revisions: run the standard
+ * {@link NotificationVerifier} over both endpoint notifications and confirm their revisions equal
+ * `fromRevision`/`toRevision` and their collection matches. Returns `"verified"` only if **both**
+ * endpoints verify and align; a forged or tampered endpoint yields `"untrusted"`.
+ */
+export async function verifyCheckpointEndpoints(summary: CheckpointSummary, verifier: NotificationVerifier): Promise<VerifyResult> {
+	const [from, to] = summary.bracketingEntries;
+	if (
+		from.collectionId !== summary.collectionId ||
+		to.collectionId !== summary.collectionId ||
+		from.revision !== summary.fromRevision ||
+		to.revision !== summary.toRevision
+	) {
+		return "untrusted";
+	}
+	const [fromVerdict, toVerdict] = await Promise.all([verifier.verify(from), verifier.verify(to)]);
+	return fromVerdict === "verified" && toVerdict === "verified" ? "verified" : "untrusted";
+}
+
+/**
+ * Narrow an already-parsed value to {@link CheckpointSummary}, throwing on any defect. Used by the resume
+ * codec to validate a checkpoint embedded in a `checkpoint_window` reply. The two `bracketingEntries` are
+ * validated as full {@link NotificationV1}s (the verifiable anchor); `mergedDelta` is optional.
+ */
+export function validateCheckpointSummary(value: unknown, what = "CheckpointSummary"): CheckpointSummary {
+	const obj = asObject(value, what);
+	const fromRevision = reqIntInRange(obj, "fromRevision", what, 0);
+	const toRevision = reqIntInRange(obj, "toRevision", what, fromRevision);
+	const bracketing = obj["bracketingEntries"];
+	if (!Array.isArray(bracketing) || bracketing.length !== 2) {
+		failWire(`${what}: field "bracketingEntries" must be a length-2 array`);
+	}
+	const summary: CheckpointSummary = {
+		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
+		fromRevision,
+		toRevision,
+		mergedDigest: b64urlField(reqString(obj, "mergedDigest", what), "mergedDigest", what),
+		bracketingEntries: [validateNotificationV1(bracketing[0]), validateNotificationV1(bracketing[1])],
+	};
+	if (obj["mergedDelta"] !== undefined) {
+		return { ...summary, mergedDelta: b64urlField(reqString(obj, "mergedDelta", what), "mergedDelta", what) };
+	}
+	return summary;
+}

package/src/reactivity/config.ts

@@ -0,0 +1,172 @@
+/**
+ * Reactivity — configuration defaults (single source for the hot path).
+ *
+ * Transcribed from `docs/reactivity.md` §Configuration. Every tunable the reactivity hot path reads
+ * is sourced from {@link DEFAULT_REACTIVITY_CONFIG} — never hard-coded at a call site — so the
+ * simulator fold-back ([fold-simulator-findings-into-design-docs]) can retune `W` / `dedupe_window`
+ * without touching origination, forwarding, the replay buffer, or delivery.
+ *
+ * **Simulator-validated-pending.** `W` (replay buffer depth), `dedupe_window`, `T_drain`, `queue_max`,
+ * and `block_fill_size` are *provisional* pending the design simulator ([simulator-reactivity-replay],
+ * folded back by [fold-simulator-findings-into-design-docs]). The simulator's REVISED guidance is that `W`
+ * SHOULD become adaptive per measured commit-rate on hot collections (`W ≈ ⌈min_coverage × cps⌉`); the
+ * static `W = 256` is kept as the Edge/low-rate default. {@link resolveW} exposes that hook; the
+ * simulator's tail-rotation scenario also confirms the re-registration burst stays inside
+ * `cap_promote_fast` within `T_drain`, and flags whether `queue_max` should scale with cohort size/tier
+ * ({@link resolveQueueMax} is the parallel hook for that fold-back). Sourcing every tunable from this
+ * single table is what lets the fold-back revise the values without touching the protocol code.
+ *
+ * Ownership: `W` / `dedupe_window` ← [reactivity-origination-replay-delivery]; `W_checkpoint` ←
+ * [reactivity-backfill-resume-checkpoints]; `queue_max` / `delta_max` / `T_drain` / `warm_threshold` /
+ * `block_fill_size` ← [reactivity-rotation-backpressure-policy] (this ticket). `T_rejoin_jitter`, TTL, and
+ * ping are inherited from the cohort-topic defaults.
+ */
+
+import type { NodeProfile } from "../cohort-topic/tiers.js";
+import { DEFAULT_T_REJOIN_JITTER_MS } from "../cohort-topic/antiflood/jitter.js";
+
+/** Replay buffer depth (revisions per cohort, per collection). Simulator-validated-pending. */
+export const W_DEFAULT = 256;
+/** Sliding dedupe-window size (revisions). Simulator-validated-pending. */
+export const DEDUPE_WINDOW_DEFAULT = 64;
+/** Parent-checkpoint span (revisions). Owned by the backfill/resume ticket; default carried here. */
+export const W_CHECKPOINT_DEFAULT = 4096;
+/** Per-subscriber bounded queue depth at a forwarder. Simulator-validated-pending (may scale with cohort/tier). */
+export const QUEUE_MAX_DEFAULT = 32;
+/** Max delta payload size on a Core node (bytes). */
+export const DELTA_MAX_CORE_BYTES = 4096;
+/** Max delta payload size on an Edge node (bytes) — Edge declines deltas (`0` ⇒ omit `delta`). */
+export const DELTA_MAX_EDGE_BYTES = 0;
+/** Subscriber registration TTL on a Core node (ms), inherited from cohort-topic. */
+export const SUBSCRIBER_TTL_CORE_MS = 90_000;
+/** Subscriber registration TTL on an Edge node (ms), inherited from cohort-topic. */
+export const SUBSCRIBER_TTL_EDGE_MS = 60_000;
+/** Transactions per block — drives tail rotation. Simulator-validated-pending. */
+export const BLOCK_FILL_SIZE_DEFAULT = 64;
+/** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
+export const T_DRAIN_MS = 60_000;
+/** Transactions remaining in tail before anticipatory warm-up. Owned by the rotation ticket. */
+export const WARM_THRESHOLD_DEFAULT = 8;
+/** Subscriber re-registration jitter span after a rotation hint (ms). Inherited from cohort-topic `T_rejoin_jitter`. */
+export const T_REJOIN_JITTER_MS = DEFAULT_T_REJOIN_JITTER_MS;
+
+/** The full reactivity config, with the documented defaults. */
+export interface ReactivityConfig {
+	/** Replay buffer depth `W`. Simulator-validated-pending. */
+	readonly w: number;
+	/** Sliding dedupe-window size. Simulator-validated-pending. */
+	readonly dedupeWindow: number;
+	/** Parent-checkpoint span (reserved; backfill/resume ticket). */
+	readonly wCheckpoint: number;
+	/** Per-subscriber bounded queue depth (reserved; backpressure ticket). */
+	readonly queueMax: number;
+	/** Max delta payload size on a Core node (bytes). */
+	readonly deltaMaxCoreBytes: number;
+	/** Max delta payload size on an Edge node (bytes). */
+	readonly deltaMaxEdgeBytes: number;
+	/** Subscriber TTL on a Core node (ms). */
+	readonly subscriberTtlCoreMs: number;
+	/** Subscriber TTL on an Edge node (ms). */
+	readonly subscriberTtlEdgeMs: number;
+	/** Transactions per block — drives tail rotation. Simulator-validated-pending. */
+	readonly blockFillSize: number;
+	/** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
+	readonly tDrainMs: number;
+	/** Transactions remaining before anticipatory warm-up. */
+	readonly warmThreshold: number;
+	/** Subscriber re-registration jitter span after a rotation (ms); inherited from cohort-topic. */
+	readonly tRejoinJitterMs: number;
+}
+
+/** The default reactivity config (`docs/reactivity.md` §Configuration). */
+export const DEFAULT_REACTIVITY_CONFIG: ReactivityConfig = {
+	w: W_DEFAULT,
+	dedupeWindow: DEDUPE_WINDOW_DEFAULT,
+	wCheckpoint: W_CHECKPOINT_DEFAULT,
+	queueMax: QUEUE_MAX_DEFAULT,
+	deltaMaxCoreBytes: DELTA_MAX_CORE_BYTES,
+	deltaMaxEdgeBytes: DELTA_MAX_EDGE_BYTES,
+	subscriberTtlCoreMs: SUBSCRIBER_TTL_CORE_MS,
+	subscriberTtlEdgeMs: SUBSCRIBER_TTL_EDGE_MS,
+	blockFillSize: BLOCK_FILL_SIZE_DEFAULT,
+	tDrainMs: T_DRAIN_MS,
+	warmThreshold: WARM_THRESHOLD_DEFAULT,
+	tRejoinJitterMs: T_REJOIN_JITTER_MS,
+};
+
+/** `delta_max` for a node profile: Core admits deltas up to `delta_max`, Edge declines them (`0`). */
+export function deltaMaxForProfile(profile: NodeProfile, config: ReactivityConfig = DEFAULT_REACTIVITY_CONFIG): number {
+	return profile.kind === "edge" ? config.deltaMaxEdgeBytes : config.deltaMaxCoreBytes;
+}
+
+/** Subscriber TTL for a node profile (`docs/reactivity.md` §Subscription): Core 90 s / Edge 60 s. */
+export function subscriberTtlForProfile(profile: NodeProfile, config: ReactivityConfig = DEFAULT_REACTIVITY_CONFIG): number {
+	return profile.kind === "edge" ? config.subscriberTtlEdgeMs : config.subscriberTtlCoreMs;
+}
+
+/**
+ * Resolve the replay-buffer depth `W` for a collection.
+ *
+ * Static default (no `cps`): returns the configured `config.w` unchanged — the simulator-confirmed
+ * Edge/low-rate default. Adaptive (a measured `cps` and `minCoverageSeconds`): returns
+ * `⌈minCoverageSeconds × cps⌉` clamped to `[config.w, maxW]`, the simulator's REVISED guidance for hot
+ * collections. This is the single hook the backfill/resume ticket extends; the hot path here only ever
+ * calls the static form, so behavior is unchanged until a `cps` is wired through.
+ */
+export function resolveW(opts: { cps?: number; minCoverageSeconds?: number; maxW?: number; config?: ReactivityConfig } = {}): number {
+	const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
+	if (opts.cps === undefined || opts.minCoverageSeconds === undefined) {
+		return config.w;
+	}
+	if (!Number.isFinite(opts.cps) || opts.cps <= 0 || !Number.isFinite(opts.minCoverageSeconds) || opts.minCoverageSeconds <= 0) {
+		return config.w;
+	}
+	const adaptive = Math.ceil(opts.minCoverageSeconds * opts.cps);
+	const maxW = opts.maxW ?? Number.POSITIVE_INFINITY;
+	return Math.min(Math.max(config.w, adaptive), maxW);
+}
+
+/** Default `W_checkpoint`-to-`W` ratio (`docs/reactivity.md` §Parent checkpoint summaries: 16×). */
+export const W_CHECKPOINT_RATIO = 16;
+
+/**
+ * Resolve the parent-checkpoint span `W_checkpoint` for a collection.
+ *
+ * Static default (no `cps`): the configured `config.wCheckpoint` (4096). Adaptive: `W_checkpoint`
+ * "scales the same way and may stay a fixed 16× multiple of the resolved `W`" (`docs/reactivity.md`
+ * §Configuration), so when a `cps` is supplied it tracks `W_CHECKPOINT_RATIO × resolveW(opts)`. This is
+ * the single hook the simulator fold-back ([fold-simulator-findings-into-design-docs]) retunes; the
+ * resume classifier reads it so a hot collection's stacked recovery range scales with the replay depth.
+ */
+export function resolveWCheckpoint(opts: { cps?: number; minCoverageSeconds?: number; maxW?: number; ratio?: number; config?: ReactivityConfig } = {}): number {
+	const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
+	if (opts.cps === undefined || opts.minCoverageSeconds === undefined) {
+		return config.wCheckpoint;
+	}
+	const ratio = opts.ratio ?? W_CHECKPOINT_RATIO;
+	return resolveW(opts) * ratio;
+}
+
+/**
+ * Resolve the per-subscriber bounded-queue depth `queue_max` for a cohort.
+ *
+ * Static default (no scaling input): the configured `config.queueMax` (32). The simulator flags whether
+ * `queue_max` should scale with cohort size / tier on hot collections; this is the single hook the
+ * fold-back ([fold-simulator-findings-into-design-docs]) retunes. When a `cohortSubscribers` count is
+ * supplied, the depth scales as `⌈queue_max × subscribers / scaleBaseline⌉` clamped to `[queueMax, maxQueue]`
+ * — never below the static default, optionally capped at a per-cohort memory budget. With no scaling input
+ * the hot path is unchanged (constant `queue_max`).
+ */
+export function resolveQueueMax(opts: { cohortSubscribers?: number; scaleBaseline?: number; maxQueue?: number; config?: ReactivityConfig } = {}): number {
+	const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
+	if (opts.cohortSubscribers === undefined) {
+		return config.queueMax;
+	}
+	const baseline = opts.scaleBaseline ?? 1;
+	if (!Number.isFinite(opts.cohortSubscribers) || opts.cohortSubscribers <= 0 || !(baseline > 0)) {
+		return config.queueMax;
+	}
+	const scaled = Math.ceil((config.queueMax * opts.cohortSubscribers) / baseline);
+	const maxQueue = opts.maxQueue ?? Number.POSITIVE_INFINITY;
+	return Math.min(Math.max(config.queueMax, scaled), maxQueue);
+}

package/src/reactivity/dedupe.ts

@@ -0,0 +1,132 @@
+/**
+ * Reactivity — per-revision dedupe (sliding-window set), `docs/reactivity.md` §Per-revision dedupe.
+ *
+ * A scalar `lastRevision` is insufficient under partition healing: the same revision may legitimately
+ * arrive from multiple parents during a merge, and dropping all but the first on `revision > lastRevision`
+ * would discard honest retransmits exactly when a subscriber needs them. Instead each forwarder keeps a
+ * sliding set of `(revision, sigDigest)` pairs for the last `dedupe_window` revisions (default 64).
+ *
+ * A notification is forwarded if:
+ *  - it is for the *highest revision* seen in the window (normal case), OR
+ *  - it is for an earlier revision, its `(revision, sigDigest)` is not already in the set, and it passes
+ *    verification (recovery: a retransmit closing a gap).
+ *
+ * Both reduce to: **forward iff the `(revision, sigDigest)` key is not already present** (verification is
+ * the forwarder's prior step, applied to every inbound). Keys already in the set are dropped silently.
+ * The set is gossiped within the cohort ({@link DedupeWindow.serialize} / {@link DedupeWindow.merge}) so
+ * all members agree on what has been seen.
+ */
+
+import { DEDUPE_WINDOW_DEFAULT } from "./config.js";
+
+/** The dedupe decision for one inbound notification. */
+export type DedupeOutcome = "forward" | "duplicate";
+
+/** Serializable dedupe state for intra-cohort gossip convergence. */
+export interface DedupeStateV1 {
+	/** Highest revision observed (anchors the sliding window's high edge). */
+	readonly highestRevision: number;
+	/** Seen `(revision, sigDigest)` keys with their revision, for window-bounded merge. */
+	readonly entries: ReadonlyArray<{ readonly key: string; readonly revision: number }>;
+}
+
+/** A sliding-window dedupe set over `(revision, sigDigest)` pairs. */
+export interface DedupeWindow {
+	/** Highest revision observed so far (`-1` before any observation). */
+	readonly highestRevision: number;
+	/** Number of retained keys. */
+	readonly size: number;
+	/** True iff `(revision, sigDigest)` is already in the set. */
+	has(revision: number, sigDigest: string): boolean;
+	/**
+	 * Record `(revision, sigDigest)` and report whether it should be forwarded. Returns `"duplicate"`
+	 * (no state change) if already seen, else records it, advances the window, and returns `"forward"`.
+	 */
+	observe(revision: number, sigDigest: string): DedupeOutcome;
+	/** Snapshot for gossip. */
+	serialize(): DedupeStateV1;
+	/** Union another member's gossiped state into this one (idempotent, commutative within the window). */
+	merge(state: DedupeStateV1): void;
+}
+
+class SlidingDedupeWindow implements DedupeWindow {
+	private readonly windowSize: number;
+	/** key → revision, for window-bounded eviction. */
+	private readonly seen = new Map<string, number>();
+	private highest = -1;
+
+	constructor(windowSize: number) {
+		if (!Number.isInteger(windowSize) || windowSize < 1) {
+			throw new RangeError(`reactivity dedupe: windowSize must be an integer >= 1, got ${windowSize}`);
+		}
+		this.windowSize = windowSize;
+	}
+
+	get highestRevision(): number {
+		return this.highest;
+	}
+
+	get size(): number {
+		return this.seen.size;
+	}
+
+	has(revision: number, sigDigest: string): boolean {
+		return this.seen.has(keyOf(revision, sigDigest));
+	}
+
+	observe(revision: number, sigDigest: string): DedupeOutcome {
+		const key = keyOf(revision, sigDigest);
+		if (this.seen.has(key)) {
+			return "duplicate";
+		}
+		this.insert(key, revision);
+		return "forward";
+	}
+
+	serialize(): DedupeStateV1 {
+		return {
+			highestRevision: this.highest,
+			entries: [...this.seen].map(([key, rev]) => ({ key, revision: rev })),
+		};
+	}
+
+	merge(state: DedupeStateV1): void {
+		if (state.highestRevision > this.highest) {
+			this.highest = state.highestRevision;
+		}
+		for (const { key, revision } of state.entries) {
+			if (!this.seen.has(key)) {
+				this.seen.set(key, revision);
+			}
+		}
+		this.evictBelowWindow();
+	}
+
+	private insert(key: string, revision: number): void {
+		if (revision > this.highest) {
+			this.highest = revision;
+		}
+		this.seen.set(key, revision);
+		this.evictBelowWindow();
+	}
+
+	/** Retain only revisions within `[highest - windowSize + 1, highest]`. */
+	private evictBelowWindow(): void {
+		const low = this.highest - this.windowSize + 1;
+		for (const [key, revision] of this.seen) {
+			if (revision < low) {
+				this.seen.delete(key);
+			}
+		}
+	}
+}
+
+/** `${revision}:${sigDigest}` — the dedupe-set key. */
+function keyOf(revision: number, sigDigest: string): string {
+	return `${revision}:${sigDigest}`;
+}
+
+/** Build a {@link DedupeWindow} with the configured (default {@link DEDUPE_WINDOW_DEFAULT}) span. */
+export function createDedupeWindow(windowSize: number = DEDUPE_WINDOW_DEFAULT): DedupeWindow {
+	return new SlidingDedupeWindow(windowSize);
+}