@optimystic/db-core 0.13.5 → 0.14.1

package/dist/src/reactivity/subscriber.js

@@ -0,0 +1,75 @@
+/**
+ * Reactivity — subscriber delivery path (`docs/reactivity.md` §Delivery).
+ *
+ * A subscriber receiving a notification:
+ *  1. **verifies** `sig` against the cached tail-cohort `MembershipCertV1` (the {@link NotificationVerifier}
+ *     owns the **one fetch-and-retry** on a stale cache);
+ *  2. checks `revision == lastRevision + 1`. If not, requests a backfill for the gap
+ *     `[lastRevision + 1, revision]` via the {@link requestBackfill} seam (the `BackfillV1` request shape
+ *     lands in [reactivity-backfill-resume-checkpoints]; this ticket only *detects* the gap and calls the
+ *     hook);
+ *  3. updates `lastRevision` once revisions are contiguous;
+ *  4. surfaces the notification to the application layer.
+ *
+ * Subscribers dedupe by `(collectionId, revision)`; duplicates from forwarder retries are discarded.
+ * A fresh subscription (`lastKnownRev == 0`, uninitialized) adopts the first verified notification as its
+ * baseline rather than demanding a backfill from revision 1.
+ */
+class CollectionSubscriber {
+    deps;
+    last;
+    initialized;
+    constructor(deps) {
+        this.deps = deps;
+        const lastKnownRev = deps.lastKnownRev ?? 0;
+        this.last = lastKnownRev;
+        // A fresh subscribe (lastKnownRev == 0) has no baseline yet; the first verified notification sets it.
+        this.initialized = lastKnownRev > 0;
+    }
+    get lastRevision() {
+        return this.last;
+    }
+    rebaseline(revision) {
+        // A verified checkpoint summarized everything up to `revision`; jump the head forward (never back).
+        if (!this.initialized || revision > this.last) {
+            this.last = revision;
+            this.initialized = true;
+        }
+    }
+    async onNotification(n) {
+        if (n.collectionId !== this.deps.collectionId) {
+            return "foreign";
+        }
+        // Verify first (one fetch-and-retry is internal to the verifier). An untrusted notification is
+        // dropped before any (collectionId, revision) dedupe or lastRevision update.
+        const verdict = await this.deps.verifier.verify(n);
+        if (verdict !== "verified") {
+            return "untrusted";
+        }
+        // Fresh subscription: adopt the first verified notification as the contiguity baseline.
+        if (!this.initialized) {
+            this.initialized = true;
+            this.last = n.revision;
+            this.deps.deliver(n);
+            return "delivered";
+        }
+        // Dedupe by (collectionId, revision): anything at or below the contiguous head is already delivered.
+        if (n.revision <= this.last) {
+            return "duplicate";
+        }
+        // Contiguity check.
+        if (n.revision === this.last + 1) {
+            this.last = n.revision;
+            this.deps.deliver(n);
+            return "delivered";
+        }
+        // Gap: request the missing range (inclusive of `revision`); the backfilled entries re-enter here.
+        this.deps.requestBackfill?.(this.last + 1, n.revision);
+        return "gap";
+    }
+}
+/** Build a {@link ReactivitySubscriber} for one collection. */
+export function createReactivitySubscriber(deps) {
+    return new CollectionSubscriber(deps);
+}
+//# sourceMappingURL=subscriber.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber.js","sourceRoot":"","sources":["../../../src/reactivity/subscriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAoDH,MAAM,oBAAoB;IAII;IAHrB,IAAI,CAAS;IACb,WAAW,CAAU;IAE7B,YAA6B,IAA8B;QAA9B,SAAI,GAAJ,IAAI,CAA0B;QAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,sGAAsG;QACtG,IAAI,CAAC,WAAW,GAAG,YAAY,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,YAAY;QACf,OAAO,IAAI,CAAC,IAAI,CAAC;IAClB,CAAC;IAED,UAAU,CAAC,QAAgB;QAC1B,oGAAoG;QACpG,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACzB,CAAC;IACF,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,CAAiB;QACrC,IAAI,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YAC/C,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,+FAA+F;QAC/F,6EAA6E;QAC7E,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;QAED,wFAAwF;QACxF,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACvB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACrB,OAAO,WAAW,CAAC;QACpB,CAAC;QAED,qGAAqG;QACrG,IAAI,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC7B,OAAO,WAAW,CAAC;QACpB,CAAC;QAED,oBAAoB;QACpB,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAClC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACrB,OAAO,WAAW,CAAC;QACpB,CAAC;QAED,kGAAkG;QAClG,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;QACvD,OAAO,KAAK,CAAC;IACd,CAAC;CACD;AAED,+DAA+D;AAC/D,MAAM,UAAU,0BAA0B,CAAC,IAA8B;IACxE,OAAO,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * Reactivity — subscriber-side subscription state (`docs/reactivity.md` §Subscription).
+ *
+ * Subscribing to a collection is an **ordinary cohort-topic registration** at tier T3 with a reactivity
+ * `appPayload`: `topicId = H(currentTailId(C) ‖ "reactivity")`, the configured TTL (Edge 60 s / Core 90 s),
+ * and the cohort-topic walk-toward-root / willingness / promotion / TTL-renewal all reused unchanged.
+ * This module owns only the subscriber-side bookkeeping struct and the `appPayload` builder; the db-p2p
+ * subscription manager drives the cohort-topic `RegisterV1`.
+ *
+ * `tailIdAtAttach` is the subscriber-side detector for tail rotation (the whole-tree migration the
+ * rotation ticket handles); `cohortEpoch` detects membership drift within the topic.
+ */
+import { type SubscribeAppPayloadV1 } from "./wire.js";
+/** Subscriber-side live state for one active subscription (`docs/reactivity.md` §Subscriber-side state). */
+export interface ActiveSubscription {
+    /** Stable collection identity. */
+    readonly collectionId: Uint8Array;
+    /** Current tail-anchored topic id. */
+    readonly topicId: Uint8Array;
+    /** Tail block id at registration time — detects tail rotation. */
+    readonly tailIdAtAttach: Uint8Array;
+    /** Serving cohort member. */
+    primary: Uint8Array;
+    /** Warm-failover cohort members. */
+    backups: Uint8Array[];
+    /** Cohort member hint set for fast re-attach. */
+    cohortHint: Uint8Array[];
+    /** Cohort epoch for membership-drift detection. */
+    cohortEpoch: Uint8Array;
+    /** Last contiguously-delivered revision. */
+    lastRevision: number;
+    /** Unix ms of the last delivery. */
+    lastDeliveredAt: number;
+    /** Unix ms the subscription attached. */
+    attachedAt: number;
+}
+/** Parameters for building a subscribe `appPayload`. */
+export interface SubscribeParams {
+    /** Collection id, base64url. */
+    readonly collectionId: string;
+    /** Tail block id at attach time, base64url. */
+    readonly tailIdAtAttach: string;
+    /** Last revision already held; `0` for a fresh subscribe. */
+    readonly lastKnownRev?: number;
+    /** Max delta bytes accepted; `0` declines deltas (Edge). */
+    readonly deltaMaxBytes: number;
+}
+/** Build the validated {@link SubscribeAppPayloadV1} for a subscription. */
+export declare function buildSubscribeAppPayload(params: SubscribeParams): SubscribeAppPayloadV1;
+/** Build the opaque `RegisterV1.appPayload` bytes for a subscription. */
+export declare function subscribeAppPayloadBytes(params: SubscribeParams): Uint8Array;
+//# sourceMappingURL=subscription.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../src/reactivity/subscription.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElF,4GAA4G;AAC5G,MAAM,WAAW,kBAAkB;IAClC,kCAAkC;IAClC,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC;IACpC,6BAA6B;IAC7B,OAAO,EAAE,UAAU,CAAC;IACpB,oCAAoC;IACpC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,iDAAiD;IACjD,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,mDAAmD;IACnD,WAAW,EAAE,UAAU,CAAC;IACxB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,qBAAqB,CAQvF;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAE5E"}

