@optimystic/db-core 0.14.1 → 0.16.3

package/src/cohort-topic/service.ts

@@ -154,9 +154,10 @@ export interface CohortTopicServiceDeps {
 	/** Monotonic-ish wall clock (unix ms); injectable for tests. Default `Date.now`. */
 	readonly clock?: () => number;
 	/**
-	 * Optional cold-start bootstrap-evidence builder (db-p2p supplies it). Invoked **only** on the
-	 * bootstrap re-issue (when the walk sets `bootstrap: true`), with the register's own canonical
-	 * fields — the same `(topicId, tier, participantCoord, timestamp)` tuple a verifier binds via
+	 * Optional cold-start bootstrap-evidence builder (db-p2p supplies it). Invoked on **either** cold-start
+	 * re-issue — the root `bootstrap: true` or the deeper-tier `followOn: true` (both gated by the same
+	 * evidence policy) — with the register's own canonical fields, the same
+	 * `(topicId, tier, participantCoord, timestamp)` tuple a verifier binds via
 	 * `bootstrapBoundImage`. It returns the **raw** envelope JSON bytes — `utf8(JSON.stringify(env))`,
 	 * NOT the already-base64url string from `serializeBootstrapEvidenceEnvelope` — or `undefined` to
 	 * attach none; the service base64url-encodes those bytes into `RegisterV1.bootstrapEvidence`
@@ -230,9 +231,10 @@ class WalkRegisterService implements CohortTopicService {
 	}
 
 	async renew(handle: RegistrationHandle): Promise<void> {
-		// Withdrawn handles drop out of the live set; renewing one is a no-op so withdraw() actually
-		// stops the local ping loop (rather than the app silently continuing to refresh it).
-		if (!this.renewals.has(recordKey(handle.topicId, this.participantId))) {
+		// Act only if this handle is still the live entry. A stale handle (superseded by a second
+		// register() for the same pair) must not drive the new registration's ping loop, and a
+		// withdrawn handle must not silently re-start it.
+		if (this.renewals.get(recordKey(handle.topicId, this.participantId)) !== handle.renewal) {
 			return;
 		}
 		await handle.renewal.pingLoop();
@@ -246,11 +248,16 @@ class WalkRegisterService implements CohortTopicService {
 		// The delete happens FIRST so a concurrent renew() already no-ops before the tombstone is sent. If
 		// the tombstone send fails (primary unreachable), the cohort soft-state TTL-expires as the
 		// fallback — withdraw never throws on a transport failure. Idempotent: a second withdraw finds
-		// `renewal === undefined` and no-ops.
+		// `renewal !== handle.renewal` (undefined ≠ any object) and no-ops.
+		// Guard: act only if this handle is still the live entry. A stale handle must not evict the
+		// new registration or send a tombstone on its behalf.
 		const key = recordKey(handle.topicId, this.participantId);
 		const renewal = this.renewals.get(key);
+		if (renewal !== handle.renewal) {
+			return;
+		}
 		this.renewals.delete(key);
-		await renewal?.withdraw();
+		await renewal.withdraw();
 	}
 
 	cohortGossip(): CohortGossipBus {
@@ -268,11 +275,11 @@ class WalkRegisterService implements CohortTopicService {
 			throw new CohortBackoffError(outcome.kind === "retry_later" ? outcome.afterMs : 0);
 		}
 		const hint = this.hintFromReply(req.topicId, req.tier, outcome.reply);
-		const renewal = this.startRenewal(req, hint, outcome.reply);
+		const renewal = this.startRenewal(req, hint, outcome.correlationId);
 		return { ...hint, renewal };
 	}
 
-	private startRenewal(req: RegisterRequest, hint: CohortHint, reply: RegisterReplyV1): RenewalParticipant {
+	private startRenewal(req: RegisterRequest, hint: CohortHint, correlationId: string): RenewalParticipant {
 		const ttl = req.ttl ?? this.ttl;
 		const initial: RegistrationRecord = {
 			topicId: req.topicId,
@@ -290,9 +297,21 @@ class WalkRegisterService implements CohortTopicService {
 			transport,
 			clock: this.clock,
 			sign: (body: UnsignedRenew): Promise<string> => this.deps.signer.signRenew(body),
-			correlationId: reply.cohortEpoch ?? bytesToB64url(this.participantId),
+			// Echo the accepted RegisterV1's correlationId: RenewV1 `correlationId` "matches original
+			// RegisterV1" (docs §Wire, RenewV1), so a future renew-path freshness/replay guard can correlate
+			// a renew back to the registration it renews.
+			// NOTE: every periodic renew for this registration shares this ONE correlationId (as it always
+			// has — this only makes the shared id equal the register's, not an independent nonce). A future
+			// renew replay guard must therefore key renews by (correlationId, timestamp-window), NOT "drop
+			// any repeated correlationId" — else it would reject the 2nd+ legitimate renew.
+			correlationId,
 			initialCohortEpoch: hint.cohortEpoch,
 		});
+		// NOTE: a second register() for the same (topicId, participantId) overwrites the map entry here,
+		// orphaning the prior renewal. renew()/withdraw() on the stale handle now no-op (identity guard),
+		// but no tombstone is sent for the superseded record — the cohort frees it via TTL expiry. Harmless
+		// for occasional re-registers; if callers ever churn-register the same pair, send a withdraw for the
+		// displaced renewal here so the cohort reclaims immediately instead of holding up to a full TTL.
 		this.renewals.set(recordKey(req.topicId, this.participantId), renewal);
 		return renewal;
 	}
@@ -351,12 +370,19 @@ class WalkRegisterService implements CohortTopicService {
 					correlationId: this.freshCorrelationId(),
 				};
 				if (params.probe) {
-					// A read-only lookup probe. Mutually exclusive with bootstrap (the walk never sets
-					// `bootstrap` on a probe), so the cold-start-evidence branch below cannot run for a probe.
+					// A read-only lookup probe. Mutually exclusive with bootstrap/followOn (the walk never sets
+					// either on a probe), so the cold-start-evidence branch below cannot run for a probe.
 					body.probe = true;
 				}
-				if (params.bootstrap) {
-					body.bootstrap = true;
+				// A cold-start re-issue — root (`bootstrap`) or deeper-tier follow-on (`followOn`). Both are
+				// gated by the identical evidence policy (§Anti-DoS), so both mint and attach the same envelope
+				// bound to the body's own canonical fields. Mutually exclusive with each other and with probe.
+				if (params.bootstrap || params.followOn) {
+					if (params.followOn) {
+						body.followOn = true;
+					} else {
+						body.bootstrap = true;
+					}
 					// Attach cold-start evidence BEFORE signing (so the signature covers it). Bind the
 					// builder to the body's own canonical fields — the exact tuple a verifier reconstructs.
 					const evidence = await this.deps.buildBootstrapEvidence?.({

package/src/cohort-topic/sig/payloads.ts

@@ -3,14 +3,22 @@
  *
  * A threshold signature is only verifiable if signer and verifier agree on the exact bytes signed.
  * These builders produce that deterministic byte image for each threshold-signed message
- * (`MembershipCertV1`, `PromotionNoticeV1`, `DemotionNoticeV1`), covering exactly the semantic
- * fields per `docs/cohort-topic.md` §Wire formats — never the `thresholdSig`/`signers` envelope.
+ * (`MembershipCertV1`, `PromotionNoticeV1`, `DemotionNoticeV1`, `ChildLinkV1`), covering exactly the
+ * semantic fields per `docs/cohort-topic.md` §Wire formats — never the `thresholdSig`/`signers` envelope.
  *
  * Determinism comes from encoding an explicitly-ordered JSON array (array order is stable, unlike
  * object key order) as UTF-8. The publisher signs this image; the verifier recomputes and checks it.
+ *
+ * The notice images carry `cohortCoord` (the served coord the deciding cohort sits at) so the coord the
+ * receiver routes by is bound into the signed bytes — rewriting it to hijack a sibling cohort breaks
+ * verification. It is inserted **just before the trailing `cohortEpoch`**, deliberately keeping `cohortEpoch`
+ * the LAST element: the `/sign` endorser (`handleSignRequest`) reads a notice's embedded epoch positionally
+ * as `image[image.length - 1]`, so `cohortEpoch` must stay last. This is a hard, coordinated change to the
+ * canonical signed bytes, acceptable pre-release (no deployed nodes speak this protocol, so there is no
+ * version to negotiate).
  */
 
-import type { DemotionNoticeV1, MembershipCertV1, PromotionNoticeV1 } from "../wire/types.js";
+import type { ChildLinkV1, DemotionNoticeV1, MembershipCertV1, PromotionNoticeV1 } from "../wire/types.js";
 
 const utf8 = new TextEncoder();
 
@@ -23,17 +31,29 @@ export function membershipCertSigningPayload(cert: MembershipCertSignable): Uint
 }
 
 /** Fields of a `PromotionNoticeV1` covered by its threshold signature. */
