@optimystic/db-p2p 0.14.0 → 0.16.2

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

@@ -31,8 +31,9 @@
  * driver to call.
  *
  * **Anti-DoS + cold-start (gaps 6–7).** Each {@link CoordEngine} is injected its own per-coord anti-DoS
- * guards — a `RegisterRateLimiter` (4/min per peer-topic), a `CorrelationReplayGuard` (60 s freshness),
- * and a `TopicBudget` (2048 topics, LRU) — so a budget/limit at one coord is independent of another. The
+ * guards — a `RegisterRateLimiter` (4/min per peer-topic), a `CorrelationReplayGuard` (60 s freshness,
+ * hard `maxKeys` LRU cap), and a `TopicBudget` (2048 topics, LRU) — so a budget/limit at one coord is
+ * independent of another. The
  * node-level {@link BootstrapEvidence} policy (one tier→verifier policy, no per-coord state) is built once
  * and shared. db-core embeds no PoW / reputation scheme, so the host supplies the real verifiers
  * ({@link createPoWVerifier} / {@link createReputationVerifier}) and the participant-side PoW minter
@@ -42,8 +43,8 @@
  * backing keeps T0/T1 permissive-but-logged so cold-root origination is not blocked
  * (`cohort-topic-bootstrap-coldstart-origination-regression`), and an entirely unconfigured host stays
  * permissive-but-logged at every tier (never an undefined gate). A cold-started tier-`d > 0` forwarder registers with
- * its tier-`(d − 1)` parent by routing a forwarder-link frame over the router (gap 7), staying
- * `awaiting_parent` until the ack.
+ * its tier-`(d − 1)` parent by routing a (child-cohort-signed) {@link ChildLinkV1} over the router; the parent
+ * authenticates + records the child and acks, and the forwarder stays `awaiting_parent` until that `linked` ack.
  *
  * **Scope.** `followOn` derivation for a promoted-redirect arrival is parked in backlog
  * (`cohort-topic-followon-derivation`); this milestone serves a **single tier-0 cohort**, so `followOn`
@@ -53,12 +54,11 @@
  * `routeAct`/`assembleCohort`) by `test/cohort-topic/live-tier.spec.ts`.
  */
 import { hashPeerId, readAllBounded } from "p2p-fret";
-import { RingHash, createRegistrationStore, createSlotAssigner, createCohortGossipBus, createWillingnessCheck, createPromotionLifecycle, createColdStartManager, createTrafficCounters, createRenewalCohortSide, createMembershipVerifier, createMembershipSourceRouter, createMembershipCertPublisher, createCohortSigner, createCohortMemberEngine, createCohortTopicService, createLoadBarometer, createTierAddressing, createRegisterRateLimiter, createCorrelationReplayGuard, createTopicBudget, createBootstrapEvidence, LruMap, coreProfile, DEFAULT_MIN_SIGS, DEFAULT_MAX_NO_POW_TIER, DEFAULT_TRAFFIC_WINDOW_SECONDS, DEFAULT_TTL_MS, bytesToB64url, b64urlToBytes, bytesEqual, compareBytes, encodeCohortMessage, decodeCohortMessage, membershipCertSignable, membershipCertSigningPayload, toCohortTopicSummary, validateRegisterV1, validateRenewV1, validateSignRequestV1, validateSignReplyV1, validatePromotionNoticeV1, validateDemotionNoticeV1, registerSigningPayload, renewSigningPayload, cohortGossipSigningPayload, promotionNoticeSigningPayload, demotionNoticeSigningPayload, } from "@optimystic/db-core";
-import { randomBytes } from "@libp2p/crypto";
+import { RingHash, createRegistrationStore, createSlotAssigner, createCohortGossipBus, createWillingnessCheck, createPromotionLifecycle, createColdStartManager, createTrafficCounters, createRenewalCohortSide, createMembershipVerifier, createMembershipSourceRouter, createMembershipCertPublisher, createCohortSigner, createCohortMemberEngine, createCohortTopicService, createLoadBarometer, createTierAddressing, createRegisterRateLimiter, DEFAULT_RATE_WINDOW_MS, createCorrelationReplayGuard, createTopicBudget, createBootstrapEvidence, LruMap, coreProfile, DEFAULT_MIN_SIGS, DEFAULT_MAX_NO_POW_TIER, DEFAULT_TRAFFIC_WINDOW_SECONDS, bytesToB64url, b64urlToBytes, bytesEqual, encodeCohortMessage, decodeCohortMessage, decodeCohortGossipV1, membershipCertSignable, membershipCertSigningPayload, toCohortTopicSummary, validateRegisterV1, validateRenewV1, validateChildLinkV1, validateChildLinkReplyV1, validateSignRequestV1, validateSignReplyV1, validatePromotionNoticeV1, validateDemotionNoticeV1, registerSigningPayload, renewSigningPayload, cohortGossipSigningPayload, promotionNoticeSigningPayload, demotionNoticeSigningPayload, childLinkSigningPayload, } from "@optimystic/db-core";
 import { peerIdFromString } from "@libp2p/peer-id";
 import { FretTopicRouter } from "./topic-router.js";
 import { FretCohortGossipTransport } from "./cohort-gossip-transport.js";
-import { buildCohortGossip, createPendingDeltas, DEFAULT_GOSSIP_INTERVAL_MS } from "./cohort-gossip-driver.js";
+import { buildCohortGossip, createPendingDeltas, DEFAULT_GOSSIP_INTERVAL_MS, DEFAULT_WILLINGNESS_HEARTBEAT_MS } from "./cohort-gossip-driver.js";
 import { FretMembershipSource } from "./membership-source.js";
 import { FretMembershipPublishSink } from "./membership-publish-sink.js";
 import { FretCohortThresholdCrypto, createVerifyOnlyThresholdCrypto } from "./threshold-crypto.js";
