@optimystic/db-p2p 0.25.1 → 0.27.0

package/dist/src/cohort-topic/host.js

@@ -162,12 +162,25 @@ export async function createCohortTopicHost(node, fret, options = {}) {
             const members = cohortAround(coord).members.map(bytesToPeerIdString);
             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, servedCoord) => {
+        // 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`
@@ -201,11 +214,6 @@ export async function createCohortTopicHost(node, fret, options = {}) {
     // {@link createBootstrapEvidencePolicy}.
     const hasCommittedParentBacking = 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 = {
         hash,
         addressing,
@@ -244,13 +252,19 @@ export async function createCohortTopicHost(node, fret, options = {}) {
         // 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) => 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) => 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, tier, topicId) => promoteGate.transitions.get(transitionKey(bytesToB64url(coord), tier, bytesToB64url(topicId))),
     };
     const registry = createCoordRegistry(ctx, options.antiDos?.coordEnginesMax);
     // --- cold-sibling engine instantiation on a verified co-member gossip frame (§Cold-start instantiation) ---
@@ -273,10 +287,11 @@ export async function createCohortTopicHost(node, fret, options = {}) {
     // 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) => {
         if (verifyGossip === undefined) {
             return; // key-less / interim mode: no co-member gate, so never auto-instantiate
@@ -731,7 +746,7 @@ function clampTier(tier) {
 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.
  */
@@ -741,20 +756,46 @@ export class CoordEngineRegistryFullError extends Error {
         this.name = "CoordEngineRegistryFullError";
     }
 }
+/**
+ * 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 = {
+    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, maxEngines = DEFAULT_COORD_ENGINES_MAX) {
     if (!Number.isInteger(maxEngines) || maxEngines <= 0) {
@@ -766,27 +807,48 @@ function createCoordRegistry(ctx, maxEngines = DEFAULT_COORD_ENGINES_MAX) {
     const recency = new Map();
     let seq = 0;
     const touch = (key) => { 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) => !engine.hasState() && !engine.hasForwarders();
-    // 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.
+    // 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) => {
+        const liveness = engine.liveness();
+        let rank = 0;
+        for (const kind of Object.keys(EVICTION_RANK)) {
+            if (!liveness[kind]) {
+                continue;
+            }
+            const r = EVICTION_RANK[kind];
+            if (r === "pinned") {
+                return undefined;
+            }
+            if (r > rank) {
+                rank = r;
+            }
+        }
+        return rank;
+    };
+    // 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 = () => {
+    // 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 = () => {
         let victimKey;
+        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;
             }
@@ -794,9 +856,11 @@ function createCoordRegistry(ctx, maxEngines = DEFAULT_COORD_ENGINES_MAX) {
         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;
     };
     return {
@@ -806,8 +870,8 @@ function createCoordRegistry(ctx, maxEngines = DEFAULT_COORD_ENGINES_MAX) {
             // 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);
@@ -907,6 +971,10 @@ class RotationState {
         return undefined;
     }
 }
+// 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() {
     const byTopic = new Map();
     // Freshness-ordered write shared by link/unlink: apply `linked` only if `effectiveAt` is strictly newer than
@@ -924,7 +992,7 @@ function createChildRegistry() {
         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) {
@@ -955,6 +1023,27 @@ function createChildRegistry() {
             }
             return n;
         },
+        hasLinkedChildren() {
+            for (const children of byTopic.values()) {
+                for (const entry of children.values()) {
+                    if (entry.linked) {
+                        return true;
+                    }
+                }
+            }
+            return false;
+        },
+        linkedChildren() {
+            const out = [];
+            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;
+        },
     };
 }
 /**
@@ -1111,6 +1200,15 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
             return undefined;
         }
     };
+    // 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
@@ -1121,7 +1219,7 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
      * tick. Key-less interim mode no-ops (the verify-only signer cannot assemble).
      */
     const publishMembership = async (now, refresh) => {
-        if (!canPublish) {
+        if (closed || !canPublish) {
             return undefined;
         }
         const snapshot = snapshotAt(now); // also observes the current identity (snapshotAt → cohort())
@@ -1168,6 +1266,11 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
         cohortCoord: () => 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) => 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.
@@ -1286,11 +1389,18 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
     // NOTE: re-broadcasts willingness for every idle-but-willing cohort every T_willingness_heartbeat; if a
     // node ever serves very many idle cohorts, batch the heartbeats or lengthen the interval.
     let lastGossipAt;
+    // 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;
     // 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) => {
+        if (closed) {
+            return undefined;
+        }
         engine.sweepStale(now);
         const topicSummaries = residentTopics().map((topicId) => toCohortTopicSummary(topicId, traffic.publish(topicId, now), {
             tier: tierOfTopic(store, topicId),
@@ -1301,6 +1411,34 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
             // consistent cohort-wide, not a single-member shard.
             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;
@@ -1335,7 +1473,7 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
     // 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) => {
-        if (!canPublish) {
+        if (closed || !canPublish) {
             return;
         }
         for (const topicId of residentTopics()) {
@@ -1352,14 +1490,39 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
             }
         }
     };
+    // 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 = () => ({
+        records: store.listAll().length > 0,
+        forwarders: coldStart.hasForwarders(),
+        children: childRegistry.hasLinkedChildren(),
+        promotion: promotion.hasAdoptedState(),
+    });
     return {
         servedCoord,
         treeTier,
         engine,
         cohort,
         cohortIdentityAt: (epoch) => rotationState.membersAt(bytesToB64url(epoch)),
-        hasState: () => store.listAll().length > 0,
-        hasForwarders: () => 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: () => liveness().records,
+        hasForwarders: () => liveness().forwarders,
         holds: (topicId, participantId) => store.getByParticipant(topicId, participantId) !== undefined,
         records: (topicId) => store.listByTopic(topicId),
         topicTraffic: (topicId) => traffic.snapshot(topicId),
@@ -1400,7 +1563,10 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
         pumpMembership: (now) => publishMembership(now, true),
         gossipRound,
         demotionTick,
-        close: () => bus.close(),
+        close: () => {
+            closed = true;
+            bus.close();
+        },
     };
 }
 /**
@@ -1624,14 +1790,53 @@ export async function handleSignRequest(request, fromPeerStr, deps) {
     return { v: 1, signer: bytesToB64url(deps.selfMember), signature: bytesToB64url(signature) };
 }
 /**
- * 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) {
-    return { rateLimiter: createRegisterRateLimiter(rateLimiterConfig), highWater: new LruMap(PROMOTE_HIGHWATER_MAX_KEYS) };
+    return { rateLimiter: createRegisterRateLimiter(rateLimiterConfig), transitions: new LruMap(PROMOTE_TRANSITIONS_MAX_KEYS) };
+}
+/** The {@link PromoteGate.transitions} key for one `(cohortCoord, tier, topicId)` (all b64url-encoded parts). */
+export function transitionKey(cohortCoordB64, tier, topicIdB64) {
+    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) {
+    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, notice) {
+    // 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) });
+    }
 }
 /**
  * Decode a `promote`-protocol frame as a {@link PromotionNoticeV1} or {@link DemotionNoticeV1} (try one,
@@ -1726,11 +1931,12 @@ export async function verifyAndApplyNotice(inbound, target, verifier, now) {
  * - `"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, registry, verifier, now) {
     const parent = registry.findByCoord(b64urlToBytes(notice.parentCohortCoord));
@@ -1764,16 +1970,17 @@ export async function applyDemotionUnlinkAtParent(notice, registry, verifier, no
  * 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.
@@ -1781,10 +1988,11 @@ export async function applyDemotionUnlinkAtParent(notice, registry, verifier, no
  *   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
@@ -1820,21 +2028,20 @@ export async function handleInboundNotice(frame, from, registry, verifier, gate,
         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);
@@ -1846,12 +2053,12 @@ export async function handleInboundNotice(frame, from, registry, verifier, gate,
     }
     // --- 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