@optimystic/db-core 0.13.5 → 0.14.1

package/dist/src/reactivity/notification.js

@@ -0,0 +1,92 @@
+/**
+ * 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";
+const utf8 = new TextEncoder();
+/**
+ * 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, commitCert, ctx) {
+    const encodeSigner = ctx.encodeSigner ?? ((s) => s);
+    const notification = {
+        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, hash = createRingHash()) {
+    return bytesToB64url(hash.H(utf8.encode(sig)));
+}
+/** The dedupe-set key for a notification: `${revision}:${sigDigest(sig)}`. */
+export function dedupeKey(revision, sig, hash) {
+    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) {
+    const seen = new Set();
+    const ordered = [];
+    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;
+}
+//# sourceMappingURL=notification.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notification.js","sourceRoot":"","sources":["../../../src/reactivity/notification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAK9D,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAyB/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAA4B,EAAE,UAAsB,EAAE,GAAuB;IAChH,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,YAAY,GAAmB;QACpC,CAAC,EAAE,CAAC;QACJ,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,KAAK,CAAC,GAAG;QACnB,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,aAAa,CAAC;QAC/C,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,GAAG,EAAE,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC;QAC3C,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;KAC7C,CAAC;IACF,IAAI,GAAG,CAAC,aAAa,GAAG,CAAC,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QAC/F,YAAY,CAAC,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACpC,YAAY,CAAC,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;IAC9C,CAAC;IACD,oGAAoG;IACpG,qGAAqG;IACrG,mGAAmG;IACnG,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACxB,YAAY,CAAC,YAAY,GAAG,IAAI,CAAC;QACjC,IAAI,KAAK,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC7C,YAAY,CAAC,mBAAmB,GAAG,KAAK,CAAC,mBAAmB,CAAC;QAC9D,CAAC;IACF,CAAC;IACD,OAAO,YAAY,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,OAAkB,cAAc,EAAE;IACxE,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,GAAW,EAAE,IAAgB;IACxE,OAAO,GAAG,QAAQ,IAAI,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAAC,aAAuC;IACnF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QAC/B,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,mBAAmB,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAC/F,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;QACrC,CAAC;IACF,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * 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 { type NodeProfile } from "../cohort-topic/tiers.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 declare function mayServeAsReactivityForwarder(profile: NodeProfile): boolean;
+/** A subscriber-only node (Edge, or a Core narrowed off T3) attempted to instantiate a reactivity forwarder. */
+export declare class ReactivityForwarderForbiddenError extends Error {
+    readonly profileKind: NodeProfile["kind"];
+    constructor(profileKind: NodeProfile["kind"]);
+}
+/**
+ * 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 declare function instantiateForwarderPushState(profile: NodeProfile, init: PushStateInit): PushState | 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 declare function requireForwarderPushState(profile: NodeProfile, init: PushStateInit): PushState;
+/**
+ * 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 declare function reactivityNodePolicy(profile: NodeProfile): ReactivityNodePolicy;
+//# sourceMappingURL=policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/reactivity/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAE3E;AAED,gHAAgH;AAChH,qBAAa,iCAAkC,SAAQ,KAAK;IAC/C,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC;gBAAhC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC;CAIrD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS,CAE9G;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,SAAS,CAK9F;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED,oGAAoG;AACpG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG,oBAAoB,CAE/E"}

package/dist/src/reactivity/policy.js

@@ -0,0 +1,64 @@
+/**
+ * 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 } from "../cohort-topic/tiers.js";
+import { deltaMaxForProfile } from "./config.js";
+import { PushState } 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) {
+    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 {
+    profileKind;
+    constructor(profileKind) {
+        super(`reactivity: a ${profileKind} node that does not forward T3 cannot instantiate a forwarder (subscriber-only)`);
+        this.profileKind = profileKind;
+        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, init) {
+    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, init) {
+    if (!mayServeAsReactivityForwarder(profile)) {
+        throw new ReactivityForwarderForbiddenError(profile.kind);
+    }
+    return new PushState(init);
+}
+/** Resolve the {@link ReactivityNodePolicy} for a profile (forwarder eligibility + `delta_max`). */
+export function reactivityNodePolicy(profile) {
+    return { mayForward: mayServeAsReactivityForwarder(profile), deltaMaxBytes: deltaMaxForProfile(profile) };
+}
+//# sourceMappingURL=policy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/reactivity/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,IAAI,EAAoB,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAAoB;IACjE,OAAO,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,gHAAgH;AAChH,MAAM,OAAO,iCAAkC,SAAQ,KAAK;IACtC;IAArB,YAAqB,WAAgC;QACpD,KAAK,CAAC,iBAAiB,WAAW,iFAAiF,CAAC,CAAC;QADjG,gBAAW,GAAX,WAAW,CAAqB;QAEpD,IAAI,CAAC,IAAI,GAAG,mCAAmC,CAAC;IACjD,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAAoB,EAAE,IAAmB;IACtF,OAAO,6BAA6B,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAoB,EAAE,IAAmB;IAClF,IAAI,CAAC,6BAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,iCAAiC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAcD,oGAAoG;AACpG,MAAM,UAAU,oBAAoB,CAAC,OAAoB;IACxD,OAAO,EAAE,UAAU,EAAE,6BAA6B,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;AAC3G,CAAC"}