@@ -86,6 +86,7 @@ export async function createCohortTopicHost(node, fret, options = {}) {
     const fanout = options.fanout ?? 16;
     const maxBytes = options.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
     const gossipIntervalMs = options.gossipIntervalMs ?? DEFAULT_GOSSIP_INTERVAL_MS;
+    const willingnessHeartbeatMs = options.willingnessHeartbeatMs ?? DEFAULT_WILLINGNESS_HEARTBEAT_MS;
     const hash = new RingHash();
     const selfPeerStr = node.peerId.toString();
     const selfMemberBytes = peerIdToBytes(node.peerId); // dialable member id
@@ -167,6 +168,12 @@ export async function createCohortTopicHost(node, fret, options = {}) {
     // transport's cohort peer resolution.
     const broadcastNotice = (notice, servedCoord) => {
         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`
+        // runs both apply semantics independently: the `cohortCoord` target does the sibling-adopt, and a demotion
+        // additionally resolves `parentCohortCoord` and — on the same threshold verify against the child cohort
+        // cert — calls `parent.unrecordChild(...)`. A parent-only node applies only the unlink; a node serving
+        // both coords applies both. See `noticeBroadcastCoords` / `handleInboundNotice`.
         for (const coord of noticeBroadcastCoords(notice, servedCoord)) {
             gossipTransport.broadcastOver(protocols.promote, coord, frame);
         }
@@ -209,6 +216,7 @@ export async function createCohortTopicHost(node, fret, options = {}) {
         wantK,
         minSigs,
         maxBytes,
+        willingnessHeartbeatMs,
         publishSink,
         privateKey: options.privateKey,
         router,
@@ -229,9 +237,83 @@ export async function createCohortTopicHost(node, fret, options = {}) {
         // Cache this node's own freshly-published cohort cert into the verifier, so an inbound notice
         // signed by this node's cohort verifies locally without a network refetch. `verifier` is declared
         // just below; the closure only runs on a (later) publish, after it is initialized.
+        //
+        // NOTE (stale trust-lock, drop-the-lock-on-demotion): `verifier.cache()` marks this coord *trusted*,
+        // which trust-LOCKS it (no un-anchored refetch can downgrade it). If this node later leaves the coord's
+        // 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.
         onCertPublished: (cert) => verifier.cache(cert),
     };
-    const registry = createCoordRegistry(ctx);
+    const registry = createCoordRegistry(ctx, options.antiDos?.coordEnginesMax);
+    // --- cold-sibling engine instantiation on a verified co-member gossip frame (§Cold-start instantiation) ---
+    // A brand-new multi-node cohort deadlocks otherwise: FRET lands every register for a coord on the ONE
+    // nearest member, so its siblings are never independently woken by a routed register — they hold no engine,
+    // are not subscribed to the coord's gossip, and silently drop the willingness/record frames the served
+    // member sends. So replication/failover never materialise. This gate lets a co-member's frame (e.g. the
+    // idle-but-willing willingness heartbeat) instantiate the sibling engine, which then joins the gossip and
+    // reciprocates its own willingness. Called from the `/cohort-gossip` handler BEFORE `deliver`, so the fresh
+    // bus is subscribed in time to merge the very frame that woke it.
+    //
+    // Bounded to genuine co-members by the existing `verifyGossip` auth check (peer-key signature verifies for
+    // `fromMember` AND `fromMember` ∈ `cohortAround(coord).members`), so a peer can only make us instantiate an
+    // engine for a coord where FRET assembly agrees we are both members. Live-signer mode only: without a key
+    // there is no co-member gate, and unauthenticated engine creation would be a DoS vector, so key-less/interim
+    // mode keeps today's behaviour (drop gossip for an unknown coord).
+    //
+    // Scope: tier-0 only (`treeTier === 0`). A tier-`d > 0` frame carries no topic/participantCoord context a
+    // bare willingness heartbeat could seed the parent-coord derivation from, and overlaps the parent-child
+    // 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.
+    const maybeInstantiateColdSibling = (frame) => {
+        if (verifyGossip === undefined) {
+            return; // key-less / interim mode: no co-member gate, so never auto-instantiate
+        }
+        let g;
+        try {
+            g = decodeCohortGossipV1(frame, maxBytes);
+        }
+        catch {
+            return; // malformed → the normal deliver path drops it
+        }
+        if (g.treeTier !== 0) {
+            return; // tier-0 milestone only (a tier-d>0 unknown-coord frame falls through to drop)
+        }
+        const coord = b64urlToBytes(g.coord);
+        // NOTE: findByCoord bumps LRU recency as a side effect, and this runs BEFORE the verifyGossip
+        // co-member gate — so an unverified gossip frame naming a coord we already serve can pin that engine
+        // against idle-eviction. Marginal today (an outsider can only pin engines that already exist, bounded
+        // by real co-membership; it cannot create engines — that path is gated below). If gossip-flood
+        // recency-pinning ever matters, add a touch-free `has(coord)` lookup for this existence probe.
+        if (registry.findByCoord(coord) !== undefined) {
+            return; // already serving this coord — nothing to instantiate
+        }
+        if (!verifyGossip(g, coord)) {
+            return; // co-member gate: bad signature or non-member → do not instantiate
+        }
+        // The dummy `participantCoord` seeds only the tier-`d > 0` parent-coord derivation, which a tier-0
+        // engine never exercises (demotion is gated on `treeTier > 0`); self's member bytes are a safe filler.
+        try {
+            registry.forCoord(coord, g.treeTier, selfMemberBytes);
+        }
+        catch (err) {
+            if (err instanceof CoordEngineRegistryFullError) {
+                return; // registry full of live cohorts — drop the cold-sibling instantiation (same as any drop)
+            }
+            throw err;
+        }
+    };
     // --- intra-cohort sign endorsement (the `/sign` handler body) ---
     // A member dials us to endorse a threshold-signed artifact; we sign the exact request payload iff we
     // and the requester share the cohort+epoch around `coord`. Exported `handleSignRequest` is the testable
@@ -325,21 +407,78 @@ export async function createCohortTopicHost(node, fret, options = {}) {
         // `d` this equals the participant's `coord_d(self, topicId)` routing key by construction, i.e. the
         // coordinate FRET routed to (§Tier addressing).
         const servedCoord = addressing.coord(reg.treeTier, participantCoord, topicId);
-        const coordEngine = registry.forCoord(servedCoord, reg.treeTier, participantCoord);
+        let coordEngine;
+        try {
+            coordEngine = registry.forCoord(servedCoord, reg.treeTier, participantCoord);
+        }
+        catch (err) {
+            if (err instanceof CoordEngineRegistryFullError) {
+                // Every engine slot holds a live cohort — refuse this new coord cleanly. `unwilling_cohort`
+                // with a back-off is the walk's "retry in time / restart at d_max" signal (§Capacity barometer),
+                // the same shape the per-coord topic budget answers when full-of-populated.
+                log("cohort-topic: register refused — coord-engine registry full");
+                return { v: 1, result: "unwilling_cohort", retryAfterMs: DEFAULT_RATE_WINDOW_MS, reason: "coord-engine registry full" };
+            }
+            throw err;
+        }
         if (fretCohort !== undefined) {
             crossCheckCohort(fret, wantK, servedCoord, fretCohort);
         }
         // `parentCoord` for a cold-start forwarder's parent registration; undefined at the root.
         const parentCoord = reg.treeTier > 0 ? addressing.coord(reg.treeTier - 1, participantCoord, topicId) : undefined;
-        return coordEngine.engine.handleRegister(reg, { followOn: false, treeTier: reg.treeTier, parentCoord }, now);
+        // Derive `followOn` straight from the participant-asserted wire flag. This is the information the
+        // child cohort genuinely cannot infer locally (the tier-addressing hash decorrelates parent/child
+        // coords, and FRET carries no breadcrumb of the redirect), so it must be carried on the frame. It is
+        // forgeable, so the engine's step-1 bootstrap-evidence gate — which demands the same proof for
+        // `followOn: true` as for a `bootstrap: true` cold-root — is what keeps it honest (§Anti-DoS).
+        const followOn = reg.followOn === true;
+        return coordEngine.engine.handleRegister(reg, { followOn, treeTier: reg.treeTier, parentCoord }, now);
+    };
+    // --- child-link dispatch: verify + record a child cohort (parent side) ---
+    // A routed `ChildLinkV1` reaches this node's parent engine through the SAME two entry points a register
+    // uses (the FRET activity handler + the direct-dial `register` handler). Live-key mode verifies the child
+    // cohort's threshold signature against the child cohort's cert; key-less mode is permissive (mirrors the
+    // `verifyRegisterSig` fallback) so unit/mock flows still link + record.
+    const verifyChildLinkSig = options.privateKey === undefined
+        ? undefined
+        : async (link, at) => {
+            // Live-key: an UNSIGNED link (misconfigured mixed mode) is never permissive-accepted — reject it,
+            // never a silent record.
+            if (link.thresholdSig.length === 0) {
+                return false;
+            }
+            let signers;
+            let sig;
+            try {
+                signers = link.signers.map(b64urlToBytes);
+                sig = b64urlToBytes(link.thresholdSig);
+            }
+            catch {
+                return false; // a signer / sig that is not valid base64url cannot verify
+            }
+            // Verify against the CHILD cohort's cert at the child coord/tier — identical to the notice verify at
+            // `verifyAndApplyNotice`, with the same bounded refetch so a link flood cannot amplify into dials.
+            const result = await verifier.verifyMessage(signers, b64urlToBytes(link.childCohortCoord), link.childTier, childLinkSigningPayload(link), sig, { minRefetchIntervalMs: PROMOTE_REFETCH_MIN_INTERVAL_MS, now: at });
+            return result === "verified";
+        };
+    const childLinkDeps = {
+        coord: (tier, pc, topicId) => addressing.coord(tier, pc, topicId),
+        resolveParent: (parentServedCoord, parentTier, childParticipantCoord) => registry.forCoord(parentServedCoord, parentTier, childParticipantCoord),
+        verifyChildLinkSig,
     };
     // --- protocol handlers + activity callback ---
     // Await registration so the host is not returned (and dialed) before the five handlers are live —
     // and, crucially, before the gossip driver below starts ticking (no tick may run on a half-wired node).
-    await registerProtocolHandlers(node, protocols, registry, dispatchRegister, signEndorse, verifier, promoteGate, gossipTransport, publishSink, membershipSource, selfCoord, maxBytes);
+    await registerProtocolHandlers(node, protocols, registry, dispatchRegister, childLinkDeps, minSigs, signEndorse, verifier, promoteGate, gossipTransport, maybeInstantiateColdSibling, publishSink, membershipSource, selfCoord, maxBytes);
     fret.setActivityHandler(async (activity, cohort) => {
-        const reg = validateRegisterV1(decodeCohortMessage(b64urlToBytes(activity), maxBytes));
-        const reply = await dispatchRegister(reg, cohort, Date.now());
+        const decoded = decodeCohortMessage(b64urlToBytes(activity), maxBytes);
+        // Decode-and-branch: a `ChildLinkV1` (a child cohort registering with this parent) runs the child-link
+        // dispatch; everything else is an ordinary participant `RegisterV1`. The two shapes are disjoint (a
+        // child-link has no `treeTier`/`signature`; a register has no `childCohortCoord`/`childTier`).
+        const link = tryValidate(() => validateChildLinkV1(decoded, minSigs));
+        const reply = link !== undefined
+            ? await dispatchChildLink(link, childLinkDeps, Date.now())
+            : await dispatchRegister(validateRegisterV1(decoded), cohort, Date.now());
         return { commitCertificate: bytesToB64url(encodeCohortMessage(reply, maxBytes)) };
     });
     // --- periodic gossip-cadence driver (gap 5) ---
@@ -392,6 +531,7 @@ export async function createCohortTopicHost(node, fret, options = {}) {
         profile,
         gossipTransport,
         promoteGate,
+        membershipSource,
         stop: async () => {
             stopped = true;
             clearInterval(timer);
@@ -536,34 +676,43 @@ function createBootstrapEvidencePolicy(antiDos, hash, log, parentTopicView, hasC
     });
 }
 /**
- * Route a forwarder→parent link to `parentCoord` and resolve on the round-trip (the parent ack).
+ * Route a child-cohort→parent link to `parentCoord` and resolve **only on a `linked` ack**.
  *
- * The link is a `RegisterV1`-style frame routed over {@link ITopicRouter.routeAndAct} keyed at the
- * parent coord: it rides the parent's serving tier (`treeTier − 1`) with this engine's seed
- * `participantCoord`, so the parent recomputes `servedCoord = coord_{d−1}(participantCoord, topicId) =
- * parentCoord`. A fresh CSPRNG `correlationId` keeps it clear of the parent's replay guard on retry.
- * Resolution of the route is treated as the ack (richer child-link confirmation — the parent recording
- * `childCohortCount` over a dedicated child-link frame — is the follow-on
- * `cohort-topic-parent-child-link`); a rejection propagates so the cold-start manager keeps the
- * forwarder `awaiting_parent`.
+ * The frame is a dedicated {@link ChildLinkV1} (not a participant `RegisterV1`) routed over
+ * {@link ITopicRouter.routeAndAct} keyed at the parent coord: it carries the child's served coord
+ * (`childCohortCoord`) and its seed `childParticipantCoord`, so the parent recomputes
+ * `coord_{d−1}(childParticipantCoord, topicId) == parentCoord` and `coord_d(...) == childCohortCoord`,
+ * binding the relationship. In live-key mode the child cohort threshold-signs the link over its own coord
+ * at its current epoch; key-less it ships unsigned (empty `thresholdSig`/`signers`). The parent authenticates
+ * + records the child and replies {@link ChildLinkReplyV1}; a `rejected` (or unreachable) reply propagates as
+ * a throw so the cold-start manager keeps the forwarder `awaiting_parent` for a later retry.
  */
 async function registerForwarderWithParent(ctx, link) {
+    const childTier = link.treeTier;
     const frame = {
         v: 1,
         topicId: bytesToB64url(link.topicId),
+        childCohortCoord: bytesToB64url(link.childCohortCoord),
+        childParticipantCoord: bytesToB64url(link.participantCoord),
+        childTier,
         tier: clampTier(link.opTier ?? 0),
-        treeTier: Math.max(0, link.treeTier - 1),
-        participantCoord: bytesToB64url(link.participantCoord),
-        ttl: DEFAULT_TTL_MS,
-        // Not a root cold-start: a follow-on link to an already-promoted parent, so no bootstrap evidence.
-        bootstrap: false,
-        timestamp: Date.now(),
-        correlationId: bytesToB64url(randomBytes(16)),
-        // Interim: the forwarder cohort cannot sign as the participant; the dedicated child-link frame
-        // (follow-on) carries the cohort threshold signature instead.
-        signature: "",
+        effectiveAt: Date.now(),
+        thresholdSig: "",
+        signers: [],
+        cohortEpoch: bytesToB64url(link.cohortEpoch()),
     };
-    await ctx.router.routeAndAct(link.parentCoord, encodeCohortMessage(frame, ctx.maxBytes), { wantK: ctx.wantK, minSigs: ctx.minSigs });
+    // Live-key: threshold-sign over the canonical child-link image (signature covers only the signable fields,
+    // so filling `thresholdSig`/`signers` after does not alter what was signed). Key-less: leave it unsigned.
+    if (link.signChildLink !== undefined) {
+        const { thresholdSig, signers } = await link.signChildLink.thresholdSign(childLinkSigningPayload(frame));
+        frame.thresholdSig = bytesToB64url(thresholdSig);
+        frame.signers = signers.map(bytesToB64url);
+    }
+    const replyBytes = await ctx.router.routeAndAct(link.parentCoord, encodeCohortMessage(frame, ctx.maxBytes), { wantK: ctx.wantK, minSigs: ctx.minSigs });
+    const reply = validateChildLinkReplyV1(decodeCohortMessage(replyBytes, ctx.maxBytes));
+    if (reply.result !== "linked") {
+        throw new Error(`cohort-topic child-link rejected by parent${reply.reason !== undefined ? `: ${reply.reason}` : ""}`);
+    }
 }
 /** Clamp an op tier to the valid T0–T3 range so the link frame validates at a (future) real parent. */
 function clampTier(tier) {
@@ -573,9 +722,82 @@ function clampTier(tier) {
     return tier > 3 ? 3 : tier;
 }
 // --- registry + coord engine ---
-/** Build the lazy `servedCoord → CoordEngine` registry over the shared collaborators. */
-function createCoordRegistry(ctx) {
+/**
+ * Default hard cap on the number of live per-coord cohort engines (see
+ * {@link CohortTopicAntiDosOptions.coordEnginesMax}). Aligned in order of magnitude with the topic-budget
+ * `topics_max` (2048): the same "this many distinct served units before an anti-abuse ceiling bites" scale.
+ */
+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).
+ * 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.
+ */
+export class CoordEngineRegistryFullError extends Error {
+    constructor(maxEngines) {
+        super(`cohort-topic coord-engine registry full (max=${maxEngines}) — every slot holds a live cohort`);
+        this.name = "CoordEngineRegistryFullError";
+    }
+}
+/**
+ * Build the lazy `servedCoord → CoordEngine` registry over the shared collaborators, hard-capped at
+ * `maxEngines` with least-recently-used eviction of **idle** engines.
+ *
+ * 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.
+ *
+ * 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.
+ */
+function createCoordRegistry(ctx, maxEngines = DEFAULT_COORD_ENGINES_MAX) {
+    if (!Number.isInteger(maxEngines) || maxEngines <= 0) {
+        throw new RangeError(`coordEnginesMax must be a positive integer, got ${maxEngines}`);
+    }
     const engines = new Map();
+    // LRU recency by engine key: a monotonic touch sequence (higher = more recently used). Every engine in
+    // `engines` has an entry; entries are dropped alongside their engine on eviction / close.
+    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.
+    //
+    // 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 = () => {
+        let victimKey;
+        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 s = recency.get(key) ?? 0;
+            if (s < victimSeq) {
+                victimSeq = s;
+                victimKey = key;
+            }
+        }
+        if (victimKey === undefined) {
+            return false;
+        }
+        engines.get(victimKey).close();
+        engines.delete(victimKey);
+        recency.delete(victimKey);
+        return true;
+    };
     return {
         forCoord(coord, treeTier, participantCoord) {
             const key = bytesToB64url(coord);
@@ -583,25 +805,39 @@ function createCoordRegistry(ctx) {
             // 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
+                    // 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);
+                }
                 engine = createCoordEngine(ctx, coord, treeTier, participantCoord);
                 engines.set(key, engine);
             }
+            touch(key);
             return engine;
         },
         findByCoord(coord) {
-            return engines.get(bytesToB64url(coord));
+            const key = bytesToB64url(coord);
+            const engine = engines.get(key);
+            if (engine !== undefined) {
+                touch(key);
+            }
+            return engine;
         },
         findHolder(topicId, participantId) {
-            for (const engine of engines.values()) {
+            for (const [key, engine] of engines) {
                 if (engine.holds(topicId, participantId)) {
+                    touch(key);
                     return engine;
                 }
             }
             return undefined;
         },
         findServing(topicId, treeTier) {
-            for (const engine of engines.values()) {
+            for (const [key, engine] of engines) {
                 if (engine.treeTier === treeTier && engine.servesTopic(topicId)) {
+                    touch(key);
                     return engine;
                 }
             }
@@ -615,6 +851,7 @@ function createCoordRegistry(ctx) {
                 engine.close();
             }
             engines.clear();
+            recency.clear();
         },
     };
 }
@@ -623,8 +860,9 @@ function createCoordRegistry(ctx) {
  * Two roles, one small object:
  *
  * - **Producer** — {@link predecessor} is the identity of the *last published* cert; a publish whose
- *   first `k − x` differ from it is a rotation, and the predecessor identity scopes the rotation `/sign`
- *   round (its epoch is `prevEpoch`, its members are the outgoing cohort to collect from).
+ *   epoch (`H(sorted members)`) differs from it is a rotation — any member change, head or tail — and the
+ *   predecessor identity scopes the rotation `/sign` round (its epoch is `prevEpoch`, its members are the
+ *   outgoing cohort to collect from).
  * - **Endorser** — {@link membersAt} answers "was I a member of the cohort at `epoch`?" over a two-deep
  *   observed-epoch history ({@link current} + {@link prior}), kept fresh by {@link observe} on every
  *   cohort assembly. A request for an epoch past that window is refused (the rapid-double-rotation gap).
@@ -668,15 +906,69 @@ class RotationState {
         return undefined;
     }
 }
+function createChildRegistry() {
+    const byTopic = new Map();
+    // Freshness-ordered write shared by link/unlink: apply `linked` only if `effectiveAt` is strictly newer than
+    // the entry's high-water (or the entry is new), so a stale/out-of-order replay is dropped and an idempotent
+    // re-apply is a no-op. Returns whether the state actually advanced (so the caller re-gossips only real changes).
+    const apply = (topicId, childCohortCoord, effectiveAt, linked) => {
+        const topicKey = bytesToB64url(topicId);
+        let children = byTopic.get(topicKey);
+        if (children === undefined) {
+            children = new Map();
+            byTopic.set(topicKey, children);
+        }
+        const childKey = bytesToB64url(childCohortCoord);
+        const existing = children.get(childKey);
+        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 });
+            return true;
+        }
+        if (effectiveAt <= existing.lastEffectiveAt) {
+            return false;
+        }
+        const changed = existing.linked !== linked;
+        existing.linked = linked;
+        existing.lastEffectiveAt = effectiveAt;
+        return changed;
+    };
+    return {
+        recordChild(topicId, childCohortCoord, effectiveAt) {
+            return apply(topicId, childCohortCoord, effectiveAt, true);
+        },
+        unrecordChild(topicId, childCohortCoord, effectiveAt) {
+            return apply(topicId, childCohortCoord, effectiveAt, false);
+        },
+        count(topicId) {
+            const children = byTopic.get(bytesToB64url(topicId));
+            if (children === undefined) {
+                return 0;
+            }
+            let n = 0;
+            for (const entry of children.values()) {
+                if (entry.linked) {
+                    n++;
+                }
+            }
+            return n;
+        },
+    };
+}
 /**
  * Compose one {@link CoordEngine} bound to `servedCoord`. The cohort it threshold-signs / shards with
  * is the FRET assembly around `servedCoord` (not the node's own ring position). The promotion tier
  * inputs are coord-derived: `treeTier` is fixed at instantiation; `parentCoord` is
  * `coord_{d-1}(participantCoord, topicId)` (the shard's parent shares the prefix, so any participant
- * routed here yields the same parent); `childCohortCount` is `0` for the single-cohort milestone.
+ * routed here yields the same parent); `childCohortCount` is the converged union of recorded child cohorts
+ * (per-cohort child registry, gossip-replicated), `0` until this cohort parents a child.
  */
 function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
     const store = createRegistrationStore();
+    // The child cohorts this cohort parents (recorded by the parent-side child-link dispatch). Its `count`
+    // feeds the demotion gate, the gossip summary, and the traffic snapshot below (was hardcoded 0).
+    const childRegistry = createChildRegistry();
     // Epoch-rotation bookkeeping. `cohort()` observes every assembly so the endorser history stays fresh
     // (the gossip-cadence driver assembles each round); the producer reads `predecessor()` on publish.
     const rotationState = new RotationState();
@@ -713,6 +1005,19 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
                 topicBudget.touch(topicId, store.directParticipants(topicId));
             }
         },
+        // Cross-member child-set convergence: merge inbound child link/unlink deltas straight into this engine's
+        // child registry (last-writer-wins by effectiveAt), so every parent member reads the same converged union
+        // — not only the FRET-routed member that recorded the child. A direct write (no re-enqueue) so a received
+        // delta is not re-gossiped; one broadcast already reaches the whole cohort. (`childRegistry` is declared
+        // just above, so it is fully initialized by the time this callback fires on an inbound merge.)
+        onChildDeltas: (childLinks, childUnlinks) => {
+            for (const ref of childLinks) {
+                childRegistry.recordChild(b64urlToBytes(ref.topicId), b64urlToBytes(ref.childCohortCoord), ref.effectiveAt);
+            }
+            for (const ref of childUnlinks) {
+                childRegistry.unrecordChild(b64urlToBytes(ref.topicId), b64urlToBytes(ref.childCohortCoord), ref.effectiveAt);
+            }
+        },
     });
     const view = bus.view();
     const selfMember = bytesToB64url(ctx.selfMemberBytes);
@@ -741,6 +1046,10 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
     };
     const noticeSigner = makeCoordSigner("promotion");
     const membershipSigner = makeCoordSigner("membership");
+    // The child cohort threshold-signs its own child-link exactly as it signs a promotion notice — over its
+    // own served coord at its current epoch (a sibling of `noticeSigner`). Verify-only key-less (the child
+    // then emits an UNSIGNED link and the parent permissive-accepts it, matching the register-sig fallback).
+    const childLinkSigner = makeCoordSigner("childlink");
     // Cohort-side membership-cert publisher: threshold-signs a MembershipCertV1 over this coord's cohort
     // and serves it through the node's publish sink. Driven by the onStabilized / pumpMembership hooks.
     const membershipPublisher = createMembershipCertPublisher({
@@ -759,10 +1068,16 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
     // gossip-cadence driver iterating `registry.all()` would reject on every key-less engine.
     const canPublish = ctx.privateKey !== undefined;
     // --- epoch-rotation attestation production (cohort-topic-trust-anchor-rotation-production) ---
-    // The first `k − x` members of the cert's ascending order; a change across a publish is a rotation
-    // (mirrors the publisher's own republish gate — same inputs, so the two agree on what is a rotation).
-    const firstKx = (members) => [...members].sort(compareBytes).slice(0, ctx.minSigs).map(bytesToB64url);
-    const firstKxChanged = (a, b) => !sameStringOrder(firstKx(a.memberBytes), firstKx(b.memberBytes));
+    // Any change to the cohort identity (`epochKey = H(sorted members)`) is a rotation — head OR tail
+    // (mirrors the publisher's own republish gate — both now key on the epoch, so the two agree on what is
+    // a rotation).
+    // NOTE: the `/sign` "rotation" endorsement gate remembers only the current + immediately-prior observed
+    // epoch (RotationState.membersAt). That two-deep bound is orthogonal to attesting on any epoch change —
+    // RotationState.observe already shifts on every observed epoch change (any member change rotates the
+    // epoch), so rapid churn could age a predecessor epoch out of the window regardless. If rapid multi-step
+    // churn ever makes rotation attestations frequently unproducible, that is a history-depth concern in
+    // RotationState, not this trigger.
+    const epochChanged = (a, b) => a.epochKey !== b.epochKey;
     /**
      * Threshold-sign the new cert's canonical payload under the **predecessor** cohort identity, producing the
      * `{ prevEpoch, rotationSig, rotationSigners }` attestation — or `undefined` if the predecessor quorum is
@@ -796,10 +1111,10 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
         }
     };
     /**
-     * Publish (or refresh) this cohort's membership cert, attaching a rotation attestation when the first
-     * `k − x` changed since the last publish. `refresh` selects the publisher path: `false` for a
+     * 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
      * stabilization event ({@link CoordEngine.onStabilized}), `true` for the periodic refresh
-     * ({@link CoordEngine.pumpMembership}). A first-`k − x` change is a stabilization regardless of which hook
+     * ({@link CoordEngine.pumpMembership}). An epoch change is a stabilization regardless of which hook
      * fired, so it routes through `onStabilized` (which republishes promptly on the change) carrying the
      * attestation; the `/sign` round runs only on that change, so it costs one round per rotation, never per
      * tick. Key-less interim mode no-ops (the verify-only signer cannot assemble).
@@ -811,7 +1126,7 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
         const snapshot = snapshotAt(now); // also observes the current identity (snapshotAt → cohort())
         const current = identityOf(snapshot);
         const predecessor = rotationState.predecessor();
-        const rotating = predecessor !== undefined && firstKxChanged(predecessor, current);
+        const rotating = predecessor !== undefined && epochChanged(predecessor, current);
         let published;
         if (rotating) {
             const rotation = await produceRotation(snapshot, predecessor);
@@ -833,16 +1148,23 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
         primaryTopicCount: (tier) => countPrimaryTopics(store, ctx.selfMemberBytes, tier),
         config: { cohortSize: ctx.wantK },
     });
-    const traffic = createTrafficCounters({ view, store, selfMember });
+    const traffic = createTrafficCounters({ view, store, selfMember, childCohortCount: (topicId) => childRegistry.count(topicId) });
     const promotion = createPromotionLifecycle({
         store,
         loadBucket: (topicId) => ctx.barometer.bucket(tierOfTopic(store, topicId)),
-        // Single-cohort milestone: a tier-0 cohort with no children. Child-cohort tracking is a follow-on.
-        childCohortCount: () => 0,
+        // Real child count off this engine's local registry — a converged union across the parent cohort (the
+        // FRET-routed member that records a child gossips a child-link delta; every member merges inbound ones),
+        // so this count is consistent cohort-wide. Blocks demotion while any child is linked; once the last
+        // child demotes (its notice unlinks it here and cohort-wide) the count falls to 0 and the parent can
+        // demote in turn (`promotion.ts` demotionTriggered).
+        childCohortCount: (topicId) => childRegistry.count(topicId),
         treeTier: () => treeTier,
         // `coord_{d-1}(P, topicId)`; never invoked at the root (demotion is gated on `treeTier > 0`), so
         // the `d = 0` branch (clamped to `coord_0`) is a well-formed placeholder that the lifecycle skips.
         parentCoord: (topicId) => ctx.addressing.coord(Math.max(0, treeTier - 1), participantCoord, topicId),
+        // The served coord this engine was instantiated at — stamped on every notice as `cohortCoord` and
+        // covered by its threshold signature, so a receiver routes + verifies the notice by exactly this coord.
+        cohortCoord: () => servedCoord,
         cohortEpoch: localEpoch,
         signer: noticeSigner,
         // Production defaults (cap_promote = 64, …) unless the host was given a promotion override — the
@@ -862,7 +1184,20 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
     // single-tier-0 milestone has no parent (the root serves immediately), so a unit test exercises this.
     const coldStart = createColdStartManager({
         parentRegistrar: {
-            registerWithParent: (topicId, parentCoord, tier, opTier) => registerForwarderWithParent(ctx, { topicId, parentCoord, treeTier: tier, opTier, participantCoord }),
+            registerWithParent: (topicId, parentCoord, tier, opTier) => registerForwarderWithParent(ctx, {
+                topicId,
+                parentCoord,
+                treeTier: tier,
+                opTier,
+                participantCoord,
+                // This engine's served coord IS `coord_d(participantCoord, topicId)` — the child cohort coord the
+                // parent verifies + records against.
+                childCohortCoord: servedCoord,
+                cohortEpoch: localEpoch,
+                // Live-key: the child threshold-signs the link over its own coord/epoch. Key-less interim: no
+                // signer, so the link ships unsigned and the parent permissive-accepts it.
+                signChildLink: canPublish ? childLinkSigner : undefined,
+            }),
         },
     });
     // Per-coord anti-DoS guards (gap 6): each CoordEngine owns its own set — a rate-limit budget / replay
@@ -873,7 +1208,19 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
     // so a probe flood cannot exhaust a participant's register budget at this coord, or vice-versa.
     const probeRateLimiter = createRegisterRateLimiter(ctx.antiDos.rateLimiter);
     const replayGuard = createCorrelationReplayGuard(ctx.antiDos.replayGuard);
-    const topicBudget = createTopicBudget(ctx.antiDos.topicBudget);
+    // Reconcile the cold-start forwarder set + traffic window with the topic budget on eviction. When the
+    // budget is full and evicts the coldest (zero-participant) resident to make room for a new topic, tear
+    // down the evicted topic's forwarder and traffic counters too — otherwise `servesTopic` stays true off
+    // the leftover forwarder, the topic is served forever with no budget slot, and the forwarder map grows
+    // unbounded. `coldStart` (declared above at the createColdStartManager call) and `traffic` are both
+    // initialized before this point, so the callback closes over live instances.
+    const topicBudget = createTopicBudget({
+        ...ctx.antiDos.topicBudget,
+        onEvict: (topicId) => {
+            coldStart.remove(topicId);
+            traffic.forget(topicId);
+        },
+    });
     const renewal = createRenewalCohortSide({
         store,
         self: ctx.selfMemberBytes,
@@ -887,6 +1234,10 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
             evicted: (rec) => pending.evicted(rec),
         },
         verifyParticipantSig: ctx.verifyParticipantSig,
+        // Freshness gate for the privileged withdraw/reattach paths. Share the register path's skew config
+        // (`ctx.antiDos.replayGuard`, the same `{ maxAgeMs, maxFutureSkewMs }` `createCorrelationReplayGuard`
+        // consumes above) so an operator tuning the window moves the register and renew paths together.
+        freshness: ctx.antiDos.replayGuard,
     });
     const engine = createCohortMemberEngine({
         self: ctx.selfMemberBytes,
@@ -926,34 +1277,53 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
         }
         return [...byKey.values()];
     };
+    // Timestamp of the last frame this engine actually emitted (any frame carries willingness). Drives the
+    // idle-but-willing heartbeat throttle: an idle round heartbeats only if this engine has never emitted
+    // (first idle round → immediate, so bootstrap converges fast) or `T_willingness_heartbeat` has elapsed.
+    // A record-carrying round emits every round and updates this clock, so the throttle governs only
+    // genuinely-idle engines. `undefined` until the first emit.
+    // 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;
     // 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. Idle
-    // empty engines (no topics, no deltas) build no frame and skip the broadcast.
+    // 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.
     const gossipRound = async (now) => {
         engine.sweepStale(now);
         const topicSummaries = residentTopics().map((topicId) => toCohortTopicSummary(topicId, traffic.publish(topicId, now), {
             tier: tierOfTopic(store, topicId),
             directParticipants: store.directParticipants(topicId),
             promoted: promotion.isPromoted(topicId),
-            // Single-cohort milestone: no child cohorts tracked. Child-cohort tracking is a follow-on.
-            childCohortCount: 0,
+            // Real child count off this engine's local registry — a converged union across the parent cohort
+            // (every member gossips its child link/unlink deltas; inbound ones merge here), so this is
+            // consistent cohort-wide, not a single-member shard.
+            childCohortCount: childRegistry.count(topicId),
         }));
-        const { records, evicted } = pending.drain();
+        const { records, evicted, childLinks, childUnlinks } = pending.drain();
+        const idle = topicSummaries.length === 0 && records.length === 0 && evicted.length === 0
+            && childLinks.length === 0 && childUnlinks.length === 0;
+        const heartbeat = idle && (lastGossipAt === undefined || now - lastGossipAt >= ctx.willingnessHeartbeatMs);
         const g = buildCohortGossip({
             fromMember: selfMember,
             coord: bytesToB64url(servedCoord),
             cohortEpoch: bytesToB64url(localEpoch()),
+            treeTier,
+            heartbeat,
             profile: ctx.profile,
             barometer: ctx.barometer,
             windowSeconds: DEFAULT_TRAFFIC_WINDOW_SECONDS,
             topicSummaries,
             records,
             evicted,
+            childLinks,
+            childUnlinks,
             timestamp: now,
         });
         if (g === undefined) {
             return undefined;
         }
+        lastGossipAt = now;
         if (ctx.signGossip !== undefined) {
             g.signature = await ctx.signGossip(g);
         }
@@ -988,14 +1358,40 @@ function createCoordEngine(ctx, servedCoord, treeTier, participantCoord) {
         cohort,
         cohortIdentityAt: (epoch) => rotationState.membersAt(bytesToB64url(epoch)),
         hasState: () => store.listAll().length > 0,
+        hasForwarders: () => coldStart.hasForwarders(),
         holds: (topicId, participantId) => store.getByParticipant(topicId, participantId) !== undefined,
         records: (topicId) => store.listByTopic(topicId),
         topicTraffic: (topicId) => traffic.snapshot(topicId),
+        // NOTE: the only production caller today is the matchmaking QueryV1 serve handler
+        // (matchmaking-query-accounting-seam). When the AggregateCountV1 sweep RPC lands it is another
+        // genuine cohort query and should bump the same seam — reuse `engine.recordQuery` at that call site.
+        // NOTE: unlike `recordArrival` (whose topic always becomes resident via the store), a query can be
+        // recorded against a NON-resident topic (the recordless `findByCoord` serve fallback). `gossipRound`
+        // only `publish`es `residentTopics()`, and `traffic.forget` fires only on topic-budget eviction, so
+        // such a topic's query window prunes only at epoch `reset`. Harmless now (bounded by epoch lifetime +
+        // the serve gate; a few timestamps per query). If a node ever serves high-volume queries for topics it
+        // holds no records for, prune non-resident windows on a timer or forget them when their engine idles.
+        recordQuery: (topicId, now) => traffic.recordQuery(topicId, now),
         cohortView: () => view,
         servesTopic: (topicId) => store.directParticipants(topicId) > 0 || coldStart.get(topicId) !== undefined,
         budgetHasTopic: (topicId) => topicBudget.has(topicId),
         budgetParticipantCount: (topicId) => topicBudget.participantCount(topicId),
         forwarder: (topicId) => coldStart.get(topicId),
+        // A local record/unrecord (parent-side child-link dispatch / demotion-notice unlink) also enqueues the
+        // corresponding gossip delta on a real state change, so the child set converges across the parent cohort.
+        // A gossip-merged delta writes the registry directly (via the bus `onChildDeltas` callback) and is NOT
+        // re-enqueued here — one broadcast reaches the whole cohort.
+        recordChild: (topicId, childCohortCoord, effectiveAt) => {
+            if (childRegistry.recordChild(topicId, childCohortCoord, effectiveAt)) {
+                pending.childLink(topicId, childCohortCoord, effectiveAt);
+            }
+        },
+        unrecordChild: (topicId, childCohortCoord, effectiveAt) => {
+            if (childRegistry.unrecordChild(topicId, childCohortCoord, effectiveAt)) {
+                pending.childUnlink(topicId, childCohortCoord, effectiveAt);
+            }
+        },
+        childCohortCount: (topicId) => childRegistry.count(topicId),
         isPromoted: (topicId) => promotion.isPromoted(topicId),
         applyPromotionNotice: (notice, now) => promotion.applyPromotionNotice(notice, now),
         applyDemotionNotice: (notice, now) => promotion.applyDemotionNotice(notice, now),
@@ -1022,6 +1418,55 @@ export function resolveRenew(registry, renew, now) {
     }
     return holder.engine.handleRenew(renew, now);
 }
+/**
+ * Parent-side handling of an inbound {@link ChildLinkV1}: bind the parent-child relationship, verify the
+ * child cohort's threshold signature, record the child, and ack. Steps:
+ *
+ * 1. **Bind.** Recompute `coord_childTier(childParticipantCoord, topicId)` and reject unless it equals the
+ *    signed `childCohortCoord`; `coord_(childTier−1)(...)` is this parent's served coord. An attacker cannot
+ *    point the link at an unrelated parent without a `childParticipantCoord` that also hashes to the signed
+ *    child coord (which it cannot, absent the prefix-class membership).
+ * 2. **Verify** (live-key) the child cohort threshold sig against the child cohort's cert; key-less-permissive
+ *    short-circuits it. A non-verified result → `rejected`.
+ * 3. **Record** the child on the parent engine (freshness-ordered, idempotent).
+ * 4. Reply `linked`.
+ */
+export async function dispatchChildLink(link, deps, now) {
+    const topicId = b64urlToBytes(link.topicId);
+    const childParticipantCoord = b64urlToBytes(link.childParticipantCoord);
+    const childCohortCoord = b64urlToBytes(link.childCohortCoord);
+    // Step 1 — bind the relationship. `validateChildLinkV1` already enforced `childTier >= 1`, so `childTier − 1`
+    // is a well-formed parent tier.
+    const recomputedChild = deps.coord(link.childTier, childParticipantCoord, topicId);
+    if (!bytesEqual(recomputedChild, childCohortCoord)) {
+        return { v: 1, result: "rejected", reason: "coord mismatch" };
+    }
+    const parentServedCoord = deps.coord(link.childTier - 1, childParticipantCoord, topicId);
+    // Step 2 — verify the child cohort threshold signature (live-key). Key-less-permissive short-circuits.
+    if (deps.verifyChildLinkSig !== undefined) {
+        const verified = await deps.verifyChildLinkSig(link, now);
+        if (!verified) {
+            return { v: 1, result: "rejected", reason: "child cohort signature not verified" };
+        }
+    }
+    // Step 3 — record on the parent engine (resolving it by its served coord). Resolving may create the parent
+    // engine, so it can hit the registry cap: a full-of-live registry refuses, which we turn into a clean
+    // `rejected` (the child re-links on a later round / after the cohort drains an idle engine) rather than an
+    // unhandled throw on the stream.
+    let parent;
+    try {
+        parent = deps.resolveParent(parentServedCoord, link.childTier - 1, childParticipantCoord);
+    }
+    catch (err) {
+        if (err instanceof CoordEngineRegistryFullError) {
+            return { v: 1, result: "rejected", reason: "parent cohort capacity" };
+        }
+        throw err;
+    }
+    parent.recordChild(topicId, childCohortCoord, link.effectiveAt);
+    // Step 4 — ack.
+    return { v: 1, result: "linked" };
+}
 /** Tolerated future skew (ms) for a `membership` payload's `stabilizedAt` — a value beyond this is refused. */
 const SIGN_STABILIZED_AT_SKEW_MS = 5_000;
 /** The canonical signable-image tag a non-`rotation` {@link SignKind} must carry (binds tag ↔ kind). */
@@ -1029,6 +1474,7 @@ const SIGNABLE_IMAGE_TAG = {
     membership: "MembershipCertV1",
     promotion: "PromotionNoticeV1",
     demotion: "DemotionNoticeV1",
+    childlink: "ChildLinkV1",
 };
 /**
  * Decode a `/sign` payload's canonical signable array image — `utf8(JSON.stringify([...]))` produced by
@@ -1143,6 +1589,9 @@ export async function handleSignRequest(request, fromPeerStr, deps) {
     // All kinds — bind the payload-internal `cohortEpoch` to our own current epoch (closes the falsified-internal
     // -epoch hole, for promotion / demotion too). It is `image[2]` for a MembershipCertV1 image and the last
     // element for promotion / demotion (see `sig/payloads.ts`).
+    // NOTE: this reads the notice epoch positionally as the LAST element — `sig/payloads.ts` deliberately keeps
+    // `cohortEpoch` last (with the newer `cohortCoord` inserted just before it) to preserve this. Do not append
+    // a field after `cohortEpoch` in those images without updating this read.
     const currentEpochB64 = bytesToB64url(deps.currentEpoch(coord));
     const embeddedEpoch = request.kind === "membership" ? image[2] : image[image.length - 1];
     if (embeddedEpoch !== currentEpochB64) {
@@ -1174,7 +1623,7 @@ export async function handleSignRequest(request, fromPeerStr, deps) {
     return { v: 1, signer: bytesToB64url(deps.selfMember), signature: bytesToB64url(signature) };
 }
 /**
- * Hard cap on tracked `(topicId, tier)` high-water entries; the least-recently-touched are evicted beyond
+ * 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.
  */
@@ -1212,8 +1661,8 @@ export const PROMOTE_REFETCH_MIN_INTERVAL_MS = 60_000;
  * Verify an inbound notice's threshold signature against the cohort `MembershipCertV1` for
  * `target.servedCoord` and, on success, apply it to the target's promotion lifecycle. Returns:
  *
- * - `"dropped"`  — no local engine serves the notice's `(topic, tier)` (e.g. a demotion arriving at a
- *   parent that does not track the child); nothing to apply to.
+ * - `"dropped"`  — no local engine serves the notice's carried `cohortCoord` (e.g. a demotion arriving at a
+ *   parent-only node that does not serve the demoting child's coord); nothing to apply to.
  * - `"untrusted"` — the `signers` are not a `≥ minSigs` subset of the cohort cert, or the multisig does
  *   not verify (a forged single-signer / short-quorum notice); local state is left unchanged.
  * - `"applied"`  — verified and applied.
@@ -1261,6 +1710,52 @@ export async function verifyAndApplyNotice(inbound, target, verifier, now) {
     target.applyDemotionNotice(inbound.notice, now);
     return "applied";
 }
+/**
+ * Parent-side apply of a demotion notice: release (unrecord) the demoting child at its parent cohort. A
+ * demoting child threshold-signs its {@link DemotionNoticeV1} and fans it to **both** its own served coord
+ * (siblings adopt `promoted = false` via {@link verifyAndApplyNotice}) and its `parentCohortCoord`. This is the
+ * second, independent apply semantics at the parent: resolve the parent engine at `parentCohortCoord`, verify
+ * the notice's threshold signature against the **child** cohort cert (identical verify to the sibling-adopt —
+ * signers ⊆ the child cohort cert at the notice's `tier`, keyed by the child's `cohortCoord`), and on
+ * `verified` call `parent.unrecordChild(topicId, cohortCoord, effectiveAt)`.
+ *
+ * Returns:
+ * - `"no-parent"` — this node does not serve `parentCohortCoord`; nothing to unrecord (a pure sibling-adopt node).
+ * - `"untrusted"` — the signature does not verify against the child cohort cert (a forged / under-quorum notice).
+ * - `"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.
+ */
+export async function applyDemotionUnlinkAtParent(notice, registry, verifier, now) {
+    const parent = registry.findByCoord(b64urlToBytes(notice.parentCohortCoord));
+    if (parent === undefined) {
+        return "no-parent";
+    }
+    let signers;
+    let sig;
+    try {
+        signers = notice.signers.map(b64urlToBytes);
+        sig = b64urlToBytes(notice.thresholdSig);
+    }
+    catch {
+        return "untrusted"; // a signer / sig that is not valid base64url cannot verify
+    }
+    // Verify against the CHILD cohort cert (the demoting cohort's served coord `notice.cohortCoord`), NOT the
+    // parent's — the demotion is threshold-signed by the child cohort. Same bounded refetch as the sibling-adopt.
+    const payload = demotionNoticeSigningPayload(notice);
+    const result = await verifier.verifyMessage(signers, b64urlToBytes(notice.cohortCoord), notice.tier, payload, sig, { minRefetchIntervalMs: PROMOTE_REFETCH_MIN_INTERVAL_MS, now });
+    if (result !== "verified") {
+        return "untrusted";
+    }
+    // `cohortCoord` is the child's served coord — the key the parent recorded the child under.
+    parent.unrecordChild(b64urlToBytes(notice.topicId), b64urlToBytes(notice.cohortCoord), notice.effectiveAt);
+    return "unlinked";
+}
 /**
  * Full inbound `promote`-frame pipeline with the anti-abuse gate, exported so it is unit-testable without a
  * live node (`cohort-topic-promote-handler-verify-amplification`). Runs the cheapest checks first — each
@@ -1268,14 +1763,27 @@ export async function verifyAndApplyNotice(inbound, target, verifier, now) {
  * work:
  *
  * ```
- *   decode → per-(peer,topic) rate limit → findServing → effectiveAt high-water → verify+apply
+ *   decode → per-(peer,topic) rate limit → resolve engine by carried cohortCoord → effectiveAt high-water → 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).
+ *
  * - **Rate limit** (`gate.rateLimiter`) keys on `(from, topicId)`; an over-rate peer is dropped before the
- *   `findServing` map scan and the verify, so a peer cannot amplify junk into verify/network work.
- * - **High-water** (`gate.highWater`, per `(topicId, tier)`) 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.
+ *   coord lookup and the verify, so a peer cannot amplify junk into verify/network work.
+ * - **Resolve engine by `cohortCoord`** ({@link CoordRegistry.findByCoord}) — the exact served coord the
+ *   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.
  * - 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
@@ -1293,32 +1801,68 @@ export async function handleInboundNotice(frame, from, registry, verifier, gate,
     }
     const tier = inbound.kind === "promotion" ? inbound.notice.fromTier : inbound.notice.tier;
     const topicId = b64urlToBytes(inbound.notice.topicId);
-    // Per-(peer, topic) rate limit — before the findServing scan and the verify.
+    // Per-(peer, topic) rate limit — before the coord lookup and the verify.
     if (gate.rateLimiter.check(from, topicId, now).ok === false) {
         log("promote: rate-limited %s notice for topic %s tier %d", inbound.kind, inbound.notice.topicId, tier);
         return "rate-limited";
     }
-    const target = registry.findServing(topicId, tier);
+    // --- Sibling-adopt path: apply to the cohort that produced the notice (its signed `cohortCoord`). ---
+    // Route by the notice's signed `cohortCoord` — the exact served coord the deciding cohort sits at. A node
+    // serving several sibling cohorts for one `(topic, tier)` (possible at `d ≥ 1`) thus applies the notice to
+    // the cohort that produced it, and `verifyAndApplyNotice` verifies against that same coord's cert. The coord
+    // is covered by the threshold signature, so it cannot be rewritten to hijack a sibling. A coord this node
+    // does not serve → `dropped` here (e.g. a demotion fanned to a parent-only node — the parent-unlink path
+    // below still runs).
+    const target = registry.findByCoord(b64urlToBytes(inbound.notice.cohortCoord));
+    let siblingOutcome;
     if (target === undefined) {
-        log("promote: dropped %s notice for topic %s tier %d (no serving engine)", inbound.kind, inbound.notice.topicId, tier);
-        return "dropped";
+        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);
+            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);
+            }
+            else {
+                log("promote: %s %s notice for topic %s tier %d", siblingOutcome, inbound.kind, inbound.notice.topicId, tier);
+            }
+        }
     }
-    // Freshness / replay gate: drop an at-or-below-high-water notice before the expensive verify.
-    const waterKey = `${inbound.notice.topicId}|${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);
-        return "stale";
+    if (inbound.kind !== "demotion") {
+        return siblingOutcome;
     }
-    const outcome = await verifyAndApplyNotice(inbound, target, verifier, now);
-    if (outcome === "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);
+    // --- 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.
+    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
     }
-    else {
-        log("promote: %s %s notice for topic %s tier %d", outcome, inbound.kind, inbound.notice.topicId, tier);
+    if (unlink === "unlinked") {
+        return "unlinked";
     }
-    return outcome;
+    if (unlink === "untrusted") {
+        log("promote: untrusted demotion notice at parent for topic %s tier %d", inbound.notice.topicId, tier);
+        return "untrusted";
+    }
+    return siblingOutcome;
 }
 /**
  * The cohort coords a notice is broadcast to over the `promote` protocol: always the cohort around
@@ -1343,7 +1887,7 @@ function crossCheckCohort(fret, wantK, servedCoord, fretCohort) {
         log("cohort cross-check mismatch at coord %s: FRET-routed=%o assembled=%o; trusting the recomputed assembly", bytesToB64url(servedCoord), fretCohort, assembled);
     }
 }
-/** Positional equality over two string lists (the first-`k − x` rotation-change check). */
+/** Positional equality over two string lists (the endorser's sorted-member-list image check). */
 function sameStringOrder(a, b) {
     if (a.length !== b.length) {
         return false;
@@ -1378,15 +1922,24 @@ function tierOfTopic(store, topicId) {
     const recs = store.listByTopic(topicId);
     return (recs.length > 0 ? recs[0].tier : 0);
 }
-async function registerProtocolHandlers(node, protocols, registry, dispatchRegister, signEndorse, verifier, promoteGate, gossipTransport, publishSink, membershipSource, selfCoord, maxBytes) {
+async function registerProtocolHandlers(node, protocols, registry, dispatchRegister, 
+/** Parent-side child-link dispatch deps + the quorum bound used to structurally validate an inbound link. */
+childLinkDeps, minSigs, signEndorse, verifier, promoteGate, gossipTransport, 
+/** Instantiate a cold sibling's coord engine off a verified co-member frame (§Cold-start instantiation). */
+maybeInstantiateColdSibling, publishSink, membershipSource, selfCoord, maxBytes) {
     await Promise.all([
-        // register: a direct dial carries either a RegisterV1 (re-attach walk fallback) or a RenewV1 (ping).
+        // register: a direct dial carries a RenewV1 (ping), a ChildLinkV1 (a child cohort registering with this
+        // parent), or a RegisterV1 (re-attach walk fallback). The three shapes are disjoint, so try each in turn.
         node.handle(protocols.register, makeFrameHandler(async (frame) => {
             const decoded = decodeCohortMessage(frame, maxBytes);
             const renew = tryValidate(() => validateRenewV1(decoded));
             if (renew !== undefined) {
                 return encodeCohortMessage(resolveRenew(registry, renew, Date.now()), maxBytes);
             }
+            const link = tryValidate(() => validateChildLinkV1(decoded, minSigs));
+            if (link !== undefined) {
+                return encodeCohortMessage(await dispatchChildLink(link, childLinkDeps, Date.now()), maxBytes);
+            }
             const reg = validateRegisterV1(decoded);
             // Direct dial (not FRET-routed): no cohort member list to cross-check against.
             const reply = await dispatchRegister(reg, undefined, Date.now());
@@ -1394,7 +1947,10 @@ async function registerProtocolHandlers(node, protocols, registry, dispatchRegis
         }, maxBytes)),
         // cohort-gossip: feed inbound gossip into the shared transport (one-way). It fans the frame to
         // every coord engine's bus; per-bus epoch matching governs which engine merges the record deltas.
+        // First, if this is a verified co-member frame for a coord we hold no engine for, instantiate that
+        // engine (§Cold-start instantiation) so its freshly-subscribed bus merges this very frame on `deliver`.
         node.handle(protocols.gossip, makeFrameHandler(async (frame, from) => {
+            maybeInstantiateColdSibling(frame);
             gossipTransport.deliver(from.toString(), frame);
             return undefined;
         }, maxBytes)),