@optimystic/db-core 0.13.5 → 0.14.0

package/src/cohort-topic/antidos/topic-budget.ts

@@ -0,0 +1,145 @@
+/**
+ * Cohort-topic substrate — per-cohort topic budget (anti-DoS).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 2. A cohort holds forwarder state for at
+ * most `topics_max` (default 2048) topics. Once the budget is full a request to instantiate a **new**
+ * topic is refused (the caller answers `UnwillingCohort`); topics already in the budget continue to
+ * serve. To keep room for genuinely active topics, the budget evicts cold ones: eviction order is
+ * **LRU by participant count**, with **zero-recent-registration topics dropped first** — a topic that
+ * carries no direct participants is the cheapest to shed and is shed before any populated topic.
+ *
+ * `admit` only ever evicts a *zero-participant* topic. If every resident topic still carries
+ * participants the budget is genuinely saturated and the new instantiation is refused — an attacker
+ * cannot, by flooding new topic ids, evict a topic that real participants are using. LRU ordering
+ * uses a monotonic access counter bumped on every `admit`/`touch`, so it is deterministic and needs
+ * no wall clock.
+ */
+
+import { bytesKey } from "../registration/bytes.js";
+import { createLogger } from "../../logger.js";
+
+const log = createLogger("cohort-topic:antidos");
+
+/** Default per-cohort forwarder-topic ceiling — `topics_max`. */
+export const DEFAULT_TOPICS_MAX = 2048;
+
+export interface TopicBudgetConfig {
+	/** Max topics with forwarder state. Default {@link DEFAULT_TOPICS_MAX}. */
+	topicsMax?: number;
+}
+
+/** Per-cohort cap on the number of topics with forwarder state, with LRU eviction of cold topics. */
+export interface TopicBudget {
+	/**
+	 * Admit `topicId` to the forwarder-state budget. Returns `true` if it is already resident or there
+	 * is (or can be freed) room; `false` when the budget is full of populated topics, in which case the
+	 * caller answers `UnwillingCohort` for the new instantiation. Admitting a *new* topic when full
+	 * evicts the coldest zero-participant resident first.
+	 */
+	admit(topicId: Uint8Array): boolean;
+	/**
+	 * Record the current direct-participant count for a resident topic (LRU bookkeeping). Updates the
+	 * eviction key and bumps the topic's recency; a no-op for a topic that is not resident.
+	 */
+	touch(topicId: Uint8Array, participantCount: number): void;
+	/** Whether `topicId` currently holds forwarder state. */
+	has(topicId: Uint8Array): boolean;
+	/**
+	 * The direct-participant count last reported for a resident `topicId` (the eviction key), or
+	 * `undefined` when the topic is not resident. A resident reporting `0` is cold/evictable. Read-only
+	 * introspection for tests/diagnostics — eviction policy reads the same field internally.
+	 */
+	participantCount(topicId: Uint8Array): number | undefined;
+	/** Number of resident topics. */
+	readonly size: number;
+}
+
+/** Per-resident eviction bookkeeping. */
+interface ResidentState {
+	/** Direct-participant count last reported via `touch` (eviction primary key; ascending = colder). */
+	participantCount: number;
+	/** Monotonic access sequence (LRU tiebreaker; lower = least-recently used). */
+	seq: number;
+}
+
+class LruTopicBudget implements TopicBudget {
+	private readonly residents = new Map<string, ResidentState>();
+	private readonly topicsMax: number;
+	private seqCounter = 0;
+
+	constructor(config: TopicBudgetConfig = {}) {
+		this.topicsMax = config.topicsMax ?? DEFAULT_TOPICS_MAX;
+		if (!Number.isInteger(this.topicsMax) || this.topicsMax <= 0) {
+			throw new RangeError(`topicsMax must be a positive integer, got ${this.topicsMax}`);
+		}
+	}
+
+	get size(): number {
+		return this.residents.size;
+	}
+
+	has(topicId: Uint8Array): boolean {
+		return this.residents.has(bytesKey(topicId));
+	}
+
+	participantCount(topicId: Uint8Array): number | undefined {
+		return this.residents.get(bytesKey(topicId))?.participantCount;
+	}
+
+	admit(topicId: Uint8Array): boolean {
+		const key = bytesKey(topicId);
+		const existing = this.residents.get(key);
+		if (existing !== undefined) {
+			existing.seq = ++this.seqCounter; // already resident — refresh recency, always allowed
+			return true;
+		}
+		if (this.residents.size < this.topicsMax) {
+			this.residents.set(key, { participantCount: 0, seq: ++this.seqCounter });
+			return true;
+		}
+		// Full: only a zero-participant resident may be evicted to make room for a new topic.
+		const victim = this.coldestEvictable();
+		if (victim === undefined) {
+			log("topic-budget full size=%d max=%d — refuse new topic", this.residents.size, this.topicsMax);
+			return false;
+		}
+		this.residents.delete(victim);
+		this.residents.set(key, { participantCount: 0, seq: ++this.seqCounter });
+		log("topic-budget evicted cold topic to admit new (size=%d max=%d)", this.residents.size, this.topicsMax);
+		return true;
+	}
+
+	touch(topicId: Uint8Array, participantCount: number): void {
+		const key = bytesKey(topicId);
+		const state = this.residents.get(key);
+		if (state === undefined) {
+			return;
+		}
+		state.participantCount = participantCount;
+		state.seq = ++this.seqCounter;
+	}
+
+	/**
+	 * The coldest evictable resident key: among zero-participant topics, the least-recently used.
+	 * `undefined` when every resident still carries participants (nothing may be evicted for a new topic).
+	 */
+	private coldestEvictable(): string | undefined {
+		let victim: string | undefined;
+		let victimSeq = Infinity;
+		for (const [key, state] of this.residents) {
+			if (state.participantCount > 0) {
+				continue; // populated topics continue — never evicted for a new instantiation
+			}
+			if (state.seq < victimSeq) {
+				victim = key;
+				victimSeq = state.seq;
+			}
+		}
+		return victim;
+	}
+}
+
+/** Build a {@link TopicBudget} over the configured `topics_max`. */
+export function createTopicBudget(config: TopicBudgetConfig = {}): TopicBudget {
+	return new LruTopicBudget(config);
+}

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