package/dist/src/reactivity/subscription.js

@@ -0,0 +1,28 @@
+/**
+ * Reactivity — subscriber-side subscription state (`docs/reactivity.md` §Subscription).
+ *
+ * Subscribing to a collection is an **ordinary cohort-topic registration** at tier T3 with a reactivity
+ * `appPayload`: `topicId = H(currentTailId(C) ‖ "reactivity")`, the configured TTL (Edge 60 s / Core 90 s),
+ * and the cohort-topic walk-toward-root / willingness / promotion / TTL-renewal all reused unchanged.
+ * This module owns only the subscriber-side bookkeeping struct and the `appPayload` builder; the db-p2p
+ * subscription manager drives the cohort-topic `RegisterV1`.
+ *
+ * `tailIdAtAttach` is the subscriber-side detector for tail rotation (the whole-tree migration the
+ * rotation ticket handles); `cohortEpoch` detects membership drift within the topic.
+ */
+import { encodeSubscribeAppPayload } from "./wire.js";
+/** Build the validated {@link SubscribeAppPayloadV1} for a subscription. */
+export function buildSubscribeAppPayload(params) {
+    return {
+        kind: "reactivity",
+        collectionId: params.collectionId,
+        tailIdAtAttach: params.tailIdAtAttach,
+        lastKnownRev: params.lastKnownRev ?? 0,
+        deltaMaxBytes: params.deltaMaxBytes,
+    };
+}
+/** Build the opaque `RegisterV1.appPayload` bytes for a subscription. */
+export function subscribeAppPayloadBytes(params) {
+    return encodeSubscribeAppPayload(buildSubscribeAppPayload(params));
+}
+//# sourceMappingURL=subscription.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.js","sourceRoot":"","sources":["../../../src/reactivity/subscription.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,yBAAyB,EAA8B,MAAM,WAAW,CAAC;AAsClF,4EAA4E;AAC5E,MAAM,UAAU,wBAAwB,CAAC,MAAuB;IAC/D,OAAO;QACN,IAAI,EAAE,YAAY;QAClB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,CAAC;QACtC,aAAa,EAAE,MAAM,CAAC,aAAa;KACnC,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,wBAAwB,CAAC,MAAuB;IAC/D,OAAO,yBAAyB,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC;AACpE,CAAC"}

