@optimystic/db-core 0.13.5 → 0.14.0

package/src/cohort-topic/willingness.ts

@@ -0,0 +1,237 @@
+/**
+ * Cohort-topic substrate — per-member willingness / admission control.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Willingness and §Tier ladder, folded back from the
+ * simulator-validated `packages/substrate-simulator/src/{willingness,backoff}.ts`. When FRET's
+ * `RouteAndMaybeAct` lands a `RegisterV1` on a member, that member runs this check and returns one
+ * of three outcomes:
+ *
+ * - **{@link AcceptedOutcome}** — the routed member is willing; it becomes `primary`.
+ * - **{@link UnwillingMemberOutcome}** — the routed member is personally unwilling, but the gossiped
+ *   willingness vector says siblings will serve this tier; the caller retries a named sibling at the
+ *   *same* coord (spatial move within the cohort).
+ * - **{@link UnwillingCohortOutcome}** — fewer than a quorum of members are willing to serve the
+ *   tier, so the cohort declines the tier entirely; the caller backs off in *time* (no spatial
+ *   move — see §Why the caller doesn't walk on UnwillingCohort). The `retryAfterMs` follows the
+ *   capped-doubling curve in {@link backoffRetryMs}.
+ *
+ * A member's *live* willingness for a tier is: its profile serves the tier, the tier's load bucket
+ * is below `overloadBucket`, **and** it is under its per-tier primary-topic budget. The coarse 1-bit
+ * gossiped willingness vector ({@link selfWillingnessBits}) carries only profile-∧-load — the budget
+ * is a per-registration gate applied live at the routed member. (Resolved open question: willingness
+ * stays at **1 bit per tier** — no finer T3 gradations; the load bucket already supplies coarse load.)
+ */
+
+import { createLoadBarometer, DEFAULT_OVERLOAD_BUCKET, type LoadBarometerState } from "./load/barometer.js";
+import type { CohortView } from "./gossip/view.js";
+import { b64urlToBytes } from "./wire/codec.js";
+import type { RegisterV1 } from "./wire/types.js";
+import { ALL_TIERS, type NodeProfile, type Tier } from "./tiers.js";
+
+/** The routed member is willing and will serve as `primary`. */
+export interface AcceptedOutcome {
+	readonly kind: "accepted";
+}
+
+/** Routed member unwilling; these siblings (raw peer-id bytes) will serve — retry one at the same coord. */
+export interface UnwillingMemberOutcome {
+	readonly kind: "unwilling_member";
+	readonly candidateMembers: Uint8Array[];
+}
+
+/** No quorum of willing members; back off `retryAfterMs` in time and retry from `d_max`. */
+export interface UnwillingCohortOutcome {
+	readonly kind: "unwilling_cohort";
+	readonly retryAfterMs: number;
+}
+
+export type WillingnessOutcome = AcceptedOutcome | UnwillingMemberOutcome | UnwillingCohortOutcome;
+
+/** Per-member willingness / admission check. */
+export interface WillingnessCheck {
+	/** Classify `reg` routed onto this member, given the member's static profile and the clock. */
+	evaluate(reg: RegisterV1, self: NodeProfile, now: number): WillingnessOutcome;
+}
+
+// --- willingness-vector bit packing (folded back from simulator `willingnessBits`) ---
+
+/** Test bit `tier` (T0 = bit 0 … T3 = bit 3) of a packed 4-bit willingness vector. */
+export function tierBit(bits: number, tier: Tier): boolean {
+	return (bits & (1 << tier)) !== 0;
+}
+
+/** Pack a per-tier predicate into a 4-bit willingness vector (bit `t` set iff `willing(t)`). */
+export function packWillingnessBits(willing: (tier: Tier) => boolean): number {
+	let bits = 0;
+	for (const t of ALL_TIERS) {
+		if (willing(t)) bits |= 1 << t;
+	}
+	return bits;
+}
+
+/** The packed vector as a single hex nibble — the `CohortGossipV1.willingnessBits` wire form. */
+export function willingnessBitsHex(bits: number): string {
+	return (bits & 0xf).toString(16);
+}
+
+/**
+ * This member's gossiped (coarse) willingness vector: bit `t` set iff the profile serves `t` and the
+ * tier is not shed under load. The per-tier primary-topic budget is deliberately **not** folded in
+ * — it is a live per-registration gate, not a gossiped signal (§Willingness: the gossiped vector is
+ * "one bit per tier per member… refreshed every gossip round").
+ */
+export function selfWillingnessBits(self: NodeProfile, barometer: LoadBarometerState): number {
+	return packWillingnessBits((t) => self.willingTiers.has(t) && barometer.loadWilling(t));
+}
+
+// --- exponential UnwillingCohort back-off (settled params, docs §Willingness L260-263) ---
+
+export interface BackoffConfig {
+	/** First-rejection delay (ms). Default 1000. */
+	readonly baseMs: number;
+	/** Geometric growth per rejection. Default 2 (doubling). */
+	readonly factor: number;
+	/** Hard ceiling on a single delay (ms). Default 60000. */
+	readonly capMs: number;
+}
+
+/** Settled back-off curve (`docs/cohort-topic.md` §Willingness): `base = 1 s`, `factor = 2`, `cap = 60 s`. */
+export const DEFAULT_BACKOFF_CONFIG: BackoffConfig = {
+	baseMs: 1000,
+	factor: 2,
+	capMs: 60_000,
+};
+
+/**
+ * `retryAfter` for the `attempt`-th rejection (0-based): `⌊base · factor^attempt⌋` capped at `capMs`.
+ * The capped doubling bounds the rejections a participant suffers across an overload window at
+ * `O(log(window/base))` (≤ ~6 to span 60 s) rather than the `window/base` a fixed interval incurs.
+ * As survivors of a burst back off geometrically, offered load sheds and accepted/sec holds at the
+ * willing-quorum capacity without a cascade.
+ */
+export function backoffRetryMs(attempt: number, config: BackoffConfig = DEFAULT_BACKOFF_CONFIG): number {
+	if (!Number.isInteger(attempt) || attempt < 0) {
+		throw new RangeError(`attempt must be a non-negative integer, got ${attempt}`);
+	}
+	const raw = config.baseMs * Math.pow(config.factor, attempt);
+	return Math.min(Math.floor(raw), config.capMs);
+}
+
+// --- willingness check ---
+
+export interface WillingnessConfig {
+	/** Cohort size `k` (drives the default quorum). Default 16. */
+	cohortSize?: number;
+	/**
+	 * Members that must be willing to serve a tier for the cohort to take it on. Default: strict
+	 * majority of `cohortSize` (`⌊k/2⌋ + 1`). Not pinned by `docs/cohort-topic.md` — §Tier ladder
+	 * only requires "a quorum"; configurable here, revisitable by the Edge/Core policy ticket.
+	 */
+	quorum?: number;
+	/** Load bucket at/above which a tier is shed. Default {@link DEFAULT_OVERLOAD_BUCKET} (6). */
+	overloadBucket?: number;
+	/**
+	 * Max topics this member may be `primary` for at a single tier. Default 2048 (`topics_max`).
+	 * The doc names the per-member per-tier budget but pins no number; configurable here.
+	 */
+	maxPrimaryTopicsPerTier?: number;
+	/** Back-off curve for `unwilling_cohort` retries. Default {@link DEFAULT_BACKOFF_CONFIG}. */
+	backoff?: BackoffConfig;
+}
+
+export interface WillingnessDeps {
+	/** This member's own per-tier load barometer (live willingness uses its buckets). */
+	barometer: LoadBarometerState;
+	/** Merged per-member gossip view — the sibling willingness vectors. */
+	view: CohortView;
+	/** This member's own id, base64url (the `fromMember` key) — excluded from the sibling scan. */
+	selfMember: string;
+	/** Count of topics this member is already `primary` for at `tier` (the budget gate input). */
+	primaryTopicCount: (tier: Tier) => number;
+	/**
+	 * Rejection-attempt count for `reg`, driving the `retryAfter` curve. The anti-DoS rate limiter
+	 * owns the counter; the *curve* lives here. Default `() => 0` (first-rejection delay).
+	 */
+	attempts?: (reg: RegisterV1) => number;
+	config?: WillingnessConfig;
+}
+
+/** Default quorum: strict majority of the cohort. */
+export function defaultQuorum(cohortSize: number): number {
+	return Math.floor(cohortSize / 2) + 1;
+}
+
+class GossipWillingnessCheck implements WillingnessCheck {
+	private readonly quorum: number;
+	private readonly overloadBucket: number;
+	private readonly maxPrimaryTopicsPerTier: number;
+	private readonly backoff: BackoffConfig;
+	private readonly attempts: (reg: RegisterV1) => number;
+
+	constructor(private readonly deps: WillingnessDeps) {
+		const cfg = deps.config ?? {};
+		const cohortSize = cfg.cohortSize ?? 16;
+		this.quorum = cfg.quorum ?? defaultQuorum(cohortSize);
+		this.overloadBucket = cfg.overloadBucket ?? DEFAULT_OVERLOAD_BUCKET;
+		this.maxPrimaryTopicsPerTier = cfg.maxPrimaryTopicsPerTier ?? 2048;
+		this.backoff = cfg.backoff ?? DEFAULT_BACKOFF_CONFIG;
+		this.attempts = deps.attempts ?? ((): number => 0);
+	}
+
+	evaluate(reg: RegisterV1, self: NodeProfile, now: number): WillingnessOutcome {
+		const tier = reg.tier as Tier;
+		if (!ALL_TIERS.includes(tier)) {
+			// An op tier outside T0..T3 is not serviceable; treat as a cohort-level decline.
+			return { kind: "unwilling_cohort", retryAfterMs: backoffRetryMs(this.attempts(reg), this.backoff) };
+		}
+
+		const selfWilling = this.selfLiveWilling(self, tier);
+		const siblings = this.willingSiblings(tier);
+		const willingCount = siblings.length + (selfWilling ? 1 : 0);
+
+		// Quorum gate (§Tier ladder): the cohort takes on tier-T duties only if a quorum of members
+		// is willing; otherwise registrations get UnwillingCohort and the caller backs off in time.
+		if (willingCount < this.quorum) {
+			return { kind: "unwilling_cohort", retryAfterMs: backoffRetryMs(this.attempts(reg), this.backoff) };
+		}
+		if (selfWilling) {
+			return { kind: "accepted" };
+		}
+		// Quorum holds and self is unwilling → some sibling will serve.
+		return { kind: "unwilling_member", candidateMembers: siblings.map((m) => b64urlToBytes(m)) };
+	}
+
+	/** Live willingness of *this* member for `tier`: profile ∧ load-under-threshold ∧ under budget. */
+	private selfLiveWilling(self: NodeProfile, tier: Tier): boolean {
+		return (
+			self.willingTiers.has(tier) &&
+			this.deps.barometer.bucket(tier) < this.overloadBucket &&
+			this.deps.primaryTopicCount(tier) < this.maxPrimaryTopicsPerTier
+		);
+	}
+
+	/** Sibling member keys (base64url) whose *gossiped* willingness vector serves `tier`. */
+	private willingSiblings(tier: Tier): string[] {
+		const out: string[] = [];
+		for (const [member, contribution] of this.deps.view.all()) {
+			if (member === this.deps.selfMember) continue; // self counted via live willingness
+			if (tierBit(contribution.willingness, tier)) {
+				out.push(member);
+			}
+		}
+		return out;
+	}
+}
+
+/** Build a {@link WillingnessCheck} over the injected barometer + gossip view + budget source. */
+export function createWillingnessCheck(deps: WillingnessDeps): WillingnessCheck {
+	return new GossipWillingnessCheck(deps);
+}
+
+/** Convenience: a willingness check with a fresh idle barometer (tests / single-tier callers). */
+export function createWillingnessCheckWithIdleBarometer(
+	deps: Omit<WillingnessDeps, "barometer">,
+): { check: WillingnessCheck; barometer: LoadBarometerState } {
+	const barometer = createLoadBarometer({ overloadBucket: deps.config?.overloadBucket });
+	return { check: createWillingnessCheck({ ...deps, barometer }), barometer };
+}

