@optimystic/db-core 0.13.4 → 0.14.0

package/src/cohort-topic/ports.ts

@@ -0,0 +1,157 @@
+/**
+ * Cohort-topic substrate — transport ports.
+ *
+ * These are the seams that keep the cohort-topic substrate split cleanly across packages:
+ * db-core defines the interfaces here (pure logic depends only on a hash function and
+ * byte-array peer IDs), and db-p2p supplies the concrete FRET + libp2p implementations.
+ *
+ * **db-core never imports FRET or libp2p.** Every db-core substrate module takes these ports
+ * by injection (constructor / factory args); db-p2p constructs the FRET-backed versions and
+ * composes them with the db-core logic in `CohortTopicService`'s transport host.
+ *
+ * See `docs/cohort-topic.md` §FRET integration and `tickets` slug
+ * `cohort-topic-package-layering` for the authoritative layering rule.
+ */
+
+import type { MembershipCertV1 } from "./wire/types.js";
+
+/**
+ * Ring coordinate — SHA-256 truncated to the ring width `B` (see {@link IRingHash}). db-core
+ * owns this type; db-p2p maps it onto FRET's coordinate type, ensuring the byte representation
+ * matches FRET's ring width so routing keys line up on the wire.
+ */
+export type RingCoord = Uint8Array;
+
+/** A peer, referenced only by its opaque byte-array id. No multiaddr, no libp2p PeerId here. */
+export interface PeerRef {
+	readonly id: Uint8Array;
+}
+
+/**
+ * Wraps FRET's `RouteAndMaybeAct` so the walk / registration decision logic in db-core stays
+ * transport-agnostic.
+ */
+export interface ITopicRouter {
+	/**
+	 * Route `activity` to the cohort owning `key` and run the cohort's activity callback,
+	 * collecting up to `wantK` participants and at least `minSigs` signatures.
+	 * @returns the encoded cohort reply.
+	 */
+	routeAndAct(key: RingCoord, activity: Uint8Array, opts: { wantK: number; minSigs: number }): Promise<Uint8Array>;
+	/** Direct dial to a cached primary; falls back to {@link routeAndAct} on failure (caller decides). */
+	dialMember(member: PeerRef, activity: Uint8Array): Promise<Uint8Array>;
+}
+
+/** Intra-cohort gossip transport (FRET cohort gossip underneath). */
+export interface ICohortGossipTransport {
+	/** Fire-and-forget broadcast of `msg` to the cohort at `coord`. */
+	broadcast(coord: RingCoord, msg: Uint8Array): void;
+	/** Subscribe to inbound cohort gossip; returns an unsubscribe handle. */
+	onMessage(handler: (from: PeerRef, msg: Uint8Array) => void): () => void;
+}
+
+/** Authoritative cohort membership snapshots (FRET `MembershipCertV1` / stabilization underneath). */
+export interface IMembershipSource {
+	/** Current cached membership cert for `coord`, encoded; `undefined` if none is cached. */
+	current(coord: RingCoord): Promise<Uint8Array | undefined>;
+	/** Force one refresh of `coord`'s membership cert (stale-cache retry); encoded, or `undefined`. */
+	fetch(coord: RingCoord): Promise<Uint8Array | undefined>;
+}
+
+/**
+ * Cohort threshold-signature primitive (FRET's `minSigs = k − x` cohort-signature assembly
+ * underneath). db-core defines the seam; db-p2p binds FRET's signer/verifier without modifying it.
+ * Peer ids are raw byte arrays here ({@link PeerRef}`.id`), matching the rest of the substrate; the
+ * wire layer carries them as base64url strings.
+ */
+export interface ICohortThresholdCrypto {
+	/**
+	 * Assemble a cohort threshold signature over `payload`, collecting at least `minSigs` signers.
+	 * Resolves to the combined signature and the peers that contributed.
+	 */
+	assemble(payload: Uint8Array, minSigs: number): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }>;
+	/** Verify `thresholdSig` is a valid cohort signature over `payload` produced by `signers`. */
+	verify(payload: Uint8Array, thresholdSig: Uint8Array, signers: readonly Uint8Array[]): boolean;
+}
+
+/**
+ * Sink the cohort uses to publish a `MembershipCertV1` (over FRET's `/membership` protocol).
+ * db-core's publisher builds + threshold-signs the cert and hands it here; db-p2p serves it.
+ */
+export interface IMembershipPublishSink {
+	/** Publish (advertise/serve) an already-signed membership certificate, encoded. */
+	publish(encodedCert: Uint8Array): void;
+}
+
+/** Network-size estimate feeding `d_max`. */
+export interface ISizeEstimator {
+	estimate(): { nEst: number; confidence: number };
+}
+
+/**
+ * Verdict on whether a {@link MembershipCertV1}'s `(cohortCoord → members)` binding is vouched by a
+ * source the verifying node *directly* trusts.
+ *
+ * - `"anchored"`  — the binding is vouched (e.g. matches FRET `assembleCohort(coord)`, or the
+ *   tx-log commit certificate). The cert is trusted on this basis.
+ * - `"rejected"`  — the binding is contradicted (a known-different keyset owns this coord). A
+ *   `"rejected"` verdict is **fatal**: the cert is a forgery and is rejected even if it is
+ *   internally self-consistent, overriding the interim TOFU fallback.
+ * - `"unknown"`   — this node has no local authority over the coord, so it cannot judge. The
+ *   verifier falls through to the attestation chain / interim TOFU fallback.
+ */
+export type TrustAnchorVerdict = "anchored" | "rejected" | "unknown";
+
+/**
+ * Direct (base-case) trust anchor for a {@link MembershipCertV1}'s `coord → keyset` binding.
+ *
+ * db-core owns the chain-of-attestations and trust-root logic; the **direct** anchor is
+ * tier/transport-specific (FRET ring agreement for T2/T3, tx-log commit certificate for T0/T1) and
+ * is therefore delegated through this port. db-p2p binds it; **db-core never imports FRET**. A node
+ * with no local authority for the coord returns `"unknown"` so the verifier falls through to the
+ * chain / interim fallback instead of breaking distant verification. See {@link noAuthorityTrustAnchor}
+ * for the db-core default (every coord `"unknown"`).
+ */
+export interface IMembershipTrustAnchor {
+	/** Judge, from a directly-trusted source, whether `cert.members` is authoritative for `cert.cohortCoord` at `tier`. */
+	directAnchor(cert: MembershipCertV1, tier: number): TrustAnchorVerdict;
+}
+
+/**
+ * An out-of-band-seeded trust root: the genesis-block-related cohorts a joining participant is told
+ * to trust (validated against the genesis block hash by the caller before seeding). A trust root is
+ * the base case of every attestation chain — a cert matching a root by `(coord, epoch, member-set)`
+ * is trusted directly. Byte fields are raw (the verifier compares them against the cert's base64url
+ * form internally).
+ */
+export interface TrustRoot {
+	/** Cohort coord (32 bytes). */
+	readonly coord: Uint8Array;
+	/** Cohort epoch (32 bytes) — required so a cert reusing a genesis coord with a swapped keyset is not a root. */
+	readonly epoch: Uint8Array;
+	/** Authoritative cohort members (any order; matched as a set). */
+	readonly members: readonly Uint8Array[];
+}
+
+/**
+ * The db-core default {@link IMembershipTrustAnchor}: it has no local authority over any coord, so it
+ * returns `"unknown"` for every cert. Existing verifier callers that inject no anchor get this, keeping
+ * the interim TOFU behavior (no regression) until db-p2p binds a real anchor.
+ */
+export const noAuthorityTrustAnchor: IMembershipTrustAnchor = {
+	directAnchor(_cert: MembershipCertV1, _tier: number): TrustAnchorVerdict {
+		return "unknown";
+	},
+};
+
+/**
+ * Hash + ring math. db-core supplies its OWN SHA-256 (it already hashes logs and block ids);
+ * the ring width is configuration. db-p2p, when mapping {@link RingCoord} onto FRET's coordinate
+ * type, ensures `ringBits` matches FRET's ring width so coords are byte-compatible.
+ */
+export interface IRingHash {
+	/** SHA-256 of `bytes`, truncated to the ring width `B` ({@link ringBits}). */
+	H(bytes: Uint8Array): RingCoord;
+	/** Ring width in bits. */
+	readonly ringBits: number;
+}