package/dist/src/reactivity/topic-anchor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Reactivity — rotating, tail-anchored topic.
+ *
+ * Transcribed from `docs/reactivity.md` §Anchor:
+ *
+ * ```
+ * topicId(collection C, tail T) = H(T.blockId ‖ "reactivity")
+ * ```
+ *
+ * Unlike matchmaking (whose anchor is a stable `(kind, label)`), the reactivity anchor **rotates** with
+ * the collection's tail block: when the tail fills and a new tail block is born, `topicId` changes and
+ * the cohort-topic layer treats it as an entirely new topic. The whole-tree migration that follows is
+ * the rotation ticket's concern; this module owns only the pure derivation.
+ *
+ * The resulting `topicId` is fed verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`),
+ * so it is derived with the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
+ * db-core's own SHA-256 truncated to the ring width, **not** a FRET import. The trailing `"reactivity"`
+ * literal domain-separates the reactivity tree from any other application anchoring on the same tail id.
+ *
+ * Concatenation is delimiter-free, exactly as the spec writes it; the constant suffix is unambiguous
+ * because no tail-id byte string can alias a `(tailId, "reactivity")` pair of a different length.
+ *
+ * `reactivityTopicId` is the small pure helper the ticket asks for once and the rotation ticket
+ * ([reactivity-rotation-backpressure-policy]) reuses per-emission — define it here, not at the call site.
+ */
+import type { IRingHash } from "../cohort-topic/ports.js";
+/**
+ * `H(tailId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` for the
+ * reactivity tree anchored on `tailId` (the collection's current tail block id, as raw bytes).
+ *
+ * The shared helper consumed by subscriber attachment, origination, and (per-emission) the rotation
+ * ticket. `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
+ */
+export declare function reactivityTopicId(tailId: Uint8Array, hash?: IRingHash): Uint8Array;
+/** Derives the rotating `topicId` for a collection's current tail. */
+export interface ReactivityTopicAnchor {
+    /** `H(tailId ‖ "reactivity")` for the given tail block id (bytes). */
+    topicId(tailId: Uint8Array): Uint8Array;
+}
+/**
+ * Build a {@link ReactivityTopicAnchor} over the injected hash. db-p2p passes the same {@link IRingHash}
+ * it binds to FRET's `RING_BITS` so the anchor and cohort-topic routing keys line up; the default
+ * constructs db-core's own {@link createRingHash} (256-bit SHA-256).
+ */
+export declare function createReactivityTopicAnchor(hash?: IRingHash): ReactivityTopicAnchor;
+//# sourceMappingURL=topic-anchor.d.ts.map

package/dist/src/reactivity/topic-anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-anchor.d.ts","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAO1D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,SAA4B,GAAG,UAAU,CAMpG;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACrC,sEAAsE;IACtE,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACxC;AAUD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,GAAE,SAA4B,GAAG,qBAAqB,CAErG"}

package/dist/src/reactivity/topic-anchor.js

@@ -0,0 +1,61 @@
+/**
+ * Reactivity — rotating, tail-anchored topic.
+ *
+ * Transcribed from `docs/reactivity.md` §Anchor:
+ *
+ * ```
+ * topicId(collection C, tail T) = H(T.blockId ‖ "reactivity")
+ * ```
+ *
+ * Unlike matchmaking (whose anchor is a stable `(kind, label)`), the reactivity anchor **rotates** with
+ * the collection's tail block: when the tail fills and a new tail block is born, `topicId` changes and
+ * the cohort-topic layer treats it as an entirely new topic. The whole-tree migration that follows is
+ * the rotation ticket's concern; this module owns only the pure derivation.
+ *
+ * The resulting `topicId` is fed verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`),
+ * so it is derived with the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
+ * db-core's own SHA-256 truncated to the ring width, **not** a FRET import. The trailing `"reactivity"`
+ * literal domain-separates the reactivity tree from any other application anchoring on the same tail id.
+ *
+ * Concatenation is delimiter-free, exactly as the spec writes it; the constant suffix is unambiguous
+ * because no tail-id byte string can alias a `(tailId, "reactivity")` pair of a different length.
+ *
+ * `reactivityTopicId` is the small pure helper the ticket asks for once and the rotation ticket
+ * ([reactivity-rotation-backpressure-policy]) reuses per-emission — define it here, not at the call site.
+ */
+import { createRingHash } from "../cohort-topic/ring-hash.js";
+/** Domain-separation suffix mixed into every reactivity anchor. */
+const REACTIVITY_SUFFIX = "reactivity";
+const utf8 = new TextEncoder();
+/**
+ * `H(tailId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` for the
+ * reactivity tree anchored on `tailId` (the collection's current tail block id, as raw bytes).
+ *
+ * The shared helper consumed by subscriber attachment, origination, and (per-emission) the rotation
+ * ticket. `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
+ */
+export function reactivityTopicId(tailId, hash = createRingHash()) {
+    const suffixBytes = utf8.encode(REACTIVITY_SUFFIX);
+    const input = new Uint8Array(tailId.length + suffixBytes.length);
+    input.set(tailId, 0);
+    input.set(suffixBytes, tailId.length);
+    return hash.H(input);
+}
+class HashReactivityTopicAnchor {
+    hash;
+    constructor(hash) {
+        this.hash = hash;
+    }
+    topicId(tailId) {
+        return reactivityTopicId(tailId, this.hash);
+    }
+}
+/**
+ * Build a {@link ReactivityTopicAnchor} over the injected hash. db-p2p passes the same {@link IRingHash}
+ * it binds to FRET's `RING_BITS` so the anchor and cohort-topic routing keys line up; the default
+ * constructs db-core's own {@link createRingHash} (256-bit SHA-256).
+ */
+export function createReactivityTopicAnchor(hash = createRingHash()) {
+    return new HashReactivityTopicAnchor(hash);
+}
+//# sourceMappingURL=topic-anchor.js.map

package/dist/src/reactivity/topic-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-anchor.js","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,mEAAmE;AACnE,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAEvC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAkB,EAAE,OAAkB,cAAc,EAAE;IACvF,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACjE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACrB,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC;AAQD,MAAM,yBAAyB;IACD;IAA7B,YAA6B,IAAe;QAAf,SAAI,GAAJ,IAAI,CAAW;IAAG,CAAC;IAEhD,OAAO,CAAC,MAAkB;QACzB,OAAO,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAkB,cAAc,EAAE;IAC7E,OAAO,IAAI,yBAAyB,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC"}

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

@@ -0,0 +1,41 @@
+/**
+ * Reactivity — subscriber/forwarder notification verification seam
+ * (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
+ *
+ * A forwarder and a subscriber both verify a notification's threshold signature against the **tail
+ * cohort's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
+ * signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
+ * ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
+ * cert, so this module is a thin adapter: derive the tail cohort's `coord_0(_, topicId)` from the
+ * notification's `tailId`, then hand `(signers, coord, tier, digest, sig)` to the verifier.
+ *
+ * The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
+ * hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
+ * as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
+ * seam is exposed for bindings that carry signers in a different encoding.
+ */
+import { Tier } from "../cohort-topic/tiers.js";
+import type { IRingHash } from "../cohort-topic/ports.js";
+import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
+import type { NotificationV1 } from "./wire.js";
+/** Verifies a {@link NotificationV1}'s threshold signature against the tail cohort's membership. */
+export interface NotificationVerifier {
+    /** `"verified"` iff `sig` is a valid `≥ minSigs` cohort signature over the commit digest. */
+    verify(n: NotificationV1): Promise<VerifyResult>;
+}
+/** Construction inputs for the default {@link NotificationVerifier}. */
+export interface NotificationVerifierDeps {
+    /** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
+    readonly verifier: MembershipVerifier;
+    /** Ring hash for `topicId` / `coord_0` derivation. Default db-core 256-bit SHA-256. */
+    readonly hash?: IRingHash;
+    /** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
+    readonly fanout?: number;
+    /** Reactivity runs at T3; overridable for tests. */
+    readonly tier?: Tier;
+    /** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
+    readonly signersToBytes?: (signer: string) => Uint8Array;
+}
+/** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
+export declare function createNotificationVerifier(deps: NotificationVerifierDeps): NotificationVerifier;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAE/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,oGAAoG;AACpG,MAAM,WAAW,oBAAoB;IACpC,6FAA6F;IAC7F,MAAM,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACjD;AAED,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACxC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,uFAAuF;IACvF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;CACzD;AAyBD,uGAAuG;AACvG,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAE/F"}

package/dist/src/reactivity/verify.js

@@ -0,0 +1,48 @@
+/**
+ * Reactivity — subscriber/forwarder notification verification seam
+ * (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
+ *
+ * A forwarder and a subscriber both verify a notification's threshold signature against the **tail
+ * cohort's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
+ * signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
+ * ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
+ * cert, so this module is a thin adapter: derive the tail cohort's `coord_0(_, topicId)` from the
+ * notification's `tailId`, then hand `(signers, coord, tier, digest, sig)` to the verifier.
+ *
+ * The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
+ * hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
+ * as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
+ * seam is exposed for bindings that carry signers in a different encoding.
+ */
+import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
+import { createRingHash } from "../cohort-topic/ring-hash.js";
+import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
+import { Tier } from "../cohort-topic/tiers.js";
+import { reactivityTopicId } from "./topic-anchor.js";
+class MembershipNotificationVerifier {
+    deps;
+    addressing;
+    hash;
+    tier;
+    signersToBytes;
+    constructor(deps) {
+        this.deps = deps;
+        this.hash = deps.hash ?? createRingHash();
+        this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
+        this.tier = deps.tier ?? Tier.T3;
+        this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
+    }
+    async verify(n) {
+        const topicId = reactivityTopicId(b64urlToBytes(n.tailId), this.hash);
+        const expectedCoord = this.addressing.coord0(topicId);
+        const signers = n.signers.map(this.signersToBytes);
+        const payload = b64urlToBytes(n.digest);
+        const sig = b64urlToBytes(n.sig);
+        return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig);
+    }
+}
+/** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
+export function createNotificationVerifier(deps) {
+    return new MembershipNotificationVerifier(deps);
+}
+//# sourceMappingURL=verify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAGhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAuBtD,MAAM,8BAA8B;IAMN;IALZ,UAAU,CAA0C;IACpD,IAAI,CAAY;IAChB,IAAI,CAAO;IACX,cAAc,CAAiC;IAEhE,YAA6B,IAA8B;QAA9B,SAAI,GAAJ,IAAI,CAA0B;QAC1D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,IAAI,cAAc,CAAC,CAAC;QACjF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,aAAa,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,CAAiB;QAC7B,MAAM,OAAO,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAC1F,CAAC;CACD;AAED,uGAAuG;AACvG,MAAM,UAAU,0BAA0B,CAAC,IAA8B;IACxE,OAAO,IAAI,8BAA8B,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC"}

package/dist/src/reactivity/wire-validate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Reactivity — shared wire-validation primitives.
+ *
+ * The reactivity message codecs ({@link import("./wire.js")}, {@link import("./push-state.js")},
+ * {@link import("./backfill.js")}, {@link import("./resume.js")}) all decode untrusted JSON into
+ * validated V1 shapes with the same structural checks. Those primitives live here so each codec module
+ * narrows fields the same way (DRY) — every helper throws {@link CohortWireError} on a defect, matching
+ * the cohort-topic wire conventions (base64url byte fields, finite/integer numbers, `v: 1`).
+ */
+/** Throw a {@link CohortWireError} with `message`. */
+export declare function failWire(message: string): never;
+/** Narrow `value` to a plain object (not null, not an array), or throw. */
+export declare function asObject(value: unknown, what: string): Record<string, unknown>;
+/** Require `obj.v === 1`. */
+export declare function requireV1(obj: Record<string, unknown>, what: string): void;
+/** Require `obj[key]` to be a string; returns it. */
+export declare function reqString(obj: Record<string, unknown>, key: string, what: string): string;
+/** Require `obj[key]` to be a boolean; returns it. */
+export declare function reqBoolean(obj: Record<string, unknown>, key: string, what: string): boolean;
+/** Require `obj[key]` to be a finite number; returns it. */
+export declare function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number;
+/** Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. */
+export declare function reqIntInRange(obj: Record<string, unknown>, key: string, what: string, min: number, max?: number): number;
+/** Assert a base64url string decodes cleanly; returns it unchanged. */
+export declare function b64urlField(value: string, key: string, what: string): string;
+/** Require `value` to be an array of strings; returns it (callers map each element through {@link b64urlField}). */
+export declare function reqStringArray(value: unknown, key: string, what: string): string[];
+//# sourceMappingURL=wire-validate.d.ts.map

package/dist/src/reactivity/wire-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-validate.d.ts","sourceRoot":"","sources":["../../../src/reactivity/wire-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAE/C;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAK9E;AAED,6BAA6B;AAC7B,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI1E;AAED,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMzF;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAM3F;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/F;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAOxH;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAO5E;AAED,oHAAoH;AACpH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKlF"}

package/dist/src/reactivity/wire-validate.js

@@ -0,0 +1,79 @@
+/**
+ * Reactivity — shared wire-validation primitives.
+ *
+ * The reactivity message codecs ({@link import("./wire.js")}, {@link import("./push-state.js")},
+ * {@link import("./backfill.js")}, {@link import("./resume.js")}) all decode untrusted JSON into
+ * validated V1 shapes with the same structural checks. Those primitives live here so each codec module
+ * narrows fields the same way (DRY) — every helper throws {@link CohortWireError} on a defect, matching
+ * the cohort-topic wire conventions (base64url byte fields, finite/integer numbers, `v: 1`).
+ */
+import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
+import { CohortWireError } from "../cohort-topic/wire/validate.js";
+/** Throw a {@link CohortWireError} with `message`. */
+export function failWire(message) {
+    throw new CohortWireError(message);
+}
+/** Narrow `value` to a plain object (not null, not an array), or throw. */
+export function asObject(value, what) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        failWire(`${what}: expected an object`);
+    }
+    return value;
+}
+/** Require `obj.v === 1`. */
+export function requireV1(obj, what) {
+    if (obj["v"] !== 1) {
+        failWire(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
+    }
+}
+/** Require `obj[key]` to be a string; returns it. */
+export function reqString(obj, key, what) {
+    const value = obj[key];
+    if (typeof value !== "string") {
+        failWire(`${what}: field "${key}" must be a string`);
+    }
+    return value;
+}
+/** Require `obj[key]` to be a boolean; returns it. */
+export function reqBoolean(obj, key, what) {
+    const value = obj[key];
+    if (typeof value !== "boolean") {
+        failWire(`${what}: field "${key}" must be a boolean`);
+    }
+    return value;
+}
+/** Require `obj[key]` to be a finite number; returns it. */
+export function reqFiniteNumber(obj, key, what) {
+    const value = obj[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        failWire(`${what}: field "${key}" must be a finite number`);
+    }
+    return value;
+}
+/** Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. */
+export function reqIntInRange(obj, key, what, min, max) {
+    const value = reqFiniteNumber(obj, key, what);
+    if (!Number.isInteger(value) || value < min || (max !== undefined && value > max)) {
+        const bound = max === undefined ? `>= ${min}` : `in ${min}..${max}`;
+        failWire(`${what}: field "${key}" must be an integer ${bound}, got ${value}`);
+    }
+    return value;
+}
+/** Assert a base64url string decodes cleanly; returns it unchanged. */
+export function b64urlField(value, key, what) {
+    try {
+        b64urlToBytes(value);
+    }
+    catch {
+        failWire(`${what}: field "${key}" is not valid base64url`);
+    }
+    return value;
+}
+/** Require `value` to be an array of strings; returns it (callers map each element through {@link b64urlField}). */
+export function reqStringArray(value, key, what) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        failWire(`${what}: field "${key}" must be an array of strings`);
+    }
+    return value;
+}
+//# sourceMappingURL=wire-validate.js.map