package/src/cohort-topic/wire/codec.ts

@@ -0,0 +1,204 @@
+/**
+ * Cohort-topic substrate — wire codec.
+ *
+ * Framing: every message is a 4-byte big-endian unsigned length prefix followed by the UTF-8
+ * JSON body, so a framed message is self-delimiting on a stream. Frames whose declared body
+ * length exceeds {@link DEFAULT_MAX_MESSAGE_BYTES} (or a caller-supplied ceiling) are rejected
+ * with {@link CohortWireError} before any allocation against the declared size.
+ *
+ * Byte fields travel as base64url (no padding); {@link bytesToB64url} / {@link b64urlToBytes}
+ * are the shared, cross-platform (browser/node/RN) helpers — no Node `Buffer`.
+ */
+
+import { CohortWireError } from "./validate.js";
+import {
+	validateCohortGossipV1,
+	validateDemotionNoticeV1,
+	validateMembershipCertV1,
+	validatePromotionNoticeV1,
+	validateRegisterReplyV1,
+	validateRegisterV1,
+	validateRenewReplyV1,
+	validateRenewV1,
+	validateSignRequestV1,
+	validateSignReplyV1,
+} from "./validate.js";
+import type {
+	CohortGossipV1,
+	DemotionNoticeV1,
+	MembershipCertV1,
+	PromotionNoticeV1,
+	RegisterReplyV1,
+	RegisterV1,
+	RenewReplyV1,
+	RenewV1,
+	SignRequestV1,
+	SignReplyV1,
+} from "./types.js";
+
+/**
+ * Default ceiling on a framed body, in bytes. Sized conservatively at 1 MiB until the
+ * simulator-validated cohort-gossip worst case (`topics_max` topic summaries, see
+ * `docs/cohort-topic.md` §Configuration) is converted into an exact bound.
+ *
+ * TODO(cohort-topic): derive the exact ceiling from `topics_max` (2048) × the per-summary JSON
+ * size plus the willingness/load header, rather than this flat 1 MiB cap.
+ */
+export const DEFAULT_MAX_MESSAGE_BYTES = 1024 * 1024;
+
+const LENGTH_PREFIX_BYTES = 4;
+
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+// --- base64url helpers (no padding, cross-platform) ---
+
+const B64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+const B64URL_LOOKUP: ReadonlyArray<number> = ((): number[] => {
+	const table = new Array<number>(128).fill(-1);
+	for (let i = 0; i < B64URL_ALPHABET.length; i++) {
+		table[B64URL_ALPHABET.charCodeAt(i)] = i;
+	}
+	return table;
+})();
+
+/** Encode bytes as base64url with no padding. */
+export function bytesToB64url(b: Uint8Array): string {
+	let out = "";
+	let i = 0;
+	for (; i + 3 <= b.length; i += 3) {
+		const n = (b[i]! << 16) | (b[i + 1]! << 8) | b[i + 2]!;
+		out += B64URL_ALPHABET[(n >> 18) & 63]! + B64URL_ALPHABET[(n >> 12) & 63]! + B64URL_ALPHABET[(n >> 6) & 63]! + B64URL_ALPHABET[n & 63]!;
+	}
+	const rem = b.length - i;
+	if (rem === 1) {
+		const n = b[i]! << 16;
+		out += B64URL_ALPHABET[(n >> 18) & 63]! + B64URL_ALPHABET[(n >> 12) & 63]!;
+	} else if (rem === 2) {
+		const n = (b[i]! << 16) | (b[i + 1]! << 8);
+		out += B64URL_ALPHABET[(n >> 18) & 63]! + B64URL_ALPHABET[(n >> 12) & 63]! + B64URL_ALPHABET[(n >> 6) & 63]!;
+	}
+	return out;
+}
+
+/** Decode a base64url string (no padding) to bytes. Throws {@link CohortWireError} on bad input. */
+export function b64urlToBytes(s: string): Uint8Array {
+	const len = s.length;
+	if (len % 4 === 1) {
+		throw new CohortWireError("base64url: invalid length");
+	}
+	const fullGroups = len >> 2;
+	const rem = len & 3;
+	const outLen = fullGroups * 3 + (rem === 0 ? 0 : rem - 1);
+	const out = new Uint8Array(outLen);
+	let si = 0;
+	let oi = 0;
+	const sext = (ch: number): number => {
+		const v = ch < 128 ? B64URL_LOOKUP[ch]! : -1;
+		if (v < 0) {
+			throw new CohortWireError("base64url: invalid character");
+		}
+		return v;
+	};
+	for (let g = 0; g < fullGroups; g++) {
+		const n = (sext(s.charCodeAt(si)) << 18) | (sext(s.charCodeAt(si + 1)) << 12) | (sext(s.charCodeAt(si + 2)) << 6) | sext(s.charCodeAt(si + 3));
+		out[oi++] = (n >> 16) & 0xff;
+		out[oi++] = (n >> 8) & 0xff;
+		out[oi++] = n & 0xff;
+		si += 4;
+	}
+	if (rem === 2) {
+		const n = (sext(s.charCodeAt(si)) << 18) | (sext(s.charCodeAt(si + 1)) << 12);
+		out[oi++] = (n >> 16) & 0xff;
+	} else if (rem === 3) {
+		const n = (sext(s.charCodeAt(si)) << 18) | (sext(s.charCodeAt(si + 1)) << 12) | (sext(s.charCodeAt(si + 2)) << 6);
+		out[oi++] = (n >> 16) & 0xff;
+		out[oi++] = (n >> 8) & 0xff;
+	}
+	return out;
+}
+
+// --- framing ---
+
+/** Encode a V1 message as a length-prefixed UTF-8 JSON frame. */
+export function encodeCohortMessage<T extends { v: 1 }>(msg: T, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
+	const body = utf8Encoder.encode(JSON.stringify(msg));
+	if (body.length > maxMessageBytes) {
+		throw new CohortWireError(`message body ${body.length} exceeds max_message_bytes ${maxMessageBytes}`);
+	}
+	const frame = new Uint8Array(LENGTH_PREFIX_BYTES + body.length);
+	const view = new DataView(frame.buffer);
+	view.setUint32(0, body.length, false);
+	frame.set(body, LENGTH_PREFIX_BYTES);
+	return frame;
+}
+
+/** Strip the length prefix and `JSON.parse` the body. Throws {@link CohortWireError} on a malformed frame. */
+export function decodeCohortMessage(bytes: Uint8Array, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): unknown {
+	if (bytes.length < LENGTH_PREFIX_BYTES) {
+		throw new CohortWireError("frame too short for length prefix");
+	}
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const declared = view.getUint32(0, false);
+	if (declared > maxMessageBytes) {
+		throw new CohortWireError(`declared body length ${declared} exceeds max_message_bytes ${maxMessageBytes}`);
+	}
+	if (LENGTH_PREFIX_BYTES + declared !== bytes.length) {
+		throw new CohortWireError(`frame length mismatch: declared ${declared}, have ${bytes.length - LENGTH_PREFIX_BYTES}`);
+	}
+	const body = bytes.subarray(LENGTH_PREFIX_BYTES, LENGTH_PREFIX_BYTES + declared);
+	let text: string;
+	try {
+		text = utf8Decoder.decode(body);
+	} catch {
+		throw new CohortWireError("frame body is not valid UTF-8");
+	}
+	try {
+		return JSON.parse(text) as unknown;
+	} catch {
+		throw new CohortWireError("frame body is not valid JSON");
+	}
+}
+
+// --- typed decoders (decode frame → validate → narrow) ---
+
+export function decodeRegisterV1(bytes: Uint8Array, maxMessageBytes?: number): RegisterV1 {
+	return validateRegisterV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodeRegisterReplyV1(bytes: Uint8Array, maxMessageBytes?: number): RegisterReplyV1 {
+	return validateRegisterReplyV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodeRenewV1(bytes: Uint8Array, maxMessageBytes?: number): RenewV1 {
+	return validateRenewV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodeRenewReplyV1(bytes: Uint8Array, maxMessageBytes?: number): RenewReplyV1 {
+	return validateRenewReplyV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodePromotionNoticeV1(bytes: Uint8Array, maxMessageBytes?: number): PromotionNoticeV1 {
+	return validatePromotionNoticeV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodeDemotionNoticeV1(bytes: Uint8Array, maxMessageBytes?: number): DemotionNoticeV1 {
+	return validateDemotionNoticeV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodeCohortGossipV1(bytes: Uint8Array, maxMessageBytes?: number): CohortGossipV1 {
+	return validateCohortGossipV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodeMembershipCertV1(bytes: Uint8Array, maxMessageBytes?: number): MembershipCertV1 {
+	return validateMembershipCertV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodeSignRequestV1(bytes: Uint8Array, maxMessageBytes?: number): SignRequestV1 {
+	return validateSignRequestV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
+export function decodeSignReplyV1(bytes: Uint8Array, maxMessageBytes?: number): SignReplyV1 {
+	return validateSignReplyV1(decodeCohortMessage(bytes, maxMessageBytes));
+}

package/src/cohort-topic/wire/index.ts

@@ -0,0 +1,16 @@
+export * from "./types.js";
+export * from "./codec.js";
+export * from "./payloads.js";
+export { CohortWireError } from "./validate.js";
+export {
+	validateRegisterV1,
+	validateRegisterReplyV1,
+	validateRenewV1,
+	validateRenewReplyV1,
+	validatePromotionNoticeV1,
+	validateDemotionNoticeV1,
+	validateCohortGossipV1,
+	validateMembershipCertV1,
+	validateSignRequestV1,
+	validateSignReplyV1,
+} from "./validate.js";

package/src/cohort-topic/wire/payloads.ts

@@ -0,0 +1,117 @@
+/**
+ * Cohort-topic substrate — canonical participant-signature payloads.
+ *
+ * A participant peer-key-signs its outbound `RegisterV1` / `RenewV1` bodies (db-p2p supplies the
+ * libp2p peer key); a cohort member recomputes the identical byte image to verify that signature
+ * before admitting a register (anti-DoS) or honoring a crash-failover `reattach` attestation (so a
+ * stray/MITM'd ping cannot usurp a live primary — `docs/cohort-topic.md` §TTL and renewal).
+ *
+ * Signer and verifier must agree byte-for-byte. Exactly like {@link import("../sig/payloads.js")}
+ * for the threshold-signed notices, determinism comes from encoding an explicitly-ordered JSON
+ * array (array order is stable, unlike object key order) as UTF-8 — never the `signature` envelope.
+ * Optional fields are normalized to a fixed placeholder (`bootstrap`→`false`, `probe`→`false`,
+ * `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as absent,
+ * `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default optional can
+ * never disagree across the wire round-trip.
+ */
+
+import type { CohortGossipV1, RegisterV1, RenewV1 } from "./types.js";
+
+const utf8 = new TextEncoder();
+
+/** A `RegisterV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
+export type RegisterSignable = Omit<RegisterV1, "signature">;
+
+/** A `RenewV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
+export type RenewSignable = Omit<RenewV1, "signature">;
+
+/** Normalize the optional bootstrap-evidence slot: absent and empty-string both map to `null`. */
+function normalizeEvidence(bootstrapEvidence: string | undefined): string | null {
+	return bootstrapEvidence === undefined || bootstrapEvidence === "" ? null : bootstrapEvidence;
+}
+
+/** Canonical signed byte image of a `RegisterV1` body (every field except `signature`). */
+export function registerSigningPayload(body: RegisterSignable): Uint8Array {
+	return utf8.encode(JSON.stringify([
+		"RegisterV1",
+		body.v,
+		body.topicId,
+		body.tier,
+		body.treeTier,
+		body.participantCoord,
+		body.ttl,
+		body.bootstrap ?? false,
+		body.appPayload ?? null,
+		normalizeEvidence(body.bootstrapEvidence),
+		body.timestamp,
+		body.correlationId,
+		// A read-only probe signs `probe: true`; a normal register signs `false`. Both sides recompute
+		// this image identically, so a probe and a register over the same fields produce distinct signatures.
+		body.probe ?? false,
+	]));
+}
+
+/** Canonical signed byte image of a `RenewV1` body (every field except `signature`). */
+export function renewSigningPayload(body: RenewSignable): Uint8Array {
+	return utf8.encode(JSON.stringify([
+		"RenewV1",
+		body.v,
+		body.topicId,
+		body.participantId,
+		body.correlationId,
+		body.timestamp,
+		body.reattach ?? false,
+		// A withdraw tombstone signs `withdraw: true`, a ping/reattach signs `false`. Strictly appended
+		// (array length 7→8) so the reattach-vs-ping distinction is preserved and a third party cannot
+		// evict someone else's registration. Signer (participant) + verifier (db-p2p) move together; no
+		// signatures are persisted, so there is no cross-version concern.
+		body.withdraw ?? false,
+	]));
+}
+
+/** A `CohortGossipV1` minus its `signature` envelope — the bytes the gossiping member peer-key-signs. */
+export type CohortGossipSignable = Omit<CohortGossipV1, "signature">;
+
+/**
+ * Canonical signed byte image of a `CohortGossipV1` (every field except `signature`). Intra-cohort
+ * gossip is peer-key-signed by the originating member so a receiver can drop a frame whose `fromMember`
+ * signature does not verify or that comes from a non-cohort member (it can never spoof willingness/load
+ * or replicate forged records). Like the other payload helpers, determinism comes from an
+ * explicitly-ordered array — nested records/summaries/evictions are emitted as fixed ordered tuples so
+ * the signer and the receiver (which re-derives this image from the validated frame) agree byte-for-byte.
+ * Absent optionals (`records`/`evicted`) normalize to `[]`, and `appState` to `null`.
+ */
+export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array {
+	return utf8.encode(JSON.stringify([
+		"CohortGossipV1",
+		g.v,
+		g.fromMember,
+		g.coord,
+		g.cohortEpoch,
+		g.willingnessBits,
+		g.loadBuckets,
+		g.windowSeconds,
+		g.topicSummaries.map((s) => [
+			s.topicId,
+			s.tier,
+			s.directParticipants,
+			s.arrivalsPerMin,
+			s.queriesPerMin,
+			s.promoted,
+			s.childCohortCount,
+		]),
+		(g.records ?? []).map((r) => [
+			r.topicId,
+			r.participantId,
+			r.tier,
+			r.primary,
+			r.backups,
+			r.attachedAt,
+			r.lastPing,
+			r.ttl,
+			r.appState ?? null,
+		]),
+		(g.evicted ?? []).map((e) => [e.topicId, e.participantId]),
+		g.timestamp,
+	]));
+}