@optimystic/db-core 0.22.0 → 0.24.0

package/src/reactivity/verify.ts

@@ -1,73 +1,73 @@
-/**
- * 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 type { IRingHash } from "../cohort-topic/ports.js";
-import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
-import { reactivityTopicId } from "./topic-anchor.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;
-}
-
-class MembershipNotificationVerifier implements NotificationVerifier {
-	private readonly addressing: ReturnType<typeof createTierAddressing>;
-	private readonly hash: IRingHash;
-	private readonly tier: Tier;
-	private readonly signersToBytes: (signer: string) => Uint8Array;
-
-	constructor(private readonly deps: NotificationVerifierDeps) {
-		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: NotificationV1): Promise<VerifyResult> {
-		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: NotificationVerifierDeps): NotificationVerifier {
-	return new MembershipNotificationVerifier(deps);
-}
+/**
+ * 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 type { IRingHash } from "../cohort-topic/ports.js";
+import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
+import { reactivityTopicId } from "./topic-anchor.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;
+}
+
+class MembershipNotificationVerifier implements NotificationVerifier {
+	private readonly addressing: ReturnType<typeof createTierAddressing>;
+	private readonly hash: IRingHash;
+	private readonly tier: Tier;
+	private readonly signersToBytes: (signer: string) => Uint8Array;
+
+	constructor(private readonly deps: NotificationVerifierDeps) {
+		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: NotificationV1): Promise<VerifyResult> {
+		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: NotificationVerifierDeps): NotificationVerifier {
+	return new MembershipNotificationVerifier(deps);
+}

package/src/reactivity/wire-validate.ts

@@ -1,13 +1,13 @@
-/**
- * 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")}, plus checkpoint / rotation / recover)
- * decode untrusted JSON into validated V1 shapes with the same structural checks the rest of the
- * substrate uses. Those generic primitives now live in one place —
- * {@link import("../cohort-topic/wire/primitives.js")} — so a hardening tweak lands once; this module is
- * a thin re-export kept so the reactivity codecs import from a sibling path. Every helper throws
- * {@link CohortWireError} on a defect (base64url byte fields, finite/integer numbers, `v: 1`).
- */
-
-export * from "../cohort-topic/wire/primitives.js";
+/**
+ * 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")}, plus checkpoint / rotation / recover)
+ * decode untrusted JSON into validated V1 shapes with the same structural checks the rest of the
+ * substrate uses. Those generic primitives now live in one place —
+ * {@link import("../cohort-topic/wire/primitives.js")} — so a hardening tweak lands once; this module is
+ * a thin re-export kept so the reactivity codecs import from a sibling path. Every helper throws
+ * {@link CohortWireError} on a defect (base64url byte fields, finite/integer numbers, `v: 1`).
+ */
+
+export * from "../cohort-topic/wire/primitives.js";

package/src/reactivity/wire.ts