package/dist/src/reactivity/wire-validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-validate.js","sourceRoot":"","sources":["../../../src/reactivity/wire-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAEnE,sDAAsD;AACtD,MAAM,UAAU,QAAQ,CAAC,OAAe;IACvC,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAE,IAAY;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,QAAQ,CAAC,GAAG,IAAI,sBAAsB,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,KAAgC,CAAC;AACzC,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,SAAS,CAAC,GAA4B,EAAE,IAAY;IACnE,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,QAAQ,CAAC,GAAG,IAAI,2BAA2B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;AACF,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,SAAS,CAAC,GAA4B,EAAE,GAAW,EAAE,IAAY;IAChF,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,QAAQ,CAAC,GAAG,IAAI,YAAY,GAAG,oBAAoB,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,UAAU,CAAC,GAA4B,EAAE,GAAW,EAAE,IAAY;IACjF,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,QAAQ,CAAC,GAAG,IAAI,YAAY,GAAG,qBAAqB,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,eAAe,CAAC,GAA4B,EAAE,GAAW,EAAE,IAAY;IACtF,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1D,QAAQ,CAAC,GAAG,IAAI,YAAY,GAAG,2BAA2B,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,aAAa,CAAC,GAA4B,EAAE,GAAW,EAAE,IAAY,EAAE,GAAW,EAAE,GAAY;IAC/G,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,GAAG,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC;QACnF,MAAM,KAAK,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,KAAK,GAAG,EAAE,CAAC;QACpE,QAAQ,CAAC,GAAG,IAAI,YAAY,GAAG,wBAAwB,KAAK,SAAS,KAAK,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,GAAW,EAAE,IAAY;IACnE,IAAI,CAAC;QACJ,aAAa,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACR,QAAQ,CAAC,GAAG,IAAI,YAAY,GAAG,0BAA0B,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,oHAAoH;AACpH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,GAAW,EAAE,IAAY;IACvE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC/E,QAAQ,CAAC,GAAG,IAAI,YAAY,GAAG,+BAA+B,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,KAAiB,CAAC;AAC1B,CAAC"}

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

