@optimystic/db-core 0.13.5 → 0.14.1

package/dist/src/reactivity/config.js

@@ -0,0 +1,135 @@
+/**
+ * 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 { 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 default reactivity config (`docs/reactivity.md` §Configuration). */
+export const DEFAULT_REACTIVITY_CONFIG = {
+    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, config = DEFAULT_REACTIVITY_CONFIG) {
+    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, config = DEFAULT_REACTIVITY_CONFIG) {
+    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 = {}) {
+    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 = {}) {
+    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 = {}) {
+    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);
+}
+//# sourceMappingURL=config.js.map

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+/** 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;
+}
+/** Build a {@link DedupeWindow} with the configured (default {@link DEDUPE_WINDOW_DEFAULT}) span. */
+export declare function createDedupeWindow(windowSize?: number): DedupeWindow;
+//# sourceMappingURL=dedupe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../../src/reactivity/dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,wDAAwD;AACxD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,CAAC;AAEpD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrF;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAClD;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC;IAC5D,2BAA2B;IAC3B,SAAS,IAAI,aAAa,CAAC;IAC3B,uGAAuG;IACvG,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CAClC;AA+ED,qGAAqG;AACrG,wBAAgB,kBAAkB,CAAC,UAAU,GAAE,MAA8B,GAAG,YAAY,CAE3F"}

package/dist/src/reactivity/dedupe.js

@@ -0,0 +1,90 @@
+/**
+ * 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";
+class SlidingDedupeWindow {
+    windowSize;
+    /** key → revision, for window-bounded eviction. */
+    seen = new Map();
+    highest = -1;
+    constructor(windowSize) {
+        if (!Number.isInteger(windowSize) || windowSize < 1) {
+            throw new RangeError(`reactivity dedupe: windowSize must be an integer >= 1, got ${windowSize}`);
+        }
+        this.windowSize = windowSize;
+    }
+    get highestRevision() {
+        return this.highest;
+    }
+    get size() {
+        return this.seen.size;
+    }
+    has(revision, sigDigest) {
+        return this.seen.has(keyOf(revision, sigDigest));
+    }
+    observe(revision, sigDigest) {
+        const key = keyOf(revision, sigDigest);
+        if (this.seen.has(key)) {
+            return "duplicate";
+        }
+        this.insert(key, revision);
+        return "forward";
+    }
+    serialize() {
+        return {
+            highestRevision: this.highest,
+            entries: [...this.seen].map(([key, rev]) => ({ key, revision: rev })),
+        };
+    }
+    merge(state) {
+        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();
+    }
+    insert(key, revision) {
+        if (revision > this.highest) {
+            this.highest = revision;
+        }
+        this.seen.set(key, revision);
+        this.evictBelowWindow();
+    }
+    /** Retain only revisions within `[highest - windowSize + 1, highest]`. */
+    evictBelowWindow() {
+        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, sigDigest) {
+    return `${revision}:${sigDigest}`;
+}
+/** Build a {@link DedupeWindow} with the configured (default {@link DEDUPE_WINDOW_DEFAULT}) span. */
+export function createDedupeWindow(windowSize = DEDUPE_WINDOW_DEFAULT) {
+    return new SlidingDedupeWindow(windowSize);
+}
+//# sourceMappingURL=dedupe.js.map

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"forwarder.d.ts","sourceRoot":"","sources":["../../../src/reactivity/forwarder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,6DAA6D;AAC7D,MAAM,MAAM,eAAe;AAC1B,gEAAgE;AAC9D,SAAS;AACX,0FAA0F;GACxF,WAAW;AACb,gFAAgF;GAC9E,WAAW,CAAC;AAEf,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAClE;AAED,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,qGAAqG;IACrG,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC1B;AA6BD,gGAAgG;AAChG,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,mBAAmB,CAE5F;AAED,mGAAmG;AACnG,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAEjF"}

package/dist/src/reactivity/forwarder.js

