@optimystic/db-core 0.13.5 → 0.14.0

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

@@ -0,0 +1,165 @@
+/**
+ * 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 type { IRingHash } from "../cohort-topic/ports.js";
+import type { VerifyResult } from "../cohort-topic/membership/verifier.js";
+import type { RevisionEntry } from "./replay-buffer.js";
+import type { NotificationVerifier } from "./verify.js";
+import { 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 declare function defaultDigestFold(hash?: IRingHash): DigestFold;
+/** The default delta coalescer: ordered concatenation of the per-revision delta bytes. */
+export declare function defaultDeltaCoalesce(deltas: readonly Uint8Array[]): Uint8Array;
+/** 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 declare function coalesceMergedDelta(ordered: readonly RevisionEntry[], coalesceDeltas: DeltaCoalesce, deltaMaxBytes: number): string | undefined;
+/**
+ * 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 declare function buildCheckpointSummary(orderedEntries: readonly RevisionEntry[], opts: CheckpointFoldOptions): CheckpointSummary | undefined;
+/** 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 declare class RollingCheckpoint {
+    readonly collectionId: string;
+    readonly span: number;
+    private readonly hash;
+    private readonly fold;
+    private readonly coalesceDeltas;
+    private readonly deltaMaxBytes;
+    /** revision → retired entry; trimmed to the highest `span` revisions. */
+    private readonly byRevision;
+    constructor(init: RollingCheckpointInit);
+    /** Number of retired revisions currently summarized. */
+    get size(): number;
+    /** Lowest summarized revision, or `undefined` when empty. */
+    get fromRevision(): number | undefined;
+    /** Highest summarized revision, or `undefined` when empty. */
+    get toRevision(): number | undefined;
+    /** True iff `revision` is within the checkpoint's covered range. */
+    covers(revision: number): boolean;
+    /**
+     * 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;
+    /** The retired entries, ascending by revision. */
+    private orderedEntries;
+    /** The fold/coalesce knobs this checkpoint applies — reused by the rotation handoff for an identical fold. */
+    get foldOptions(): CheckpointFoldOptions;
+    /** Build the {@link CheckpointSummary} over the currently-summarized range, or `undefined` if empty. */
+    summary(): CheckpointSummary | undefined;
+}
+/**
+ * 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 declare function verifyCheckpointEndpoints(summary: CheckpointSummary, verifier: NotificationVerifier): Promise<VerifyResult>;
+/**
+ * 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 declare function validateCheckpointSummary(value: unknown, what?: string): CheckpointSummary;
+//# sourceMappingURL=checkpoint.d.ts.map

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

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

package/dist/src/reactivity/checkpoint.js

@@ -0,0 +1,232 @@
+/**
+ * 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 { W_CHECKPOINT_DEFAULT } from "./config.js";
+import { asObject, b64urlField, failWire, reqIntInRange, reqString } from "./wire-validate.js";
+import { validateNotificationV1 } from "./wire.js";
+/**
+ * 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 = createRingHash()) {
+    return (digests) => {
+        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) {
+    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;
+}
+/**
+ * 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, coalesceDeltas, deltaMaxBytes) {
+    if (deltaMaxBytes <= 0) {
+        return undefined;
+    }
+    const deltas = [];
+    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, opts) {
+    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 = {
+        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;
+}
+/**
+ * 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 {
+    collectionId;
+    span;
+    hash;
+    fold;
+    coalesceDeltas;
+    deltaMaxBytes;
+    /** revision → retired entry; trimmed to the highest `span` revisions. */
+    byRevision = new Map();
+    constructor(init) {
+        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() {
+        return this.byRevision.size;
+    }
+    /** Lowest summarized revision, or `undefined` when empty. */
+    get fromRevision() {
+        return this.size === 0 ? undefined : Math.min(...this.byRevision.keys());
+    }
+    /** Highest summarized revision, or `undefined` when empty. */
+    get toRevision() {
+        return this.size === 0 ? undefined : Math.max(...this.byRevision.keys());
+    }
+    /** True iff `revision` is within the checkpoint's covered range. */
+    covers(revision) {
+        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) {
+        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. */
+    orderedEntries() {
+        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() {
+        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() {
+        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, verifier) {
+    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, what = "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 = {
+        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;
+}
+//# sourceMappingURL=checkpoint.js.map

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

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

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

@@ -0,0 +1,131 @@
+/**
+ * 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";
+/** Replay buffer depth (revisions per cohort, per collection). Simulator-validated-pending. */
+export declare const W_DEFAULT = 256;
+/** Sliding dedupe-window size (revisions). Simulator-validated-pending. */
+export declare const DEDUPE_WINDOW_DEFAULT = 64;
+/** Parent-checkpoint span (revisions). Owned by the backfill/resume ticket; default carried here. */
+export declare const W_CHECKPOINT_DEFAULT = 4096;
+/** Per-subscriber bounded queue depth at a forwarder. Simulator-validated-pending (may scale with cohort/tier). */
+export declare const QUEUE_MAX_DEFAULT = 32;
+/** Max delta payload size on a Core node (bytes). */
+export declare const DELTA_MAX_CORE_BYTES = 4096;
+/** Max delta payload size on an Edge node (bytes) — Edge declines deltas (`0` ⇒ omit `delta`). */
+export declare const DELTA_MAX_EDGE_BYTES = 0;
+/** Subscriber registration TTL on a Core node (ms), inherited from cohort-topic. */
+export declare const SUBSCRIBER_TTL_CORE_MS = 90000;
+/** Subscriber registration TTL on an Edge node (ms), inherited from cohort-topic. */
+export declare const SUBSCRIBER_TTL_EDGE_MS = 60000;
+/** Transactions per block — drives tail rotation. Simulator-validated-pending. */
+export declare const BLOCK_FILL_SIZE_DEFAULT = 64;
+/** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
+export declare const T_DRAIN_MS = 60000;
+/** Transactions remaining in tail before anticipatory warm-up. Owned by the rotation ticket. */
+export declare const WARM_THRESHOLD_DEFAULT = 8;
+/** Subscriber re-registration jitter span after a rotation hint (ms). Inherited from cohort-topic `T_rejoin_jitter`. */
+export declare const T_REJOIN_JITTER_MS = 30000;
+/** 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 declare const DEFAULT_REACTIVITY_CONFIG: ReactivityConfig;
+/** `delta_max` for a node profile: Core admits deltas up to `delta_max`, Edge declines them (`0`). */
+export declare function deltaMaxForProfile(profile: NodeProfile, config?: ReactivityConfig): number;
+/** Subscriber TTL for a node profile (`docs/reactivity.md` §Subscription): Core 90 s / Edge 60 s. */
+export declare function subscriberTtlForProfile(profile: NodeProfile, config?: ReactivityConfig): number;
+/**
+ * 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 declare function resolveW(opts?: {
+    cps?: number;
+    minCoverageSeconds?: number;
+    maxW?: number;
+    config?: ReactivityConfig;
+}): number;
+/** Default `W_checkpoint`-to-`W` ratio (`docs/reactivity.md` §Parent checkpoint summaries: 16×). */
+export declare 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 declare function resolveWCheckpoint(opts?: {
+    cps?: number;
+    minCoverageSeconds?: number;
+    maxW?: number;
+    ratio?: number;
+    config?: ReactivityConfig;
+}): number;
+/**
+ * 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 declare function resolveQueueMax(opts?: {
+    cohortSubscribers?: number;
+    scaleBaseline?: number;
+    maxQueue?: number;
+    config?: ReactivityConfig;
+}): number;
+//# sourceMappingURL=config.d.ts.map

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

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