@@ -0,0 +1,102 @@
+/**
+ * Reactivity — V1 wire types, codecs, and per-message validation.
+ *
+ * Transcribed from `docs/reactivity.md` §Wire formats. Reactivity reuses the cohort-topic `RegisterV1`
+ * / `RenewV1` envelopes **unchanged**; the reactivity-specific shapes live in two places:
+ *
+ *  1. **Subscribe app payload** ({@link SubscribeAppPayloadV1}) carried opaquely inside
+ *     `RegisterV1.appPayload`. Serialized to UTF-8 JSON bytes and handed to the cohort-topic
+ *     {@link import("../cohort-topic/service.js").RegisterRequest}`.appPayload` slot, which base64url-encodes
+ *     it on the wire. It is therefore **not** length-framed here — the cohort-topic `RegisterV1` frame
+ *     wraps it. The subscribe RPC's authentication (peer-key signature over `correlationId` + `timestamp`)
+ *     is the cohort-topic `RegisterV1` envelope's job, so the payload itself carries no signature.
+ *
+ *  2. **Notification** ({@link NotificationV1}) sent as a standalone RPC over the reactivity application
+ *     protocol. It rides the same length-prefixed UTF-8 JSON framing as cohort-topic messages
+ *     ({@link encodeCohortMessage}). Its `sig` is **bit-for-bit** the commit certificate's threshold
+ *     signature — reactivity never re-signs (`docs/reactivity.md` §Notification origination).
+ *
+ * Conventions (matching the cohort-topic wire conventions): all JSON, byte fields base64url (no
+ * padding), unix-millisecond timestamps, per-message structural validation on decode, byte-fidelity
+ * round-trips (encode→decode→encode is stable). `collectionId` / `tailId` travel as the collection's
+ * base64url block ids verbatim. The `BackfillV1` / `ResumeV1` codecs belong to the sibling tickets.
+ */
+/** Ceiling for an opaque subscribe app payload, guarding decode allocation. */
+export declare const DEFAULT_MAX_SUBSCRIBE_PAYLOAD_BYTES: number;
+/** A subscriber's registration payload (`RegisterV1.appPayload`, `kind == "reactivity"`). */
+export interface SubscribeAppPayloadV1 {
+    kind: "reactivity";
+    /** Stable collection identity, base64url (the collection's id block id). */
+    collectionId: string;
+    /** Tail block id at registration time, base64url (the subscriber-side rotation detector). */
+    tailIdAtAttach: string;
+    /** Last revision the subscriber already holds; `0` for a fresh subscribe. */
+    lastKnownRev: number;
+    /** Max delta bytes the subscriber accepts; `0` declines delta payloads (Edge). */
+    deltaMaxBytes: number;
+}
+/** The tail cohort's rotation pre-announce, carried inside (and signed by) a {@link NotificationV1}. */
+export interface RotationHintV1 {
+    /** New tail block id the topic anchor is rotating to, base64url. */
+    newTailId: string;
+    /** Revision at which the new tail becomes effective. */
+    effectiveAtRevision: number;
+}
+/** A signed change notification fanned out through the reactivity tree (`docs/reactivity.md` §Notification origination). */
+export interface NotificationV1 {
+    v: 1;
+    /** Collection id, base64url. */
+    collectionId: string;
+    /** Tail block id the reactivity topic is anchored on, base64url. */
+    tailId: string;
+    /** Per-collection monotonic revision. */
+    revision: number;
+    /**
+     * The commit-vote **signed payload** `utf8(commitHash + ":approve")`, base64url — the exact bytes the
+     * threshold signature {@link sig} was computed over. A subscriber threshold-verifies {@link sig} over
+     * `b64urlToBytes(digest)`, so this reproduces the signed image against real Ed25519.
+     */
+    digest: string;
+    /** Optional bounded delta, base64url; omitted when `delta_max == 0` or the collection declines it. */
+    delta?: string;
+    /** Unix ms. */
+    timestamp: number;
+    /** Threshold signature, base64url — **= the commit cert**, never re-signed. */
+    sig: string;
+    /** PeerIds contributing to {@link sig}, base64url of the cohort member-id bytes. */
+    signers: string[];
+    /** Tail-rotation pre-announce, when this notification carries one (rotation ticket fills it). */
+    rotationHint?: RotationHintV1;
+    /**
+     * `true` iff this notification announces a durable **invalidation** (a reversal of a previously
+     * committed action proven invalid by dispute) rather than an ordinary commit
+     * (`docs/reactivity.md` §Notification origination, `docs/right-is-right.md` §Durable Invalidation).
+     * An invalidation is a committed collection change like any other and rides the same notification
+     * path, reusing the **invalidation's** commit cert as {@link sig} (never re-signed) — so it verifies
+     * against the tail cohort exactly like a commit notification. The flag is a hint that lets a
+     * subscriber react (drop derived results + resubmit) rather than merely refresh; a subscriber that
+     * ignores it still re-reads the authoritative reverted state. Omitted (falsy) on commit notifications.
+     */
+    invalidation?: boolean;
+    /**
+     * When {@link invalidation} is set, the original action id that was reversed
+     * (`InvalidationEntry.invalidatedActionId`). Lets a client dedup/coalesce the several cascade
+     * notifications a single dispute can produce by the action they reverse. Omitted on commits.
+     */
+    invalidatedActionId?: string;
+}
+/** Narrow an already-parsed value to {@link SubscribeAppPayloadV1}, throwing on any defect. */
+export declare function validateSubscribeAppPayloadV1(value: unknown): SubscribeAppPayloadV1;
+/** Serialize a {@link SubscribeAppPayloadV1} to the opaque UTF-8 JSON bytes for `RegisterV1.appPayload`. */
+export declare function encodeSubscribeAppPayload(payload: SubscribeAppPayloadV1): Uint8Array;
+/** Decode opaque `RegisterV1.appPayload` bytes back to a validated {@link SubscribeAppPayloadV1}. */
+export declare function decodeSubscribeAppPayload(bytes: Uint8Array, maxBytes?: number): SubscribeAppPayloadV1;
+/** Narrow an already-parsed value to {@link NotificationV1}, throwing on any defect. */
+export declare function validateNotificationV1(value: unknown): NotificationV1;
+/** Validate an array of {@link NotificationV1} (the `entries`/`recentEntries` carried in backfill/resume replies). */
+export declare function validateNotificationArray(value: unknown, what: string): NotificationV1[];
+/** Encode a {@link NotificationV1} as a length-prefixed UTF-8 JSON frame. */
+export declare function encodeNotificationV1(msg: NotificationV1, maxMessageBytes?: number): Uint8Array;
+/** Decode a length-prefixed {@link NotificationV1} frame. */
+export declare function decodeNotificationV1(bytes: Uint8Array, maxMessageBytes?: number): NotificationV1;
+//# sourceMappingURL=wire.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/reactivity/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAsBH,+EAA+E;AAC/E,eAAO,MAAM,mCAAmC,QAAY,CAAC;AAI7D,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;CACtB;AAID,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC9B,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,mBAAmB,EAAE,MAAM,CAAC;CAC5B;AAED,4HAA4H;AAC5H,MAAM,WAAW,cAAc;IAC9B,CAAC,EAAE,CAAC,CAAC;IACL,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iGAAiG;IACjG,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAgBD,+FAA+F;AAC/F,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAanF;AAED,4GAA4G;AAC5G,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAEpF;AAED,qGAAqG;AACrG,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,MAA4C,GAAG,qBAAqB,CAE1I;AAsBD,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA4BrE;AAED,sHAAsH;AACtH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAKxF;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,EAAE,eAAe,GAAE,MAAkC,GAAG,UAAU,CAEzH;AAED,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,cAAc,CAEhG"}