@@ -0,0 +1,52 @@
+/**
+ * Reactivity — forwarder receive path (`docs/reactivity.md` §Propagation).
+ *
+ * A receiving forwarder primary, for each inbound notification:
+ *  1. **verifies** the threshold signature against the tail cohort's `MembershipCertV1`;
+ *  2. runs the **dedupe** check (sliding `(revision, sigDigest)` window);
+ *  3. **appends** to the replay buffer;
+ *  4. **forwards the unmodified notification** to its own direct subscribers and child cohorts.
+ *
+ * This module owns steps 1–3 and the forward *decision* (step 4's transport — dialing each subscriber's
+ * primary and each child cohort — is the db-p2p binding). Forwarders never re-sign: a compromised
+ * forwarder can drop or delay, but cannot forge. An unverifiable notification is dropped **before**
+ * touching the dedupe set or buffer, so a forged payload can neither poison dedupe nor occupy a ring
+ * slot. The buffer + dedupe set are gossiped across the cohort by the host's gossip cadence (see
+ * {@link PushState}), so any member can serve a replay.
+ */
+import { dedupeKey, sigDigest } from "./notification.js";
+class PushStateForwarder {
+    deps;
+    state;
+    constructor(deps) {
+        this.deps = deps;
+        this.state = deps.state;
+    }
+    async receive(n, now) {
+        // 1. Verify end-to-end before any state mutation — a forged notification touches nothing.
+        const verdict = await this.deps.verifier.verify(n);
+        if (verdict !== "verified") {
+            return "untrusted";
+        }
+        // 2. Dedupe on `(revision, sigDigest)`. Already-seen → drop silently.
+        const digest = sigDigest(n.sig, this.deps.hash);
+        if (this.state.dedupe.observe(n.revision, digest) === "duplicate") {
+            return "duplicate";
+        }
+        // 3. Append the full signed notification to the replay ring (gossiped across the cohort).
+        this.state.replayBuffer.append({ revision: n.revision, payload: n, receivedAt: now });
+        if (n.revision > this.state.lastRevision) {
+            this.state.lastRevision = n.revision;
+        }
+        return "forward";
+    }
+}
+/** Build a {@link ReactivityForwarder} over a collection's {@link PushState} and a verifier. */
+export function createReactivityForwarder(deps) {
+    return new PushStateForwarder(deps);
+}
+/** The dedupe key a forwarder would compute for a notification (exposed for tests/diagnostics). */
+export function notificationDedupeKey(n, hash) {
+    return dedupeKey(n.revision, n.sig, hash);
+}
+//# sourceMappingURL=forwarder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"forwarder.js","sourceRoot":"","sources":["../../../src/reactivity/forwarder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAkCzD,MAAM,kBAAkB;IAGM;IAFpB,KAAK,CAAY;IAE1B,YAA6B,IAA6B;QAA7B,SAAI,GAAJ,IAAI,CAAyB;QACzD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,CAAiB,EAAE,GAAW;QAC3C,0FAA0F;QAC1F,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACnD,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;YAC5B,OAAO,WAAW,CAAC;QACpB,CAAC;QACD,sEAAsE;QACtE,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,WAAW,EAAE,CAAC;YACnE,OAAO,WAAW,CAAC;QACpB,CAAC;QACD,0FAA0F;QAC1F,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;YAC1C,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,QAAQ,CAAC;QACtC,CAAC;QACD,OAAO,SAAS,CAAC;IAClB,CAAC;CACD;AAED,gGAAgG;AAChG,MAAM,UAAU,yBAAyB,CAAC,IAA6B;IACtE,OAAO,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,qBAAqB,CAAC,CAAiB,EAAE,IAAgB;IACxE,OAAO,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC3C,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/reactivity/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/src/reactivity/index.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/reactivity/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

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

@@ -0,0 +1,72 @@
+/**
+ * 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 type { IRingHash } from "../cohort-topic/ports.js";
+import type { CollectionChangeEvent, CommitCert } from "../transactor/change-notifier.js";
+import type { NotificationV1, RotationHintV1 } from "./wire.js";
+/** Per-emission context the origination point supplies alongside the bridge's event + cert. */
+export interface OriginationContext {
+    /** Current tail block id (base64url) the reactivity topic is anchored on. */
+    readonly tailId: string;
+    /** Emission timestamp (unix ms). */
+    readonly timestamp: number;
+    /**
+     * Per-collection delta budget (bytes). `0` ⇒ omit `delta` entirely (Edge profile, or a collection
+     * that declines deltas). Origination MUST respect a `deltaMaxBytes` of `0` by omitting the field.
+     */
+    readonly deltaMaxBytes: number;
+    /** Optional bounded delta (raw bytes); included only when within `deltaMaxBytes` and `> 0`. */
+    readonly delta?: Uint8Array;
+    /** Tail-rotation pre-announce to embed (rotation ticket supplies it). */
+    readonly rotationHint?: RotationHintV1;
+    /**
+     * Map a {@link CommitCert} signer (the cluster's peer-id string keying its commit vote) to the
+     * base64url cohort member-id bytes the subscriber's membership verifier compares against. Default:
+     * identity (the signer is already base64url) — db-p2p supplies `s ⇒ bytesToB64url(peerIdToBytes(s))`.
+     */
+    readonly encodeSigner?: (signer: string) => string;
+}
+/**
+ * Assemble the {@link NotificationV1} for one committed change, reusing the commit cert's threshold
+ * signature unchanged.
+ *
+ * `digest` carries the commit-vote **signed payload** the threshold signature was computed over —
+ * `commitCert.signedPayload`, the cluster's per-member `utf8(commitHash + ":approve")` byte image,
+ * identical across all approving signers. Because the verifier recomputes the cohort threshold check over
+ * exactly these bytes (`payload = b64urlToBytes(n.digest)`), a subscriber's **real** Ed25519
+ * threshold-verify over `digest` reproduces the signed image and succeeds — the cluster↔reactivity
+ * integration seam is **closed** (no pass-crypto stub required). The hint-only contract still holds for
+ * the optional `delta`: deltas are advisory; the digest + threshold signature are the authoritative proof.
+ */
+export declare function buildNotificationV1(event: CollectionChangeEvent, commitCert: CommitCert, ctx: OriginationContext): NotificationV1;
+/**
+ * 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 declare function sigDigest(sig: string, hash?: IRingHash): string;
+/** The dedupe-set key for a notification: `${revision}:${sigDigest(sig)}`. */
+export declare function dedupeKey(revision: number, sig: string, hash?: IRingHash): string;
+/**
+ * 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 declare function coalesceInvalidatedActionIds(notifications: Iterable<NotificationV1>): string[];
+//# sourceMappingURL=notification.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notification.d.ts","sourceRoot":"","sources":["../../../src/reactivity/notification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAIhE,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CACnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,kBAAkB,GAAG,cAAc,CA4BjI;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,SAA4B,GAAG,MAAM,CAEjF;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAEjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,MAAM,EAAE,CAU9F"}