package/src/cohort-topic/promotion.ts

@@ -0,0 +1,384 @@
+/**
+ * Cohort-topic substrate — promotion / demotion lifecycle.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Promotion and demotion lifecycle and folded back from the
+ * simulator-validated `packages/substrate-simulator/src/topic-tree.ts`. A forwarder cohort grows
+ * (promotes) and shrinks (demotes) for a topic `T` based on its per-topic direct-participant count
+ * and the per-tier load barometer; both transitions are **threshold-signed** (via the gossip ticket's
+ * {@link CohortSigner}) so participants can verify them.
+ *
+ * **Promote** when, for a quorum (the quorum is enforced by the threshold signature — `minSigs`
+ * signers must agree to the notice):
+ * - `directParticipants(T) ≥ cap_promote` (64), OR
+ * - `loadBucket[tier(T)] ≥ bucket_overload` (6) AND `directParticipants(T) ≥ cap_promote_fast` (32)
+ *   — the hot-load fast path from the capacity-barometer ticket, OR
+ * - the growth **slope** predicts crossing `cap_promote` within `T_promote_lookahead` (30s) — fires
+ *   early to avoid the gossip-lag overshoot (`§Promotion`: pre-promotion on slope).
+ *
+ * Once promoted, the state is **sticky** for ≥ `T_promote_sticky` (60s) before it can be reconsidered
+ * for demotion, so transient count drops don't flap a cohort back to accepting.
+ *
+ * **Demote** when, for a quorum: `directParticipants(T) ≤ cap_demote` (16) AND that has held for
+ * ≥ `T_demote` (5min) AND the cohort has no live child cohorts AND it has a parent (the root, tree
+ * tier 0, never demotes — it has nowhere to hand off). The `4×` gap between `cap_promote` and
+ * `cap_demote` plus `T_demote` is the hysteresis that prevents thrash.
+ *
+ * **Deviation from the doc's interface sketch (documented).** `docs/cohort-topic.md` sketches
+ * `onParticipantCountChange` as returning `void` and "may emit `PromotionNoticeV1`". Because
+ * threshold signing is asynchronous ({@link CohortSigner.thresholdSign} resolves a Promise), the
+ * methods here are `async` and **return** the signed notice (or `undefined`) instead of emitting it
+ * through a side channel — the caller broadcasts whatever it gets back. This keeps the module pure
+ * and unit-testable and avoids an awkward async callback. The op-tier `tier(T)` the barometer is
+ * indexed by is supplied through the injected {@link PromotionDeps.loadBucket} resolver, so this
+ * module never needs to know a topic's tier.
+ *
+ * **Remote apply path.** `promote()` / `demote()` set this cohort's per-topic state as a side effect of
+ * the **local** signing path — only the member that originates a notice adopts the new state that way. A
+ * member that *learns* of a promotion/demotion via gossip or a broadcast notice adopts it through
+ * {@link PromotionLifecycle.applyPromotionNotice} / {@link PromotionLifecycle.applyDemotionNotice},
+ * which set the same {@link PromotionState} **without re-signing** (the notice is already a verified
+ * quorum decision). **Precondition: the caller has already verified the notice's threshold signature**
+ * (db-p2p's `MembershipVerifier`); this module is crypto-free and trusts that gate. The apply path is
+ * 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.
+ */
+
+import { b64urlToBytes, bytesToB64url } from "./wire/codec.js";
+import type { CohortSigner } from "./sig/threshold.js";
+import { demotionNoticeSigningPayload, promotionNoticeSigningPayload } from "./sig/payloads.js";
+import type { DemotionNoticeV1, PromotionNoticeV1 } from "./wire/types.js";
+import type { RegistrationStore } from "./registration/types.js";
+import { bytesKey } from "./registration/bytes.js";
+
+// --- defaults (docs/cohort-topic.md §Configuration; simulator-confirmed) ---
+
+/** Direct-participant cap before promotion. */
+export const DEFAULT_CAP_PROMOTE = 64;
+/** Direct-participant cap when the load barometer is hot (fast path). */
+export const DEFAULT_CAP_PROMOTE_FAST = 32;
+/** Load-barometer bucket at/above which the fast promote path is armed. */
+export const DEFAULT_BUCKET_OVERLOAD = 6;
+/** Direct-participant floor for demotion (= `cap_promote / 4`). */
+export const DEFAULT_CAP_DEMOTE = 16;
+/** Hysteresis window the low-load condition must hold before demotion (ms). */
+export const DEFAULT_T_DEMOTE_MS = 300_000;
+/** Pre-promotion slope lookahead (ms). */
+export const DEFAULT_T_PROMOTE_LOOKAHEAD_MS = 30_000;
+/** Minimum time a cohort stays promoted before it can be reconsidered for demotion (ms). */
+export const DEFAULT_T_PROMOTE_STICKY_MS = 60_000;
+/**
+ * Slope window over which the growth rate is measured for pre-promotion. **Not pinned by
+ * `docs/cohort-topic.md`** — the simulator (`topic-tree.ts` `DEFAULT_LIFECYCLE_CONFIG`) uses 10s and
+ * this matches it.
+ */
+export const DEFAULT_GROWTH_WINDOW_MS = 10_000;
+
+export interface PromotionConfig {
+	capPromote?: number;
+	capPromoteFast?: number;
+	bucketOverload?: number;
+	capDemote?: number;
+	tDemoteMs?: number;
+	tPromoteLookaheadMs?: number;
+	tPromoteStickyMs?: number;
+	growthWindowMs?: number;
+}
+
+/** A sampled `(time, count)` growth point, for slope-based pre-promotion. */
+interface GrowthSample {
+	readonly t: number;
+	readonly count: number;
+}
+
+/** Per-topic promotion bookkeeping held by this cohort. */
+interface PromotionState {
+	promoted: boolean;
+	/** When the cohort last entered promoted mode (sticky-window anchor). */
+	promotedAt?: number;
+	/** When `directParticipants` last dropped to ≤ `cap_demote` (demotion hysteresis anchor). */
+	lowLoadSince?: number;
+	/** Recent growth samples within `growthWindowMs`, for slope extrapolation. */
+	samples: GrowthSample[];
+	/**
+	 * `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.
+	 */
+	lastEffectiveAt?: number;
+}
+
+export interface PromotionDeps {
+	/** Replicated registration store — supplies the per-topic `directParticipants` stock count. */
+	store: Pick<RegistrationStore, "directParticipants">;
+	/**
+	 * Current load-barometer bucket (0..7) for the topic's op tier `tier(T)`. The caller resolves the
+	 * topic→tier mapping and the barometer lookup, keeping this module tier-agnostic and FRET-free.
+	 */
+	loadBucket: (topicId: Uint8Array) => number;
+	/** Live child-cohort count for the topic (0 if none); `> 0` blocks demotion. */
+	childCohortCount: (topicId: Uint8Array) => number;
+	/** Tree tier `d` this cohort serves the topic at — `fromTier` on a notice; `toTier = d + 1`. */
+	treeTier: (topicId: Uint8Array) => number;
+	/** The tier-`(d − 1)` parent cohort coord, target of a {@link DemotionNoticeV1}. */
+	parentCoord: (topicId: Uint8Array) => Uint8Array;
+	/** Cohort epoch (raw bytes) the notices are signed under. */
+	cohortEpoch: () => Uint8Array;
+	/** Threshold signer (the gossip ticket's `k − x` cohort signer). */
+	signer: CohortSigner;
+	config?: PromotionConfig;
+}
+
+/**
+ * Promotion / demotion lifecycle for one cohort across all the topics it serves. Keyed by `topicId`;
+ * each topic carries its own promoted/low-load/sticky state.
+ */
+export interface PromotionLifecycle {
+	/**
+	 * React to a change in `topicId`'s direct-participant count (call after every arrival/eviction).
+	 * Refreshes the growth + hysteresis clocks and, if a promote trigger fires and the cohort is not
+	 * already promoted, threshold-signs and returns a {@link PromotionNoticeV1}. Returns `undefined`
+	 * when no promotion fires.
+	 */
+	onParticipantCountChange(topicId: Uint8Array, now: number): Promise<PromotionNoticeV1 | undefined>;
+	/**
+	 * Time-driven demotion check (call on the gossip tick). Returns a threshold-signed
+	 * {@link DemotionNoticeV1} for the parent when every demotion condition holds, else `undefined`.
+	 */
+	maybeDemote(topicId: Uint8Array, now: number): Promise<DemotionNoticeV1 | undefined>;
+	/** Whether `topicId` is currently in promoted mode (new registrations get `Promoted(d+1)`). */
+	isPromoted(topicId: Uint8Array): boolean;
+	/**
+	 * Adopt a promotion this member did **not** originate (learned via a verified broadcast notice).
+	 * Sets `promoted = true` for `n.topicId` without re-signing. **Precondition: the caller has verified
+	 * `n`'s threshold signature** — this module performs no crypto. Idempotent and `effectiveAt`-ordered
+	 * (see {@link PromotionState.lastEffectiveAt}): a notice not strictly newer than the last adopted
+	 * transition is a no-op, so this member's own echoed broadcast and stale replays are absorbed.
+	 */
+	applyPromotionNotice(n: PromotionNoticeV1, now: number): void;
+	/**
+	 * Adopt a demotion this member did **not** originate (learned via a verified broadcast notice).
+	 * Clears `promoted` state for `n.topicId` without re-signing. Same precondition, idempotency, and
+	 * `effectiveAt` ordering as {@link applyPromotionNotice} — a stale promotion can never un-demote.
+	 */
+	applyDemotionNotice(n: DemotionNoticeV1, now: number): void;
+}
+
+class CohortPromotionLifecycle implements PromotionLifecycle {
+	private readonly states = new Map<string, PromotionState>();
+	private readonly capPromote: number;
+	private readonly capPromoteFast: number;
+	private readonly bucketOverload: number;
+	private readonly capDemote: number;
+	private readonly tDemoteMs: number;
+	private readonly tPromoteLookaheadMs: number;
+	private readonly tPromoteStickyMs: number;
+	private readonly growthWindowMs: number;
+
+	constructor(private readonly deps: PromotionDeps) {
+		const cfg = deps.config ?? {};
+		this.capPromote = cfg.capPromote ?? DEFAULT_CAP_PROMOTE;
+		this.capPromoteFast = cfg.capPromoteFast ?? DEFAULT_CAP_PROMOTE_FAST;
+		this.bucketOverload = cfg.bucketOverload ?? DEFAULT_BUCKET_OVERLOAD;
+		this.capDemote = cfg.capDemote ?? DEFAULT_CAP_DEMOTE;
+		this.tDemoteMs = cfg.tDemoteMs ?? DEFAULT_T_DEMOTE_MS;
+		this.tPromoteLookaheadMs = cfg.tPromoteLookaheadMs ?? DEFAULT_T_PROMOTE_LOOKAHEAD_MS;
+		this.tPromoteStickyMs = cfg.tPromoteStickyMs ?? DEFAULT_T_PROMOTE_STICKY_MS;
+		this.growthWindowMs = cfg.growthWindowMs ?? DEFAULT_GROWTH_WINDOW_MS;
+	}
+
+	async onParticipantCountChange(topicId: Uint8Array, now: number): Promise<PromotionNoticeV1 | undefined> {
+		const state = this.stateFor(topicId);
+		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)) {
+			return undefined;
+		}
+		return this.promote(topicId, state, now);
+	}
+
+	async maybeDemote(topicId: Uint8Array, now: number): Promise<DemotionNoticeV1 | undefined> {
+		const state = this.states.get(bytesKey(topicId));
+		if (state === undefined) {
+			return undefined;
+		}
+		if (!this.demotionTriggered(topicId, state, now)) {
+			return undefined;
+		}
+		return this.demote(topicId, state, now);
+	}
+
+	isPromoted(topicId: Uint8Array): boolean {
+		return this.states.get(bytesKey(topicId))?.promoted ?? false;
+	}
+
+	// --- remote apply (verified notices this member did not originate) ---
+
+	applyPromotionNotice(n: PromotionNoticeV1, now: number): void {
+		const state = this.stateFor(b64urlToBytes(n.topicId));
+		if (!this.isNewerTransition(state, n.effectiveAt)) {
+			return; // already adopted, our own echoed broadcast, or a stale replay
+		}
+		state.promoted = true;
+		state.promotedAt = now;
+		state.lastEffectiveAt = n.effectiveAt;
+	}
+
+	applyDemotionNotice(n: DemotionNoticeV1, _now: number): void {
+		const state = this.stateFor(b64urlToBytes(n.topicId));
+		if (!this.isNewerTransition(state, n.effectiveAt)) {
+			return;
+		}
+		// Mirror the local demote() release so a later re-growth re-evaluates cleanly.
+		state.promoted = false;
+		state.promotedAt = undefined;
+		state.lowLoadSince = undefined;
+		state.lastEffectiveAt = n.effectiveAt;
+	}
+
+	/** A notice is adopted only if strictly newer than the last transition we adopted (the high-water mark). */
+	private isNewerTransition(state: PromotionState, effectiveAt: number): boolean {
+		return state.lastEffectiveAt === undefined || effectiveAt > state.lastEffectiveAt;
+	}
+
+	// --- promotion ---
+
+	private promotionTriggered(topicId: Uint8Array, state: PromotionState, count: number, now: 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);
+	}
+
+	/** Linear extrapolation over the growth window: will `directParticipants` cross `cap_promote` within lookahead? */
+	private slopePredictsCrossing(state: PromotionState, count: number, now: number): boolean {
+		const samples = state.samples;
+		if (samples.length < 2) {
+			return false;
+		}
+		const first = samples[0]!;
+		const last = samples[samples.length - 1]!;
+		const span = last.t - first.t;
+		if (span <= 0) {
+			return false;
+		}
+		const slope = (last.count - first.count) / span; // participants per ms
+		if (slope <= 0) {
+			return false;
+		}
+		const predicted = count + slope * this.tPromoteLookaheadMs;
+		return predicted >= this.capPromote;
+	}
+
+	private async promote(topicId: Uint8Array, state: PromotionState, now: number): Promise<PromotionNoticeV1> {
+		const fromTier = this.deps.treeTier(topicId);
+		const topicB64 = bytesToB64url(topicId);
+		const epochB64 = bytesToB64url(this.deps.cohortEpoch());
+		const signable = { topicId: topicB64, fromTier, toTier: fromTier + 1, effectiveAt: now, cohortEpoch: epochB64 };
+		const { thresholdSig, signers } = await this.deps.signer.thresholdSign(promotionNoticeSigningPayload(signable));
+		state.promoted = true;
+		state.promotedAt = now;
+		state.lastEffectiveAt = now; // local effectiveAt — so our own echoed broadcast applies as a no-op
+		return {
+			v: 1,
+			topicId: topicB64,
+			fromTier,
+			toTier: fromTier + 1,
+			effectiveAt: now,
+			thresholdSig: bytesToB64url(thresholdSig),
+			signers: signers.map(bytesToB64url),
+			cohortEpoch: epochB64,
+		};
+	}
+
+	// --- demotion ---
+
+	private demotionTriggered(topicId: Uint8Array, state: PromotionState, now: number): boolean {
+		// The root (tree tier 0) has no parent to hand off to — it never demotes.
+		if (this.deps.treeTier(topicId) <= 0) {
+			return false;
+		}
+		// Sticky: a freshly-promoted cohort holds promoted mode through transient drops.
+		if (state.promoted && state.promotedAt !== undefined && now - state.promotedAt < this.tPromoteStickyMs) {
+			return false;
+		}
+		// Never collapse a cohort that still has live children beneath it.
+		if (this.deps.childCohortCount(topicId) > 0) {
+			return false;
+		}
+		if (this.deps.store.directParticipants(topicId) > this.capDemote) {
+			return false;
+		}
+		if (state.lowLoadSince === undefined) {
+			return false;
+		}
+		return now - state.lowLoadSince >= this.tDemoteMs;
+	}
+
+	private async demote(topicId: Uint8Array, state: PromotionState, now: number): Promise<DemotionNoticeV1> {
+		const tier = this.deps.treeTier(topicId);
+		const topicB64 = bytesToB64url(topicId);
+		const epochB64 = bytesToB64url(this.deps.cohortEpoch());
+		const parentB64 = bytesToB64url(this.deps.parentCoord(topicId));
+		const signable = { topicId: topicB64, tier, parentCohortCoord: parentB64, effectiveAt: now, cohortEpoch: epochB64 };
+		const { thresholdSig, signers } = await this.deps.signer.thresholdSign(demotionNoticeSigningPayload(signable));
+		// Release forwarder state: a demoted cohort leaves promoted mode and resets its clocks so a
+		// later re-growth re-evaluates cleanly.
+		state.promoted = false;
+		state.promotedAt = undefined;
+		state.lowLoadSince = undefined;
+		state.lastEffectiveAt = now; // local effectiveAt — so our own echoed broadcast applies as a no-op
+		return {
+			v: 1,
+			topicId: topicB64,
+			tier,
+			parentCohortCoord: parentB64,
+			effectiveAt: now,
+			thresholdSig: bytesToB64url(thresholdSig),
+			signers: signers.map(bytesToB64url),
+			cohortEpoch: epochB64,
+		};
+	}
+
+	// --- bookkeeping ---
+
+	private stateFor(topicId: Uint8Array): PromotionState {
+		const key = bytesKey(topicId);
+		let state = this.states.get(key);
+		if (state === undefined) {
+			state = { promoted: false, samples: [] };
+			this.states.set(key, state);
+		}
+		return state;
+	}
+
+	private pushGrowthSample(state: PromotionState, count: number, now: number): void {
+		state.samples.push({ t: now, count });
+		const cutoff = now - this.growthWindowMs;
+		while (state.samples.length > 1 && state.samples[0]!.t < cutoff) {
+			state.samples.shift();
+		}
+	}
+
+	private refreshLowLoadClock(state: PromotionState, count: number, now: number): void {
+		if (count <= this.capDemote) {
+			state.lowLoadSince ??= now;
+		} else {
+			state.lowLoadSince = undefined;
+		}
+	}
+}
+
+/** Build a {@link PromotionLifecycle} over the injected store, barometer resolver, and signer. */
+export function createPromotionLifecycle(deps: PromotionDeps): PromotionLifecycle {
+	return new CohortPromotionLifecycle(deps);
+}