@@ -0,0 +1,2 @@
+export * from "./jitter.js";
+export * from "./invariants.js";

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

@@ -0,0 +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;
+}

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

@@ -0,0 +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);
+}

package/src/cohort-topic/coldstart.ts

@@ -0,0 +1,204 @@
+/**
+ * Cohort-topic substrate — cold-start instantiation.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Cold-start instantiation and folded back from the
+ * simulator-validated `packages/substrate-simulator/src/walk.ts` (the `followOn` / `bootstrap`
+ * instantiation paths). A **cold** cohort — one holding no forwarder state for a topic — instantiates
+ * as a forwarder for `T` when:
+ *
+ * - it receives a `RegisterV1` for `T` it does not yet serve, AND
+ * - the registration is a legitimate growth point: its `bootstrap: true` flag is set (the root
+ *   cold-start case) **or** it arrived as a follow-on to a parent cohort's `Promoted` redirect, AND
+ * - a quorum of cohort members is willing to serve `T` at the registration's tier.
+ *
+ * The `followOn` signal is **not** carried on the wire (`RegisterV1` has only `bootstrap`); a cold
+ * high-tier cohort returns `NoState` to a *speculative* `d_max` probe, but the single-direction walk
+ * means the only registrations that reach a cold tier-`(d+1)` cohort are those that followed the
+ * parent's `Promoted` redirect. Determining `followOn` for a given inbound register therefore belongs
+ * to the db-p2p cohort host (it has the routing context); db-core takes it as an explicit input to
+ * {@link shouldInstantiate}, keeping this module FRET-free. (See the implement handoff for the wiring
+ * gap this leaves for the db-p2p binding.)
+ *
+ * Once instantiated, the new forwarder **registers itself with its tier-`(d − 1)` parent at first
+ * opportunity**; until that registration is acked it {@link Forwarder.acceptsParticipants | accepts
+ * participants} but {@link Forwarder.servesParentOps | holds} notifications/queries that need parent
+ * involvement. The root (tree tier 0) has no parent and is serving immediately.
+ *
+ * **Just-promoted burst (GROUNDING-resolved: bounce, don't buffer).** A cohort that has just promoted
+ * but whose tier-`(d+1)` isn't fully instantiated yet, on a burst of new same-tier registrations,
+ * replies `Promoted(d+1)` ({@link promotedRedirectReply}) — a cheap single RPC. It does **not** buffer
+ * the registrations and does **not** decline with `UnwillingCohort`; the promotion sticky window
+ * (`T_promote_sticky`) keeps it in promoted mode through the burst.
+ */
+
+import { attachTopicTraffic } from "./traffic.js";
+import { bytesKey } from "./registration/bytes.js";
+import type { RegisterReplyV1, TopicTrafficV1 } from "./wire/types.js";
+
+/** Inputs to the cold-start admission gate. */
+export interface ColdStartTrigger {
+	/** `RegisterV1.bootstrap` — the root cold-start request flag. */
+	readonly bootstrap: boolean;
+	/** This register arrived as a follow-on to a parent's `Promoted` redirect (db-p2p-determined). */
+	readonly followOn: boolean;
+	/** A quorum of cohort members is willing to serve the topic at this tier. */
+	readonly quorumWilling: boolean;
+}
+
+/**
+ * Whether a cold cohort should instantiate forwarder state for an inbound register: it must be a
+ * legitimate growth point (`bootstrap` root case **or** a `Promoted` follow-on) **and** have a willing
+ * quorum. A speculative `d_max` probe (neither flag set) yields `false`, so the walk gets `NoState`
+ * and steps toward the root instead of forking a parallel branch (§Cold-start; §Why the caller
+ * doesn't walk on UnwillingCohort).
+ */
+export function shouldInstantiate(trigger: ColdStartTrigger): boolean {
+	return (trigger.bootstrap || trigger.followOn) && trigger.quorumWilling;
+}
+
+/** Lifecycle phase of a freshly-instantiated forwarder. */
+export type ForwarderPhase =
+	/** Instantiated, registering with the parent; accepts participants, holds parent-involving ops. */
+	| "awaiting_parent"
+	/** Fully linked (parent acked, or root with no parent); serves everything. */
+	| "serving";
+
+/**
+ * A freshly cold-started forwarder for one topic at this cohort. Holds the "registered with parent
+ * yet?" state that gates parent-involving operations during the link-up window.
+ */
+export interface Forwarder {
+	/** Tree tier `d` this forwarder serves the topic at. */
+	readonly tier: number;
+	/** Current lifecycle phase. */
+	phase(): ForwarderPhase;
+	/** Accept new participants? True from instantiation onward (even before the parent ack). */
+	acceptsParticipants(): boolean;
+	/** Serve an operation needing parent involvement (notifications/queries)? Only once `serving`. */
+	servesParentOps(): boolean;
+	/** Mark the parent-registration RPC acked → transition to `serving`. Idempotent; no-op at the root. */
+	onParentAck(): void;
+}
+
+class ForwarderState implements Forwarder {
+	private serving: boolean;
+
+	constructor(readonly tier: number, hasParent: boolean) {
+		// The root (tree tier 0 / no parent) has nothing to hand off to — it serves immediately.
+		this.serving = !hasParent;
+	}
+
+	phase(): ForwarderPhase {
+		return this.serving ? "serving" : "awaiting_parent";
+	}
+
+	acceptsParticipants(): boolean {
+		return true;
+	}
+
+	servesParentOps(): boolean {
+		return this.serving;
+	}
+
+	onParentAck(): void {
+		this.serving = true;
+	}
+}
+
+/**
+ * Construct a forwarder. A tier-`0` forwarder (the root) has no parent and starts `serving`; a deeper
+ * forwarder starts `awaiting_parent` until {@link Forwarder.onParentAck} fires.
+ */
+export function createForwarder(tier: number): Forwarder {
+	if (!Number.isInteger(tier) || tier < 0) {
+		throw new RangeError(`forwarder tier must be a non-negative integer, got ${tier}`);
+	}
+	return new ForwarderState(tier, tier > 0);
+}
+
+/**
+ * Build a `Promoted(targetTier)` redirect reply — used both for the normal promotion redirect and for
+ * the just-promoted-burst bounce (the registrations arriving at a promoted cohort while its child tier
+ * is still instantiating). The outgoing cohort's `topicTraffic` is attached when supplied, so the
+ * redirected participant can estimate whether the target tier is hot (§Topic traffic signal).
+ */
+export function promotedRedirectReply(targetTier: number, traffic?: TopicTrafficV1): RegisterReplyV1 {
+	if (!Number.isInteger(targetTier) || targetTier < 1) {
+		throw new RangeError(`promoted targetTier must be an integer ≥ 1, got ${targetTier}`);
+	}
+	const reply: RegisterReplyV1 = { v: 1, result: "promoted", targetTier };
+	return traffic !== undefined ? attachTopicTraffic(reply, traffic) : reply;
+}
+
+/** Registers a newly-instantiated forwarder with its tier-`(d − 1)` parent; resolves on the parent ack. */
+export interface ParentRegistrar {
+	/**
+	 * Register the forwarder for `topicId` (served at tree tier `tier`, i.e. `d`) with the cohort at
+	 * `parentCoord`; resolves on ack. `opTier` is the topic's *capacity* tier (T0–T3), threaded so the
+	 * transport can stamp a well-formed forwarder-link frame; absent when the caller has no op-tier
+	 * context (the cohort host always supplies it from the instantiating `RegisterV1`).
+	 */
+	registerWithParent(topicId: Uint8Array, parentCoord: Uint8Array, tier: number, opTier?: number): Promise<void>;
+}
+
+export interface ColdStartManagerDeps {
+	/** Drives the parent-registration RPC (db-p2p binds it to the router). */
+	parentRegistrar: ParentRegistrar;
+}
+
+/**
+ * Tracks cold-started forwarders for a cohort and drives each one's parent registration. Keyed by
+ * `topicId`; idempotent per topic (a second instantiate for an already-tracked topic returns the
+ * existing forwarder).
+ */
+export interface ColdStartManager {
+	/**
+	 * Instantiate (or return the existing) forwarder for `topicId` at tree tier `tier` (`d`). For a
+	 * deeper-than-root forwarder this kicks off parent registration in the background and flips the
+	 * forwarder to `serving` on ack. The returned forwarder accepts participants immediately. `opTier`
+	 * (the topic's T0–T3 capacity tier) is forwarded to the parent registrar for the link frame.
+	 */
+	instantiate(topicId: Uint8Array, tier: number, parentCoord?: Uint8Array, opTier?: number): Forwarder;
+	/** The tracked forwarder for `topicId`, or `undefined`. */
+	get(topicId: Uint8Array): Forwarder | undefined;
+}
+
+class TrackingColdStartManager implements ColdStartManager {
+	private readonly forwarders = new Map<string, Forwarder>();
+
+	constructor(private readonly deps: ColdStartManagerDeps) {}
+
+	instantiate(topicId: Uint8Array, tier: number, parentCoord?: Uint8Array, opTier?: number): Forwarder {
+		const key = bytesKey(topicId);
+		const existing = this.forwarders.get(key);
+		if (existing !== undefined) {
+			return existing;
+		}
+		const forwarder = createForwarder(tier);
+		this.forwarders.set(key, forwarder);
+		if (tier > 0) {
+			if (parentCoord === undefined) {
+				throw new Error(`cold-start of a tier-${tier} forwarder requires a parentCoord`);
+			}
+			// Register with the parent at first opportunity; flip to serving on ack. A failed parent
+			// registration leaves the forwarder accepting participants but holding parent-involving ops,
+			// so a later retry (driven by the host) can complete the link-up — surfaced, not swallowed.
+			void this.deps.parentRegistrar
+				.registerWithParent(topicId, parentCoord, tier, opTier)
+				.then(() => forwarder.onParentAck())
+				.catch((err: unknown) => {
+					console.warn(`cohort-topic cold-start: parent registration for tier-${tier} forwarder failed`, err);
+				});
+		}
+		return forwarder;
+	}
+
+	get(topicId: Uint8Array): Forwarder | undefined {
+		return this.forwarders.get(bytesKey(topicId));
+	}
+}
+
+/** Build a {@link ColdStartManager} over the injected parent registrar. */
+export function createColdStartManager(deps: ColdStartManagerDeps): ColdStartManager {
+	return new TrackingColdStartManager(deps);
+}

