@optimystic/db-core 0.22.0 → 0.24.0

package/src/cohort-topic/antiflood/invariants.ts

@@ -1,108 +1,108 @@
-/**
- * Cohort-topic substrate — anti-flood structural invariants (centralized for the e2e suite).
- *
- * Transcribed from `docs/cohort-topic.md` §Anti-flood properties. Three of the five named floods are
- * defended *by construction* in the walk / promotion machinery already; this module does not
- * re-implement that machinery — it provides pure, dependency-free predicates over a recorded walk
- * trace so the unit and e2e suites can assert the invariants hold on the real engine's behaviour,
- * the same way `packages/substrate-simulator/src/walk-metrics.ts` instruments
- * `outwardMovesArePromoted` / `unwillingRetriesRestartAtDMax` on the simulator side.
- *
- * The caller records one {@link WalkProbe} per probe RPC the {@link import("../walk.js").WalkEngine}
- * issues (its `treeTier` and the reply `result`), grouping the probes of one
- * {@link import("../walk.js").WalkEngine.register} call into a {@link WalkTrace}. The predicates then
- * check the anti-flood discipline:
- *
- * - **claim 3 — no speculative outward probe:** {@link outwardMovesArePromoted}. The only tier
- *   *increase* between consecutive probes is one taken immediately after a `promoted` reply.
- * - **walk discipline — inward only on `no_state`:** {@link inwardStepsFollowNoState}. Every single
- *   tier *decrease* is the response to a `no_state` (no inward move on any other reply).
- * - **claim 4 — inward retry restarts at `d_max`:** {@link retriesRestartAtDMax}. A fresh walk (the
- *   restart after an `unwilling_cohort` / cohort-level back-off) begins at `d_max`, never re-hitting
- *   the declined coord.
- * - **claim 5 — sticky promotion:** {@link DEFAULT_T_PROMOTE_STICKY_MS} re-exported as the canonical
- *   sticky window; the promotion lifecycle (`promotion.ts`) enforces it and `promotion.spec.ts`
- *   covers the no-flap behaviour. {@link stickyHolds} is the predicate the e2e suite uses to confirm
- *   a freshly-promoted cohort refuses demotion within the window.
- */
-
-import type { RegisterResult } from "../wire/types.js";
-import { DEFAULT_T_PROMOTE_STICKY_MS } from "../promotion.js";
-
-export { DEFAULT_T_PROMOTE_STICKY_MS };
-
-/** One probe RPC in a walk: the tier it was issued at and the reply result it drew. */
-export interface WalkProbe {
-	/** Walk position `d` the probe was issued at. */
-	readonly treeTier: number;
-	/** The cohort reply classification. */
-	readonly result: RegisterResult;
-}
-
-/** The ordered probe log of a single {@link import("../walk.js").WalkEngine.register} call. */
-export interface WalkTrace {
-	/** `d_max` the walk started from. */
-	readonly dMax: number;
-	/** Probes in issue order. */
-	readonly probes: readonly WalkProbe[];
-}
-
-/**
- * Claim 3 (no speculative outward probe): every tier *increase* between consecutive probes is taken
- * only in response to a `promoted` redirect on the preceding probe. Any outward move not preceded by
- * `promoted` is a speculative deeper probe — the flood this invariant forbids.
- */
-export function outwardMovesArePromoted(trace: WalkTrace): boolean {
-	const { probes } = trace;
-	for (let i = 1; i < probes.length; i++) {
-		const moveOutward = probes[i]!.treeTier > probes[i - 1]!.treeTier;
-		if (moveOutward && probes[i - 1]!.result !== "promoted") {
-			return false;
-		}
-	}
-	return true;
-}
-
-/**
- * Walk discipline: every single inward step (`treeTier` decreased by exactly 1, or reset to 0 at the
- * root cold-start) is the response to a `no_state`. The walk never moves toward the root on any other
- * reply, so inward traffic is one-hop-per-`no_state`, not a storm.
- */
-export function inwardStepsFollowNoState(trace: WalkTrace): boolean {
-	const { probes } = trace;
-	for (let i = 1; i < probes.length; i++) {
-		const moveInward = probes[i]!.treeTier < probes[i - 1]!.treeTier;
-		if (moveInward && probes[i - 1]!.result !== "no_state") {
-			return false;
-		}
-	}
-	return true;
-}
-
-/**
- * Claim 4 (inward retry restarts at `d_max`): each fresh walk in a re-registration sequence starts at
- * its `d_max`, so a participant that drew `unwilling_cohort` backs off in *time* and re-walks from the
- * top rather than re-hitting the declined coord. `traces` are consecutive `register` calls by one
- * participant; the first probe of each must sit at that walk's `d_max`.
- */
-export function retriesRestartAtDMax(traces: readonly WalkTrace[]): boolean {
-	for (const trace of traces) {
-		const first = trace.probes[0];
-		if (first === undefined) {
-			continue;
-		}
-		if (first.treeTier !== trace.dMax) {
-			return false;
-		}
-	}
-	return true;
-}
-
-/**
- * Claim 5 (sticky promotion): a cohort promoted at `promotedAt` must not be reconsidered for demotion
- * before `promotedAt + stickyMs`. Returns whether `now` is still inside the sticky window — the e2e
- * suite asserts the promotion lifecycle refuses demotion exactly while this is `true`.
- */
-export function stickyHolds(promotedAt: number, now: number, stickyMs: number = DEFAULT_T_PROMOTE_STICKY_MS): boolean {
-	return now - promotedAt < stickyMs;
-}
+/**
+ * Cohort-topic substrate — anti-flood structural invariants (centralized for the e2e suite).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-flood properties. Three of the five named floods are
+ * defended *by construction* in the walk / promotion machinery already; this module does not
+ * re-implement that machinery — it provides pure, dependency-free predicates over a recorded walk
+ * trace so the unit and e2e suites can assert the invariants hold on the real engine's behaviour,
+ * the same way `packages/substrate-simulator/src/walk-metrics.ts` instruments
+ * `outwardMovesArePromoted` / `unwillingRetriesRestartAtDMax` on the simulator side.
+ *
+ * The caller records one {@link WalkProbe} per probe RPC the {@link import("../walk.js").WalkEngine}
+ * issues (its `treeTier` and the reply `result`), grouping the probes of one
+ * {@link import("../walk.js").WalkEngine.register} call into a {@link WalkTrace}. The predicates then
+ * check the anti-flood discipline:
+ *
+ * - **claim 3 — no speculative outward probe:** {@link outwardMovesArePromoted}. The only tier
+ *   *increase* between consecutive probes is one taken immediately after a `promoted` reply.
+ * - **walk discipline — inward only on `no_state`:** {@link inwardStepsFollowNoState}. Every single
+ *   tier *decrease* is the response to a `no_state` (no inward move on any other reply).
+ * - **claim 4 — inward retry restarts at `d_max`:** {@link retriesRestartAtDMax}. A fresh walk (the
+ *   restart after an `unwilling_cohort` / cohort-level back-off) begins at `d_max`, never re-hitting
+ *   the declined coord.
+ * - **claim 5 — sticky promotion:** {@link DEFAULT_T_PROMOTE_STICKY_MS} re-exported as the canonical
+ *   sticky window; the promotion lifecycle (`promotion.ts`) enforces it and `promotion.spec.ts`
+ *   covers the no-flap behaviour. {@link stickyHolds} is the predicate the e2e suite uses to confirm
+ *   a freshly-promoted cohort refuses demotion within the window.
+ */
+
+import type { RegisterResult } from "../wire/types.js";
+import { DEFAULT_T_PROMOTE_STICKY_MS } from "../promotion.js";
+
+export { DEFAULT_T_PROMOTE_STICKY_MS };
+
+/** One probe RPC in a walk: the tier it was issued at and the reply result it drew. */
+export interface WalkProbe {
+	/** Walk position `d` the probe was issued at. */
+	readonly treeTier: number;
+	/** The cohort reply classification. */
+	readonly result: RegisterResult;
+}
+
+/** The ordered probe log of a single {@link import("../walk.js").WalkEngine.register} call. */
+export interface WalkTrace {
+	/** `d_max` the walk started from. */
+	readonly dMax: number;
+	/** Probes in issue order. */
+	readonly probes: readonly WalkProbe[];
+}
+
+/**
+ * Claim 3 (no speculative outward probe): every tier *increase* between consecutive probes is taken
+ * only in response to a `promoted` redirect on the preceding probe. Any outward move not preceded by
+ * `promoted` is a speculative deeper probe — the flood this invariant forbids.
+ */
+export function outwardMovesArePromoted(trace: WalkTrace): boolean {
+	const { probes } = trace;
+	for (let i = 1; i < probes.length; i++) {
+		const moveOutward = probes[i]!.treeTier > probes[i - 1]!.treeTier;
+		if (moveOutward && probes[i - 1]!.result !== "promoted") {
+			return false;
+		}
+	}
+	return true;
+}
+
+/**
+ * Walk discipline: every single inward step (`treeTier` decreased by exactly 1, or reset to 0 at the
+ * root cold-start) is the response to a `no_state`. The walk never moves toward the root on any other
+ * reply, so inward traffic is one-hop-per-`no_state`, not a storm.
+ */
+export function inwardStepsFollowNoState(trace: WalkTrace): boolean {
+	const { probes } = trace;
+	for (let i = 1; i < probes.length; i++) {
+		const moveInward = probes[i]!.treeTier < probes[i - 1]!.treeTier;
+		if (moveInward && probes[i - 1]!.result !== "no_state") {
+			return false;
+		}
+	}
+	return true;
+}
+
+/**
+ * Claim 4 (inward retry restarts at `d_max`): each fresh walk in a re-registration sequence starts at
+ * its `d_max`, so a participant that drew `unwilling_cohort` backs off in *time* and re-walks from the
+ * top rather than re-hitting the declined coord. `traces` are consecutive `register` calls by one
+ * participant; the first probe of each must sit at that walk's `d_max`.
+ */
+export function retriesRestartAtDMax(traces: readonly WalkTrace[]): boolean {
+	for (const trace of traces) {
+		const first = trace.probes[0];
+		if (first === undefined) {
+			continue;
+		}
+		if (first.treeTier !== trace.dMax) {
+			return false;
+		}
+	}
+	return true;
+}
+
+/**
+ * Claim 5 (sticky promotion): a cohort promoted at `promotedAt` must not be reconsidered for demotion
+ * before `promotedAt + stickyMs`. Returns whether `now` is still inside the sticky window — the e2e
+ * suite asserts the promotion lifecycle refuses demotion exactly while this is `true`.
+ */
+export function stickyHolds(promotedAt: number, now: number, stickyMs: number = DEFAULT_T_PROMOTE_STICKY_MS): boolean {
+	return now - promotedAt < stickyMs;
+}

