@optimystic/db-core 0.25.0 → 0.26.0

package/src/cohort-topic/promotion.ts

@@ -42,6 +42,9 @@
  * idempotent and `effectiveAt`-ordered via the monotonic {@link PromotionState.lastEffectiveAt}
  * high-water mark, so re-applying a notice (including this member's own echoed broadcast) or a replayed
  * older notice is a no-op — a stale promotion can never un-demote a cohort that has since demoted.
+ * A freshly created lifecycle can seed that per-topic ordering from a longer-lived node-level record via
+ * the optional {@link PromotionDeps.seedTransition}, so recreating an engine (e.g. after a memory-pressure
+ * eviction) does not reopen the replay window.
  */
 
 import { b64urlToBytes, bytesToB64url } from "./wire/codec.js";
@@ -103,9 +106,14 @@ interface PromotionState {
 	/**
 	 * `effectiveAt` of the most recent promotion/demotion this cohort has adopted — locally originated
 	 * (`promote()` / `demote()`) or remotely applied (`applyPromotionNotice` / `applyDemotionNotice`).
-	 * Monotonic and **never cleared** (a demotion clears `promoted`/`promotedAt` but keeps this), so it
-	 * is the high-water mark the remote-apply path orders against: a notice whose `effectiveAt` is not
-	 * strictly newer is a no-op — re-applied (incl. this member's own echoed broadcast) or stale-replayed.
+	 * Monotonic and never cleared within the lifecycle's lifetime (a demotion clears
+	 * `promoted`/`promotedAt` but keeps this), so it is the high-water mark the remote-apply path orders
+	 * against: a notice whose `effectiveAt` is not strictly newer is a no-op — re-applied (incl. this
+	 * member's own echoed broadcast) or stale-replayed. It is the **in-engine layer** of the replay
+	 * ordering, not the durable anchor: the lifecycle lives inside an engine the host may evict under
+	 * memory pressure, so on first touch of a topic it is seeded from the node-level adopted-transition
+	 * record ({@link PromotionDeps.seedTransition} — db-p2p's promote-gate `transitions` map), which
+	 * outlives the engine.
 	 */
 	lastEffectiveAt?: number;
 }
@@ -135,6 +143,16 @@ export interface PromotionDeps {
 	cohortEpoch: () => Uint8Array;
 	/** Threshold signer (the gossip ticket's `k − x` cohort signer). */
 	signer: CohortSigner;
+	/**
+	 * The node-level record of the last adopted promotion/demotion transition for `topicId` at this
+	 * cohort's `(coord, tier)` — db-p2p's promote-gate `transitions` map, which outlives the engine this
+	 * lifecycle lives in. Read once per topic, on first state creation, to seed
+	 * {@link PromotionState.lastEffectiveAt} and the promoted direction — so a recreated engine (after a
+	 * memory-pressure eviction) neither re-adopts a replayed stale notice nor forgets a correct
+	 * `promoted = true`. Optional: absent (key-less / unit composition) a fresh lifecycle starts cold,
+	 * exactly as before.
+	 */
+	seedTransition?: (topicId: Uint8Array) => { readonly effectiveAt: number; readonly promoted: boolean } | undefined;
 	config?: PromotionConfig;
 }
 
@@ -171,6 +189,15 @@ export interface PromotionLifecycle {
 	 * `effectiveAt` ordering as {@link applyPromotionNotice} — a stale promotion can never un-demote.
 	 */
 	applyDemotionNotice(n: DemotionNoticeV1, now: number): void;
+	/**
+	 * True iff any topic carries adopted promotion/demotion state — a `promoted` flag or a
+	 * `lastEffectiveAt` high-water. Growth samples / `lowLoadSince` alone do not count: they are
+	 * reconstructed from the store on the next {@link onParticipantCountChange}. Read by the host's
+	 * engine-eviction ranking, which prefers to keep an engine holding an adopted transition. A ranking
+	 * preference, not the safety mechanism: the node-level adopted-transition record
+	 * ({@link PromotionDeps.seedTransition}) outlives the engine and re-seeds a recreated one.
+	 */
+	hasAdoptedState(): boolean;
 }
 
 class CohortPromotionLifecycle implements PromotionLifecycle {
@@ -197,14 +224,14 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 	}
 
 	async onParticipantCountChange(topicId: Uint8Array, now: number): Promise<PromotionNoticeV1 | undefined> {
-		const state = this.stateFor(topicId);
+		const state = this.stateFor(topicId, now);
 		const count = this.deps.store.directParticipants(topicId);
 		this.pushGrowthSample(state, count, now);
 		this.refreshLowLoadClock(state, count, now);
 		if (state.promoted) {
 			return undefined; // already promoted — sticky until a demotion clears it
 		}
-		if (!this.promotionTriggered(topicId, state, count, now)) {
+		if (!this.promotionTriggered(topicId, state, count)) {
 			return undefined;
 		}
 		return this.promote(topicId, state, now);
@@ -222,13 +249,41 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 	}
 
 	isPromoted(topicId: Uint8Array): boolean {
-		return this.states.get(bytesKey(topicId))?.promoted ?? false;
+		const state = this.states.get(bytesKey(topicId));
+		if (state !== undefined) {
+			// In-engine state wins when present: it was itself seed-initialized on creation, so any divergence
+			// from the node-level record means a newer transition landed here first.
+			return state.promoted;
+		}
+		// Seed peek, not a state creation. `isPromoted` has no `now` to arm the sticky-window anchor
+		// (`promotedAt`), and creating promoted state without it would skip the sticky gate and allow an
+		// early demotion — so the direction is read straight off the node-level record. Nothing else calls
+		// `stateFor` on a freshly recreated engine before `isPromoted` is first read, so without this peek a
+		// correct `promoted = true` would be invisible until some notice or count change re-created the state.
+		return this.deps.seedTransition?.(topicId)?.promoted ?? false;
+	}
+
+	hasAdoptedState(): boolean {
+		// Adopted transition state only: a promoted flag or the lastEffectiveAt high-water. Growth samples /
+		// lowLoadSince are rebuilt from the store on the next onParticipantCountChange, so they never count.
+		// NOTE: this reports only in-engine state, so a freshly recreated engine whose promoted mode is
+		// currently visible ONLY through the `isPromoted` seed peek (no `stateFor` call yet) answers false and
+		// ranks 0 in the host's eviction ranking — as evictable as an engine holding nothing. Correctness is
+		// unaffected (the node-level record survives eviction and re-seeds again), so this is a ranking
+		// preference lost, not state lost. If recreated-promoted engines are ever observed thrashing through
+		// eviction, give the peek a `now` and let it create the seeded state instead of peeking.
+		for (const state of this.states.values()) {
+			if (state.promoted || state.lastEffectiveAt !== undefined) {
+				return true;
+			}
+		}
+		return false;
 	}
 
 	// --- remote apply (verified notices this member did not originate) ---
 
 	applyPromotionNotice(n: PromotionNoticeV1, now: number): void {
-		const state = this.stateFor(b64urlToBytes(n.topicId));
+		const state = this.stateFor(b64urlToBytes(n.topicId), now);
 		if (!this.isNewerTransition(state, n.effectiveAt)) {
 			return; // already adopted, our own echoed broadcast, or a stale replay
 		}
@@ -237,8 +292,8 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 		state.lastEffectiveAt = n.effectiveAt;
 	}
 
-	applyDemotionNotice(n: DemotionNoticeV1, _now: number): void {
-		const state = this.stateFor(b64urlToBytes(n.topicId));
+	applyDemotionNotice(n: DemotionNoticeV1, now: number): void {
+		const state = this.stateFor(b64urlToBytes(n.topicId), now);
 		if (!this.isNewerTransition(state, n.effectiveAt)) {
 			return;
 		}
@@ -256,18 +311,22 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 
 	// --- promotion ---
 
-	private promotionTriggered(topicId: Uint8Array, state: PromotionState, count: number, now: number): boolean {
+	private promotionTriggered(topicId: Uint8Array, state: PromotionState, count: number): boolean {
 		if (count >= this.capPromote) {
 			return true;
 		}
 		if (this.deps.loadBucket(topicId) >= this.bucketOverload && count >= this.capPromoteFast) {
 			return true;
 		}
-		return this.slopePredictsCrossing(state, count, now);
+		return this.slopePredictsCrossing(state, count);
 	}
 
-	/** Linear extrapolation over the growth window: will `directParticipants` cross `cap_promote` within lookahead? */
-	private slopePredictsCrossing(state: PromotionState, count: number, now: number): boolean {
+	/**
+	 * Linear extrapolation over the growth window: will `directParticipants` cross `cap_promote` within
+	 * lookahead? Needs no `now` — the caller stamps the current `(now, count)` as the last growth sample
+	 * before asking, so `samples[last].t` *is* `now`.
+	 */
+	private slopePredictsCrossing(state: PromotionState, count: number): boolean {
 		const samples = state.samples;
 		if (samples.length < 2) {
 			return false;
@@ -372,11 +431,24 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 
 	// --- bookkeeping ---
 
-	private stateFor(topicId: Uint8Array): PromotionState {
+	private stateFor(topicId: Uint8Array, now: number): PromotionState {
 		const key = bytesKey(topicId);
 		let state = this.states.get(key);
 		if (state === undefined) {
 			state = { promoted: false, samples: [] };
+			// Seed the replay ordering (and direction) from the node-level adopted-transition record, so a
+			// recreated engine picks up where the evicted one left off. The original sticky-window anchor is
+			// unrecoverable, so a seeded promotion re-arms `promotedAt` at `now` — that only delays demotion
+			// (the conservative direction), never allows an early one. `lowLoadSince` stays undefined: it is
+			// rebuilt from the store on the next `onParticipantCountChange`.
+			const seed = this.deps.seedTransition?.(topicId);
+			if (seed !== undefined) {
+				state.lastEffectiveAt = seed.effectiveAt;
+				state.promoted = seed.promoted;
+				if (seed.promoted) {
+					state.promotedAt = now;
+				}
+			}
 			this.states.set(key, state);
 		}
 		return state;

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

@@ -1,188 +1,195 @@
-/**
- * Cohort-topic wire substrate — shared structural-validation primitives.
- *
- * The generic per-field checks every wire codec across the substrate (cohort-topic, matchmaking,
- * reactivity) uses to narrow an already-parsed `unknown` (the output of `JSON.parse` on a decoded
- * frame) into a validated V1 shape. Each helper throws {@link CohortWireError} on a structural defect:
- * missing required field, wrong `v`, out-of-enum discriminant, a byte field that does not decode as
- * base64url, or an out-of-range numeric.
- *
- * These are the *only* generic primitives — domain-specific narrowing (the `validate*V1` functions, the
- * cohort-topic `tier` / `treeTier` semantics, matchmaking utf8 coders, reactivity notification shapes)
- * lives in the modules that own those message shapes. Keeping the primitives in one place means a
- * hardening tweak to a check (e.g. the fixed-length byte-width guard in {@link b64urlFixedLen}) lands
- * once and every consumer inherits it.
- */
-
-import { b64urlToBytes } from "./codec.js";
-
-/** Thrown for any malformed, oversized, or structurally invalid cohort-topic frame. */
-export class CohortWireError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = "CohortWireError";
-	}
-}
-
-/** Throw a {@link CohortWireError} with `message`. */
-export function failWire(message: string): never {
-	throw new CohortWireError(message);
-}
-
-/** Set `obj[key]` only when `value` is defined — keeps absent optionals off the decoded object. */
-export function assignDefined<T extends object, K extends keyof T>(obj: T, key: K, value: T[K] | undefined): void {
-	if (value !== undefined) {
-		obj[key] = value;
-	}
-}
-
-/** Narrow `value` to a plain object (not null, not an array), or throw. */
-export function asObject(value: unknown, what: string): Record<string, unknown> {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		failWire(`${what}: expected an object`);
-	}
-	return value as Record<string, unknown>;
-}
-
-/** Require `obj.v === 1`. */
-export function requireV1(obj: Record<string, unknown>, what: string): void {
-	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: Record<string, unknown>, key: string, what: string): string {
-	const value = obj[key];
-	if (typeof value !== "string") {
-		failWire(`${what}: field "${key}" must be a string`);
-	}
-	return value;
-}
-
-/** Return `obj[key]` when it is a string, `undefined` when absent; throw on any other type. */
-export function optString(obj: Record<string, unknown>, key: string, what: string): string | undefined {
-	const value = obj[key];
-	if (value === undefined) {
-		return undefined;
-	}
-	if (typeof value !== "string") {
-		failWire(`${what}: field "${key}" must be a string when present`);
-	}
-	return value;
-}
-
-/** Require `obj[key]` to be a finite number; returns it. */
-export function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
-	const value = obj[key];
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		failWire(`${what}: field "${key}" must be a finite number`);
-	}
-	return value;
-}
-
-/** Return `obj[key]` when it is a finite number, `undefined` when absent; throw on any other type. */
-export function optFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number | undefined {
-	const value = obj[key];
-	if (value === undefined) {
-		return undefined;
-	}
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		failWire(`${what}: field "${key}" must be a finite number when present`);
-	}
-	return value;
-}
-
-/** Require `obj[key]` to be a boolean; returns it. */
-export function reqBool(obj: Record<string, unknown>, key: string, what: string): boolean {
-	const value = obj[key];
-	if (typeof value !== "boolean") {
-		failWire(`${what}: field "${key}" must be a boolean`);
-	}
-	return value;
-}
-
-/** Return `obj[key]` when it is a boolean, `undefined` when absent; throw on any other type. */
-export function optBool(obj: Record<string, unknown>, key: string, what: string): boolean | undefined {
-	const value = obj[key];
-	if (value === undefined) {
-		return undefined;
-	}
-	if (typeof value !== "boolean") {
-		failWire(`${what}: field "${key}" must be a boolean when present`);
-	}
-	return value;
-}
-
-/**
- * Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. Reads and
- * finite-checks the field itself (via {@link reqFiniteNumber}) so callers pass the object + key rather
- * than a pre-extracted value — this composes with the other `req*` helpers.
- */
-export function reqIntInRange(obj: Record<string, unknown>, key: string, what: string, min: number, max?: number): number {
-	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;
-}
-
-/** Require `obj[key]` to be an array of strings; returns it. */
-export function reqStringArray(obj: Record<string, unknown>, key: string, what: string): string[] {
-	const value = obj[key];
-	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
-		failWire(`${what}: field "${key}" must be an array of strings`);
-	}
-	return value as string[];
-}
-
-/** Return `obj[key]` when it is an array of strings, `undefined` when absent; throw on any other type. */
-export function optStringArray(obj: Record<string, unknown>, key: string, what: string): string[] | undefined {
-	if (obj[key] === undefined) {
-		return undefined;
-	}
-	return reqStringArray(obj, key, what);
-}
-
-/** Require `obj[key]` to be one of `allowed`; returns it narrowed to the enum type. */
-export function reqEnum<T extends string>(obj: Record<string, unknown>, key: string, allowed: readonly T[], what: string): T {
-	const value = obj[key];
-	if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
-		failWire(`${what}: field "${key}" must be one of ${allowed.join(" | ")}`);
-	}
-	return value as T;
-}
-
-/**
- * Assert a base64url string decodes cleanly; returns it unchanged. Used for variable-width fields —
- * peer ids (multihash-encoded, not 32 raw bytes), signatures, and opaque application payloads.
- *
- * NOTE: no max-length bound here. A hostile peer can still bloat one of these variable-width fields
- * (e.g. `participantCoord`, a signature) into a large map key in the store / rate limiter / replay
- * guard. Their widths aren't pinned by the spec, so a ceiling would be a chosen policy value rather
- * than a decode of the format. If a bloated one is ever seen as a map key in practice, add a
- * `b64urlMaxLen` ceiling here. (Fixed-width hash-derived fields go through `b64urlFixedLen` instead.)
- */
-export function b64urlField(value: string, key: string, what: string): string {
-	try {
-		b64urlToBytes(value);
-	} catch {
-		failWire(`${what}: field "${key}" is not valid base64url`);
-	}
-	return value;
-}
-
-/** Assert a base64url string decodes cleanly to exactly `len` bytes; returns it unchanged. */
-export function b64urlFixedLen(value: string, key: string, len: number, what: string): string {
-	let bytes: Uint8Array;
-	try {
-		bytes = b64urlToBytes(value);
-	} catch {
-		return failWire(`${what}: field "${key}" is not valid base64url`);
-	}
-	if (bytes.length !== len) {
-		failWire(`${what}: field "${key}" must decode to ${len} bytes, got ${bytes.length}`);
-	}
-	return value;
-}
+/**
+ * Cohort-topic wire substrate — shared structural-validation primitives.
+ *
+ * The generic per-field checks every wire codec across the substrate (cohort-topic, matchmaking,
+ * reactivity) uses to narrow an already-parsed `unknown` (the output of `JSON.parse` on a decoded
+ * frame) into a validated V1 shape. Each helper throws {@link CohortWireError} on a structural defect:
+ * missing required field, wrong `v`, out-of-enum discriminant, a byte field that does not decode as
+ * base64url, or an out-of-range numeric.
+ *
+ * These are the *only* generic primitives — domain-specific narrowing (the `validate*V1` functions, the
+ * cohort-topic `tier` / `treeTier` semantics, matchmaking utf8 coders, reactivity notification shapes)
+ * lives in the modules that own those message shapes. Keeping the primitives in one place means a
+ * hardening tweak to a check (e.g. the fixed-length byte-width guard in {@link b64urlFixedLen}) lands
+ * once and every consumer inherits it.
+ */
+
+import { b64urlToBytes } from "./codec.js";
+
+/**
+ * Ring-coord / topic-id / cohort-epoch byte width (SHA-256 truncated to the ring width). Lives here,
+ * not in a single validator module, because both wires built on these primitives — cohort-topic and
+ * matchmaking — pin the same hash-derived fields to it.
+ */
+export const COORD_BYTES = 32;
+
+/** Thrown for any malformed, oversized, or structurally invalid cohort-topic frame. */
+export class CohortWireError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CohortWireError";
+	}
+}
+
+/** Throw a {@link CohortWireError} with `message`. */
+export function failWire(message: string): never {
+	throw new CohortWireError(message);
+}
+
+/** Set `obj[key]` only when `value` is defined — keeps absent optionals off the decoded object. */
+export function assignDefined<T extends object, K extends keyof T>(obj: T, key: K, value: T[K] | undefined): void {
+	if (value !== undefined) {
+		obj[key] = value;
+	}
+}
+
+/** Narrow `value` to a plain object (not null, not an array), or throw. */
+export function asObject(value: unknown, what: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		failWire(`${what}: expected an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+/** Require `obj.v === 1`. */
+export function requireV1(obj: Record<string, unknown>, what: string): void {
+	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: Record<string, unknown>, key: string, what: string): string {
+	const value = obj[key];
+	if (typeof value !== "string") {
+		failWire(`${what}: field "${key}" must be a string`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a string, `undefined` when absent; throw on any other type. */
+export function optString(obj: Record<string, unknown>, key: string, what: string): string | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "string") {
+		failWire(`${what}: field "${key}" must be a string when present`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be a finite number; returns it. */
+export function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
+	const value = obj[key];
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		failWire(`${what}: field "${key}" must be a finite number`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a finite number, `undefined` when absent; throw on any other type. */
+export function optFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		failWire(`${what}: field "${key}" must be a finite number when present`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be a boolean; returns it. */
+export function reqBool(obj: Record<string, unknown>, key: string, what: string): boolean {
+	const value = obj[key];
+	if (typeof value !== "boolean") {
+		failWire(`${what}: field "${key}" must be a boolean`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a boolean, `undefined` when absent; throw on any other type. */
+export function optBool(obj: Record<string, unknown>, key: string, what: string): boolean | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "boolean") {
+		failWire(`${what}: field "${key}" must be a boolean when present`);
+	}
+	return value;
+}
+
+/**
+ * Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. Reads and
+ * finite-checks the field itself (via {@link reqFiniteNumber}) so callers pass the object + key rather
+ * than a pre-extracted value — this composes with the other `req*` helpers.
+ */
+export function reqIntInRange(obj: Record<string, unknown>, key: string, what: string, min: number, max?: number): number {
+	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;
+}
+
+/** Require `obj[key]` to be an array of strings; returns it. */
+export function reqStringArray(obj: Record<string, unknown>, key: string, what: string): string[] {
+	const value = obj[key];
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+		failWire(`${what}: field "${key}" must be an array of strings`);
+	}
+	return value as string[];
+}
+
+/** Return `obj[key]` when it is an array of strings, `undefined` when absent; throw on any other type. */
+export function optStringArray(obj: Record<string, unknown>, key: string, what: string): string[] | undefined {
+	if (obj[key] === undefined) {
+		return undefined;
+	}
+	return reqStringArray(obj, key, what);
+}
+
+/** Require `obj[key]` to be one of `allowed`; returns it narrowed to the enum type. */
+export function reqEnum<T extends string>(obj: Record<string, unknown>, key: string, allowed: readonly T[], what: string): T {
+	const value = obj[key];
+	if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
+		failWire(`${what}: field "${key}" must be one of ${allowed.join(" | ")}`);
+	}
+	return value as T;
+}
+
+/**
+ * Assert a base64url string decodes cleanly; returns it unchanged. Used for variable-width fields —
+ * peer ids (multihash-encoded, not 32 raw bytes), signatures, and opaque application payloads.
+ *
+ * NOTE: no max-length bound here. A hostile peer can still bloat one of these variable-width fields
+ * (e.g. `participantCoord`, a signature) into a large map key in the store / rate limiter / replay
+ * guard. Their widths aren't pinned by the spec, so a ceiling would be a chosen policy value rather
+ * than a decode of the format. If a bloated one is ever seen as a map key in practice, add a
+ * `b64urlMaxLen` ceiling here. (Fixed-width hash-derived fields go through `b64urlFixedLen` instead.)
+ */
+export function b64urlField(value: string, key: string, what: string): string {
+	try {
+		b64urlToBytes(value);
+	} catch {
+		failWire(`${what}: field "${key}" is not valid base64url`);
+	}
+	return value;
+}
+
+/** Assert a base64url string decodes cleanly to exactly `len` bytes; returns it unchanged. */
+export function b64urlFixedLen(value: string, key: string, len: number, what: string): string {
+	let bytes: Uint8Array;
+	try {
+		bytes = b64urlToBytes(value);
+	} catch {
+		return failWire(`${what}: field "${key}" is not valid base64url`);
+	}
+	if (bytes.length !== len) {
+		failWire(`${what}: field "${key}" must decode to ${len} bytes, got ${bytes.length}`);
+	}
+	return value;
+}