package/src/cohort-topic/dmax.ts

@@ -0,0 +1,88 @@
+/**
+ * Cohort-topic substrate — network-size-driven `d_max`.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Maximum useful depth:
+ *
+ * ```
+ * d_max = max(0, ⌊log_F(n_est)⌋ − 1)
+ * ```
+ *
+ * If `n_est` confidence falls below `confidence_min` (default 0.3) the computation caps `d_max` at
+ * `⌊d_max_cap / 2⌋` (`d_max_cap` default 60) as an upper bound — i.e. `min(formula, ⌊d_max_cap / 2⌋)` —
+ * to avoid pathological deep probes from an over-estimated population. Small/sparse populations
+ * (where the formula already yields a small value) are unaffected.
+ *
+ * `d_max` is the start tier of the walk-toward-root and is recomputed **lazily** — participants
+ * don't need it precise. The size estimate is read through the injected {@link ISizeEstimator}
+ * (db-p2p wraps FRET's `estimateSizeAndConfidence`; db-core never imports FRET).
+ */
+
+import type { ISizeEstimator } from "./ports.js";
+
+/** Lazily computes the walk start tier `d_max` from the current network-size estimate. */
+export interface DMaxComputer {
+	/** Reads the size estimate, applies the low-confidence cap, returns `d_max`. */
+	dMax(): number;
+}
+
+/** Default below which `n_est` confidence triggers the `d_max` cap. */
+export const DEFAULT_CONFIDENCE_MIN = 0.3;
+/** Default hard cap on the walk-toward-root start tier. */
+export const DEFAULT_D_MAX_CAP = 60;
+
+export interface DMaxConfig {
+	/** Network-size estimate source (db-p2p wraps FRET `estimateSizeAndConfidence`). */
+	estimator: ISizeEstimator;
+	/** Fan-out per tier (the `F` in `log_F`). */
+	F: number;
+	/** Confidence floor; below it `d_max` is capped at `⌊d_max_cap / 2⌋` (upper bound). Default 0.3. */
+	confidenceMin?: number;
+	/** Hard cap on `d_max`; also drives the low-confidence cap value. Default 60. */
+	dMaxCap?: number;
+}
+
+/**
+ * `⌊log_F(n)⌋` computed without floating-point drift near exact powers of `F`. Multiplies back up to
+ * confirm the floor (`Math.log` can return e.g. `2.9999999` for `log_16(4096)`), so the result is
+ * exact for all `n` representable as a JS integer.
+ */
+function floorLogF(n: number, F: number): number {
+	if (n < 1) return 0;
+	let d = Math.floor(Math.log(n) / Math.log(F));
+	if (d < 0) d = 0;
+	// Correct floating-point error at the boundary in both directions.
+	while (Math.pow(F, d + 1) <= n) d++;
+	while (d > 0 && Math.pow(F, d) > n) d--;
+	return d;
+}
+
+/**
+ * Build a {@link DMaxComputer}. The estimate is read on every {@link DMaxComputer.dMax} call so the
+ * value tracks the latest FRET sample; callers cache it themselves if they want stability.
+ */
+export function makeDMaxComputer(config: DMaxConfig): DMaxComputer {
+	const { estimator, F } = config;
+	if (!Number.isInteger(F) || F < 2) {
+		throw new RangeError(`fan-out F must be an integer ≥ 2, got ${F}`);
+	}
+	const confidenceMin = config.confidenceMin ?? DEFAULT_CONFIDENCE_MIN;
+	const dMaxCap = config.dMaxCap ?? DEFAULT_D_MAX_CAP;
+	if (!Number.isInteger(dMaxCap) || dMaxCap < 0) {
+		throw new RangeError(`d_max_cap must be a non-negative integer, got ${dMaxCap}`);
+	}
+	const capValue = Math.floor(dMaxCap / 2);
+
+	return {
+		dMax(): number {
+			const { nEst, confidence } = estimator.estimate();
+			const formula = Math.min(Math.max(0, floorLogF(nEst, F) - 1), dMaxCap);
+			// Low confidence caps d_max as an upper bound (not a set-to): an over-estimated
+			// population can't push the walk deeper than ⌊d_max_cap / 2⌋, while small
+			// populations keep their (smaller) formula value.
+			if (confidence < confidenceMin) {
+				return Math.min(formula, capValue);
+			}
+			return formula;
+		},
+	};
+}