-export type PromotionSignable = Pick<PromotionNoticeV1, "topicId" | "fromTier" | "toTier" | "effectiveAt" | "cohortEpoch">;
+export type PromotionSignable = Pick<PromotionNoticeV1, "topicId" | "fromTier" | "toTier" | "effectiveAt" | "cohortEpoch" | "cohortCoord">;
 
-/** Canonical signed byte image of a promotion notice. */
+/** Canonical signed byte image of a promotion notice. `cohortEpoch` stays last (the `/sign` endorser reads it positionally). */
 export function promotionNoticeSigningPayload(n: PromotionSignable): Uint8Array {
-	return utf8.encode(JSON.stringify(["PromotionNoticeV1", n.topicId, n.fromTier, n.toTier, n.effectiveAt, n.cohortEpoch]));
+	return utf8.encode(JSON.stringify(["PromotionNoticeV1", n.topicId, n.fromTier, n.toTier, n.effectiveAt, n.cohortCoord, n.cohortEpoch]));
 }
 
 /** Fields of a `DemotionNoticeV1` covered by its threshold signature. */
-export type DemotionSignable = Pick<DemotionNoticeV1, "topicId" | "tier" | "parentCohortCoord" | "effectiveAt" | "cohortEpoch">;
+export type DemotionSignable = Pick<DemotionNoticeV1, "topicId" | "tier" | "parentCohortCoord" | "effectiveAt" | "cohortEpoch" | "cohortCoord">;
 
