@optimystic/db-core 0.21.0 → 0.24.0

package/src/cohort-topic/coldstart.ts

@@ -1,237 +1,237 @@
-/**
- * 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** carried on the wire (`RegisterV1.followOn`), set only on the dedicated
- * re-issue a participant sends after a parent cohort's `Promoted` redirect target answered `NoState`
- * (the deeper child is cold). A cold high-tier cohort still returns `NoState` to a *speculative* `d_max`
- * probe (neither flag set), but the single-direction walk means the only registrations that reach a cold
- * tier-`(d+1)` cohort carrying `followOn: true` are those that followed the parent's `Promoted` redirect.
- * The db-p2p cohort host derives `ctx.followOn` from the wire flag (`followOn: reg.followOn === true`) and
- * db-core takes it as an explicit input to {@link shouldInstantiate}, keeping this module FRET-free. Because
- * the flag is participant-forgeable, a `followOn: true` register is gated by the **same** tier-dependent
- * bootstrap-evidence policy a `bootstrap: true` cold-root register passes (§Anti-DoS), so an unbacked
- * follow-on never reaches this instantiation decision.
- *
- * Once instantiated, the new forwarder **registers itself with its tier-`(d − 1)` parent at first
- * opportunity** by sending a child-link the parent authenticates + records; until that link is acked
- * (`linked`) 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";
-import { createLogger } from "../logger.js";
-
-const log = createLogger('cohort-topic:coldstart');
-
-/** 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 only when the parent
- * authenticates + records the child and returns a `linked` ack. A `rejected` reply (bad coord binding /
- * failed threshold verify) or an unreachable parent rejects the promise, so the forwarder stays
- * `awaiting_parent` for a later retry.
- */
-export interface ParentRegistrar {
-	/**
-	 * Register the forwarder for `topicId` (served at tree tier `tier`, i.e. `d`) with the cohort at
-	 * `parentCoord`; resolves on a `linked` ack. `opTier` is the topic's *capacity* tier (T0–T3), threaded so
-	 * the transport can stamp a well-formed child-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;
-	/**
-	 * Drop the forwarder for `topicId` (budget eviction / teardown). Idempotent; a no-op if the topic is
-	 * not tracked. After this, {@link get} returns `undefined` for `topicId`, so the cohort no longer
-	 * reports serving it via cold-start state.
-	 */
-	remove(topicId: Uint8Array): void;
-	/**
-	 * Whether this manager currently tracks any forwarder. The host's idle-engine eviction reads this to
-	 * avoid reclaiming a cohort that holds a live (possibly `awaiting_parent`) cold-start forwarder.
-	 */
-	hasForwarders(): boolean;
-}
-
-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) => {
-					log('WARN: parent registration for tier-%s forwarder failed %o', tier, err);
-				});
-		}
-		return forwarder;
-	}
-
-	get(topicId: Uint8Array): Forwarder | undefined {
-		return this.forwarders.get(bytesKey(topicId));
-	}
-
-	remove(topicId: Uint8Array): void {
-		// Idempotent: `Map.delete` on an absent key is a safe no-op, so a double-remove (or a remove of a
-		// never-instantiated topic) does nothing.
-		this.forwarders.delete(bytesKey(topicId));
-	}
-
-	hasForwarders(): boolean {
-		return this.forwarders.size > 0;
-	}
-}
-
-/** Build a {@link ColdStartManager} over the injected parent registrar. */
-export function createColdStartManager(deps: ColdStartManagerDeps): ColdStartManager {
-	return new TrackingColdStartManager(deps);
-}
+/**
+ * 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** carried on the wire (`RegisterV1.followOn`), set only on the dedicated
+ * re-issue a participant sends after a parent cohort's `Promoted` redirect target answered `NoState`
+ * (the deeper child is cold). A cold high-tier cohort still returns `NoState` to a *speculative* `d_max`
+ * probe (neither flag set), but the single-direction walk means the only registrations that reach a cold
+ * tier-`(d+1)` cohort carrying `followOn: true` are those that followed the parent's `Promoted` redirect.
+ * The db-p2p cohort host derives `ctx.followOn` from the wire flag (`followOn: reg.followOn === true`) and
+ * db-core takes it as an explicit input to {@link shouldInstantiate}, keeping this module FRET-free. Because
+ * the flag is participant-forgeable, a `followOn: true` register is gated by the **same** tier-dependent
+ * bootstrap-evidence policy a `bootstrap: true` cold-root register passes (§Anti-DoS), so an unbacked
+ * follow-on never reaches this instantiation decision.
+ *
+ * Once instantiated, the new forwarder **registers itself with its tier-`(d − 1)` parent at first
+ * opportunity** by sending a child-link the parent authenticates + records; until that link is acked
+ * (`linked`) 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";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('cohort-topic:coldstart');
+
+/** 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 only when the parent
+ * authenticates + records the child and returns a `linked` ack. A `rejected` reply (bad coord binding /
+ * failed threshold verify) or an unreachable parent rejects the promise, so the forwarder stays
+ * `awaiting_parent` for a later retry.
+ */
+export interface ParentRegistrar {
+	/**
+	 * Register the forwarder for `topicId` (served at tree tier `tier`, i.e. `d`) with the cohort at
+	 * `parentCoord`; resolves on a `linked` ack. `opTier` is the topic's *capacity* tier (T0–T3), threaded so
+	 * the transport can stamp a well-formed child-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;
+	/**
+	 * Drop the forwarder for `topicId` (budget eviction / teardown). Idempotent; a no-op if the topic is
+	 * not tracked. After this, {@link get} returns `undefined` for `topicId`, so the cohort no longer
+	 * reports serving it via cold-start state.
+	 */
+	remove(topicId: Uint8Array): void;
+	/**
+	 * Whether this manager currently tracks any forwarder. The host's idle-engine eviction reads this to
+	 * avoid reclaiming a cohort that holds a live (possibly `awaiting_parent`) cold-start forwarder.
+	 */
+	hasForwarders(): boolean;
+}
+
+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) => {
+					log('WARN: parent registration for tier-%s forwarder failed %o', tier, err);
+				});
+		}
+		return forwarder;
+	}
+
+	get(topicId: Uint8Array): Forwarder | undefined {
+		return this.forwarders.get(bytesKey(topicId));
+	}
+
+	remove(topicId: Uint8Array): void {
+		// Idempotent: `Map.delete` on an absent key is a safe no-op, so a double-remove (or a remove of a
+		// never-instantiated topic) does nothing.
+		this.forwarders.delete(bytesKey(topicId));
+	}
+
+	hasForwarders(): boolean {
+		return this.forwarders.size > 0;
+	}
+}
+
+/** 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

@@ -1,88 +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;
-		},
-	};
-}
+/**
+ * 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;
+		},
+	};
+}