@optimystic/db-p2p 0.25.1 → 0.27.0

package/src/cohort-topic/host.ts

@@ -285,9 +285,10 @@ export interface CohortTopicAntiDosOptions {
 	 * Hard cap on the number of live per-coord cohort engines this node keeps. The served coord is a hash
 	 * over attacker-chosen `(treeTier, participantCoord, topicId)`, and an engine is created **before** the
 	 * per-coord anti-DoS gates run, so without this cap one peer spraying distinct coords forces unbounded
-	 * engine allocation. On overflow the registry evicts the least-recently-used **idle** engine (no records,
-	 * no cold-start forwarder) and tears it down; if every slot holds a live cohort it refuses the new coord.
-	 * Default {@link DEFAULT_COORD_ENGINES_MAX}.
+	 * engine allocation. On overflow the registry evicts the lowest-ranked, least-recently-used candidate
+	 * engine (see {@link EVICTION_RANK}: engines holding nothing go first, child-/promotion-holding engines
+	 * last) and tears it down; if every slot holds a pinned engine (records or a cold-start forwarder) it
+	 * refuses the new coord. Default {@link DEFAULT_COORD_ENGINES_MAX}.
 	 */
 	readonly coordEnginesMax?: number;
 	/**
@@ -335,6 +336,18 @@ export interface CohortTopicAntiDosOptions {
 	readonly parentTopicView?: BootstrapParentTopicView;
 }
 
+/**
+ * The classes of engine-owned state that evicting a {@link CoordEngine} destroys. **Exhaustive by
+ * contract**: every piece of state a `CoordEngine` owns and eviction would lose must appear here, and
+ * every consumer indexes it as a total `Record` ({@link EngineLiveness}, {@link EVICTION_RANK}), so
+ * adding a member without declaring it everywhere is a compile error — never a silently-evictable
+ * fifth piece of state.
+ */
+export type EngineStateKind = "records" | "forwarders" | "children" | "promotion";
+
+/** Which state classes an engine currently holds. Total — one boolean per kind, never partial. */
+export type EngineLiveness = Readonly<Record<EngineStateKind, boolean>>;
+
 /**
  * One cohort the node serves, bound to a FRET-routed coordinate. Owns the per-coord slice of cohort
  * state; the node-wide collaborators are injected (see {@link CoordEngineContext}).
@@ -356,13 +369,19 @@ export interface CoordEngine {
 	 * the requester then re-anchors). See `cohort-topic-trust-anchor-rotation-production`.
 	 */
 	cohortIdentityAt(epoch: Uint8Array): readonly string[] | undefined;
-	/** True iff this engine currently holds any registration record (a cold probe leaves it empty). */
+	/**
+	 * Which classes of engine-owned state this engine currently holds — the single, exhaustive answer to
+	 * "does evicting this engine destroy state it cannot cheaply reconstruct?". The registry's eviction
+	 * ranking consumes it ({@link EVICTION_RANK}); {@link hasState} / {@link hasForwarders} are
+	 * derivations of it, so the two views can never disagree.
+	 */
+	liveness(): EngineLiveness;
+	/** True iff this engine currently holds any registration record (= `liveness().records`). */
 	hasState(): boolean;
 	/**
-	 * True iff this engine currently holds any cold-start forwarder (possibly `awaiting_parent`). Together
-	 * with {@link hasState}, this is the "engine is idle / safe to reclaim" predicate the coord-engine
-	 * registry's LRU eviction reads: an engine with neither a record nor a forwarder is a throwaway (an
-	 * attacker-sprayed cold coord), an engine with either holds genuine cohort state and is never evicted.
+	 * True iff this engine currently holds any cold-start forwarder (possibly `awaiting_parent`)
+	 * (= `liveness().forwarders`). Records and forwarders are the *pinned* state classes: an engine holding
+	 * either is never an eviction candidate at all (see {@link EVICTION_RANK}).
 	 */
 	hasForwarders(): boolean;
 	/** True iff this engine holds the record for `(topicId, participantId)` — the renewal lookup key. */
@@ -475,9 +494,11 @@ export interface CoordRegistry {
 	 *
 	 * **Capacity.** The registry is hard-capped (see {@link CohortTopicAntiDosOptions.coordEnginesMax}). A
 	 * lookup that returns an already-resident engine always succeeds. A *creation* over a full registry
-	 * first evicts the least-recently-used idle engine; when every slot holds a live cohort it throws
-	 * {@link CoordEngineRegistryFullError} rather than growing unbounded — callers on the register /
-	 * child-link / cold-sibling paths catch it and answer a clean capacity refusal.
+	 * first evicts the lowest-ranked, least-recently-used candidate engine ({@link EVICTION_RANK}: engines
+	 * holding nothing before child-/promotion-holding ones); when every slot holds a pinned engine (records
+	 * or a cold-start forwarder) it throws {@link CoordEngineRegistryFullError} rather than growing
+	 * unbounded — callers on the register / child-link / cold-sibling paths catch it and answer a clean
+	 * capacity refusal.
 	 */
 	forCoord(coord: RingCoord, treeTier: number, participantCoord: Uint8Array): CoordEngine;
 	/** The engine holding the record for `(topicId, participantId)`, or `undefined` (renewal dispatch). */
@@ -528,9 +549,10 @@ export interface CohortTopicHost {
 	 */
 	readonly gossipTransport: FretCohortGossipTransport;
 	/**
-	 * The node-level `promote`-handler anti-abuse gate (per-`(peer, topic)` rate limiter + per-`(topic, tier)`
-	 * `effectiveAt` high-water). Exposed for test/diagnostic introspection over its bounded-memory state — the
-	 * limiter's `size` and the `highWater` `LruMap` — and so the gossip-cadence sweep wiring is observable.
+	 * The node-level `promote`-handler anti-abuse gate (per-`(peer, topic)` rate limiter + the
+	 * per-`(coord, tier, topic)` adopted-transition record). Exposed for test/diagnostic introspection over
+	 * its bounded-memory state — the limiter's `size` and the `transitions` `LruMap` — and so the
+	 * gossip-cadence sweep wiring is observable.
 	 */
 	readonly promoteGate: PromoteGate;
 	/**
@@ -611,6 +633,26 @@ interface CoordEngineContext {
 	 * notices signed by its own cohort without a network refetch. Absent in unit composition.
 	 */
 	readonly onCertPublished?: (cert: MembershipCertV1) => void;
+	/**
+	 * Hook fired by the coord-engine registry AFTER it evicts (and closes) an engine, with the evicted
+	 * engine's served coord. The host wires it to `verifier.forget(coord)`: on a keyed node the
+	 * gossip-cadence driver calls {@link CoordEngine.pumpMembership} for EVERY engine — record-less ones
+	 * included — so any evicted engine may have published a cert and trust-locked its coord in the
+	 * verifier ({@link onCertPublished} → `verifier.cache`). Eviction therefore drops the lock
+	 * unconditionally (a cheap no-op for a coord that never published) rather than trying to track "did
+	 * this engine publish" — that would be another declare-yourself-or-be-forgotten trap. Absent in
+	 * key-less / unit composition.
+	 */
+	readonly onEngineEvicted?: (coord: RingCoord) => void;
+	/**
+	 * Read the node-level record of the last adopted promotion/demotion transition for one
+	 * `(coord, tier, topic)` — the host's {@link PromoteGate.transitions} map, which outlives every
+	 * engine. A freshly created {@link CoordEngine} seeds its {@link PromotionLifecycle}'s per-topic
+	 * ordering and direction from it (via `PromotionDeps.seedTransition`), so eviction + recreation
+	 * neither reopens the replay window nor forgets a correct promoted mode. Wired unconditionally by the
+	 * host (key-less nodes also adopt verified inbound notices); optional only for unit composition.
+	 */
+	readonly adoptedTransition?: (coord: RingCoord, tier: number, topicId: Uint8Array) => AdoptedTransition | undefined;
 }
 
 /**
@@ -713,12 +755,26 @@ export async function createCohortTopicHost(node: Libp2p, fret: FretService, opt
 			return members.includes(bytesToPeerIdString(fromBytes));
 		};
 
+	// Node-level `promote`-handler anti-abuse gate (`cohort-topic-promote-handler-verify-amplification`):
+	// a per-(peer, topic) rate limiter (own instance — the register-path limiter is per-coord inside each
+	// engine; this handler is node-level) plus the per-(coord, tier, topic) adopted-transition record.
+	// Defaults to `register_rate_per_peer` (4 / min / peer / topic) with exponential back-off. Declared here
+	// rather than with the other anti-DoS wiring below because `broadcastNotice` writes the record on the
+	// origination path.
+	const promoteGate = createPromoteGate(options.antiDos?.rateLimiter);
+
 	// --- outbound notice broadcast (gap 4) ---
 	// A coord engine that threshold-signs a promotion/demotion notice hands it here; we fan it over the
 	// `promote` protocol to the cohort around the served coord (siblings adopt the state) and, for a
 	// demotion, additionally to the parent coord (childCohortCount bookkeeping). Reuses the gossip
 	// transport's cohort peer resolution.
 	const broadcastNotice = (notice: PromotionNoticeV1 | DemotionNoticeV1, servedCoord: RingCoord): void => {
+		// Record the origination in the node-level adopted-transition map BEFORE fanning out: `broadcastOver`
+		// excludes self, so an originated notice never arrives back on the inbound path — this is the ONLY
+		// write for locally-originated transitions. Keyed off the notice's own `cohortCoord` only; the parent
+		// coord a demotion also fans to is deliberately outside this ordering (the parent-unlink is ordered by
+		// the child registry's per-child `lastEffectiveAt` — see `applyDemotionUnlinkAtParent`).
+		recordAdoptedTransition(promoteGate, notice);
 		const frame = encodeCohortMessage(notice, maxBytes);
 		// A demotion fans to BOTH the demoting child's served coord (siblings adopt `promoted = false` via the
 		// `cohortCoord`-routed apply) and the parent coord (the parent unrecords the child). `handleInboundNotice`
@@ -755,12 +811,6 @@ export async function createCohortTopicHost(node: Libp2p, fret: FretService, opt
 		options.antiDos?.parentTopicView !== undefined || options.committedParentTopicReader !== undefined;
 	const bootstrapEvidence = createBootstrapEvidencePolicy(options.antiDos, hash, log, parentTopicView, hasCommittedParentBacking);
 
-	// Node-level `promote`-handler anti-abuse gate (`cohort-topic-promote-handler-verify-amplification`):
-	// a per-(peer, topic) rate limiter (own instance — the register-path limiter is per-coord inside each
-	// engine; this handler is node-level) plus the per-(topic, tier) effectiveAt high-water. Defaults to
-	// `register_rate_per_peer` (4 / min / peer / topic) with exponential back-off.
-	const promoteGate = createPromoteGate(options.antiDos?.rateLimiter);
-
 	const ctx: CoordEngineContext = {
 		hash,
 		addressing,
@@ -799,13 +849,20 @@ export async function createCohortTopicHost(node: Libp2p, fret: FretService, opt
 		// cohort it stops republishing and its anchor goes `"unknown"`, so it can be stranded distrusting the
 		// coord's later-epoch messages. The verifier self-heals via bounded re-TOFU on a demonstrated chain gap
 		// (`staleGapRecoveryStrikes`, see `db-core/.../membership/verifier.ts` + `docs/cohort-topic.md`
-		// §Bootstrapping trust). The *root-cause* fix is for the host to drop the lock here on demotion, but
-		// that needs an engine-reclaim / demotion signal the host does not emit today. `createCoordRegistry`
-		// now evicts, but only IDLE engines (no records → never published a cert), so it never strands a
-		// trust-lock and does not resolve this on its own (see the NOTE at `evictOneIdle`). When a demotion /
-		// cert-publishing-engine reclaim signal lands, add a `verifier.forget(coord)` / downgrade call on
-		// demotion and prefer it over (or alongside) the strike-counter heuristic.
+		// §Bootstrapping trust). Engine EVICTION drops the lock for the evicted coord via `onEngineEvicted`
+		// below — on a keyed node `pumpMembership` publishes for every engine (record-less ones included), so
+		// eviction cannot assume "no records → never published". Demotion, however, does NOT release the engine
+		// (a demoted engine keeps its records/forwarder and stays resident), so the demotion-side lock drop
+		// still has no signal to hang off; the strike-counter heuristic remains the recovery there.
 		onCertPublished: (cert: MembershipCertV1): void => verifier.cache(cert),
+		// Drop the verifier trust-lock for an evicted engine's coord — unconditional, because on a keyed node
+		// ANY engine (even one holding no records) may have published a cert via the gossip-cadence
+		// `pumpMembership` sweep. A no-op for a coord the verifier holds nothing for.
+		onEngineEvicted: (coord: RingCoord): void => verifier.forget(bytesToB64url(coord)),
+		// Node-level adopted-transition reader (engine seeding). Wired unconditionally — key-less hosts also
+		// adopt verified inbound notices, so their recreated engines need the seed just the same.
+		adoptedTransition: (coord: RingCoord, tier: number, topicId: Uint8Array): AdoptedTransition | undefined =>
+			promoteGate.transitions.get(transitionKey(bytesToB64url(coord), tier, bytesToB64url(topicId))),
 	};
 	const registry = createCoordRegistry(ctx, options.antiDos?.coordEnginesMax);
 
@@ -829,10 +886,11 @@ export async function createCohortTopicHost(node: Libp2p, fret: FretService, opt
 	// link work — so a tier-`d > 0` frame for an unknown coord falls through to today's drop (the bus has no
 	// engine subscribed to it). See `docs/cohort-topic.md` §Cold-start instantiation.
 	//
-	// The registry is hard-capped with LRU eviction of idle engines (`createCoordRegistry`), so a
-	// gossip-instantiated cold sibling is no longer a permanent per-co-member-coord cost: an idle one is
-	// reclaimed under memory pressure like any other cold engine, and a creation over a full-of-live registry
-	// is refused (`CoordEngineRegistryFullError`) and dropped here rather than crashing the gossip handler.
+	// The registry is hard-capped with ranked LRU eviction (`createCoordRegistry`), so a
+	// gossip-instantiated cold sibling is no longer a permanent per-co-member-coord cost: one holding no
+	// state is reclaimed under memory pressure like any other cold engine, and a creation over a
+	// full-of-pinned registry is refused (`CoordEngineRegistryFullError`) and dropped here rather than
+	// crashing the gossip handler.
 	const maybeInstantiateColdSibling = (frame: Uint8Array): void => {
 		if (verifyGossip === undefined) {
 			return; // key-less / interim mode: no co-member gate, so never auto-instantiate
@@ -1347,7 +1405,7 @@ export const DEFAULT_COORD_ENGINES_MAX = 2048;
 
 /**
  * Thrown by {@link CoordRegistry.forCoord} when it must create a new engine but the registry is full of
- * **live** cohorts (every slot holds records or a cold-start forwarder, so nothing is idle-evictable).
+ * **pinned** engines (every slot holds records or a cold-start forwarder, so nothing is evictable).
  * Signals a capacity refusal, not a bug — the register / child-link / cold-sibling dispatch paths catch it
  * and answer a clean refusal (`unwilling_cohort` / `rejected` / drop) rather than letting it escape.
  */
@@ -1358,20 +1416,47 @@ export class CoordEngineRegistryFullError extends Error {
 	}
 }
 
+/**
+ * Eviction rank per {@link EngineStateKind}. `"pinned"` — an engine holding it is not an eviction
+ * candidate at all. A number — the engine IS a candidate, but only after every candidate whose rank is
+ * strictly lower; higher = evicted later. An engine holding nothing is rank 0: the genuinely-cold
+ * attacker-sprayed coord the cap exists for.
+ *
+ * `children` / `promotion` are deliberately NOT pinned. A child link is peer-supplied input —
+ * key-less-permissive mode records one without any signature check — so pinning on it would let any peer
+ * make all `coordEnginesMax` slots un-evictable and drive {@link CoordEngineRegistryFullError} for
+ * legitimate coords, reopening the exact spray vector the cap closes. Ranking keeps the hard guarantee
+ * (some engine is always evictable while any unpinned one exists) while making the realistic loss — a
+ * handful of real parent/promoted engines among ~2000 attacker-cold ones — the *last* to go instead of a
+ * pure LRU-age pick.
+ *
+ * EXHAUSTIVE: a new {@link EngineStateKind} with no rank here does not typecheck, and the spec's
+ * exhaustiveness guard cross-checks this table's keys against a `liveness()` result at runtime.
+ */
+export const EVICTION_RANK: Record<EngineStateKind, "pinned" | number> = {
+	records: "pinned",
+	forwarders: "pinned",
+	children: 1,
+	promotion: 1,
+};
+
 /**
  * Build the lazy `servedCoord → CoordEngine` registry over the shared collaborators, hard-capped at
- * `maxEngines` with least-recently-used eviction of **idle** engines.
+ * `maxEngines` with ranked least-recently-used eviction.
  *
  * The served coord is a hash over attacker-chosen `(treeTier, participantCoord, topicId)`, and `forCoord`
  * runs on the register hot path **before** the per-coord anti-DoS gates — so, uncapped, one peer spraying
  * distinct coords drives unbounded engine allocation (each engine owns a store, gossip bus, rate limiter,
  * replay guard, topic budget, …). The cap bounds that: on a creation over a full registry we evict the
- * least-recently-used **idle** engine (no records, no cold-start forwarder — a throwaway cold coord) and
- * tear it down; when every slot holds a live cohort we refuse the new coord ({@link CoordEngineRegistryFullError})
- * so a legitimate multi-cohort node keeps working while attacker-driven cold engines cannot pile up.
+ * `(rank, recency)`-least candidate engine ({@link EVICTION_RANK} over {@link CoordEngine.liveness}) and
+ * tear it down; when every slot holds a pinned engine (records or a forwarder) we refuse the new coord
+ * ({@link CoordEngineRegistryFullError}) so a legitimate multi-cohort node keeps working while
+ * attacker-driven cold engines cannot pile up.
  *
  * Recency is bumped on every lookup that hands back an engine (`forCoord` / `findByCoord` / `findHolder` /
- * `findServing`), so a hot cohort under load is never the eviction victim.
+ * `findServing`) and breaks ties *within* a rank, so a hot cohort under load loses only to a colder engine
+ * of the same rank — but rank is applied first, so even a hot rank-0 engine is evicted before any rank-1
+ * one (intended: a child-/promotion-holding engine survives a spray of freshly-touched cold coords).
  */
 function createCoordRegistry(ctx: CoordEngineContext, maxEngines: number = DEFAULT_COORD_ENGINES_MAX): CoordRegistry {
 	if (!Number.isInteger(maxEngines) || maxEngines <= 0) {
@@ -1384,28 +1469,49 @@ function createCoordRegistry(ctx: CoordEngineContext, maxEngines: number = DEFAU
 	let seq = 0;
 	const touch = (key: string): void => { recency.set(key, ++seq); };
 
-	// An engine is idle-evictable iff it holds no registration record AND no cold-start forwarder — i.e. no
-	// genuine cohort state to lose. A live engine (records or a forwarder) is never a throwaway.
-	const isIdle = (engine: CoordEngine): boolean => !engine.hasState() && !engine.hasForwarders();
+	// An engine's eviction rank: `undefined` when it holds any pinned state class (not a candidate at all),
+	// else the maximum numeric rank over the classes it holds (0 when it holds nothing). Iterates the rank
+	// table, whose keys the type system pins to exactly the EngineStateKind set the liveness record carries.
+	const evictionRank = (engine: CoordEngine): number | undefined => {
+		const liveness = engine.liveness();
+		let rank = 0;
+		for (const kind of Object.keys(EVICTION_RANK) as EngineStateKind[]) {
+			if (!liveness[kind]) {
+				continue;
+			}
+			const r = EVICTION_RANK[kind];
+			if (r === "pinned") {
+				return undefined;
+			}
+			if (r > rank) {
+				rank = r;
+			}
+		}
+		return rank;
+	};
 
-	// Evict the least-recently-used idle engine to free a slot; returns true iff one was freed. Tears the
-	// victim down (`close()` drops its gossip-bus subscription) so eviction does not leak the subscription.
+	// Evict the `(rank, recency)`-lexicographically-least candidate engine to free a slot; returns true iff
+	// one was freed. Tears the victim down (`close()` drops its gossip-bus subscription) so eviction does not
+	// leak the subscription, and fires `ctx.onEngineEvicted` so the host drops the coord's verifier
+	// trust-lock.
 	//
-	// NOTE (verifier trust-lock, cohort-topic-treetier-bound-engine-cap): only IDLE engines are evicted here,
-	// and an idle engine (`hasState() === false`) has never published a membership cert — so there is no
-	// verifier trust-lock (`onCertPublished` → `verifier.cache`, above) to drop for its coord. If this policy
-	// is ever widened to evict a cert-publishing engine, add a `verifier.forget(coord)` / downgrade here:
-	// otherwise the stale trust-lock strands the coord's later-epoch messages (the drop-the-lock tripwire the
-	// `onCertPublished` NOTE describes). Do NOT widen without that.
-	const evictOneIdle = (): boolean => {
+	// NOTE (verifier trust-lock): eviction can reclaim an engine that HAS published a membership cert — on a
+	// keyed node the gossip-cadence driver calls `pumpMembership` for every engine in `registry.all()`,
+	// record-less ones included, so "no records" never implied "never published". `onEngineEvicted` is
+	// therefore called for EVERY victim, unconditionally (the host wires it to `verifier.forget(coord)`, a
+	// cheap no-op for a coord that never published); do not try to track which engines published.
+	const evictOne = (): boolean => {
 		let victimKey: string | undefined;
+		let victimRank = Infinity;
 		let victimSeq = Infinity;
 		for (const [key, engine] of engines) {
-			if (!isIdle(engine)) {
-				continue; // live cohort (records) or mid-link cold-start forwarder — never evicted
+			const rank = evictionRank(engine);
+			if (rank === undefined) {
+				continue; // pinned: holds records or a mid-link cold-start forwarder — never evicted
 			}
 			const s = recency.get(key) ?? 0;
-			if (s < victimSeq) {
+			if (rank < victimRank || (rank === victimRank && s < victimSeq)) {
+				victimRank = rank;
 				victimSeq = s;
 				victimKey = key;
 			}
@@ -1413,9 +1519,11 @@ function createCoordRegistry(ctx: CoordEngineContext, maxEngines: number = DEFAU
 		if (victimKey === undefined) {
 			return false;
 		}
-		engines.get(victimKey)!.close();
+		const victim = engines.get(victimKey)!;
+		victim.close();
 		engines.delete(victimKey);
 		recency.delete(victimKey);
+		ctx.onEngineEvicted?.(victim.servedCoord);
 		return true;
 	};
 
@@ -1426,8 +1534,8 @@ function createCoordRegistry(ctx: CoordEngineContext, maxEngines: number = DEFAU
 			// share one engine rather than racing to construct a second.
 			let engine = engines.get(key);
 			if (engine === undefined) {
-				if (engines.size >= maxEngines && !evictOneIdle()) {
-					// Full of live cohorts — refuse rather than grow unbounded. Callers turn this into a clean
+				if (engines.size >= maxEngines && !evictOne()) {
+					// Full of pinned engines — refuse rather than grow unbounded. Callers turn this into a clean
 					// capacity reply/drop (see the paths listed on `CoordEngineRegistryFullError`).
 					log("cohort-topic: coord-engine registry full (max=%d) — refusing new coord %s", maxEngines, key);
 					throw new CoordEngineRegistryFullError(maxEngines);
@@ -1560,9 +1668,10 @@ class RotationState {
  * cohort-wide. Because merge is last-writer-wins by `effectiveAt`, a link and a later unlink converge in any
  * arrival order, and a never-seen unlink writes a `linked = false` tombstone that a subsequently-arriving stale
  * link cannot resurrect. The union is keyed by child coord, never the parent epoch, so a parent membership
- * rotation does not reset it. NOTE: a link/unlink is broadcast once (drained from the pending delta queue);
- * a parent member that joins the cohort *after* the delta drained (rotation cold-start) learns the child set
- * only on the next local record/unrecord for that child — see `debt-cohort-topic-child-set-late-joiner-resync`.
+ * rotation does not reset it. A link/unlink is broadcast once (drained from the pending delta queue), so a
+ * member that missed that one frame — a rotation cold-start, most of all — is healed by the throttled
+ * re-advertisement of {@link ChildRegistry.linkedChildren} in `gossipRound` (one frame per
+ * `T_willingness_heartbeat`, see there).
  */
 interface ChildRegistry {
 	/** Link the child; returns true iff this advanced the state (a fresh link or a strictly-newer effectiveAt). */
@@ -1570,13 +1679,45 @@ interface ChildRegistry {
 	/** Release the child (linked = false); returns true iff this advanced the state. A never-seen child writes a tombstone. */
 	unrecordChild(topicId: Uint8Array, childCohortCoord: Uint8Array, effectiveAt: number): boolean;
 	count(topicId: Uint8Array): number;
+	/**
+	 * Every currently-linked child across **all** topics (released children — tombstones — excluded), each at
+	 * the `effectiveAt` that linked it. Deliberately not per-topic: `gossipRound` iterates only *resident*
+	 * topics (ones this engine holds records or forwarders for), and a parent can hold child links for a topic
+	 * whose participants sharded entirely down to the children, so a per-topic accessor would miss exactly the
+	 * parents that matter.
+	 */
+	linkedChildren(): readonly LinkedChild[];
+	/**
+	 * Whether any child is currently linked (tombstones excluded) — the same predicate as
+	 * `linkedChildren().length > 0`, but short-circuiting and allocation-free. The eviction census
+	 * ({@link CoordEngine.liveness}) runs it once per resident engine per eviction, where materializing every
+	 * linked child only to read `.length` is pure garbage.
+	 */
+	hasLinkedChildren(): boolean;
+}
+
+/**
+ * One linked child cohort, as re-advertised by the throttled child-set resync round. The two byte fields
+ * alias the registry's own copies (never clone-on-read), so a consumer must treat them as read-only.
+ */
+interface LinkedChild {
+	readonly topicId: Uint8Array;
+	readonly childCohortCoord: Uint8Array;
+	readonly effectiveAt: number;
 }
 
 interface ChildEntry {
 	linked: boolean;
 	lastEffectiveAt: number;
+	/** The key's original bytes, retained on first insert (both are in hand in `apply`) so `linkedChildren` needs no key decode. */
+	topicId: Uint8Array;
+	childCohortCoord: Uint8Array;
 }
 
+// NOTE: released children are kept forever as `linked = false` tombstones (the high-water that stops a stale
+// link resurrecting them), so a long-lived engine's map grows with child churn. They cost memory only, never
+// traffic — `linkedChildren` excludes them, so re-advertisement volume is bounded by the *live* child count.
+// If child churn on a long-lived parent ever makes this map large, age tombstones out past a demotion horizon.
 function createChildRegistry(): ChildRegistry {
 	const byTopic = new Map<string, Map<string, ChildEntry>>();
 	// Freshness-ordered write shared by link/unlink: apply `linked` only if `effectiveAt` is strictly newer than
@@ -1594,7 +1735,7 @@ function createChildRegistry(): ChildRegistry {
 		if (existing === undefined) {
 			// A never-seen unlink writes a `linked = false` tombstone (never a negative count), so a later stale
 			// link with an earlier effectiveAt cannot resurrect a demoted child.
-			children.set(childKey, { linked, lastEffectiveAt: effectiveAt });
+			children.set(childKey, { linked, lastEffectiveAt: effectiveAt, topicId, childCohortCoord });
 			return true;
 		}
 		if (effectiveAt <= existing.lastEffectiveAt) {
@@ -1625,6 +1766,27 @@ function createChildRegistry(): ChildRegistry {
 			}
 			return n;
 		},
+		hasLinkedChildren(): boolean {
+			for (const children of byTopic.values()) {
+				for (const entry of children.values()) {
+					if (entry.linked) {
+						return true;
+					}
+				}
+			}
+			return false;
+		},
+		linkedChildren(): readonly LinkedChild[] {
+			const out: LinkedChild[] = [];
+			for (const children of byTopic.values()) {
+				for (const entry of children.values()) {
+					if (entry.linked) {
+						out.push({ topicId: entry.topicId, childCohortCoord: entry.childCohortCoord, effectiveAt: entry.lastEffectiveAt });
+					}
+				}
+			}
+			return out;
+		},
 	};
 }
 
@@ -1788,6 +1950,16 @@ function createCoordEngine(ctx: CoordEngineContext, servedCoord: RingCoord, tree
 		}
 	};
 
+	// Set by `close()` (registry eviction, or host `stop()`); makes every time-driven entry point below inert.
+	// The gossip-cadence driver iterates a `registry.all()` SNAPSHOT and awaits between engines, so an inbound
+	// register / child-link / cold-sibling frame landing in one of those awaits can evict — and close — an
+	// engine the tick is still walking. Driving a closed engine afterwards is not merely wasted work: a
+	// `pumpMembership` would publish a cert and re-run `onCertPublished` → `verifier.cache`, re-locking the very
+	// coord `onEngineEvicted` → `verifier.forget` had just released, for a coord this node no longer serves.
+	// Guarding here rather than in the driver keeps the invariant total: a closed engine does nothing, whoever
+	// still holds a reference to it.
+	let closed = false;
+
 	/**
 	 * Publish (or refresh) this cohort's membership cert, attaching a rotation attestation when the cohort
 	 * identity (epoch) changed since the last publish. `refresh` selects the publisher path: `false` for a
@@ -1798,7 +1970,7 @@ function createCoordEngine(ctx: CoordEngineContext, servedCoord: RingCoord, tree
 	 * tick. Key-less interim mode no-ops (the verify-only signer cannot assemble).
 	 */
 	const publishMembership = async (now: number, refresh: boolean): Promise<MembershipCertV1 | undefined> => {
-		if (!canPublish) {
+		if (closed || !canPublish) {
 			return undefined;
 		}
 		const snapshot = snapshotAt(now); // also observes the current identity (snapshotAt → cohort())
@@ -1845,6 +2017,11 @@ function createCoordEngine(ctx: CoordEngineContext, servedCoord: RingCoord, tree
 		cohortCoord: (): Uint8Array => servedCoord,
 		cohortEpoch: localEpoch,
 		signer: noticeSigner,
+		// Seed a topic's replay ordering + direction from the node-level adopted-transition record (the
+		// promote gate's map), which outlives this engine — so recreating an evicted engine neither reopens
+		// the replay window nor forgets a correct promoted mode. For a notice at this served coord both a
+		// promotion's `fromTier` and a demotion's `tier` equal `treeTier`, so this key matches both writes.
+		seedTransition: (topicId: Uint8Array): AdoptedTransition | undefined => ctx.adoptedTransition?.(servedCoord, treeTier, topicId),
 		// Production defaults (cap_promote = 64, …) unless the host was given a promotion override — the
 		// live-tier e2e lowers `capPromote` to drive promotion with a small participant count. The
 		// coord-derived inputs above (treeTier / childCohortCount / parentCoord) are never overridden.
@@ -1969,11 +2146,19 @@ function createCoordEngine(ctx: CoordEngineContext, servedCoord: RingCoord, tree
 	// node ever serves very many idle cohorts, batch the heartbeats or lengthen the interval.
 	let lastGossipAt: number | undefined;
 
+	// Timestamp of the last round in which this engine re-advertised its linked child set, or `undefined` if it
+	// never has. Bounds child-set resync to one frame per `T_willingness_heartbeat`, not one per gossip round.
+	let lastChildReadvertAt: number | undefined;
+
 	// One gossip round: sweep stale records (firing the `evicted` deltas), freeze each resident topic's
-	// traffic summary, drain the touch/evicted deltas, then assemble + sign + broadcast the frame. An idle
-	// engine (no topics, no deltas) normally builds no frame — except a willingness heartbeat, where an idle
-	// but willing engine still emits a willingness/load-only frame so a cold cohort can bootstrap.
+	// traffic summary, re-advertise the linked child set on its throttle, drain the touch/evicted/child deltas,
+	// then assemble + sign + broadcast the frame. An idle engine (no topics, no deltas) normally builds no
+	// frame — except a willingness heartbeat, where an idle but willing engine still emits a willingness/load-
+	// only frame so a cold cohort can bootstrap.
 	const gossipRound = async (now: number): Promise<CohortGossipV1 | undefined> => {
+		if (closed) {
+			return undefined;
+		}
 		engine.sweepStale(now);
 		const topicSummaries = residentTopics().map((topicId) =>
 			toCohortTopicSummary(topicId, traffic.publish(topicId, now), {
@@ -1986,6 +2171,34 @@ function createCoordEngine(ctx: CoordEngineContext, servedCoord: RingCoord, tree
 				childCohortCount: childRegistry.count(topicId),
 			}),
 		);
+		// Child-set resync. A link/unlink delta is broadcast exactly once, so a member whose engine was
+		// instantiated after a link drained (a parent rotation, or any FRET reshuffle adding a node to the
+		// parent cohort) would read `childCohortCount == 0` for children that plainly exist — wrongly clearing
+		// the demotion gate and telling seekers the topic is not promoted. So every `willingnessHeartbeatMs`
+		// re-emit the *currently-linked* set at each child's original `effectiveAt`. Safe by construction: the
+		// receiving merge is last-writer-wins on `effectiveAt`, so a re-advertisement is a no-op on a member
+		// that already holds it and cannot resurrect a child released by a newer unlink. Queued through
+		// `pending` (not straight into the frame) so a same-round *local* link for the same child collapses to
+		// one ref instead of two (`queueChild` is last-writer-wins per `(topic, child)`). Sourcing from the
+		// registry rather than the queue is what makes the unlink direction safe: an already-released child is
+		// simply absent from `linkedChildren()`, and nothing between here and `drain()` awaits, so a
+		// re-advertisement can never race a same-round unlink. Bounded to one extra frame per engine per
+		// heartbeat, and the round is deliberately non-idle — the frame is the carrier.
+		// NOTE: this heals a missed *link*, never a missed *unlink* — absence is not advertised, so a member
+		// that dropped an unlink frame over-counts until it hears another delta for that child. Both consumers
+		// fail conservatively there (demotion stays blocked; a seeker sweeps a no-longer-promoted tier —
+		// wasteful, not wrong). If over-counting ever needs healing too, advertise the tombstones as well.
+		if (lastChildReadvertAt === undefined || now - lastChildReadvertAt >= ctx.willingnessHeartbeatMs) {
+			const linked = childRegistry.linkedChildren();
+			for (const child of linked) {
+				pending.childLink(child.topicId, child.childCohortCoord, child.effectiveAt);
+			}
+			// Only start the clock once something was actually enqueued: an engine that parents nothing stays
+			// silent and re-advertises immediately when it first does hold a child.
+			if (linked.length > 0) {
+				lastChildReadvertAt = now;
+			}
+		}
 		const { records, evicted, childLinks, childUnlinks } = pending.drain();
 		const idle = topicSummaries.length === 0 && records.length === 0 && evicted.length === 0
 			&& childLinks.length === 0 && childUnlinks.length === 0;
@@ -2021,7 +2234,7 @@ function createCoordEngine(ctx: CoordEngineContext, servedCoord: RingCoord, tree
 	// parent coord) via the same path a promotion uses. Skipped without a key (verify-only signer can't
 	// assemble); for the single-cohort tier-0 milestone the lifecycle never demotes (the root has no parent).
 	const demotionTick = async (now: number): Promise<void> => {
-		if (!canPublish) {
+		if (closed || !canPublish) {
 			return;
 		}
 		for (const topicId of residentTopics()) {
@@ -2038,14 +2251,40 @@ function createCoordEngine(ctx: CoordEngineContext, servedCoord: RingCoord, tree
 		}
 	};
 
+	// The exhaustive engine-owned-state census the registry's eviction ranking consults. One entry per
+	// EngineStateKind — the total-Record type makes forgetting a new kind here a compile error. `children`
+	// derives from the *linked* set (tombstones excluded), so a parent whose every child demoted away is
+	// reclaimable again; `promotion` counts only adopted transition state (a `promoted` flag or a
+	// `lastEffectiveAt` high-water — growth samples alone are rebuilt from the store and do not count).
+	// NOTE: `evictOne` runs this once per resident engine per eviction — up to `coordEnginesMax` (2048)
+	// censuses for one reclaim. Three of the four arms short-circuit and allocate nothing; `records` still
+	// materializes every registration via `store.listAll()` only to read `.length` (pre-dating this census —
+	// the old idle predicate did the same). Unmeasured, and bounded by a registry that is full of *cold*
+	// engines in the case that matters. If eviction ever shows up in a profile, give `RegistrationStore` an
+	// `isEmpty()` (its `byTopic` map already knows) and read that here.
+	const liveness = (): EngineLiveness => ({
+		records: store.listAll().length > 0,
+		forwarders: coldStart.hasForwarders(),
+		children: childRegistry.hasLinkedChildren(),
+		promotion: promotion.hasAdoptedState(),
+	});
+
 	return {
 		servedCoord,
 		treeTier,
 		engine,
 		cohort,
 		cohortIdentityAt: (epoch: Uint8Array): readonly string[] | undefined => rotationState.membersAt(bytesToB64url(epoch)),
-		hasState: (): boolean => store.listAll().length > 0,
-		hasForwarders: (): boolean => coldStart.hasForwarders(),
+		liveness,
+		// Derivations of `liveness()` — kept on the interface for existing callers/specs, but sourced from
+		// the same census so the two views cannot drift.
+		// NOTE: each call runs the FULL census (allocating one record, and touching the child registry and
+		// promotion lifecycle) where it used to be a bare `store.listAll()` check. Free today: as of this
+		// writing nothing in `src/` calls either accessor — the registry ranks via `liveness()` directly and
+		// the only callers are specs. If a hot path (a per-frame dispatch gate, say) ever starts calling one
+		// per message, give it a direct single-field read instead of routing it through the census.
+		hasState: (): boolean => liveness().records,
+		hasForwarders: (): boolean => liveness().forwarders,
 		holds: (topicId: Uint8Array, participantId: Uint8Array): boolean =>
 			store.getByParticipant(topicId, participantId) !== undefined,
 		records: (topicId: Uint8Array): readonly RegistrationRecord[] => store.listByTopic(topicId),
@@ -2088,7 +2327,10 @@ function createCoordEngine(ctx: CoordEngineContext, servedCoord: RingCoord, tree
 		pumpMembership: (now: number): Promise<MembershipCertV1 | undefined> => publishMembership(now, true),
 		gossipRound,
 		demotionTick,
-		close: (): void => bus.close(),
+		close: (): void => {
+			closed = true;
+			bus.close();
+		},
 	};
 }
 
@@ -2398,14 +2640,25 @@ export type NoticeOutcome = "applied" | "untrusted" | "dropped";
  *
  * - `"undecodable"`  — the frame is neither a promotion nor a demotion notice.
  * - `"rate-limited"` — the dialing `(peer, topic)` is over its `register_rate_per_peer` ceiling.
- * - `"stale"`        — the notice's `effectiveAt` is at or below the last *applied* notice for its served
- *   cohort coord (a replay / out-of-order frame); dropped before `verifyMessage`.
+ * - `"stale"`        — the notice's `effectiveAt` is at or below the last *adopted* transition recorded for
+ *   its `(cohortCoord, tier, topicId)` (a replay / out-of-order frame); dropped before `verifyMessage`.
  * - `"unlinked"`     — a demotion notice that did not sibling-adopt on this node (no local child-coord engine,
  *   or that path was stale) but **did** verify + unrecord the demoting child at its parent cohort here (the
  *   parent-unlink path). Distinct from `"applied"` (a sibling-adopt) so a test can assert the parent-only case.
  */
 export type InboundNoticeResult = NoticeOutcome | "undecodable" | "rate-limited" | "stale" | "unlinked";
 
+/**
+ * The last promotion/demotion transition this node adopted for one `(coord, tier, topic)`: its
+ * `effectiveAt` (the replay ordering) and its direction (`promoted` — what the transition left the cohort
+ * as). Stored in {@link PromoteGate.transitions}; direction matters because a recreated engine must
+ * restore *which way* the last transition went, not just how recent it was.
+ */
+export interface AdoptedTransition {
+	readonly effectiveAt: number;
+	readonly promoted: boolean;
+}
+
 /**
  * Node-level anti-abuse state for the `promote` handler (`cohort-topic-promote-handler-verify-amplification`).
  * The handler is node-level (one per node, not per coord), so unlike the per-{@link CoordEngine} register-path
@@ -2418,35 +2671,85 @@ export interface PromoteGate {
 	 */
 	readonly rateLimiter: RegisterRateLimiter;
 	/**
-	 * Per-served-coord high-water (key: `` `${cohortCoord}|${tier}` ``) of the last *applied* notice's
-	 * `effectiveAt`. A notice at or below the water is a replay / out-of-order frame and is dropped before
-	 * verification. Keyed by the served coord — not `(topic, tier)` — so two sibling cohorts a node serves for
-	 * one `(topic, tier)` do not share an entry (an applied notice for one must not stale-drop a legitimate
-	 * notice for the other). Updated **only** on an `"applied"` outcome (never on an unverified frame), so a
-	 * forged notice carrying `effectiveAt = Infinity` cannot poison the water and lock out legitimate notices.
+	 * The node's durable record of the last adopted promotion/demotion transition per
+	 * `(cohortCoord, tier, topicId)` (key: {@link transitionKey}). Written by **every** adopt path —
+	 * a verified inbound apply ({@link handleInboundNotice}) *and* a locally-originated broadcast (the
+	 * host's `broadcastNotice`, which `broadcastOver` never echoes back to self) — via
+	 * {@link recordAdoptedTransition}, and read by two consumers: the inbound stale gate (a notice at or
+	 * below the recorded `effectiveAt` is dropped before verification) and engine seeding (a freshly
+	 * created {@link CoordEngine}'s {@link PromotionLifecycle} initializes its per-topic ordering and
+	 * direction from here, via `CoordEngineContext.adoptedTransition` → `PromotionDeps.seedTransition`).
 	 *
-	 * **Bounded.** An {@link LruMap} capped at {@link PROMOTE_HIGHWATER_MAX_KEYS} so the retain-forever shape
-	 * cannot leak on a long-lived node. Unlike the limiter this is *not* attacker-growable (it is written only
-	 * on an `"applied"` outcome, which needs a verified `≥ minSigs` cohort signature — reads of forged
-	 * `topicId`s via `.get` create nothing), so it never evicts under legitimate load; the cap is the
-	 * belt-and-suspenders bound. Evicting an entry is safe: the engine's {@link PromotionLifecycle} is
-	 * independently idempotent and `effectiveAt`-ordered (`PromotionState.lastEffectiveAt`), so an
-	 * evicted-then-replayed older notice re-verifies (one bounded, rate-capped `verifyMessage`) and then
-	 * **no-ops at the engine** rather than (re-)applying. Water absence only *opens* the gate, never closes it.
+	 * This map — not the engine — is the node's replay-ordering authority: the engine's
+	 * `PromotionState.lastEffectiveAt` is a same-process second layer that is discarded whenever the
+	 * registry evicts the engine under memory pressure, while this map outlives every engine. Keying
+	 * includes the coord so two sibling cohorts a node serves for one `(topic, tier)` never share an
+	 * entry, and the topic so two topics at one coord order independently.
+	 *
+	 * **Bounded.** An {@link LruMap} capped at {@link PROMOTE_TRANSITIONS_MAX_KEYS}, so the retain-forever
+	 * shape cannot leak on a long-lived node. Not attacker-growable: it is written only on adopted
+	 * transitions — a verified `≥ minSigs` cohort signature, or a locally threshold-signed notice — and
+	 * reads of forged keys via `.get` create nothing. Both consumers read through `.get`, which refreshes
+	 * recency, so an actively-transitioning `(coord, tier, topic)` stays resident. Record absence only
+	 * *opens* the stale gate, never closes it: losing an entry while its engine is still resident costs
+	 * one re-verify (the engine's `lastEffectiveAt` still no-ops the replay), and only losing BOTH the
+	 * entry and the engine reopens the replay window.
 	 */
-	readonly highWater: LruMap<string, number>;
+	readonly transitions: LruMap<string, AdoptedTransition>;
 }
 
 /**
- * Hard cap on tracked per-served-coord high-water entries; the least-recently-touched are evicted beyond
- * this. A modest bound is plenty — only verified applies grow the map, so it never evicts under legitimate
- * load — but it caps the otherwise retain-forever shape on a long-lived node.
+ * Hard cap on tracked adopted-transition entries; the least-recently-touched are evicted beyond this. A
+ * modest bound is plenty — only adopted transitions grow the map — but it caps the otherwise
+ * retain-forever shape on a long-lived node.
+ *
+ * NOTE: this counts `(coord, tier, topic)` triples, NOT engines, so it is not a per-engine guarantee: a
+ * node at the {@link DEFAULT_COORD_ENGINES_MAX} (2048) registry cap that has transitioned more than ~4
+ * topics per coord can overflow it, and the least-recently-touched entries go first. That is safe while
+ * the owning engine is resident (its `lastEffectiveAt` still orders replays); if a node ever runs that
+ * wide AND evicts engines, raise this cap rather than relying on the engine layer.
  */
-export const PROMOTE_HIGHWATER_MAX_KEYS = 8192;
+export const PROMOTE_TRANSITIONS_MAX_KEYS = 8192;
 
 /** Build the default {@link PromoteGate} from the (optional) anti-DoS rate-limiter config. */
 export function createPromoteGate(rateLimiterConfig?: RegisterRateLimiterConfig): PromoteGate {
-	return { rateLimiter: createRegisterRateLimiter(rateLimiterConfig), highWater: new LruMap<string, number>(PROMOTE_HIGHWATER_MAX_KEYS) };
+	return { rateLimiter: createRegisterRateLimiter(rateLimiterConfig), transitions: new LruMap<string, AdoptedTransition>(PROMOTE_TRANSITIONS_MAX_KEYS) };
+}
+
+/** The {@link PromoteGate.transitions} key for one `(cohortCoord, tier, topicId)` (all b64url-encoded parts). */
+export function transitionKey(cohortCoordB64: string, tier: number, topicIdB64: string): string {
+	return `${cohortCoordB64}|${tier}|${topicIdB64}`;
+}
+
+/**
+ * The {@link transitionKey} a notice's own fields address: the served `cohortCoord` it was decided at, the
+ * tier the deciding cohort serves the topic at (`fromTier` on a promotion, `tier` on a demotion — both the
+ * engine's own tree tier for a notice at its served coord), and the topic. A demotion also fans to the
+ * parent coord, but that parent-unlink path is deliberately outside this ordering — see
+ * {@link applyDemotionUnlinkAtParent}.
+ */
+export function noticeTransitionKey(notice: PromotionNoticeV1 | DemotionNoticeV1): string {
+	return transitionKey(notice.cohortCoord, "parentCohortCoord" in notice ? notice.tier : notice.fromTier, notice.topicId);
+}
+
+/**
+ * Record `notice` as the last adopted transition for its `(coord, tier, topic)` — monotonic per key (an
+ * older or equal `effectiveAt` never overwrites), with the direction taken from the notice's shape (a
+ * promotion sets `promoted = true`, a demotion `false`). Called from BOTH adopt paths: the verified
+ * inbound apply in {@link handleInboundNotice} and the host's `broadcastNotice` origination seam.
+ */
+export function recordAdoptedTransition(gate: PromoteGate, notice: PromotionNoticeV1 | DemotionNoticeV1): void {
+	// NOTE: this write is monotonic but `promote()` / `demote()` origination is not — the lifecycle stamps
+	// `effectiveAt = now` without consulting its own `lastEffectiveAt`. A backwards local clock can therefore
+	// originate a transition the record refuses, leaving the record's direction stale relative to the engine
+	// until the next forward-clock transition. Harmless today (the wall clock only skews backwards on an NTP
+	// step, and the same skew already perturbs every `effectiveAt`-ordered path); if origination ever gains a
+	// monotonic clock, drop the divergence by ordering `promote()` / `demote()` against `lastEffectiveAt` too.
+	const key = noticeTransitionKey(notice);
+	const held = gate.transitions.get(key);
+	if (held === undefined || notice.effectiveAt > held.effectiveAt) {
+		gate.transitions.set(key, { effectiveAt: notice.effectiveAt, promoted: !("parentCohortCoord" in notice) });
+	}
 }
 
 /**
@@ -2565,11 +2868,12 @@ export type ParentUnlinkOutcome = "unlinked" | "no-parent" | "untrusted";
  * - `"unlinked"`  — verified; the child was unrecorded (or was already released — the child registry's own
  *   per-`(topic, childCoord)` freshness makes a replay an idempotent no-op).
  *
- * **Freshness is the child registry's, not the promote-gate high-water.** The sibling-adopt high-water is keyed
- * by the child coord and advanced only on a sibling-adopt `"applied"`; the unlink is ordered independently by
- * the child registry's per-child `lastEffectiveAt`, so a demotion that is a stale no-op for the sibling-adopt
- * target still applies the unlink at the parent, and vice-versa. The verify carries the same
- * {@link PROMOTE_REFETCH_MIN_INTERVAL_MS} bound as the sibling-adopt, so it cannot amplify into dials.
+ * **Freshness is the child registry's, not the promote-gate transition record.** The sibling-adopt record is
+ * keyed by the child coord and, on the inbound path, advanced only on a sibling-adopt `"applied"`; the unlink
+ * is ordered independently by the child registry's per-child `lastEffectiveAt`, so a demotion that is a stale
+ * no-op for the sibling-adopt target still applies the unlink at the parent, and vice-versa. The verify
+ * carries the same {@link PROMOTE_REFETCH_MIN_INTERVAL_MS} bound as the sibling-adopt, so it cannot amplify
+ * into dials.
  */
 export async function applyDemotionUnlinkAtParent(
 	notice: DemotionNoticeV1,
@@ -2608,16 +2912,17 @@ export async function applyDemotionUnlinkAtParent(
  * work:
  *
  * ```
- *   decode → per-(peer,topic) rate limit → resolve engine by carried cohortCoord → effectiveAt high-water → verify+apply
- *                                                                                                          ↘ (demotion) parent-unlink at parentCohortCoord
+ *   decode → per-(peer,topic) rate limit → resolve engine by carried cohortCoord → adopted-transition stale gate → verify+apply
+ *                                                                                                                ↘ (demotion) parent-unlink at parentCohortCoord
  * ```
  *
  * A **demotion** carries a second, independent apply semantics: beyond the sibling-adopt above, it also
  * releases the demoting child at its parent cohort ({@link applyDemotionUnlinkAtParent}). Both paths may fire
  * on one node (one that serves both the child coord and the parent coord). The parent-unlink runs OUTSIDE the
- * sibling-adopt high-water (which is keyed by the child coord and would otherwise stale-drop the parent-coord
- * frame after the child-coord frame advanced it); its freshness is the child registry's own per-child key.
- * `"unlinked"` is returned when the unlink fired but the sibling-adopt did not (a parent-only node).
+ * sibling-adopt transition record (which is keyed by the child coord and would otherwise stale-drop the
+ * parent-coord frame after the child-coord frame advanced it); its freshness is the child registry's own
+ * per-child key. `"unlinked"` is returned when the unlink fired but the sibling-adopt did not (a parent-only
+ * node).
  *
  * - **Rate limit** (`gate.rateLimiter`) keys on `(from, topicId)`; an over-rate peer is dropped before the
  *   coord lookup and the verify, so a peer cannot amplify junk into verify/network work.
@@ -2625,10 +2930,11 @@ export async function applyDemotionUnlinkAtParent(
  *   notice was decided for, covered by its signature. A node serving several sibling cohorts for one
  *   `(topic, tier)` applies the notice to the cohort that produced it, never a first-match `(topic, tier)`
  *   scan; a coord this node does not serve is dropped.
- * - **High-water** (`gate.highWater`, keyed per served `cohortCoord`) drops a notice whose `effectiveAt` is
- *   at or below the last *applied* one — a replay / out-of-order frame — before `verifyMessage`. It is
- *   advanced **only** on an `"applied"` outcome, so a forged frame (which never verifies) cannot poison it.
- *   Keying by coord (not `(topic, tier)`) keeps two sibling cohorts on one node from sharing a water.
+ * - **Stale gate** (`gate.transitions`, keyed per `(cohortCoord, tier, topicId)`) drops a notice whose
+ *   `effectiveAt` is at or below the last *adopted* transition — a replay / out-of-order frame — before
+ *   `verifyMessage`. On this inbound path it advances **only** on an `"applied"` outcome, so a forged frame
+ *   (which never verifies) cannot poison it. Keying by coord keeps two sibling cohorts on one node from
+ *   sharing an entry; keying by topic keeps two topics at one coord ordering independently.
  * - The receiver-side `cohortEpoch` is intentionally **not** gated on: the epoch rotates on every
  *   membership change, so a legitimately in-flight notice can briefly carry the prior epoch right after a
  *   rotation — making an epoch check a brittle, false-positive-prone filter. The rate limiter + high-water
@@ -2673,20 +2979,19 @@ export async function handleInboundNotice(
 	if (target === undefined) {
 		siblingOutcome = "dropped";
 	} else {
-		// Freshness / replay gate: drop an at-or-below-high-water notice before the expensive verify. Keyed by the
-		// served coord (which uniquely identifies the cohort) so two sibling cohorts on one node do not share a
-		// high-water — an applied notice for cohort A must not stale-drop a legitimate cohort-B notice. `tier` is
-		// kept in the key only for readability.
-		const waterKey = `${inbound.notice.cohortCoord}|${tier}`;
-		const water = gate.highWater.get(waterKey);
-		if (water !== undefined && inbound.notice.effectiveAt <= water) {
-			log("promote: stale %s notice for topic %s tier %d (effectiveAt %d <= high-water %d)", inbound.kind, inbound.notice.topicId, tier, inbound.notice.effectiveAt, water);
+		// Freshness / replay gate: drop a notice at or below the last adopted transition for its
+		// `(coord, tier, topic)` before the expensive verify. Keyed per coord (so two sibling cohorts on one
+		// node never share an entry) AND per topic (so an applied notice for topic A never stale-drops a
+		// legitimate topic-B notice at the same coord).
+		const held = gate.transitions.get(noticeTransitionKey(inbound.notice));
+		if (held !== undefined && inbound.notice.effectiveAt <= held.effectiveAt) {
+			log("promote: stale %s notice for topic %s tier %d (effectiveAt %d <= last adopted %d)", inbound.kind, inbound.notice.topicId, tier, inbound.notice.effectiveAt, held.effectiveAt);
 			siblingOutcome = "stale";
 		} else {
 			siblingOutcome = await verifyAndApplyNotice(inbound, target, verifier, now);
 			if (siblingOutcome === "applied") {
-				// Advance the high-water only on a *verified-and-applied* notice, so a forged frame cannot poison it.
-				gate.highWater.set(waterKey, inbound.notice.effectiveAt);
+				// Record only a *verified-and-applied* notice, so a forged frame cannot poison the ordering.
+				recordAdoptedTransition(gate, inbound.notice);
 			} else {
 				log("promote: %s %s notice for topic %s tier %d", siblingOutcome, inbound.kind, inbound.notice.topicId, tier);
 			}
@@ -2699,12 +3004,12 @@ export async function handleInboundNotice(
 
 	// --- Parent-unlink path (demotion only): additionally release the demoting child at its parent cohort. ---
 	// A demotion is fanned to BOTH the child coord (sibling-adopt, above) and the parent coord (this unlink),
-	// arriving as two independent frames. This path is deliberately OUTSIDE the sibling-adopt high-water: that
-	// water is keyed by the child coord and advanced only on a sibling-adopt apply, so — on a node serving both
-	// coords — the child-coord frame would advance the water and stale-drop the parent-coord frame before it
-	// could unrecord. The child registry's own per-`(topic, childCoord)` freshness orders the unlink instead, so
-	// a replay is an idempotent no-op. The verify is against the child cohort cert (same as the sibling-adopt),
-	// so a forged demotion cannot unrecord.
+	// arriving as two independent frames. This path is deliberately OUTSIDE the sibling-adopt transition
+	// record: that record is keyed by the child coord and advanced on a sibling-adopt apply, so — on a node
+	// serving both coords — the child-coord frame would advance it and stale-drop the parent-coord frame before
+	// it could unrecord. The child registry's own per-`(topic, childCoord)` freshness orders the unlink instead,
+	// so a replay is an idempotent no-op. The verify is against the child cohort cert (same as the
+	// sibling-adopt), so a forged demotion cannot unrecord.
 	const unlink = await applyDemotionUnlinkAtParent(inbound.notice, registry, verifier, now);
 	if (siblingOutcome === "applied") {
 		return "applied"; // a node serving both coords: the sibling-adopt is the primary reported outcome