package/src/cohort-topic/antiflood/jitter.ts

@@ -1,117 +1,117 @@
-/**
- * Cohort-topic substrate — re-registration jitter (anti-flood claim 2).
- *
- * Transcribed from `docs/cohort-topic.md` §Anti-flood properties (claim 2: "Re-registration storm
- * after cohort failure") and folded back from the simulator-validated
- * `packages/substrate-simulator/src/walk.ts` (`rejoinStagger` / `rateLimitedStagger`). When a cohort
- * fails, every participant it served re-registers at once; without staggering, the recovering or
- * replacement cohort takes the whole wave in a single instant and is shoved straight past
- * `cap_promote`. Spreading the wave over `T_rejoin_jitter` (default 30 s, widened with the observed
- * FRET cohort-failure rate) bounds the recovering cohort's inbound rate to
- * `cap_promote / T_rejoin_jitter`.
- *
- * Two staggering forms, both exposed here:
- * - {@link RejoinJitter.scheduleRejoin} — a single participant draws a uniform offset over the
- *   jitter window. Decorrelates one participant's retry from its peers (the production API: a
- *   participant that loses its cohort calls this once). Random, so the bound holds *in expectation*.
- * - {@link RejoinJitter.scheduleWave} — a whole wave of `count` rejoiners is placed at a fixed
- *   interval `windowMs / cap_promote`, so **any** `windowMs`-long window contains at most
- *   `cap_promote` arrivals *by construction*. This is the hard-bound form the e2e suite asserts
- *   against; it widens the span past one window when `count > cap_promote` so the rate ceiling
- *   `cap_promote / T_rejoin_jitter` is never exceeded.
- *
- * This module is FRET-free and side-effect-free apart from the injected RNG: the caller schedules a
- * timer at the returned timestamp.
- */
-
-import { createLogger } from "../../logger.js";
-
-const log = createLogger("cohort-topic:antiflood");
-
-/** Default jitter window `T_rejoin_jitter` (ms) — `docs/cohort-topic.md` §Configuration. */
-export const DEFAULT_T_REJOIN_JITTER_MS = 30_000;
-/** Default `cap_promote` — sets the inbound-rate ceiling `cap_promote / T_rejoin_jitter`. */
-export const DEFAULT_REJOIN_CAP_PROMOTE = 64;
-
-export interface RejoinJitterConfig {
-	/** Base jitter window `T_rejoin_jitter` (ms). Default {@link DEFAULT_T_REJOIN_JITTER_MS}. */
-	tRejoinJitterMs?: number;
-	/** Acceptance ceiling per window; the rate bound is `capPromote / T_rejoin_jitter`. Default 64. */
-	capPromote?: number;
-	/**
-	 * Multiplier applied to the base window to track the observed FRET cohort-failure rate (claim 2:
-	 * "scaled with cohort failure rate observed from FRET"). A higher failure rate → a wider window so
-	 * the larger expected re-registration wave still respects the rate ceiling. Default 1 (steady FRET).
-	 */
-	failureRateScale?: number;
-	/** Uniform RNG in `[0, 1)`. Injected for determinism in tests; defaults to `Math.random`. */
-	random?: () => number;
-}
-
-/** Staggers post-cohort-failure re-registration so the recovering cohort isn't stormed. */
-export interface RejoinJitter {
-	/**
-	 * Jittered re-registration timestamp for **one** participant: `now + ⌊U[0, windowMs)⌋`. Random,
-	 * so a wave of independent callers spreads roughly uniformly over the window.
-	 */
-	scheduleRejoin(now: number): number;
-	/**
-	 * Rate-bounded timestamps for a whole re-registration wave of `count` participants. Arrivals are
-	 * evenly spaced at `windowMs / capPromote`, so any `windowMs`-long sliding window holds at most
-	 * `capPromote` of them — the `cap_promote / T_rejoin_jitter` ceiling, exactly rather than in
-	 * expectation. Returns one timestamp per participant, ascending.
-	 */
-	scheduleWave(count: number, now: number): number[];
-	/** Effective jitter window (ms) = base `T_rejoin_jitter` × `failureRateScale`. */
-	readonly windowMs: number;
-	/** Per-window acceptance ceiling (`capPromote`); the inbound-rate bound's numerator. */
-	readonly capPromote: number;
-}
-
-class StaggeredRejoinJitter implements RejoinJitter {
-	readonly windowMs: number;
-	readonly capPromote: number;
-	private readonly random: () => number;
-
-	constructor(config: RejoinJitterConfig = {}) {
-		const base = config.tRejoinJitterMs ?? DEFAULT_T_REJOIN_JITTER_MS;
-		if (!(base > 0)) {
-			throw new RangeError(`tRejoinJitterMs must be > 0, got ${base}`);
-		}
-		const scale = config.failureRateScale ?? 1;
-		if (!(scale >= 1)) {
-			throw new RangeError(`failureRateScale must be >= 1, got ${scale}`);
-		}
-		this.capPromote = config.capPromote ?? DEFAULT_REJOIN_CAP_PROMOTE;
-		if (!Number.isInteger(this.capPromote) || this.capPromote <= 0) {
-			throw new RangeError(`capPromote must be a positive integer, got ${this.capPromote}`);
-		}
-		this.windowMs = base * scale;
-		this.random = config.random ?? ((): number => Math.random());
-	}
-
-	scheduleRejoin(now: number): number {
-		const offset = Math.floor(this.random() * this.windowMs);
-		return now + offset;
-	}
-
-	scheduleWave(count: number, now: number): number[] {
-		if (!Number.isInteger(count) || count < 0) {
-			throw new RangeError(`count must be a non-negative integer, got ${count}`);
-		}
-		// Even spacing at windowMs/capPromote guarantees ≤ capPromote arrivals in any windowMs window;
-		// for count > capPromote the wave necessarily spans more than one window, holding the rate.
-		const interval = this.windowMs / this.capPromote;
-		const out = new Array<number>(count);
-		for (let i = 0; i < count; i++) {
-			out[i] = now + Math.floor(i * interval);
-		}
-		log("scheduleWave count=%d window=%d cap=%d span=%d", count, this.windowMs, this.capPromote, count > 0 ? out[count - 1]! - now : 0);
-		return out;
-	}
-}
-
-/** Build a {@link RejoinJitter} over the configured window, rate ceiling, and (test-injectable) RNG. */
-export function createRejoinJitter(config: RejoinJitterConfig = {}): RejoinJitter {
-	return new StaggeredRejoinJitter(config);
-}
+/**
+ * Cohort-topic substrate — re-registration jitter (anti-flood claim 2).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-flood properties (claim 2: "Re-registration storm
+ * after cohort failure") and folded back from the simulator-validated
+ * `packages/substrate-simulator/src/walk.ts` (`rejoinStagger` / `rateLimitedStagger`). When a cohort
+ * fails, every participant it served re-registers at once; without staggering, the recovering or
+ * replacement cohort takes the whole wave in a single instant and is shoved straight past
+ * `cap_promote`. Spreading the wave over `T_rejoin_jitter` (default 30 s, widened with the observed
+ * FRET cohort-failure rate) bounds the recovering cohort's inbound rate to
+ * `cap_promote / T_rejoin_jitter`.
+ *
+ * Two staggering forms, both exposed here:
+ * - {@link RejoinJitter.scheduleRejoin} — a single participant draws a uniform offset over the
+ *   jitter window. Decorrelates one participant's retry from its peers (the production API: a
+ *   participant that loses its cohort calls this once). Random, so the bound holds *in expectation*.
+ * - {@link RejoinJitter.scheduleWave} — a whole wave of `count` rejoiners is placed at a fixed
+ *   interval `windowMs / cap_promote`, so **any** `windowMs`-long window contains at most
+ *   `cap_promote` arrivals *by construction*. This is the hard-bound form the e2e suite asserts
+ *   against; it widens the span past one window when `count > cap_promote` so the rate ceiling
+ *   `cap_promote / T_rejoin_jitter` is never exceeded.
+ *
+ * This module is FRET-free and side-effect-free apart from the injected RNG: the caller schedules a
+ * timer at the returned timestamp.
+ */
+
+import { createLogger } from "../../logger.js";
+
+const log = createLogger("cohort-topic:antiflood");
+
+/** Default jitter window `T_rejoin_jitter` (ms) — `docs/cohort-topic.md` §Configuration. */
+export const DEFAULT_T_REJOIN_JITTER_MS = 30_000;
+/** Default `cap_promote` — sets the inbound-rate ceiling `cap_promote / T_rejoin_jitter`. */
+export const DEFAULT_REJOIN_CAP_PROMOTE = 64;
+
+export interface RejoinJitterConfig {
+	/** Base jitter window `T_rejoin_jitter` (ms). Default {@link DEFAULT_T_REJOIN_JITTER_MS}. */
+	tRejoinJitterMs?: number;
+	/** Acceptance ceiling per window; the rate bound is `capPromote / T_rejoin_jitter`. Default 64. */
+	capPromote?: number;
+	/**
+	 * Multiplier applied to the base window to track the observed FRET cohort-failure rate (claim 2:
+	 * "scaled with cohort failure rate observed from FRET"). A higher failure rate → a wider window so
+	 * the larger expected re-registration wave still respects the rate ceiling. Default 1 (steady FRET).
+	 */
+	failureRateScale?: number;
+	/** Uniform RNG in `[0, 1)`. Injected for determinism in tests; defaults to `Math.random`. */
+	random?: () => number;
+}
+
+/** Staggers post-cohort-failure re-registration so the recovering cohort isn't stormed. */
+export interface RejoinJitter {
+	/**
+	 * Jittered re-registration timestamp for **one** participant: `now + ⌊U[0, windowMs)⌋`. Random,
+	 * so a wave of independent callers spreads roughly uniformly over the window.
+	 */
+	scheduleRejoin(now: number): number;
+	/**
+	 * Rate-bounded timestamps for a whole re-registration wave of `count` participants. Arrivals are
+	 * evenly spaced at `windowMs / capPromote`, so any `windowMs`-long sliding window holds at most
+	 * `capPromote` of them — the `cap_promote / T_rejoin_jitter` ceiling, exactly rather than in
+	 * expectation. Returns one timestamp per participant, ascending.
+	 */
+	scheduleWave(count: number, now: number): number[];
+	/** Effective jitter window (ms) = base `T_rejoin_jitter` × `failureRateScale`. */
+	readonly windowMs: number;
+	/** Per-window acceptance ceiling (`capPromote`); the inbound-rate bound's numerator. */
+	readonly capPromote: number;
+}
+
+class StaggeredRejoinJitter implements RejoinJitter {
+	readonly windowMs: number;
+	readonly capPromote: number;
+	private readonly random: () => number;
+
+	constructor(config: RejoinJitterConfig = {}) {
+		const base = config.tRejoinJitterMs ?? DEFAULT_T_REJOIN_JITTER_MS;
+		if (!(base > 0)) {
+			throw new RangeError(`tRejoinJitterMs must be > 0, got ${base}`);
+		}
+		const scale = config.failureRateScale ?? 1;
+		if (!(scale >= 1)) {
+			throw new RangeError(`failureRateScale must be >= 1, got ${scale}`);
+		}
+		this.capPromote = config.capPromote ?? DEFAULT_REJOIN_CAP_PROMOTE;
+		if (!Number.isInteger(this.capPromote) || this.capPromote <= 0) {
+			throw new RangeError(`capPromote must be a positive integer, got ${this.capPromote}`);
+		}
+		this.windowMs = base * scale;
+		this.random = config.random ?? ((): number => Math.random());
+	}
+
+	scheduleRejoin(now: number): number {
+		const offset = Math.floor(this.random() * this.windowMs);
+		return now + offset;
+	}
+
+	scheduleWave(count: number, now: number): number[] {
+		if (!Number.isInteger(count) || count < 0) {
+			throw new RangeError(`count must be a non-negative integer, got ${count}`);
+		}
+		// Even spacing at windowMs/capPromote guarantees ≤ capPromote arrivals in any windowMs window;
+		// for count > capPromote the wave necessarily spans more than one window, holding the rate.
+		const interval = this.windowMs / this.capPromote;
+		const out = new Array<number>(count);
+		for (let i = 0; i < count; i++) {
+			out[i] = now + Math.floor(i * interval);
+		}
+		log("scheduleWave count=%d window=%d cap=%d span=%d", count, this.windowMs, this.capPromote, count > 0 ? out[count - 1]! - now : 0);
+		return out;
+	}
+}
+
+/** Build a {@link RejoinJitter} over the configured window, rate ceiling, and (test-injectable) RNG. */
+export function createRejoinJitter(config: RejoinJitterConfig = {}): RejoinJitter {
+	return new StaggeredRejoinJitter(config);
+}