package/dist/src/reactivity/push-state.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 { type SubscriberBackpressure, type SubscriberEnqueueResult } from "./backpressure.js";
+import { RollingCheckpoint, type CheckpointSummary, type DeltaCoalesce, type DigestFold } from "./checkpoint.js";
+import { type DedupeStateV1, type DedupeWindow } from "./dedupe.js";
+import { type ReplayBuffer, type ReplayBufferStateV1 } from "./replay-buffer.js";
+import { 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 declare 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?;
+    constructor(init: PushStateInit);
+    /**
+     * 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[];
+    /** The checkpoint inherited from the outgoing tail on rotation, or `undefined` until a handoff lands. */
+    get inheritedCheckpoint(): CheckpointSummary | undefined;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Snapshot the gossipable slice for cohort replication. */
+    serializeGossip(): PushStateGossipV1;
+    /** Merge a peer member's gossiped state so the whole cohort converges (any member can then serve). */
+    mergeGossip(g: PushStateGossipV1): void;
+}
+/** Narrow an already-parsed value to {@link PushStateGossipV1}, throwing on any defect. */
+export declare function validatePushStateGossipV1(value: unknown): PushStateGossipV1;
+/** Encode a {@link PushStateGossipV1} as a length-prefixed UTF-8 JSON frame. */
+export declare function encodePushStateGossipV1(msg: PushStateGossipV1, maxMessageBytes?: number): Uint8Array;
+/** Decode a length-prefixed {@link PushStateGossipV1} frame. */
+export declare function decodePushStateGossipV1(bytes: Uint8Array, maxMessageBytes?: number): PushStateGossipV1;
+/** Round-trip helper for `bytesToB64url` consumers wanting the raw coord bytes of a {@link CohortRef}. */
+export declare function cohortRefCoordBytes(ref: CohortRef): Uint8Array;
+/** Build a {@link CohortRef} from raw coord (and optional primary) bytes. */
+export declare function makeCohortRef(coord: Uint8Array, primary?: Uint8Array): CohortRef;
+//# sourceMappingURL=push-state.d.ts.map

package/dist/src/reactivity/push-state.d.ts.map

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

package/dist/src/reactivity/push-state.js

@@ -0,0 +1,270 @@
+/**
+ * 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 } from "./backpressure.js";
+import { RollingCheckpoint } from "./checkpoint.js";
+import { createDedupeWindow } from "./dedupe.js";
+import { createReplayBuffer } from "./replay-buffer.js";
+import { validateNotificationV1 } from "./wire.js";
+/**
+ * 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 {
+    collectionId;
+    topicId;
+    tailIdAtJoin;
+    parentCohort;
+    childCohorts;
+    replayBuffer;
+    dedupe;
+    lastRevision;
+    /**
+     * 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).
+     */
+    checkpoint;
+    /**
+     * 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}.
+     */
+    perSubscriberQueue;
+    /**
+     * 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.
+     */
+    inherited;
+    constructor(init) {
+        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, n) {
+        return this.perSubscriberQueue.fanOut(subscriberIds, n);
+    }
+    /** The checkpoint inherited from the outgoing tail on rotation, or `undefined` until a handoff lands. */
+    get inheritedCheckpoint() {
+        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) {
+        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() {
+        return this.checkpoint.summary();
+    }
+    /** Snapshot the gossipable slice for cohort replication. */
+    serializeGossip() {
+        const out = {
+            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) {
+        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) {
+    throw new CohortWireError(message);
+}
+function asObject(value, what) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(`${what}: expected an object`);
+    }
+    return value;
+}
+function reqString(obj, key, what) {
+    const value = obj[key];
+    if (typeof value !== "string") {
+        fail(`${what}: field "${key}" must be a string`);
+    }
+    return value;
+}
+function reqFiniteNumber(obj, key, what) {
+    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, key, what) {
+    if (!Number.isInteger(value)) {
+        fail(`${what}: field "${key}" must be an integer, got ${value}`);
+    }
+    return value;
+}
+function b64urlField(value, key, what) {
+    try {
+        b64urlToBytes(value);
+    }
+    catch {
+        fail(`${what}: field "${key}" is not valid base64url`);
+    }
+    return value;
+}
+function validateCohortRef(value, what) {
+    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, what) {
+    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, what) {
+    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, what) {
+    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) {
+    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 = {
+        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, maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES) {
+    return encodeCohortMessage(validatePushStateGossipV1(msg), maxMessageBytes);
+}
+/** Decode a length-prefixed {@link PushStateGossipV1} frame. */
+export function decodePushStateGossipV1(bytes, maxMessageBytes) {
+    return validatePushStateGossipV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+/** Round-trip helper for `bytesToB64url` consumers wanting the raw coord bytes of a {@link CohortRef}. */
+export function cohortRefCoordBytes(ref) {
+    return b64urlToBytes(ref.coord);
+}
+/** Build a {@link CohortRef} from raw coord (and optional primary) bytes. */
+export function makeCohortRef(coord, primary) {
+    return primary !== undefined
+        ? { coord: bytesToB64url(coord), primary: bytesToB64url(primary) }
+        : { coord: bytesToB64url(coord) };
+}
+//# sourceMappingURL=push-state.js.map