-/** Canonical signed byte image of a demotion notice. */
+/** Canonical signed byte image of a demotion notice. `cohortEpoch` stays last (the `/sign` endorser reads it positionally). */
 export function demotionNoticeSigningPayload(n: DemotionSignable): Uint8Array {
-	return utf8.encode(JSON.stringify(["DemotionNoticeV1", n.topicId, n.tier, n.parentCohortCoord, n.effectiveAt, n.cohortEpoch]));
+	return utf8.encode(JSON.stringify(["DemotionNoticeV1", n.topicId, n.tier, n.parentCohortCoord, n.effectiveAt, n.cohortCoord, n.cohortEpoch]));
+}
+
+/** Fields of a `ChildLinkV1` covered by the child cohort's threshold signature. */
+export type ChildLinkSignable = Pick<ChildLinkV1, "topicId" | "childCohortCoord" | "childParticipantCoord" | "childTier" | "tier" | "effectiveAt" | "cohortEpoch">;
+
+/**
+ * Canonical signed byte image of a child-link frame. `cohortEpoch` stays **last** so the `/sign` endorser
+ * (`handleSignRequest`) reads the embedded epoch positionally as `image[image.length - 1]`, exactly as it
+ * does for a promotion / demotion notice.
+ */
+export function childLinkSigningPayload(n: ChildLinkSignable): Uint8Array {
+	return utf8.encode(JSON.stringify(["ChildLinkV1", n.topicId, n.childCohortCoord, n.childParticipantCoord, n.childTier, n.tier, n.effectiveAt, n.cohortEpoch]));
 }

package/src/cohort-topic/traffic.ts