package/src/cohort-topic/registration/bytes.ts

@@ -0,0 +1,37 @@
+/**
+ * Cohort-topic substrate — byte-array helpers shared by the registration store, sharding, and
+ * handoff. Peer ids and topic ids are raw {@link Uint8Array}; these give them stable string map
+ * keys, value equality, and the ascending order the sharding hash relies on.
+ */
+
+import { compare as compareU8 } from "uint8arrays/compare";
+import { equals as equalsU8 } from "uint8arrays/equals";
+import { bytesToB64url } from "../wire/codec.js";
+
+/** Stable, collision-free string map key for a byte array (base64url, the package's canonical form). */
+export function bytesKey(b: Uint8Array): string {
+	return bytesToB64url(b);
+}
+
+/** Composite key for a registration, `topicKey|participantKey`. */
+export function recordKey(topicId: Uint8Array, participantId: Uint8Array): string {
+	return `${bytesKey(topicId)}|${bytesKey(participantId)}`;
+}
+
+/** Value equality over byte arrays. */
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+	return equalsU8(a, b);
+}
+
+/** Lexicographic byte order — the `sort(... by PeerId ascending)` of §Primary and backup sharding. */
+export function compareBytes(a: Uint8Array, b: Uint8Array): number {
+	return compareU8(a, b);
+}
+
+/** Concatenate two byte arrays into a fresh buffer (the `participantId ‖ cohortEpoch` hash input). */
+export function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+	const out = new Uint8Array(a.length + b.length);
+	out.set(a, 0);
+	out.set(b, a.length);
+	return out;
+}