@@ -1,224 +1,224 @@
-/**
- * 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.
- */
-
-import {
-	decodeCohortMessage,
-	encodeCohortMessage,
-	DEFAULT_MAX_MESSAGE_BYTES,
-} from "../cohort-topic/wire/codec.js";
-import {
-	asObject,
-	b64urlField,
-	failWire as fail,
-	reqBool,
-	reqFiniteNumber,
-	reqIntInRange,
-	reqString,
-	reqStringArray,
-	requireV1,
-} from "./wire-validate.js";
-
-const utf8Encoder = new TextEncoder();
-const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
-
-/** Ceiling for an opaque subscribe app payload, guarding decode allocation. */
-export const DEFAULT_MAX_SUBSCRIBE_PAYLOAD_BYTES = 64 * 1024;
-
-// --- Subscribe app payload (carried inside cohort-topic RegisterV1.appPayload) ---
-
-/** 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;
-}
-
-// --- Notification (length-framed RPC) ---
-
-/** 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;
-}
-
-// --- validation helpers ---
-// Generic primitives live in ./wire-validate.js (shared across the reactivity codecs); the
-// notification-specific narrowing stays here next to the type it produces.
-
-function validateRotationHint(value: unknown, what: string): RotationHintV1 {
-	const obj = asObject(value, what);
-	return {
-		newTailId: b64urlField(reqString(obj, "newTailId", what), "newTailId", what),
-		effectiveAtRevision: reqIntInRange(obj, "effectiveAtRevision", what, 0),
-	};
-}
-
-// --- Subscribe app payload (opaque RegisterV1.appPayload bytes) ---
-
-/** Narrow an already-parsed value to {@link SubscribeAppPayloadV1}, throwing on any defect. */
-export function validateSubscribeAppPayloadV1(value: unknown): SubscribeAppPayloadV1 {
-	const what = "SubscribeAppPayloadV1";
-	const obj = asObject(value, what);
-	if (obj["kind"] !== "reactivity") {
-		fail(`${what}: field "kind" must be exactly "reactivity"`);
-	}
-	return {
-		kind: "reactivity",
-		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
-		tailIdAtAttach: b64urlField(reqString(obj, "tailIdAtAttach", what), "tailIdAtAttach", what),
-		lastKnownRev: reqIntInRange(obj, "lastKnownRev", what, 0),
-		deltaMaxBytes: reqIntInRange(obj, "deltaMaxBytes", what, 0),
-	};
-}
-
-/** Serialize a {@link SubscribeAppPayloadV1} to the opaque UTF-8 JSON bytes for `RegisterV1.appPayload`. */
-export function encodeSubscribeAppPayload(payload: SubscribeAppPayloadV1): Uint8Array {
-	return utf8Encoder.encode(JSON.stringify(validateSubscribeAppPayloadV1(payload)));
-}
-
-/** Decode opaque `RegisterV1.appPayload` bytes back to a validated {@link SubscribeAppPayloadV1}. */
-export function decodeSubscribeAppPayload(bytes: Uint8Array, maxBytes: number = DEFAULT_MAX_SUBSCRIBE_PAYLOAD_BYTES): SubscribeAppPayloadV1 {
-	return validateSubscribeAppPayloadV1(parseJsonBytes(bytes, maxBytes, "SubscribeAppPayloadV1"));
-}
-
-/** Parse opaque (non-framed) UTF-8 JSON payload bytes, rejecting oversized/invalid input. */
-function parseJsonBytes(bytes: Uint8Array, maxBytes: number, what: string): unknown {
-	if (bytes.length > maxBytes) {
-		fail(`${what}: payload ${bytes.length} exceeds max ${maxBytes} bytes`);
-	}
-	let text: string;
-	try {
-		text = utf8Decoder.decode(bytes);
-	} catch {
-		fail(`${what}: payload is not valid UTF-8`);
-	}
-	try {
-		return JSON.parse(text) as unknown;
-	} catch {
-		fail(`${what}: payload is not valid JSON`);
-	}
-}
-
-// --- Notification (length-framed) ---
-
-/** Narrow an already-parsed value to {@link NotificationV1}, throwing on any defect. */
-export function validateNotificationV1(value: unknown): NotificationV1 {
-	const what = "NotificationV1";
-	const obj = asObject(value, what);
-	requireV1(obj, what);
-	const signers = reqStringArray(obj, "signers", what);
-	const out: NotificationV1 = {
-		v: 1,
-		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
-		tailId: b64urlField(reqString(obj, "tailId", what), "tailId", what),
-		revision: reqIntInRange(obj, "revision", what, 0),
-		digest: b64urlField(reqString(obj, "digest", what), "digest", what),
-		timestamp: reqFiniteNumber(obj, "timestamp", what),
-		sig: b64urlField(reqString(obj, "sig", what), "sig", what),
-		signers: signers.map((s, i) => b64urlField(s, `signers[${i}]`, what)),
-	};
-	if (obj["delta"] !== undefined) {
-		out.delta = b64urlField(reqString(obj, "delta", what), "delta", what);
-	}
-	if (obj["rotationHint"] !== undefined) {
-		out.rotationHint = validateRotationHint(obj["rotationHint"], `${what}.rotationHint`);
-	}
-	if (obj["invalidation"] !== undefined) {
-		out.invalidation = reqBool(obj, "invalidation", what);
-	}
-	if (obj["invalidatedActionId"] !== undefined) {
-		out.invalidatedActionId = reqString(obj, "invalidatedActionId", what);
-	}
-	return out;
-}
-
-/** Validate an array of {@link NotificationV1} (the `entries`/`recentEntries` carried in backfill/resume replies). */
-export function validateNotificationArray(value: unknown, what: string): NotificationV1[] {
-	if (!Array.isArray(value)) {
-		fail(`${what}: field "entries" must be an array`);
-	}
-	return value.map((entry) => validateNotificationV1(entry));
-}
-
-/** Encode a {@link NotificationV1} as a length-prefixed UTF-8 JSON frame. */
-export function encodeNotificationV1(msg: NotificationV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
-	return encodeCohortMessage(validateNotificationV1(msg), maxMessageBytes);
-}
-
-/** Decode a length-prefixed {@link NotificationV1} frame. */
-export function decodeNotificationV1(bytes: Uint8Array, maxMessageBytes?: number): NotificationV1 {
-	return validateNotificationV1(decodeCohortMessage(bytes, maxMessageBytes));
-}
+/**
+ * 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.
+ */
+
+import {
+	decodeCohortMessage,
+	encodeCohortMessage,
+	DEFAULT_MAX_MESSAGE_BYTES,
+} from "../cohort-topic/wire/codec.js";
+import {
+	asObject,
+	b64urlField,
+	failWire as fail,
+	reqBool,
+	reqFiniteNumber,
+	reqIntInRange,
+	reqString,
+	reqStringArray,
+	requireV1,
+} from "./wire-validate.js";
+
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** Ceiling for an opaque subscribe app payload, guarding decode allocation. */
+export const DEFAULT_MAX_SUBSCRIBE_PAYLOAD_BYTES = 64 * 1024;
+
+// --- Subscribe app payload (carried inside cohort-topic RegisterV1.appPayload) ---
+
+/** 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;
+}
+
+// --- Notification (length-framed RPC) ---
+
+/** 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;
+}
+
+// --- validation helpers ---
+// Generic primitives live in ./wire-validate.js (shared across the reactivity codecs); the
+// notification-specific narrowing stays here next to the type it produces.
+
+function validateRotationHint(value: unknown, what: string): RotationHintV1 {
+	const obj = asObject(value, what);
+	return {
+		newTailId: b64urlField(reqString(obj, "newTailId", what), "newTailId", what),
+		effectiveAtRevision: reqIntInRange(obj, "effectiveAtRevision", what, 0),
+	};
+}
+
+// --- Subscribe app payload (opaque RegisterV1.appPayload bytes) ---
+
+/** Narrow an already-parsed value to {@link SubscribeAppPayloadV1}, throwing on any defect. */
+export function validateSubscribeAppPayloadV1(value: unknown): SubscribeAppPayloadV1 {
+	const what = "SubscribeAppPayloadV1";
+	const obj = asObject(value, what);
+	if (obj["kind"] !== "reactivity") {
+		fail(`${what}: field "kind" must be exactly "reactivity"`);
+	}
+	return {
+		kind: "reactivity",
+		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
+		tailIdAtAttach: b64urlField(reqString(obj, "tailIdAtAttach", what), "tailIdAtAttach", what),
+		lastKnownRev: reqIntInRange(obj, "lastKnownRev", what, 0),
+		deltaMaxBytes: reqIntInRange(obj, "deltaMaxBytes", what, 0),
+	};
+}
+
+/** Serialize a {@link SubscribeAppPayloadV1} to the opaque UTF-8 JSON bytes for `RegisterV1.appPayload`. */
+export function encodeSubscribeAppPayload(payload: SubscribeAppPayloadV1): Uint8Array {
+	return utf8Encoder.encode(JSON.stringify(validateSubscribeAppPayloadV1(payload)));
+}
+
+/** Decode opaque `RegisterV1.appPayload` bytes back to a validated {@link SubscribeAppPayloadV1}. */
+export function decodeSubscribeAppPayload(bytes: Uint8Array, maxBytes: number = DEFAULT_MAX_SUBSCRIBE_PAYLOAD_BYTES): SubscribeAppPayloadV1 {
+	return validateSubscribeAppPayloadV1(parseJsonBytes(bytes, maxBytes, "SubscribeAppPayloadV1"));
+}
+
+/** Parse opaque (non-framed) UTF-8 JSON payload bytes, rejecting oversized/invalid input. */
+function parseJsonBytes(bytes: Uint8Array, maxBytes: number, what: string): unknown {
+	if (bytes.length > maxBytes) {
+		fail(`${what}: payload ${bytes.length} exceeds max ${maxBytes} bytes`);
+	}
+	let text: string;
+	try {
+		text = utf8Decoder.decode(bytes);
+	} catch {
+		fail(`${what}: payload is not valid UTF-8`);
+	}
+	try {
+		return JSON.parse(text) as unknown;
+	} catch {
+		fail(`${what}: payload is not valid JSON`);
+	}
+}
+
+// --- Notification (length-framed) ---
+
+/** Narrow an already-parsed value to {@link NotificationV1}, throwing on any defect. */
+export function validateNotificationV1(value: unknown): NotificationV1 {
+	const what = "NotificationV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const signers = reqStringArray(obj, "signers", what);
+	const out: NotificationV1 = {
+		v: 1,
+		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
+		tailId: b64urlField(reqString(obj, "tailId", what), "tailId", what),
+		revision: reqIntInRange(obj, "revision", what, 0),
+		digest: b64urlField(reqString(obj, "digest", what), "digest", what),
+		timestamp: reqFiniteNumber(obj, "timestamp", what),
+		sig: b64urlField(reqString(obj, "sig", what), "sig", what),
+		signers: signers.map((s, i) => b64urlField(s, `signers[${i}]`, what)),
+	};
+	if (obj["delta"] !== undefined) {
+		out.delta = b64urlField(reqString(obj, "delta", what), "delta", what);
+	}
+	if (obj["rotationHint"] !== undefined) {
+		out.rotationHint = validateRotationHint(obj["rotationHint"], `${what}.rotationHint`);
+	}
+	if (obj["invalidation"] !== undefined) {
+		out.invalidation = reqBool(obj, "invalidation", what);
+	}
+	if (obj["invalidatedActionId"] !== undefined) {
+		out.invalidatedActionId = reqString(obj, "invalidatedActionId", what);
+	}
+	return out;
+}
+
+/** Validate an array of {@link NotificationV1} (the `entries`/`recentEntries` carried in backfill/resume replies). */
+export function validateNotificationArray(value: unknown, what: string): NotificationV1[] {
+	if (!Array.isArray(value)) {
+		fail(`${what}: field "entries" must be an array`);
+	}
+	return value.map((entry) => validateNotificationV1(entry));
+}
+
+/** Encode a {@link NotificationV1} as a length-prefixed UTF-8 JSON frame. */
+export function encodeNotificationV1(msg: NotificationV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
+	return encodeCohortMessage(validateNotificationV1(msg), maxMessageBytes);
+}
+
+/** Decode a length-prefixed {@link NotificationV1} frame. */
+export function decodeNotificationV1(bytes: Uint8Array, maxMessageBytes?: number): NotificationV1 {
+	return validateNotificationV1(decodeCohortMessage(bytes, maxMessageBytes));
+}