@@ -70,6 +70,12 @@ export interface TrafficCounters {
 	snapshot(topicId: Uint8Array): TopicTrafficV1;
 	/** Reset all counters to zero (call on `cohortEpoch` change). */
 	reset(): void;
+	/**
+	 * Drop all local windowed counts and the last-published summary for `topicId` (the cohort no longer
+	 * serves it — budget eviction / teardown). Idempotent; a no-op if never observed. Siblings' gossiped
+	 * contributions age out of {@link snapshot} on their own as their summaries stop naming the topic.
+	 */
+	forget(topicId: Uint8Array): void;
 }
 
 export interface TrafficCountersDeps {
@@ -128,7 +134,11 @@ class WindowedTrafficCounters implements TrafficCounters {
 		let childCohortCount = 0;
 		for (const [member, contribution] of this.deps.view.all()) {
 			if (member === this.deps.selfMember) continue; // own contribution comes from lastPublished
-			const summary = contribution.topicSummaries.find((s) => s.topicId === topicB64);
+			// O(1) per-topic lookup via the merge-time index; fall back to a scan only for a contribution
+			// not built through `merge` (which populates `topicIndex`). Net: snapshot is O(members + summaries).
+			const summary = contribution.topicIndex !== undefined
+				? contribution.topicIndex.get(topicB64)
+				: contribution.topicSummaries.find((s) => s.topicId === topicB64);
 			if (summary === undefined) continue;
 			arrivals += summary.arrivalsPerMin;
 			queries += summary.queriesPerMin;
@@ -136,6 +146,10 @@ class WindowedTrafficCounters implements TrafficCounters {
 				childCohortCount = summary.childCohortCount;
 			}
 		}
+		// NOTE: `childCohortCount` (the max of siblings' gossiped counts above) is dormant whenever the
+		// registry override is wired — the override returns a number (0 included), so `?? childCohortCount`
+		// never falls through. It becomes the effective value only if the override is unwired; the child-set
+		// replication follow-on converges siblings by populating each engine's registry, not via this max.
 		const childOverride = this.deps.childCohortCount?.(topicId);
 		return {
 			windowSeconds: this.windowMs / 1000,
@@ -151,6 +165,14 @@ class WindowedTrafficCounters implements TrafficCounters {
 		this.lastPublished.clear();
 	}
 
+	forget(topicId: Uint8Array): void {
+		// Idempotent: `Map.delete` on an absent key is a safe no-op. Clears both the raw windowed events
+		// and the frozen last-published summary so a re-instantiated topic starts from zero.
+		const key = bytesKey(topicId);
+		this.windows.delete(key);
+		this.lastPublished.delete(key);
+	}
+
 	private windowFor(topicId: Uint8Array): TopicWindow {
 		const key = bytesKey(topicId);
 		let w = this.windows.get(key);

package/src/cohort-topic/walk.ts

@@ -10,7 +10,12 @@
  * Reply handling (§Lookup):
  * - **`accepted`** → done; return the reply (carries `primary`/`backups`/`cohortEpoch` to cache).
  * - **`no_state`** at tier `d` → step one tier toward the root (`d − 1`); no traffic signal. At the
- *   root (`d − 1 < 0`) re-issue once at tier 0 with `bootstrap: true` (cold-start request).
+ *   root (`d − 1 < 0`) re-issue once at tier 0 with `bootstrap: true` (cold-start request). **If this
+ *   `no_state` is the redirect target of a `Promoted` this walk just followed** (`followedPromoted`),
+ *   the deeper child is cold: a register re-issues **once** at the same tier with `followOn: true` (a
+ *   deeper-tier cold-start, gated by the same evidence a `bootstrap` pays), then backs off if that too
+ *   returns `no_state`; a probe never instantiates, so it backs off immediately. This is what lets a
+ *   join that lands on a freshly-promoted-but-not-yet-grown branch converge instead of oscillating.
  * - **`promoted(targetTier)`** → recompute `coord_targetTier(self, topicId)` and register there — the
  *   one outward move, taken only on this explicit redirect.
  * - **`unwilling_member(candidates)`** → retry the **same** coord at a named alternative member
@@ -29,6 +34,7 @@
 import type { ITopicRouter, PeerRef } from "./ports.js";
 import type { TierAddressing } from "./addressing.js";
 import type { DMaxComputer } from "./dmax.js";
+import { DEFAULT_D_MAX_CAP } from "./dmax.js";
 import { backoffRetryMs } from "./willingness.js";
 import { b64urlToBytes, decodeRegisterReplyV1, encodeCohortMessage } from "./wire/codec.js";
 import type { RegisterReplyV1, RegisterV1 } from "./wire/types.js";
@@ -37,6 +43,12 @@ import type { RegisterReplyV1, RegisterV1 } from "./wire/types.js";
 export interface AcceptedWalkOutcome {
 	readonly kind: "accepted";
 	readonly reply: RegisterReplyV1;
+	/**
+	 * The accepted register probe's own `correlationId`. The participant echoes it on every renew for this
+	 * registration so `RenewV1.correlationId` "matches original `RegisterV1`" (docs §Wire, RenewV1). Each
+	 * probe carries a distinct correlationId; this is the one the cohort admitted.
+	 */
+	readonly correlationId: string;
 }
 
 /**
@@ -65,18 +77,22 @@ export type WalkOutcome = AcceptedWalkOutcome | PromotedWalkOutcome | RetryLater
 /** Builds (and signs) the {@link RegisterV1} for one probe; owns participant identity + crypto. */
 export interface RegisterMessageFactory {
 	/**
-	 * Produce a signed `RegisterV1` for this participant at walk position `treeTier`. `bootstrap` is
-	 * set only on the root cold-start re-issue. `appPayload` is the opaque application slot. On the
-	 * bootstrap re-issue the factory may additionally mint and attach the signed `bootstrapEvidence`
-	 * envelope (§Anti-DoS) via the injected builder seam before signing — keyed off `bootstrap`, so no
-	 * extra build parameter is needed (the walk decides `bootstrap` internally, not the application).
+	 * Produce a signed `RegisterV1` for this participant at walk position `treeTier`. `bootstrap` is set
+	 * only on the root cold-start re-issue; `followOn` only on the dedicated re-issue after a `Promoted`
+	 * redirect target answered `NoState` (§Cold-start). `appPayload` is the opaque application slot. On
+	 * either cold-start re-issue the factory mints and attaches the signed `bootstrapEvidence` envelope
+	 * (§Anti-DoS — a follow-on is gated identically to a bootstrap) via the injected builder seam before
+	 * signing — keyed off `bootstrap`/`followOn`, so no extra parameter is needed (the walk decides both
+	 * internally, not the application). `bootstrap`, `followOn`, and `probe` are mutually exclusive.
 	 */
 	build(params: {
 		topicId: Uint8Array;
 		tier: number;
 		treeTier: number;
 		bootstrap: boolean;
-		/** Read-only lookup probe: the factory stamps `RegisterV1.probe` and never mints bootstrap evidence. */
+		/** Follow-on cold-start re-issue after a `Promoted` redirect target answered `NoState` (`treeTier >= 1`). */
+		followOn: boolean;
+		/** Read-only lookup probe: the factory stamps `RegisterV1.probe` and never mints cold-start evidence. */
 		probe: boolean;
 		appPayload?: Uint8Array;
 	}): Promise<RegisterV1>;
@@ -128,6 +144,16 @@ export interface WalkEngine {
 	register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?: { probe?: boolean }): Promise<WalkOutcome>;
 }
 
+/**
+ * A walk tier is valid iff it is an integer in `0..DEFAULT_D_MAX_CAP` — the substrate's own walk-depth
+ * ceiling. A `promoted` reply's explicit `targetTier` is untrusted: an out-of-range value (non-integer,
+ * negative, or above the ceiling) cannot name a real cohort and would reach `addressing.coord()` →
+ * `coordD`, which throws a raw `RangeError`. Matches the range the wire `treeTier` validator enforces.
+ */
+function isValidTreeTier(value: number): boolean {
+	return Number.isInteger(value) && value >= 0 && value <= DEFAULT_D_MAX_CAP;
+}
+
 class RouterWalkEngine implements WalkEngine {
 	private readonly wantK: number;
 	private readonly minSigs: number;
@@ -153,10 +179,19 @@ class RouterWalkEngine implements WalkEngine {
 
 		let d = dMax;
 		let bootstrap = false;
-		let memberAttempts = 0;
+		let followOn = false;
+		// Member ids (base64url) already dialed on this walk's `unwilling_member` retries. Tracking WHICH
+		// members were tried — not a positional counter — lets each fresh candidate list be consumed from
+		// its best (index-0) member; a counter would permanently skip index 0 of every list after the first.
+		const triedMembers = new Set<string>();
 		let dialTarget: PeerRef | undefined;
 		let steps = 0;
-		let probeFollowedPromoted = false;
+		// True once this walk has followed a `Promoted` redirect outward (either mode). On a subsequent
+		// `NoState` the redirect target is cold: a probe backs off (never instantiates), a register
+		// re-issues once with `followOn: true` to instantiate the child, then backs off.
+		let followedPromoted = false;
+		// True once the register path has spent its single `followOn: true` re-issue at the cold child.
+		let followOnReissued = false;
 
 		for (;;) {
 			if (++steps > maxSteps) {
@@ -165,7 +200,7 @@ class RouterWalkEngine implements WalkEngine {
 				return { kind: "retry_later", afterMs: backoffRetryMs(0) };
 			}
 
-			const reg = await this.deps.factory.build({ topicId, tier, treeTier: d, bootstrap, probe, appPayload });
+			const reg = await this.deps.factory.build({ topicId, tier, treeTier: d, bootstrap, followOn, probe, appPayload });
 			const activity = encodeCohortMessage(reg, this.maxMessageBytes);
 			const raw = dialTarget !== undefined
 				? await this.deps.router.dialMember(dialTarget, activity)
@@ -177,16 +212,30 @@ class RouterWalkEngine implements WalkEngine {
 
 			switch (reply.result) {
 				case "accepted": {
-					return { kind: "accepted", reply };
+					// Surface the accepted probe's correlationId so the participant's renewals can echo it
+					// (RenewV1 correlationId "matches original RegisterV1"). `reg` is the frame just admitted.
+					return { kind: "accepted", reply, correlationId: reg.correlationId };
 				}
 				case "no_state": {
 					// Step toward the root. The cohort served nothing here; no spatial sibling state.
 					dialTarget = undefined;
-					memberAttempts = 0;
-					if (probe && probeFollowedPromoted) {
-						// The promoted child is cold (not yet instantiated). A probe never instantiates it,
-						// so back off immediately — walking inward to the promoting ancestor would just
-						// re-trigger the Promoted redirect and loop.
+					triedMembers.clear(); // a spatial move to a new coord starts sibling retries fresh
+					if (followedPromoted) {
+						// The `Promoted` redirect target is cold (not yet instantiated). Walking inward to the
+						// promoting ancestor would just re-trigger the redirect and oscillate, so handle it here.
+						if (probe) {
+							// A probe never instantiates — back off immediately (mirror of the register re-issue).
+							return { kind: "retry_later", afterMs: backoffRetryMs(0) };
+						}
+						if (!followOnReissued) {
+							// Re-issue ONCE at the SAME child tier as a follow-on cold-start: RegisterV1{ followOn:
+							// true } + minted evidence. The mirror of the root NoState → bootstrap:true re-issue.
+							followOn = true;
+							followOnReissued = true;
+							break; // re-register at the same coord/tier, now carrying followOn
+						}
+						// The follow-on re-issue still got NoState → the cold child's quorum is unwilling to
+						// instantiate. Back off in time; do NOT loop inward.
 						return { kind: "retry_later", afterMs: backoffRetryMs(0) };
 					}
 					const next = d - 1;
@@ -212,12 +261,30 @@ class RouterWalkEngine implements WalkEngine {
 				}
 				case "promoted": {
 					dialTarget = undefined;
-					memberAttempts = 0;
+					triedMembers.clear(); // spatial move to the redirect target: sibling retries start fresh
 					bootstrap = false;
 					const targetTier = reply.targetTier ?? d + 1;
-					if (probe) {
-						probeFollowedPromoted = true;
+					// The cohort names the tier to jump outward to. When it supplied `targetTier` EXPLICITLY it is
+					// untrusted: an out-of-range value would reach `coord()` → `coordD` and throw a raw RangeError,
+					// an unclassified crash out of register()/lookup() rather than a clean outcome. Bound it before
+					// BOTH adoption sites (the followPromoted-false surface below and the `d = targetTier` hop) and
+					// back off in time instead. Only the EXPLICIT attacker value is the hazard; the `d + 1`
+					// fallback is left unchecked because `d` is walk-bounded to `dMax + maxSteps` (≈190 under the
+					// default `maxSteps`), comfortably under coordD's 255 range.
+					// NOTE: `maxSteps` is operator-configurable — a value above ~195 plus an adversarial chain of
+					// no-`targetTier` `promoted` replies (each bumps `d` by +1) could push the `d + 1` fallback
+					// past coordD's range and reintroduce the RangeError. If maxSteps is ever raised that high,
+					// bound the fallback here too.
+					if (reply.targetTier !== undefined && !isValidTreeTier(targetTier)) {
+						return { kind: "retry_later", afterMs: backoffRetryMs(0) };
 					}
+					// Following a (fresh) redirect: mark it, and reset the follow-on latch so a cold child at
+					// THIS target gets its own single follow-on re-issue. The honest flow re-registers the
+					// child with a PLAIN frame first (followOn false) and only escalates to followOn on its
+					// NoState — so clear the flag here; the NoState branch re-arms it.
+					followedPromoted = true;
+					followOn = false;
+					followOnReissued = false;
 					if (!this.followPromoted) {
 						return { kind: "promoted", targetTier };
 					}
@@ -226,14 +293,18 @@ class RouterWalkEngine implements WalkEngine {
 				}
 				case "unwilling_member": {
 					const candidates = reply.candidateMembers ?? [];
-					if (candidates.length === 0 || memberAttempts >= this.maxMemberRetries) {
-						// Exhausted the named siblings (or none offered) → fall through to a cohort-level
-						// temporal back-off, restarting at d_max on the caller's retry.
+					// Consume this (possibly fresh) list from its best (index-0) member: pick the FIRST
+					// candidate not already dialed on this walk. A positional `memberAttempts % len` offset
+					// would skip index 0 of every list after the first, permanently starving the best member.
+					const next = candidates.find((c) => !triedMembers.has(c));
+					if (next === undefined || triedMembers.size >= this.maxMemberRetries) {
+						// No untried candidate offered (or the retry cap is spent) → fall through to a
+						// cohort-level temporal back-off, restarting at d_max on the caller's retry.
 						return { kind: "retry_later", afterMs: backoffRetryMs(0) };
 					}
 					// Retry the SAME coord at a named alternative member (spatial move within the cohort).
-					dialTarget = { id: b64urlToBytes(candidates[memberAttempts % candidates.length]!) };
-					memberAttempts++;
+					triedMembers.add(next);
+					dialTarget = { id: b64urlToBytes(next) };
 					break;
 				}
 				case "unwilling_cohort": {

package/src/cohort-topic/wire/codec.ts

@@ -12,6 +12,8 @@
 
 import { CohortWireError } from "./validate.js";
 import {
+	validateChildLinkReplyV1,
+	validateChildLinkV1,
 	validateCohortGossipV1,
 	validateDemotionNoticeV1,
 	validateMembershipCertV1,
@@ -24,6 +26,8 @@ import {
 	validateSignReplyV1,
 } from "./validate.js";
 import type {
+	ChildLinkReplyV1,
+	ChildLinkV1,
 	CohortGossipV1,
 	DemotionNoticeV1,
 	MembershipCertV1,
@@ -179,6 +183,14 @@ export function decodeRenewReplyV1(bytes: Uint8Array, maxMessageBytes?: number):
 	return validateRenewReplyV1(decodeCohortMessage(bytes, maxMessageBytes));
 }
 
+export function decodeChildLinkV1(bytes: Uint8Array, maxMessageBytes?: number, minSigs?: number): ChildLinkV1 {
+	return validateChildLinkV1(decodeCohortMessage(bytes, maxMessageBytes), minSigs);
+}
+
+export function decodeChildLinkReplyV1(bytes: Uint8Array, maxMessageBytes?: number): ChildLinkReplyV1 {
+	return validateChildLinkReplyV1(decodeCohortMessage(bytes, maxMessageBytes));
+}
+
 export function decodePromotionNoticeV1(bytes: Uint8Array, maxMessageBytes?: number): PromotionNoticeV1 {
 	return validatePromotionNoticeV1(decodeCohortMessage(bytes, maxMessageBytes));
 }

package/src/cohort-topic/wire/index.ts

@@ -7,6 +7,8 @@ export {
 	validateRegisterReplyV1,
 	validateRenewV1,
 	validateRenewReplyV1,
+	validateChildLinkV1,
+	validateChildLinkReplyV1,
 	validatePromotionNoticeV1,
 	validateDemotionNoticeV1,
 	validateCohortGossipV1,

package/src/cohort-topic/wire/payloads.ts

@@ -10,9 +10,9 @@
  * for the threshold-signed notices, determinism comes from encoding an explicitly-ordered JSON
  * array (array order is stable, unlike object key order) as UTF-8 — never the `signature` envelope.
  * Optional fields are normalized to a fixed placeholder (`bootstrap`→`false`, `probe`→`false`,
- * `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as absent,
- * `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default optional can
- * never disagree across the wire round-trip.
+ * `followOn`→`false`, `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as
+ * absent, `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default
+ * optional can never disagree across the wire round-trip.
  */
 
 import type { CohortGossipV1, RegisterV1, RenewV1 } from "./types.js";
@@ -48,6 +48,11 @@ export function registerSigningPayload(body: RegisterSignable): Uint8Array {
 		// A read-only probe signs `probe: true`; a normal register signs `false`. Both sides recompute
 		// this image identically, so a probe and a register over the same fields produce distinct signatures.
 		body.probe ?? false,
+		// A follow-on cold-start re-issue signs `followOn: true`, everything else `false`. Strictly appended
+		// (sibling to `probe`/`withdraw`) so a MITM cannot strip or flip the follow-on assertion and the
+		// signer (participant) + verifier (db-p2p cohort) agree byte-for-byte. Safe to append: no register
+		// signatures are persisted (each is recomputed per verify), so there is no cross-version image concern.
+		body.followOn ?? false,
 	]));
 }
 
@@ -79,7 +84,8 @@ export type CohortGossipSignable = Omit<CohortGossipV1, "signature">;
  * or replicate forged records). Like the other payload helpers, determinism comes from an
  * explicitly-ordered array — nested records/summaries/evictions are emitted as fixed ordered tuples so
  * the signer and the receiver (which re-derives this image from the validated frame) agree byte-for-byte.
- * Absent optionals (`records`/`evicted`) normalize to `[]`, and `appState` to `null`.
+ * Absent optionals (`records`/`evicted`/`childLinks`/`childUnlinks`) normalize to `[]`, and `appState` to
+ * `null`. `childLinks`/`childUnlinks` are covered so a MITM cannot strip or inject a child link/unlink.
  */
 export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array {
 	return utf8.encode(JSON.stringify([
@@ -88,6 +94,7 @@ export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array
 		g.fromMember,
 		g.coord,
 		g.cohortEpoch,
+		g.treeTier,
 		g.willingnessBits,
 		g.loadBuckets,
 		g.windowSeconds,
@@ -111,7 +118,9 @@ export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array
 			r.ttl,
 			r.appState ?? null,
 		]),
-		(g.evicted ?? []).map((e) => [e.topicId, e.participantId]),
+		(g.evicted ?? []).map((e) => [e.topicId, e.participantId, e.lastPing]),
+		(g.childLinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
+		(g.childUnlinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
 		g.timestamp,
 	]));
 }